@tmorrow/cre8-wc 2.0.2 → 2.0.4

package/a2ui/registry.js

@@ -0,0 +1,166 @@
+export function registerCatalog(schema) {
+    const defs = schema.$defs?.components ?? {};
+    const components = new Map(Object.entries(defs));
+    const id = schema['x-a2ui']?.catalogId ?? schema.$id ?? 'unknown';
+    return { id, schema, components };
+}
+function validatePropValue(value, schema, path) {
+    if (value === undefined || value === null)
+        return;
+    if (!schema)
+        return;
+    if (schema.const !== undefined && value !== schema.const) {
+        throw new Error(`${path}: expected const ${JSON.stringify(schema.const)}, got ${JSON.stringify(value)}`);
+    }
+    if (schema.enum && !schema.enum.includes(value)) {
+        const allowed = schema.enum.map((v) => JSON.stringify(v)).join(', ');
+        throw new Error(`${path}: value ${JSON.stringify(value)} not in enum [${allowed}]`);
+    }
+    if (schema.oneOf && schema.oneOf.length) {
+        const errors = [];
+        for (const branch of schema.oneOf) {
+            try {
+                validatePropValue(value, branch, path);
+                return;
+            }
+            catch (e) {
+                errors.push(e.message);
+            }
+        }
+        throw new Error(`${path}: value ${JSON.stringify(value)} matched none of oneOf branches: ${errors.join(' | ')}`);
+    }
+    const types = Array.isArray(schema.type) ? schema.type : schema.type ? [schema.type] : [];
+    if (types.length && !types.some((t) => matchesType(t, value))) {
+        throw new Error(`${path}: expected type ${types.join('|')}, got ${describeType(value)}`);
+    }
+    if (Array.isArray(value) && schema.items) {
+        value.forEach((item, i) => validatePropValue(item, schema.items, `${path}[${i}]`));
+    }
+    if (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        schema.properties) {
+        const obj = value;
+        if (schema.required) {
+            for (const req of schema.required) {
+                if (!(req in obj)) {
+                    throw new Error(`${path}.${req}: required property missing`);
+                }
+            }
+        }
+        for (const [key, childVal] of Object.entries(obj)) {
+            const childSchema = schema.properties[key];
+            if (!childSchema) {
+                if (schema.additionalProperties === false) {
+                    throw new Error(`${path}.${key}: unexpected property`);
+                }
+                continue;
+            }
+            validatePropValue(childVal, childSchema, `${path}.${key}`);
+        }
+    }
+}
+function matchesType(t, v) {
+    switch (t) {
+        case 'string':
+            return typeof v === 'string';
+        case 'number':
+            return typeof v === 'number' && Number.isFinite(v);
+        case 'integer':
+            return typeof v === 'number' && Number.isInteger(v);
+        case 'boolean':
+            return typeof v === 'boolean';
+        case 'array':
+            return Array.isArray(v);
+        case 'object':
+            return typeof v === 'object' && v !== null && !Array.isArray(v);
+        case 'null':
+            return v === null;
+        default:
+            return true;
+    }
+}
+function describeType(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    return typeof v;
+}
+export function validateSpec(spec, catalog, path = '$') {
+    if (!spec || typeof spec !== 'object') {
+        throw new Error(`${path}: spec must be an object`);
+    }
+    const s = spec;
+    if (typeof s.component !== 'string') {
+        throw new Error(`${path}: spec.component must be a string`);
+    }
+    if (!catalog.components.has(s.component)) {
+        throw new Error(`${path}: component "${s.component}" is not registered in catalog "${catalog.id}"`);
+    }
+    const def = catalog.components.get(s.component);
+    const allowedProps = new Set(Object.keys(def.properties?.props?.properties ?? {}));
+    const hasChildren = def.properties?.children !== undefined;
+    const allowedSlots = def.properties?.slots
+        ? new Set(Object.keys(def.properties.slots.properties ?? {}))
+        : null;
+    if (s.props) {
+        if (typeof s.props !== 'object')
+            throw new Error(`${path}.props: must be an object`);
+        const propDefs = def.properties?.props?.properties ?? {};
+        for (const [prop, value] of Object.entries(s.props)) {
+            if (!allowedProps.has(prop)) {
+                throw new Error(`${path}.props.${prop}: not a declared prop on ${s.component}`);
+            }
+            validatePropValue(value, propDefs[prop], `${path}.props.${prop}`);
+        }
+    }
+    if (s.children !== undefined) {
+        if (!hasChildren) {
+            throw new Error(`${path}.children: ${s.component} does not accept default children`);
+        }
+        if (!Array.isArray(s.children))
+            throw new Error(`${path}.children: must be an array`);
+        s.children.forEach((c, i) => {
+            if (typeof c === 'string')
+                return;
+            validateSpec(c, catalog, `${path}.children[${i}]`);
+        });
+    }
+    if (s.events !== undefined) {
+        if (!s.events || typeof s.events !== 'object' || Array.isArray(s.events)) {
+            throw new Error(`${path}.events: must be an object`);
+        }
+        for (const [evtName, binding] of Object.entries(s.events)) {
+            if (typeof binding === 'string')
+                continue;
+            if (!binding || typeof binding !== 'object') {
+                throw new Error(`${path}.events.${evtName}: must be a string or { handler } object`);
+            }
+            const b = binding;
+            if (typeof b.handler !== 'string' || b.handler.length === 0) {
+                throw new Error(`${path}.events.${evtName}.handler: must be a non-empty string`);
+            }
+        }
+    }
+    if (s.slots !== undefined) {
+        if (!allowedSlots) {
+            throw new Error(`${path}.slots: ${s.component} does not accept named slots`);
+        }
+        if (typeof s.slots !== 'object')
+            throw new Error(`${path}.slots: must be an object`);
+        for (const [slotName, arr] of Object.entries(s.slots)) {
+            if (!allowedSlots.has(slotName)) {
+                throw new Error(`${path}.slots.${slotName}: not a declared slot on ${s.component}`);
+            }
+            if (!Array.isArray(arr)) {
+                throw new Error(`${path}.slots.${slotName}: must be an array`);
+            }
+            arr.forEach((c, i) => {
+                if (typeof c === 'string')
+                    return;
+                validateSpec(c, catalog, `${path}.slots.${slotName}[${i}]`);
+            });
+        }
+    }
+}

