@triggerix-ai/component 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 imba97 <https://github.com/imba97>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";class ComponentDef{container;props;prompt;eventBindings=new Map;bind(e,n){return this.eventBindings.set(e,n),this}get events(){return[...this.eventBindings.values()]}}function defineAIComponent(t){return t}class ComponentRegistry{components=new Map;registerComponent(e){this.components.set(e.type,e)}use(e){for(const n of e)this.components.set(n.type,{type:n.type,label:n.label,description:n.description,props:n.props,container:n.container,prompt:n.prompt,events:n.events})}getComponent(e){return this.components.get(e)}getComponents(){return[...this.components.values()]}}function createComponentRegistry(){return new ComponentRegistry}class BaseRenderer{components=new ComponentRegistry;constructor(e={}){e.components?.length&&this.components.use(e.components)}}exports.BaseRenderer=BaseRenderer,exports.ComponentDef=ComponentDef,exports.ComponentRegistry=ComponentRegistry,exports.createComponentRegistry=createComponentRegistry,exports.defineAIComponent=defineAIComponent;

package/dist/index.d.cts

@@ -0,0 +1,164 @@
+/**
+ * Schema for a single component prop.
+ * Describes the shape of an AI-configurable prop without runtime behavior.
+ */
+interface ComponentPropSchema {
+    type: 'string' | 'number' | 'boolean' | 'object';
+    description?: string;
+    enum?: unknown[];
+    default?: unknown;
+    required?: boolean;
+}
+/**
+ * AI-facing metadata for a component.
+ * What the LLM sees and reasons about — no rendering concerns.
+ */
+interface AIComponentDef {
+    /** Unique component type identifier (e.g. `'button'`, `'input'`). */
+    type: string;
+    /** Human-readable label. */
+    label: string;
+    /** Description of what the component does, written for an LLM audience. */
+    description: string;
+    /** Triggerix event IDs this component can emit. */
+    events?: string[];
+    /** Per-prop schema. */
+    props?: Record<string, ComponentPropSchema>;
+    /** Whether this component can contain child components. */
+    container?: boolean;
+    /** Optional AI guidance. */
+    prompt?: string;
+}
+/**
+ * A component instance emitted by the AI.
+ *
+ * `name` is a semantic local identifier — unique within a single AI output,
+ * but not globally. Renderers scope names per mount so cross-turn reuse
+ * requires no random suffixes.
+ */
+interface ComponentInstance {
+    type: string;
+    name?: string;
+    props?: Record<string, unknown>;
+    children?: ComponentInstance[];
+}
+/**
+ * Callback for a component to emit a Triggerix event.
+ * The renderer's mount scope wires this to trigger evaluation.
+ */
+type EmitFn = (eventId: string, payload?: Record<string, unknown>) => void;
+/**
+ * Complete AI output — components to render plus triggers to bind.
+ * Kept loose-typed for `triggers` to avoid cross-package type coupling.
+ */
+interface AIOutput {
+    components: ComponentInstance[];
+    triggers: unknown[];
+}
+/**
+ * Lifecycle handle returned by `Renderer.mount()`.
+ */
+interface Scope {
+    /** Tear down DOM nodes, listeners, and references. */
+    unmount: () => void;
+}
+
+/**
+ * Abstract base class for a concrete component implementation.
+ *
+ * Concrete renderers (DOM / React / Vue) extend this and implement `create()`
+ * to produce the renderer's element type. The base class manages:
+ *
+ *  - AI-facing metadata (`type`, `label`, `description`, `props`, …)
+ *  - DOM-event → Triggerix-event ID bindings (e.g. `bind('click', 'button.click')`)
+ *  - The derived `events` list read by `ComponentRegistry.use()`
+ *
+ * Subclasses only need to implement `create()`.
+ */
+declare abstract class ComponentDef<T = unknown> {
+    abstract readonly type: string;
+    abstract readonly label: string;
+    abstract readonly description: string;
+    readonly container?: boolean;
+    readonly props?: Record<string, ComponentPropSchema>;
+    readonly prompt?: string;
+    /** domEvent → Triggerix eventId bindings (renderer-specific convention). */
+    protected readonly eventBindings: Map<string, string>;
+    /**
+     * Map a renderer-native event name to a Triggerix event ID.
+     * Chainable. Re-binding the same DOM event overrides.
+     */
+    bind(domEvent: string, eventId: string): this;
+    /** Triggerix event IDs declared via `bind()`. */
+    get events(): string[];
+    /**
+     * Build a renderer-native element for a given AI prop bag.
+     * Implementations should attach `emit` listeners for any bound DOM events.
+     */
+    abstract create(props: Record<string, unknown>, emit: EmitFn): T;
+}
+/**
+ * Identity helper for declaring pure AI metadata without a concrete implementation.
+ * Use when you only need to constrain what the AI can emit, with no renderer attached.
+ */
+declare function defineAIComponent(def: AIComponentDef): AIComponentDef;
+
+/**
+ * Shape accepted by `ComponentRegistry.use()`.
+ *
+ * Expressed in terms of `AIComponentDef` (minus `events`, which the renderer
+ * implementation provides via its `bind()` mappings) so the field set stays
+ * in lockstep with the AI metadata interface.
+ */
+type ComponentMetadataSource = Omit<AIComponentDef, 'events'> & {
+    events: string[];
+};
+/**
+ * Registry of AI-facing component metadata.
+ *
+ * Two registration paths:
+ *  - `registerComponent(def)` — register plain `AIComponentDef` (no implementation).
+ *  - `use(components)` — auto-extract AI metadata from concrete `ComponentDef` implementations.
+ */
+declare class ComponentRegistry {
+    private readonly components;
+    /** Register AI metadata directly. */
+    registerComponent(def: AIComponentDef): void;
+    /**
+     * Extract AI metadata from concrete `ComponentDef` implementations
+     * and register them. Equivalent to calling `registerComponent` for each
+     * with metadata pulled from the implementation.
+     */
+    use(components: ReadonlyArray<ComponentMetadataSource>): void;
+    getComponent(type: string): AIComponentDef | undefined;
+    getComponents(): AIComponentDef[];
+}
+/**
+ * Factory for ComponentRegistry.
+ */
+declare function createComponentRegistry(): ComponentRegistry;
+
+/**
+ * Renderer interface — turns AI output into renderer-native elements.
+ * Implementations live in downstream packages (e.g. `triggerix-ai-ui-native`).
+ */
+interface Renderer<T = unknown> {
+    mount: (output: AIOutput, container: T) => Scope;
+}
+/**
+ * Common base for renderers. Holds the component registry and accepts
+ * concrete `ComponentDef` instances in its constructor.
+ *
+ * Concrete renderers only need to implement `mount()` — the registry
+ * setup is handled here.
+ */
+declare abstract class BaseRenderer<T = unknown> implements Renderer<T> {
+    readonly components: ComponentRegistry;
+    constructor(options?: {
+        components?: ReadonlyArray<ComponentDef<unknown>>;
+    });
+    abstract mount(output: AIOutput, container: T): Scope;
+}
+
+export { BaseRenderer, ComponentDef, ComponentRegistry, createComponentRegistry, defineAIComponent };
+export type { AIComponentDef, AIOutput, ComponentInstance, ComponentPropSchema, EmitFn, Renderer, Scope };

