Metadata-Version: 2.4
Name: scic-webgui
Version: 0.3.0
Summary: DataValue-driven dashboard and WebGUI for SCIC Framework
Author: Specter
License-Expression: MIT
Project-URL: Homepage, https://github.com/specter327/scic-webgui
Project-URL: Repository, https://github.com/specter327/scic-webgui
Project-URL: Issues, https://github.com/specter327/scic-webgui/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: scic-framework<0.3.0,>=0.2.3
Requires-Dist: datavalue<0.2.0,>=0.1.21
Requires-Dist: fastapi<1.0,>=0.115
Requires-Dist: uvicorn[standard]<1.0,>=0.30
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23; extra == "test"
Requires-Dist: httpx>=0.27; extra == "test"
Provides-Extra: build
Requires-Dist: build>=1.2; extra == "build"
Requires-Dist: twine>=5.0; extra == "build"
Dynamic: license-file

# scic-webgui 0.3.0

Dashboard web autogenerable para [`scic-framework`](https://github.com/specter327/scic-framework), dirigido por los contratos de [`DataValue`](https://github.com/specter327/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

![Dashboard](docs/screenshots/dashboard.png)

### Formulario recursivo generado desde ComplexData

![ComplexData form](docs/screenshots/complex-form.png)

### Resultado estructurado por el contrato DataValue

![Structured result](docs/screenshots/structured-result.png)

## Modelo

```text
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

```python
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:

```python
# application.py
application = build_scic()
```

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

## Configuración

```python
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:

```python
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

```javascript
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

```bash
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

```bash
./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`.