package/a2ui/registry.ts

@@ -0,0 +1,182 @@
+import type { CatalogSchema, ComponentSpec, PropSchema, RegisteredCatalog } from './types.js';
+
+export function registerCatalog(schema: CatalogSchema): RegisteredCatalog {
+  const defs = schema.$defs?.components ?? {};
+  const components = new Map(Object.entries(defs));
+  const id = schema['x-a2ui']?.catalogId ?? schema.$id ?? 'unknown';
+  return { id, schema, components };
+}
+
+function validatePropValue(value: unknown, schema: PropSchema | undefined, path: string): void {
+  if (value === undefined || value === null) return;
+  if (!schema) return;
+
+  if (schema.const !== undefined && value !== schema.const) {
+    throw new Error(
+      `${path}: expected const ${JSON.stringify(schema.const)}, got ${JSON.stringify(value)}`
+    );
+  }
+
+  if (schema.enum && !schema.enum.includes(value as string)) {
+    const allowed = schema.enum.map((v) => JSON.stringify(v)).join(', ');
+    throw new Error(`${path}: value ${JSON.stringify(value)} not in enum [${allowed}]`);
+  }
+
+  if (schema.oneOf && schema.oneOf.length) {
+    const errors: string[] = [];
+    for (const branch of schema.oneOf) {
+      try {
+        validatePropValue(value, branch, path);
+        return;
+      } catch (e) {
+        errors.push((e as Error).message);
+      }
+    }
+    throw new Error(
+      `${path}: value ${JSON.stringify(value)} matched none of oneOf branches: ${errors.join(' | ')}`
+    );
+  }
+
+  const types = Array.isArray(schema.type) ? schema.type : schema.type ? [schema.type] : [];
+  if (types.length && !types.some((t) => matchesType(t, value))) {
+    throw new Error(`${path}: expected type ${types.join('|')}, got ${describeType(value)}`);
+  }
+
+  if (Array.isArray(value) && schema.items) {
+    value.forEach((item, i) => validatePropValue(item, schema.items, `${path}[${i}]`));
+  }
+
+  if (
+    typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    schema.properties
+  ) {
+    const obj = value as Record<string, unknown>;
+    if (schema.required) {
+      for (const req of schema.required) {
+        if (!(req in obj)) {
+          throw new Error(`${path}.${req}: required property missing`);
+        }
+      }
+    }
+    for (const [key, childVal] of Object.entries(obj)) {
+      const childSchema = schema.properties[key];
+      if (!childSchema) {
+        if (schema.additionalProperties === false) {
+          throw new Error(`${path}.${key}: unexpected property`);
+        }
+        continue;
+      }
+      validatePropValue(childVal, childSchema, `${path}.${key}`);
+    }
+  }
+}
+
+function matchesType(t: string, v: unknown): boolean {
+  switch (t) {
+    case 'string':
+      return typeof v === 'string';
+    case 'number':
+      return typeof v === 'number' && Number.isFinite(v);
+    case 'integer':
+      return typeof v === 'number' && Number.isInteger(v);
+    case 'boolean':
+      return typeof v === 'boolean';
+    case 'array':
+      return Array.isArray(v);
+    case 'object':
+      return typeof v === 'object' && v !== null && !Array.isArray(v);
+    case 'null':
+      return v === null;
+    default:
+      return true;
+  }
+}
+
+function describeType(v: unknown): string {
+  if (v === null) return 'null';
+  if (Array.isArray(v)) return 'array';
+  return typeof v;
+}
+
+export function validateSpec(spec: unknown, catalog: RegisteredCatalog, path = '$'): asserts spec is ComponentSpec {
+  if (!spec || typeof spec !== 'object') {
+    throw new Error(`${path}: spec must be an object`);
+  }
+  const s = spec as Record<string, unknown>;
+  if (typeof s.component !== 'string') {
+    throw new Error(`${path}: spec.component must be a string`);
+  }
+  if (!catalog.components.has(s.component)) {
+    throw new Error(
+      `${path}: component "${s.component}" is not registered in catalog "${catalog.id}"`
+    );
+  }
+
+  const def = catalog.components.get(s.component)!;
+  const allowedProps = new Set(Object.keys(def.properties?.props?.properties ?? {}));
+  const hasChildren = def.properties?.children !== undefined;
+  const allowedSlots = def.properties?.slots
+    ? new Set(Object.keys(def.properties.slots.properties ?? {}))
+    : null;
+
+  if (s.props) {
+    if (typeof s.props !== 'object') throw new Error(`${path}.props: must be an object`);
+    const propDefs = def.properties?.props?.properties ?? {};
+    for (const [prop, value] of Object.entries(s.props as Record<string, unknown>)) {
+      if (!allowedProps.has(prop)) {
+        throw new Error(`${path}.props.${prop}: not a declared prop on ${s.component}`);
+      }
+      validatePropValue(value, propDefs[prop], `${path}.props.${prop}`);
+    }
+  }
+
+  if (s.children !== undefined) {
+    if (!hasChildren) {
+      throw new Error(`${path}.children: ${s.component} does not accept default children`);
+    }
+    if (!Array.isArray(s.children)) throw new Error(`${path}.children: must be an array`);
+    s.children.forEach((c, i) => {
+      if (typeof c === 'string') return;
+      validateSpec(c, catalog, `${path}.children[${i}]`);
+    });
+  }
+
+  if (s.events !== undefined) {
+    if (!s.events || typeof s.events !== 'object' || Array.isArray(s.events)) {
+      throw new Error(`${path}.events: must be an object`);
+    }
+    for (const [evtName, binding] of Object.entries(s.events as Record<string, unknown>)) {
+      if (typeof binding === 'string') continue;
+      if (!binding || typeof binding !== 'object') {
+        throw new Error(`${path}.events.${evtName}: must be a string or { handler } object`);
+      }
+      const b = binding as Record<string, unknown>;
+      if (typeof b.handler !== 'string' || b.handler.length === 0) {
+        throw new Error(`${path}.events.${evtName}.handler: must be a non-empty string`);
+      }
+    }
+  }
+
+  if (s.slots !== undefined) {
+    if (!allowedSlots) {
+      throw new Error(`${path}.slots: ${s.component} does not accept named slots`);
+    }
+    if (typeof s.slots !== 'object') throw new Error(`${path}.slots: must be an object`);
+    for (const [slotName, arr] of Object.entries(s.slots as Record<string, unknown>)) {
+      if (!allowedSlots.has(slotName)) {
+        throw new Error(
+          `${path}.slots.${slotName}: not a declared slot on ${s.component}`
+        );
+      }
+      if (!Array.isArray(arr)) {
+        throw new Error(`${path}.slots.${slotName}: must be an array`);
+      }
+      arr.forEach((c, i) => {
+        if (typeof c === 'string') return;
+        validateSpec(c, catalog, `${path}.slots.${slotName}[${i}]`);
+      });
+    }
+  }
+}