package/dist/index.d.mts

@@ -0,0 +1,164 @@
+/**
+ * Schema for a single component prop.
+ * Describes the shape of an AI-configurable prop without runtime behavior.
+ */
+interface ComponentPropSchema {
+    type: 'string' | 'number' | 'boolean' | 'object';
+    description?: string;
+    enum?: unknown[];
+    default?: unknown;
+    required?: boolean;
+}
+/**
+ * AI-facing metadata for a component.
+ * What the LLM sees and reasons about — no rendering concerns.
+ */
+interface AIComponentDef {
+    /** Unique component type identifier (e.g. `'button'`, `'input'`). */
+    type: string;
+    /** Human-readable label. */
+    label: string;
+    /** Description of what the component does, written for an LLM audience. */
+    description: string;
+    /** Triggerix event IDs this component can emit. */
+    events?: string[];
+    /** Per-prop schema. */
+    props?: Record<string, ComponentPropSchema>;
+    /** Whether this component can contain child components. */
+    container?: boolean;
+    /** Optional AI guidance. */
+    prompt?: string;
+}
+/**
+ * A component instance emitted by the AI.
+ *
+ * `name` is a semantic local identifier — unique within a single AI output,
+ * but not globally. Renderers scope names per mount so cross-turn reuse
+ * requires no random suffixes.
+ */
+interface ComponentInstance {
+    type: string;
+    name?: string;
+    props?: Record<string, unknown>;
+    children?: ComponentInstance[];
+}
+/**
+ * Callback for a component to emit a Triggerix event.
+ * The renderer's mount scope wires this to trigger evaluation.
+ */
+type EmitFn = (eventId: string, payload?: Record<string, unknown>) => void;
+/**
+ * Complete AI output — components to render plus triggers to bind.
+ * Kept loose-typed for `triggers` to avoid cross-package type coupling.
+ */
+interface AIOutput {
+    components: ComponentInstance[];
+    triggers: unknown[];
+}
+/**
+ * Lifecycle handle returned by `Renderer.mount()`.
+ */
+interface Scope {
+    /** Tear down DOM nodes, listeners, and references. */
+    unmount: () => void;
+}
+
+/**
+ * Abstract base class for a concrete component implementation.
+ *
+ * Concrete renderers (DOM / React / Vue) extend this and implement `create()`
+ * to produce the renderer's element type. The base class manages:
+ *
+ *  - AI-facing metadata (`type`, `label`, `description`, `props`, …)
+ *  - DOM-event → Triggerix-event ID bindings (e.g. `bind('click', 'button.click')`)
+ *  - The derived `events` list read by `ComponentRegistry.use()`
+ *
+ * Subclasses only need to implement `create()`.
+ */
+declare abstract class ComponentDef<T = unknown> {
+    abstract readonly type: string;
+    abstract readonly label: string;
+    abstract readonly description: string;
+    readonly container?: boolean;
+    readonly props?: Record<string, ComponentPropSchema>;
+    readonly prompt?: string;
+    /** domEvent → Triggerix eventId bindings (renderer-specific convention). */
+    protected readonly eventBindings: Map<string, string>;
+    /**
+     * Map a renderer-native event name to a Triggerix event ID.
+     * Chainable. Re-binding the same DOM event overrides.
+     */
+    bind(domEvent: string, eventId: string): this;
+    /** Triggerix event IDs declared via `bind()`. */
+    get events(): string[];
+    /**
+     * Build a renderer-native element for a given AI prop bag.
+     * Implementations should attach `emit` listeners for any bound DOM events.
+     */
+    abstract create(props: Record<string, unknown>, emit: EmitFn): T;
+}
+/**
+ * Identity helper for declaring pure AI metadata without a concrete implementation.
+ * Use when you only need to constrain what the AI can emit, with no renderer attached.
+ */
+declare function defineAIComponent(def: AIComponentDef): AIComponentDef;
+
+/**
+ * Shape accepted by `ComponentRegistry.use()`.
+ *
+ * Expressed in terms of `AIComponentDef` (minus `events`, which the renderer
+ * implementation provides via its `bind()` mappings) so the field set stays
+ * in lockstep with the AI metadata interface.
+ */
+type ComponentMetadataSource = Omit<AIComponentDef, 'events'> & {
+    events: string[];
+};
+/**
+ * Registry of AI-facing component metadata.
+ *
+ * Two registration paths:
+ *  - `registerComponent(def)` — register plain `AIComponentDef` (no implementation).
+ *  - `use(components)` — auto-extract AI metadata from concrete `ComponentDef` implementations.
+ */
+declare class ComponentRegistry {
+    private readonly components;
+    /** Register AI metadata directly. */
+    registerComponent(def: AIComponentDef): void;
+    /**
+     * Extract AI metadata from concrete `ComponentDef` implementations
+     * and register them. Equivalent to calling `registerComponent` for each
+     * with metadata pulled from the implementation.
+     */
+    use(components: ReadonlyArray<ComponentMetadataSource>): void;
+    getComponent(type: string): AIComponentDef | undefined;
+    getComponents(): AIComponentDef[];
+}
+/**
+ * Factory for ComponentRegistry.
+ */
+declare function createComponentRegistry(): ComponentRegistry;
+
+/**
+ * Renderer interface — turns AI output into renderer-native elements.
+ * Implementations live in downstream packages (e.g. `triggerix-ai-ui-native`).
+ */
+interface Renderer<T = unknown> {
+    mount: (output: AIOutput, container: T) => Scope;
+}
+/**
+ * Common base for renderers. Holds the component registry and accepts
+ * concrete `ComponentDef` instances in its constructor.
+ *
+ * Concrete renderers only need to implement `mount()` — the registry
+ * setup is handled here.
+ */
+declare abstract class BaseRenderer<T = unknown> implements Renderer<T> {
+    readonly components: ComponentRegistry;
+    constructor(options?: {
+        components?: ReadonlyArray<ComponentDef<unknown>>;
+    });
+    abstract mount(output: AIOutput, container: T): Scope;
+}
+
+export { BaseRenderer, ComponentDef, ComponentRegistry, createComponentRegistry, defineAIComponent };
+export type { AIComponentDef, AIOutput, ComponentInstance, ComponentPropSchema, EmitFn, Renderer, Scope };

