scic-webgui 0.3.0

Dashboard web autogenerable para scic-framework, dirigido por los contratos de DataValue.

La interfaz ya no trata cada función como «un formulario genérico que devuelve JSON». Interpreta explícitamente PrimitiveData y ComplexData para generar navegación, formularios recursivos, validación inmediata y resultados estructurados.

Vista previa

Dashboard y contextos plegables

Formulario recursivo generado desde ComplexData

Resultado estructurado por el contrato DataValue

Modelo

SCIC Context
├── Subcontexto plegable
├── Subcontexto plegable
└── Executable
    ├── Página independiente
    ├── Parameters: ComplexData posicional
    │   └── PrimitiveData / ComplexData recursivos
    └── Results: ComplexData posicional
        └── Renderizado estructurado / tabla / gráfica / JSON

scic-framework no se modifica. scic-webgui consume el resultado de Executable.describe() y normaliza la serialización original de DataValue.

PrimitiveData → campo

DataValue	Control generado
bool	Switch
str	Campo de texto
int	Selector numérico entero
float	Selector numérico decimal
bytes / bytearray	Editor de texto/bytes
possible_values literales	Lista seleccionable

Restricciones soportadas:

• minimum_length / maximum_length;
• minimum_size / maximum_size;
• possible_values;
• regular_expression;
• name;
• description;
• data_class.

La validación del navegador es inmediata, pero DataValue continúa siendo la autoridad final cuando SCIC adapta y valida los argumentos.

ComplexData → composición

• validation_mode="positional": campos fijos y ordenados.
• Lista homogénea con un esquema: editor repetible con añadir/eliminar.
• Diccionario con claves literales descritas: formulario de objeto.
• Diccionario dinámico o contrato ambiguo: editor JSON con vista del contrato.
• Anidación arbitraria de PrimitiveData y ComplexData.
• Límites de colección mediante minimum_length / maximum_length y aliases futuros minimum_size / maximum_size.

Resultados

Los resultados se emparejan con Executable.results:

• primitivo booleano → indicador;
• primitivo numérico → valor destacado;
• objeto/dict → vista de propiedades con nombres y descripciones;
• lista de objetos → tabla;
• lista numérica → gráfica SVG automática;
• lista simple → lista visual;
• complejo posicional → secciones etiquetadas;
• JSON original → disponible como vista secundaria.

Uso

from scic_webgui import SCICWebGUI, WebGUIConfig

webgui = SCICWebGUI(
    scic,
    WebGUIConfig(
        application_name="OpenShell Manager",
        application_description="OSAM administrative interface",
        locale="es",
        default_variant="dark",
    ),
)

app = webgui.app
# o:
webgui.run()

Launcher

Expón una instancia SCIC o una factory sin argumentos:

# application.py
application = build_scic()

scic-webgui application:application \
  --name "OpenShell Manager" \
  --variant dark \
  --open-browser

Configuración

WebGUIConfig(
    application_name="OpenShell Manager",
    application_description="OSAM administrative interface",
    host="127.0.0.1",
    port=8080,
    api_prefix="/api/scic/v1",
    default_theme="default",
    default_variant="system",
    locale="es",
    show_raw_results=True,
    show_contract=True,
    dashboard_enabled=True,
    activity_enabled=True,
    sidebar_collapsible=True,
    extension_scripts=("/static/osam-webgui.js",),
)

Pistas visuales opcionales

DataValue describe el contrato. Para los pocos casos donde el mismo tipo necesita widgets diferentes, el metadata del Executable puede añadir una capa opcional:

metadata={
    "parameter_ui": {
        "profile": {
            "input_kind": "json-file",
            "accepted_extensions": [".json"],
        },
        "password": {
            "input_kind": "password",
            "secret": True,
        },
    }
}

Prioridad de selección:

1. renderer especializado registrado;
2. pista parameter_ui;
3. possible_values;
4. DATA_TYPE de DataValue;
5. fallback JSON.

Extensiones

SCICWebGUI.registerView("/osam/root-authority/list", async context => {
  // Página completa especializada.
});

SCICWebGUI.registerInputRenderer(
  ({ schema }) => schema.name === "entity_uid",
  ({ path }) => `<input data-value-path="${path}" pattern="[0-9a-f-]+">`,
  100,
);

SCICWebGUI.registerResultRenderer(
  ({ schema }) => schema?.name === "certificate",
  ({ value }) => `<article class="certificate">...</article>`,
  100,
);

SCICWebGUI.registerDashboardWidget(
  "osam-health",
  () => `<section class="panel">...</section>`,
  100,
);

Probar el ejemplo rico

python3 -m pip install -e '.[test,build]'
python3 examples/rich_demo.py

El ejemplo demuestra:

• str con longitud y regex;
• int y float con límites;
• bool como switch;
• possible_values como selector;
• ComplexData dict como objeto;
• lista de objetos como tabla;
• lista numérica como gráfica.

Validación y build

./check.sh

El script ejecuta:

• compilación Python;
• node --check para todos los módulos JavaScript cuando Node está disponible;
• pytest;
• construcción de wheel y sdist;
• twine check.