package/a2ui/renderer.d.ts

@@ -0,0 +1,7 @@
+import type { ComponentSpec, EmittedEvent, RegisteredCatalog } from './types.js';
+export interface RenderOptions {
+    root?: HTMLElement;
+    doc?: Document;
+    onEvent?: (evt: EmittedEvent) => void;
+}
+export declare function render(spec: ComponentSpec, catalog: RegisteredCatalog, options?: RenderOptions): HTMLElement;

package/a2ui/renderer.js

@@ -0,0 +1,108 @@
+import { validateSpec } from './registry.js';
+export function render(spec, catalog, options = {}) {
+    validateSpec(spec, catalog);
+    const doc = options.doc ?? document;
+    const el = buildElement(spec, catalog, doc, '$', options.onEvent);
+    if (options.root)
+        options.root.replaceChildren(el);
+    return el;
+}
+function buildElement(spec, catalog, doc, path, onEvent) {
+    const def = catalog.components.get(spec.component);
+    const propDefs = def.properties?.props?.properties ?? {};
+    const el = doc.createElement(spec.component);
+    if (spec.props) {
+        for (const [key, value] of Object.entries(spec.props)) {
+            applyProp(el, key, value, propDefs[key]);
+        }
+    }
+    if (spec.events && onEvent) {
+        for (const [evtName, binding] of Object.entries(spec.events)) {
+            attachEvent(el, spec.component, path, evtName, binding, onEvent);
+        }
+    }
+    if (spec.children) {
+        spec.children.forEach((child, i) => {
+            if (typeof child === 'string') {
+                el.appendChild(doc.createTextNode(child));
+                return;
+            }
+            el.appendChild(buildElement(child, catalog, doc, `${path}.children[${i}]`, onEvent));
+        });
+    }
+    if (spec.slots) {
+        for (const [slotName, children] of Object.entries(spec.slots)) {
+            children.forEach((child, i) => {
+                if (typeof child === 'string') {
+                    if (slotName === 'default') {
+                        el.appendChild(doc.createTextNode(child));
+                    }
+                    else {
+                        const wrap = doc.createElement('span');
+                        wrap.setAttribute('slot', slotName);
+                        wrap.textContent = child;
+                        el.appendChild(wrap);
+                    }
+                    return;
+                }
+                const childEl = buildElement(child, catalog, doc, `${path}.slots.${slotName}[${i}]`, onEvent);
+                if (slotName !== 'default')
+                    childEl.setAttribute('slot', slotName);
+                el.appendChild(childEl);
+            });
+        }
+    }
+    return el;
+}
+function attachEvent(el, component, path, eventName, binding, onEvent) {
+    const handler = typeof binding === 'string' ? binding : binding.handler;
+    const stop = typeof binding === 'object' && binding.stopPropagation === true;
+    const prevent = typeof binding === 'object' && binding.preventDefault === true;
+    el.addEventListener(eventName, (nativeEvent) => {
+        if (stop)
+            nativeEvent.stopPropagation();
+        if (prevent)
+            nativeEvent.preventDefault();
+        const detail = 'detail' in nativeEvent
+            ? nativeEvent.detail
+            : undefined;
+        onEvent({
+            component,
+            path,
+            event: eventName,
+            handler,
+            detail,
+            nativeEvent,
+        });
+    });
+}
+function applyProp(el, key, value, schema) {
+    if (value === undefined || value === null)
+        return;
+    if (schema?.['x-kind'] === 'property') {
+        el[key] = value;
+        return;
+    }
+    if (typeof value === 'boolean') {
+        if (value)
+            el.setAttribute(key, '');
+        else
+            el.removeAttribute(key);
+        return;
+    }
+    if (Array.isArray(value) || (typeof value === 'object' && value !== null)) {
+        el[key] = value;
+        return;
+    }
+    if (schema && isComplexSchema(schema)) {
+        el[key] = value;
+        return;
+    }
+    el.setAttribute(key, String(value));
+}
+function isComplexSchema(schema) {
+    const t = schema.type;
+    if (Array.isArray(t))
+        return t.some((x) => x === 'object' || x === 'array');
+    return t === 'object' || t === 'array';
+}