package/dist/index.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Schema for a single component prop.
+ * Describes the shape of an AI-configurable prop without runtime behavior.
+ */
+interface ComponentPropSchema {
+    type: 'string' | 'number' | 'boolean' | 'object';
+    description?: string;
+    enum?: unknown[];
+    default?: unknown;
+    required?: boolean;
+}
+/**
+ * AI-facing metadata for a component.
+ * What the LLM sees and reasons about — no rendering concerns.
+ */
+interface AIComponentDef {
+    /** Unique component type identifier (e.g. `'button'`, `'input'`). */
+    type: string;
+    /** Human-readable label. */
+    label: string;
+    /** Description of what the component does, written for an LLM audience. */
+    description: string;
+    /** Triggerix event IDs this component can emit. */
+    events?: string[];
+    /** Per-prop schema. */
+    props?: Record<string, ComponentPropSchema>;
+    /** Whether this component can contain child components. */
+    container?: boolean;
+    /** Optional AI guidance. */
+    prompt?: string;
+}
+/**
+ * A component instance emitted by the AI.
+ *
+ * `name` is a semantic local identifier — unique within a single AI output,
+ * but not globally. Renderers scope names per mount so cross-turn reuse
+ * requires no random suffixes.
+ */
+interface ComponentInstance {
+    type: string;
+    name?: string;
+    props?: Record<string, unknown>;
+    children?: ComponentInstance[];
+}
+/**
+ * Callback for a component to emit a Triggerix event.
+ * The renderer's mount scope wires this to trigger evaluation.
+ */
+type EmitFn = (eventId: string, payload?: Record<string, unknown>) => void;
+/**
+ * Complete AI output — components to render plus triggers to bind.
+ * Kept loose-typed for `triggers` to avoid cross-package type coupling.
+ */
+interface AIOutput {
+    components: ComponentInstance[];
+    triggers: unknown[];
+}
+/**
+ * Lifecycle handle returned by `Renderer.mount()`.
+ */
+interface Scope {
+    /** Tear down DOM nodes, listeners, and references. */
+    unmount: () => void;
+}
+
+/**
+ * Abstract base class for a concrete component implementation.
+ *
+ * Concrete renderers (DOM / React / Vue) extend this and implement `create()`
+ * to produce the renderer's element type. The base class manages:
+ *
+ *  - AI-facing metadata (`type`, `label`, `description`, `props`, …)
+ *  - DOM-event → Triggerix-event ID bindings (e.g. `bind('click', 'button.click')`)
+ *  - The derived `events` list read by `ComponentRegistry.use()`
+ *
+ * Subclasses only need to implement `create()`.
+ */
+declare abstract class ComponentDef<T = unknown> {
+    abstract readonly type: string;
+    abstract readonly label: string;
+    abstract readonly description: string;
+    readonly container?: boolean;
+    readonly props?: Record<string, ComponentPropSchema>;
+    readonly prompt?: string;
+    /** domEvent → Triggerix eventId bindings (renderer-specific convention). */
+    protected readonly eventBindings: Map<string, string>;
+    /**
+     * Map a renderer-native event name to a Triggerix event ID.
+     * Chainable. Re-binding the same DOM event overrides.
+     */
+    bind(domEvent: string, eventId: string): this;
+    /** Triggerix event IDs declared via `bind()`. */
+    get events(): string[];
+    /**
+     * Build a renderer-native element for a given AI prop bag.
+     * Implementations should attach `emit` listeners for any bound DOM events.
+     */
+    abstract create(props: Record<string, unknown>, emit: EmitFn): T;
+}
+/**
+ * Identity helper for declaring pure AI metadata without a concrete implementation.
+ * Use when you only need to constrain what the AI can emit, with no renderer attached.
+ */
+declare function defineAIComponent(def: AIComponentDef): AIComponentDef;
+
+/**
+ * Shape accepted by `ComponentRegistry.use()`.
+ *
+ * Expressed in terms of `AIComponentDef` (minus `events`, which the renderer
+ * implementation provides via its `bind()` mappings) so the field set stays
+ * in lockstep with the AI metadata interface.
+ */
+type ComponentMetadataSource = Omit<AIComponentDef, 'events'> & {
+    events: string[];
+};
+/**
+ * Registry of AI-facing component metadata.
+ *
+ * Two registration paths:
+ *  - `registerComponent(def)` — register plain `AIComponentDef` (no implementation).
+ *  - `use(components)` — auto-extract AI metadata from concrete `ComponentDef` implementations.
+ */
+declare class ComponentRegistry {
+    private readonly components;
+    /** Register AI metadata directly. */
+    registerComponent(def: AIComponentDef): void;
+    /**
+     * Extract AI metadata from concrete `ComponentDef` implementations
+     * and register them. Equivalent to calling `registerComponent` for each
+     * with metadata pulled from the implementation.
+     */
+    use(components: ReadonlyArray<ComponentMetadataSource>): void;
+    getComponent(type: string): AIComponentDef | undefined;
+    getComponents(): AIComponentDef[];
+}
+/**
+ * Factory for ComponentRegistry.
+ */
+declare function createComponentRegistry(): ComponentRegistry;
+
+/**
+ * Renderer interface — turns AI output into renderer-native elements.
+ * Implementations live in downstream packages (e.g. `triggerix-ai-ui-native`).
+ */
+interface Renderer<T = unknown> {
+    mount: (output: AIOutput, container: T) => Scope;
+}
+/**
+ * Common base for renderers. Holds the component registry and accepts
+ * concrete `ComponentDef` instances in its constructor.
+ *
+ * Concrete renderers only need to implement `mount()` — the registry
+ * setup is handled here.
+ */
+declare abstract class BaseRenderer<T = unknown> implements Renderer<T> {
+    readonly components: ComponentRegistry;
+    constructor(options?: {
+        components?: ReadonlyArray<ComponentDef<unknown>>;
+    });
+    abstract mount(output: AIOutput, container: T): Scope;
+}
+
+export { BaseRenderer, ComponentDef, ComponentRegistry, createComponentRegistry, defineAIComponent };
+export type { AIComponentDef, AIOutput, ComponentInstance, ComponentPropSchema, EmitFn, Renderer, Scope };

