@decido/sdk-core

Internal Core SDK for Decido OS Canvas & Plugin Architecture.
El puente de extensibilidad e interoperabilidad crucial y agnóstico de UI para el lienzo interactivo de Decido OS.

1. Rol Arquitectónico y Extensibilidad

@decido/sdk-core es la interfaz puente central y agnóstica de UI que permite a los plugins interactuar e inyectarse en el motor de renderizado de la pizarra interactiva (yo-decido-core). Garantiza que el contrato del lienzo se declare una sola vez y sea respetado de forma isomórfica por cualquier componente.

graph TD
    A[Plugin Externo] -->|implementa| B(PluginConfig)
    B -->|registra vía| C{CoreSDK}
    C -->|__init| D[Motor de Pizarra: window.decidoWhiteboard]
    D -->|renderiza| E[Nodos SVG / HTML]

2. Instalación e Integración

Este paquete está integrado nativamente como parte del pnpm workspace monorepo de Decido OS:

{
  "dependencies": {
    "@decido/sdk-core": "workspace:*"
  }
}

3. Tabla de APIs y Tipos Expuestos

A continuación se detallan los principales contratos, interfaces y utilidades expuestas por el SDK:

| API / Tipo | Categoría | Propósito y Descripción | | :--- | :--- | :--- | | CoreSDK | Singleton / Fachada | Punto de entrada centralizado para registrar plugins, comandos de la palette y gestionar elementos. | | h(tag, props, ...children) | Helper DOM | Utilería de renderizado ultra-rápida y segura contra ataques XSS. Discrimina namespaces HTML/SVG automáticamente. | | PluginConfig<TState, TProperties, TPayload, TResult> | Interfaz (TS) | Contrato de configuración obligatorio para definir la lógica, esquema y renderizado de un plugin de nodo interactivo. | | CanvasNode<TState> | Interfaz (TS) | Representa la instancia activa de un nodo posicionado en el lienzo interactivo con su estado reactivo. | | PluginUtils<TState> | Interfaz (TS) | Métodos reactivos inyectados por el motor (updateState, triggerEvent) para mutar el lienzo de forma segura. | | PropertySchemaItem | Interfaz (TS) | Declaración de propiedades para la autogeneración de la UI en el panel lateral del inspector de nodos. | | PinType | Tipo (TS) | Define los tipos de puertos admitidos en los grafos de flujo (EXEC, ANY, STRING, NUMBER, etc.). |

4. Guía de Uso Rápido (DX Premium con Genéricos)

Registro de Plugin con Tipado Estricto

Define el estado del nodo y las propiedades deseadas con interfaces fuertes para dotar a tu plugin de un autocompletado robusto en el IDE:

import { CoreSDK, PluginConfig, CanvasNode, PluginUtils, h } from '@decido/sdk-core';

// 1. Define tu estado personalizado
interface MiNodoState {
  titulo: string;
  contador: number;
  w: number;
  h: number;
}

// 2. Implementa la configuración del plugin
const miPluginConfig: PluginConfig<MiNodoState> = {
  label: 'Contador Interactivo',
  icon: 'plus-circle',
  group: 'Utilidades',
  defaultState: {
    titulo: 'Mi Contador',
    contador: 0,
    w: 200,
    h: 120
  },
  
  // Renderizado SVG seguro con h
  render(node: CanvasNode<MiNodoState>, selected: boolean, utils: PluginUtils<MiNodoState>) {
    return h('g', {},
      // Rectángulo base
      h('rect', {
        width: node.w,
        height: node.h,
        fill: '#1e1e2e',
        rx: 8,
        stroke: selected ? '#8b5cf6' : '#313244',
        'stroke-width': 2
      }),
      
      // Texto de título
      h('text', {
        x: 15,
        y: 30,
        fill: '#cdd6f4',
        'font-family': 'sans-serif',
        'font-weight': 'bold'
      }, node.state.titulo),
      
      // Botón de interacción con trigger reactivo de estado
      h('g', {
        transform: 'translate(15, 50)',
        cursor: 'pointer',
        onclick: () => {
          utils.updateState({ contador: node.state.contador + 1 });
        }
      },
        h('rect', { width: 170, height: 40, fill: '#8b5cf6', rx: 4 }),
        h('text', {
          x: 85,
          y: 24,
          fill: '#ffffff',
          'text-anchor': 'middle',
          'font-family': 'sans-serif'
        }, `Clicks: ${node.state.contador}`)
      )
    );
  },

  // Lógica de ejecución del flujo de datos
  execute(node: CanvasNode<MiNodoState>, payload: any) {
    console.log('Ejecutando lógica de contador:', node.state.contador);
    return node.state.contador;
  }
};

// 3. Registrar el plugin en el Core
CoreSDK.registerPlugin('mi-contador-nodo', miPluginConfig);

Uso del Helper Seguro h

El helper h analiza el tag para decidir si crea un nodo estándar de HTML o uno con el espacio de nombres de SVG:

import { h } from '@decido/sdk-core';

// Creación de elemento HTML con estilos como objeto y eventos
const boton = h('button', {
  class: 'btn-primary',
  style: { backgroundColor: '#8b5cf6', color: '#fff', border: 'none' },
  onclick: () => alert('Click seguro!')
}, 'Presióname');

// Creación de elemento SVG (el namespace de SVG y xmlns se gestionan internamente)
const circulo = h('circle', {
  cx: 50,
  cy: 50,
  r: 40,
  fill: 'red'
});

5. Robustez y Pruebas (Decido Unit Test Shield)

El paquete @decido/sdk-core cumple estrictamente con el estándar Decido Unit Test Shield, garantizando una cobertura total e inmunidad completa contra regresiones:

• Pruebas Unitarias de DOM: Cobertura exhaustiva en la creación de nodos HTML/SVG, aplicación de estilos en string/objeto y escuchas seguras de eventos DOM.
• Pruebas de Singleton: Validación de inicialización formal, fallbacks seguros a entornos heredados (window.decidoWhiteboard) y enrutamiento completo de fachadas.

Ejecución de Suite de Pruebas locales:

pnpm --filter @decido/sdk-core test

Generación de Reporte de Cobertura (100%):

pnpm --filter @decido/sdk-core test:coverage

Resumen de Calidad:

• Sentencias: 100%
• Ramas (Branches): 100%
• Funciones: 100%
• Líneas: 100%
• Aserciones Falsas/Placeholders: 0%