package/a2ui/renderer.ts

@@ -0,0 +1,156 @@
+import type {
+  ComponentSpec,
+  EmittedEvent,
+  EventBinding,
+  PropSchema,
+  RegisteredCatalog,
+} from './types.js';
+import { validateSpec } from './registry.js';
+
+export interface RenderOptions {
+  root?: HTMLElement;
+  doc?: Document;
+  onEvent?: (evt: EmittedEvent) => void;
+}
+
+export function render(
+  spec: ComponentSpec,
+  catalog: RegisteredCatalog,
+  options: RenderOptions = {}
+): HTMLElement {
+  validateSpec(spec, catalog);
+  const doc = options.doc ?? document;
+  const el = buildElement(spec, catalog, doc, '$', options.onEvent);
+  if (options.root) options.root.replaceChildren(el);
+  return el;
+}
+
+function buildElement(
+  spec: ComponentSpec,
+  catalog: RegisteredCatalog,
+  doc: Document,
+  path: string,
+  onEvent?: (evt: EmittedEvent) => void
+): HTMLElement {
+  const def = catalog.components.get(spec.component)!;
+  const propDefs = def.properties?.props?.properties ?? {};
+  const el = doc.createElement(spec.component);
+
+  if (spec.props) {
+    for (const [key, value] of Object.entries(spec.props)) {
+      applyProp(el, key, value, propDefs[key]);
+    }
+  }
+
+  if (spec.events && onEvent) {
+    for (const [evtName, binding] of Object.entries(spec.events)) {
+      attachEvent(el, spec.component, path, evtName, binding, onEvent);
+    }
+  }
+
+  if (spec.children) {
+    spec.children.forEach((child, i) => {
+      if (typeof child === 'string') {
+        el.appendChild(doc.createTextNode(child));
+        return;
+      }
+      el.appendChild(buildElement(child, catalog, doc, `${path}.children[${i}]`, onEvent));
+    });
+  }
+
+  if (spec.slots) {
+    for (const [slotName, children] of Object.entries(spec.slots)) {
+      children.forEach((child, i) => {
+        if (typeof child === 'string') {
+          if (slotName === 'default') {
+            el.appendChild(doc.createTextNode(child));
+          } else {
+            const wrap = doc.createElement('span');
+            wrap.setAttribute('slot', slotName);
+            wrap.textContent = child;
+            el.appendChild(wrap);
+          }
+          return;
+        }
+        const childEl = buildElement(
+          child,
+          catalog,
+          doc,
+          `${path}.slots.${slotName}[${i}]`,
+          onEvent
+        );
+        if (slotName !== 'default') childEl.setAttribute('slot', slotName);
+        el.appendChild(childEl);
+      });
+    }
+  }
+
+  return el;
+}
+
+function attachEvent(
+  el: HTMLElement,
+  component: string,
+  path: string,
+  eventName: string,
+  binding: EventBinding,
+  onEvent: (evt: EmittedEvent) => void
+): void {
+  const handler = typeof binding === 'string' ? binding : binding.handler;
+  const stop = typeof binding === 'object' && binding.stopPropagation === true;
+  const prevent = typeof binding === 'object' && binding.preventDefault === true;
+
+  el.addEventListener(eventName, (nativeEvent) => {
+    if (stop) nativeEvent.stopPropagation();
+    if (prevent) nativeEvent.preventDefault();
+    const detail = 'detail' in nativeEvent
+      ? (nativeEvent as CustomEvent).detail
+      : undefined;
+    onEvent({
+      component,
+      path,
+      event: eventName,
+      handler,
+      detail,
+      nativeEvent,
+    });
+  });
+}
+
+function applyProp(
+  el: HTMLElement,
+  key: string,
+  value: unknown,
+  schema: PropSchema | undefined
+): void {
+  if (value === undefined || value === null) return;
+
+  if (schema?.['x-kind'] === 'property') {
+    (el as unknown as Record<string, unknown>)[key] = value;
+    return;
+  }
+
+  if (typeof value === 'boolean') {
+    if (value) el.setAttribute(key, '');
+    else el.removeAttribute(key);
+    return;
+  }
+
+  if (Array.isArray(value) || (typeof value === 'object' && value !== null)) {
+    (el as unknown as Record<string, unknown>)[key] = value;
+    return;
+  }
+
+  if (schema && isComplexSchema(schema)) {
+    (el as unknown as Record<string, unknown>)[key] = value;
+    return;
+  }
+
+  el.setAttribute(key, String(value));
+}
+
+function isComplexSchema(schema: PropSchema): boolean {
+  const t = schema.type;
+  if (Array.isArray(t)) return t.some((x) => x === 'object' || x === 'array');
+  return t === 'object' || t === 'array';
+}