package/dist/index.mjs

@@ -0,0 +1 @@
+class s{container;props;prompt;eventBindings=new Map;bind(e,n){return this.eventBindings.set(e,n),this}get events(){return[...this.eventBindings.values()]}}function p(t){return t}class o{components=new Map;registerComponent(e){this.components.set(e.type,e)}use(e){for(const n of e)this.components.set(n.type,{type:n.type,label:n.label,description:n.description,props:n.props,container:n.container,prompt:n.prompt,events:n.events})}getComponent(e){return this.components.get(e)}getComponents(){return[...this.components.values()]}}function r(){return new o}class i{components=new o;constructor(e={}){e.components?.length&&this.components.use(e.components)}}export{i as BaseRenderer,s as ComponentDef,o as ComponentRegistry,r as createComponentRegistry,p as defineAIComponent};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@triggerix-ai/component",
+  "type": "module",
+  "version": "0.0.0",
+  "description": "Component protocol layer for Triggerix AI — AI metadata definitions, component registry, and renderer abstraction",
+  "license": "MIT",
+  "homepage": "https://github.com/triggerix-lang/triggerix-ai#readme",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:triggerix-lang/triggerix-ai.git",
+    "directory": "packages/component"
+  },
+  "bugs": {
+    "url": "https://github.com/triggerix-lang/triggerix-ai/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "unbuild": "^3.6.1"
+  },
+  "scripts": {
+    "stub": "unbuild --stub",
+    "build": "unbuild"
+  }
+}