@ai-gui/plugin-ui 0.4.0

package/dist/index.d.cts

@@ -0,0 +1,303 @@
+import MarkdownIt from "markdown-it";
+
+//#region ../core/dist/index.d.ts
+
+//#endregion
+//#region src/types.d.ts
+/** Framework-agnostic render node. */
+interface ASTNode {
+  key: string;
+  type: string;
+  tag?: string;
+  content?: string;
+  html?: string;
+  attrs?: Record<string, string>;
+  children?: ASTNode[];
+  /** Whether a streaming block has enough source to invoke its renderer. */
+  complete?: boolean;
+  /** card-specific payload */
+  card?: {
+    id?: string;
+    type: string;
+    data: unknown;
+    complete: boolean;
+    valid: boolean;
+  };
+}
+/** Patch event produced by diffing. */
+
+/** Framework-neutral render descriptor returned by plugin node renderers. */
+type RenderOutput = {
+  kind: "html";
+  html: string;
+} | {
+  kind: "element";
+  tag: string;
+  props?: Record<string, unknown>;
+  children?: RenderOutput[];
+} | {
+  kind: "card";
+  type: string;
+  data: unknown;
+} | {
+  kind: "mount";
+  mount: (el: HTMLElement, context: RenderMountContext) => void | (() => void);
+};
+interface MountCardSlotRequest {
+  type: string;
+  data: unknown;
+}
+interface MountedCardSlot {
+  update(data: unknown): void;
+  destroy(): void;
+}
+interface RenderMountContext {
+  mountCard?: (host: HTMLElement, request: MountCardSlotRequest) => MountedCardSlot | undefined;
+}
+type NodeRenderer = (node: ASTNode) => RenderOutput | Promise<RenderOutput>;
+interface PluginCommitContext {
+  readonly generation: number;
+  emitDebug(type: string, data?: Record<string, unknown>): void;
+}
+type KnownJSONSchemaType = "object" | "array" | "string" | "number" | "integer" | "boolean" | "null";
+interface JSONSchema {
+  type?: KnownJSONSchemaType | (string & {});
+  properties?: Record<string, JSONSchema>;
+  items?: JSONSchema;
+  required?: readonly string[];
+  additionalProperties?: boolean | JSONSchema;
+  enum?: readonly unknown[];
+  const?: unknown;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  minimum?: number;
+  maximum?: number;
+  minItems?: number;
+  maxItems?: number;
+  [k: string]: unknown;
+}
+interface CardDef<TData = unknown, TComponent = unknown> {
+  type: string;
+  description: string;
+  schema?: JSONSchema;
+  example?: TData;
+  render?: TComponent;
+  validate?: (data: TData) => boolean;
+}
+interface AIGuiPlugin {
+  name: string;
+  extendParser?: (md: MarkdownIt) => void;
+  cards?: CardDef[];
+  nodeRenderers?: Record<string, NodeRenderer>;
+  isBlockComplete?: (nodeType: string, raw: string) => boolean;
+  /** Runs synchronously after the AST is finalized and before patches are dispatched. */
+  onASTCommit?: (nodes: readonly ASTNode[], context: PluginCommitContext) => void;
+  css?: string;
+  /** LLM-facing guidance describing this plugin's fence syntax. */
+  promptSpec?: string | (() => string);
+}
+interface ActionRequest<TParams = unknown> {
+  type: string;
+  params: TParams;
+  cardType?: string;
+  cardId?: string;
+}
+interface ActionDispatchOptions {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  owner?: object;
+} //#endregion
+//#region src/types.d.ts
+type UIScalar = string | number | boolean | null;
+interface UIStateBinding {
+  $state: string;
+}
+type UIScalarExpression = UIScalar | UIStateBinding;
+type UIBoundJSON = UIScalarExpression | UIBoundJSON[] | {
+  [key: string]: UIBoundJSON;
+};
+type UIGap = "none" | "sm" | "md" | "lg";
+type UIAlign = "start" | "center" | "end" | "stretch";
+type UITextTone = "default" | "muted" | "positive" | "warning" | "critical";
+type UIFieldType = "text" | "textarea" | "number" | "date" | "select" | "checkbox" | "radio";
+interface UIAction {
+  type: string;
+  params?: UIBoundJSON;
+}
+interface UIOption {
+  label: string;
+  value: string;
+}
+interface UIKeyValueItem {
+  label: string;
+  value: UIScalarExpression;
+}
+interface UIStackNode {
+  kind: "stack";
+  id: string;
+  direction?: "row" | "column";
+  gap?: UIGap;
+  align?: UIAlign;
+  children: UINode[];
+}
+interface UIGridNode {
+  kind: "grid";
+  id: string;
+  columns: 1 | 2 | 3 | 4;
+  gap?: UIGap;
+  children: UINode[];
+}
+interface UITextNode {
+  kind: "text";
+  id: string;
+  text: UIScalarExpression;
+  tone?: UITextTone;
+}
+interface UIHeadingNode {
+  kind: "heading";
+  id: string;
+  level: 2 | 3 | 4;
+  text: UIScalarExpression;
+}
+interface UIDividerNode {
+  kind: "divider";
+  id: string;
+}
+interface UIListNode {
+  kind: "list";
+  id: string;
+  ordered?: boolean;
+  items: UIScalar[];
+}
+interface UITableNode {
+  kind: "table";
+  id: string;
+  caption: string;
+  headers: string[];
+  rows: UIScalar[][];
+}
+interface UIKeyValueNode {
+  kind: "keyValue";
+  id: string;
+  items: UIKeyValueItem[];
+}
+interface UIFormNode {
+  kind: "form";
+  id: string;
+  children: UINode[];
+  submit: {
+    type: string;
+  };
+  submitLabel?: string;
+}
+interface UIFieldNode {
+  kind: "field";
+  id: string;
+  bind: string;
+  fieldType: UIFieldType;
+  label: string;
+  required?: boolean;
+  placeholder?: string;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  min?: number;
+  max?: number;
+  options?: UIOption[];
+}
+interface UIButtonNode {
+  kind: "button";
+  id: string;
+  label: string;
+  variant?: "primary" | "secondary" | "danger";
+  action: UIAction;
+}
+interface UICardNode {
+  kind: "card";
+  id: string;
+  type: string;
+  data: UIBoundJSON;
+}
+type UINode = UIStackNode | UIGridNode | UITextNode | UIHeadingNode | UIDividerNode | UIListNode | UITableNode | UIKeyValueNode | UIFormNode | UIFieldNode | UIButtonNode | UICardNode;
+interface UIDocument {
+  version: 1;
+  id: string;
+  state?: Record<string, UIScalar>;
+  root: UINode;
+}
+interface UILimits {
+  sourceBytes: number;
+  nodes: number;
+  depth: number;
+  children: number;
+  state: number;
+  string: number;
+  totalStrings: number;
+  tableRows: number;
+  tableColumns: number;
+  options: number;
+  boundJSONDepth: number;
+  boundJSONNodes: number;
+}
+type UILimitOverrides = Partial<UILimits>;
+interface UIValidationOptions {
+  registry: UICardRegistry;
+  actionRuntime: UIActionRuntime;
+  limits?: UILimitOverrides;
+}
+interface UIMountOptions {
+  actionRuntime: UIActionRuntime;
+  mountContext?: RenderMountContext;
+}
+interface UIPluginOptions extends UIValidationOptions {}
+interface UICardRegistry {
+  get(type: string): Readonly<CardDef> | undefined;
+  list(): Readonly<CardDef>[];
+  validate(type: string, data: unknown): boolean;
+}
+interface UIActionRuntime {
+  hasAction(type: string): boolean;
+  listActionTypes(): readonly string[];
+  dispatch<TResult = unknown>(request: ActionRequest, options?: ActionDispatchOptions): Promise<TResult>;
+}
+
+//#endregion
+//#region src/css.d.ts
+declare const uiCss = "\n[data-aigui-ui] { display: block; color: inherit; font: inherit; }\n[data-aigui-ui-stack=\"row\"] { display: flex; flex-direction: row; flex-wrap: wrap; }\n[data-aigui-ui-stack=\"column\"] { display: flex; flex-direction: column; }\n[data-aigui-ui-grid] { display: grid; grid-template-columns: repeat(var(--aigui-ui-columns, 1), minmax(0, 1fr)); }\n[data-aigui-ui-grid=\"2\"] { --aigui-ui-columns: 2; }\n[data-aigui-ui-grid=\"3\"] { --aigui-ui-columns: 3; }\n[data-aigui-ui-grid=\"4\"] { --aigui-ui-columns: 4; }\n[data-gap=\"sm\"] { gap: .5rem; } [data-gap=\"md\"] { gap: 1rem; } [data-gap=\"lg\"] { gap: 1.5rem; }\n[data-align=\"start\"] { align-items: flex-start; } [data-align=\"center\"] { align-items: center; } [data-align=\"end\"] { align-items: flex-end; } [data-align=\"stretch\"] { align-items: stretch; }\n[data-tone=\"muted\"] { color: color-mix(in srgb, currentColor 60%, transparent); }\n[data-tone=\"positive\"] { color: #18794e; } [data-tone=\"warning\"] { color: #9a6700; } [data-tone=\"critical\"] { color: #b42318; }\n[data-aigui-ui] table { border-collapse: collapse; width: 100%; }\n[data-aigui-ui] th, [data-aigui-ui] td { border: 1px solid currentColor; padding: .4rem .6rem; text-align: left; }\n[data-aigui-ui-field] { display: grid; gap: .25rem; }\n[data-aigui-ui-field-error], [data-aigui-ui-action-error] { color: #b42318; }\n";
+
+//#endregion
+//#region src/errors.d.ts
+declare class UIDocumentError extends Error {
+  readonly issues: readonly string[];
+  constructor(issues: readonly string[]);
+}
+declare class UILimitError extends UIDocumentError {
+  constructor(message: string);
+}
+
+//#endregion
+//#region src/limits.d.ts
+declare const DEFAULT_UI_LIMITS: Readonly<UILimits>;
+declare function resolveUILimits(overrides?: UILimitOverrides): UILimits;
+
+//#endregion
+//#region src/mount.d.ts
+declare function mountUIDocument(host: HTMLElement, document: UIDocument, options: UIMountOptions): () => void;
+
+//#endregion
+//#region src/prompt.d.ts
+declare function uiPromptSpec(registry: UICardRegistry, actionRuntime: UIActionRuntime, limits?: UILimitOverrides): string;
+
+//#endregion
+//#region src/validate.d.ts
+declare function parseUIDocument(source: string, options: UIValidationOptions): UIDocument;
+declare function validateUIDocument(value: unknown, options: UIValidationOptions): UIDocument;
+declare function resolveBoundJSON(value: UIBoundJSON, state: Record<string, UIScalar>): unknown;
+
+//#endregion
+//#region src/index.d.ts
+declare function ui(options: UIPluginOptions): AIGuiPlugin;
+
+//#endregion
+export { DEFAULT_UI_LIMITS, UIAction, UIActionRuntime, UIAlign, UIBoundJSON, UIButtonNode, UICardNode, UICardRegistry, UIDividerNode, UIDocument, UIDocumentError, UIFieldNode, UIFieldType, UIFormNode, UIGap, UIGridNode, UIHeadingNode, UIKeyValueItem, UIKeyValueNode, UILimitError, UILimitOverrides, UILimits, UIListNode, UIMountOptions, UINode, UIOption, UIPluginOptions, UIScalar, UIScalarExpression, UIStackNode, UIStateBinding, UITableNode, UITextNode, UITextTone, UIValidationOptions, mountUIDocument, parseUIDocument, resolveBoundJSON, resolveUILimits, ui, uiCss, uiPromptSpec, validateUIDocument };

package/dist/index.d.ts

@@ -0,0 +1,303 @@
+import MarkdownIt from "markdown-it";
+
+//#region ../core/dist/index.d.ts
+
+//#endregion
+//#region src/types.d.ts
+/** Framework-agnostic render node. */
+interface ASTNode {
+  key: string;
+  type: string;
+  tag?: string;
+  content?: string;
+  html?: string;
+  attrs?: Record<string, string>;
+  children?: ASTNode[];
+  /** Whether a streaming block has enough source to invoke its renderer. */
+  complete?: boolean;
+  /** card-specific payload */
+  card?: {
+    id?: string;
+    type: string;
+    data: unknown;
+    complete: boolean;
+    valid: boolean;
+  };
+}
+/** Patch event produced by diffing. */
+
+/** Framework-neutral render descriptor returned by plugin node renderers. */
+type RenderOutput = {
+  kind: "html";
+  html: string;
+} | {
+  kind: "element";
+  tag: string;
+  props?: Record<string, unknown>;
+  children?: RenderOutput[];
+} | {
+  kind: "card";
+  type: string;
+  data: unknown;
+} | {
+  kind: "mount";
+  mount: (el: HTMLElement, context: RenderMountContext) => void | (() => void);
+};
+interface MountCardSlotRequest {
+  type: string;
+  data: unknown;
+}
+interface MountedCardSlot {
+  update(data: unknown): void;
+  destroy(): void;
+}
+interface RenderMountContext {
+  mountCard?: (host: HTMLElement, request: MountCardSlotRequest) => MountedCardSlot | undefined;
+}
+type NodeRenderer = (node: ASTNode) => RenderOutput | Promise<RenderOutput>;
+interface PluginCommitContext {
+  readonly generation: number;
+  emitDebug(type: string, data?: Record<string, unknown>): void;
+}
+type KnownJSONSchemaType = "object" | "array" | "string" | "number" | "integer" | "boolean" | "null";
+interface JSONSchema {
+  type?: KnownJSONSchemaType | (string & {});
+  properties?: Record<string, JSONSchema>;
+  items?: JSONSchema;
+  required?: readonly string[];
+  additionalProperties?: boolean | JSONSchema;
+  enum?: readonly unknown[];
+  const?: unknown;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  minimum?: number;
+  maximum?: number;
+  minItems?: number;
+  maxItems?: number;
+  [k: string]: unknown;
+}
+interface CardDef<TData = unknown, TComponent = unknown> {
+  type: string;
+  description: string;
+  schema?: JSONSchema;
+  example?: TData;
+  render?: TComponent;
+  validate?: (data: TData) => boolean;
+}
+interface AIGuiPlugin {
+  name: string;
+  extendParser?: (md: MarkdownIt) => void;
+  cards?: CardDef[];
+  nodeRenderers?: Record<string, NodeRenderer>;
+  isBlockComplete?: (nodeType: string, raw: string) => boolean;
+  /** Runs synchronously after the AST is finalized and before patches are dispatched. */
+  onASTCommit?: (nodes: readonly ASTNode[], context: PluginCommitContext) => void;
+  css?: string;
+  /** LLM-facing guidance describing this plugin's fence syntax. */
+  promptSpec?: string | (() => string);
+}
+interface ActionRequest<TParams = unknown> {
+  type: string;
+  params: TParams;
+  cardType?: string;
+  cardId?: string;
+}
+interface ActionDispatchOptions {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  owner?: object;
+} //#endregion
+//#region src/types.d.ts
+type UIScalar = string | number | boolean | null;
+interface UIStateBinding {
+  $state: string;
+}
+type UIScalarExpression = UIScalar | UIStateBinding;
+type UIBoundJSON = UIScalarExpression | UIBoundJSON[] | {
+  [key: string]: UIBoundJSON;
+};
+type UIGap = "none" | "sm" | "md" | "lg";
+type UIAlign = "start" | "center" | "end" | "stretch";
+type UITextTone = "default" | "muted" | "positive" | "warning" | "critical";
+type UIFieldType = "text" | "textarea" | "number" | "date" | "select" | "checkbox" | "radio";
+interface UIAction {
+  type: string;
+  params?: UIBoundJSON;
+}
+interface UIOption {
+  label: string;
+  value: string;
+}
+interface UIKeyValueItem {
+  label: string;
+  value: UIScalarExpression;
+}
+interface UIStackNode {
+  kind: "stack";
+  id: string;
+  direction?: "row" | "column";
+  gap?: UIGap;
+  align?: UIAlign;
+  children: UINode[];
+}
+interface UIGridNode {
+  kind: "grid";
+  id: string;
+  columns: 1 | 2 | 3 | 4;
+  gap?: UIGap;
+  children: UINode[];
+}
+interface UITextNode {
+  kind: "text";
+  id: string;
+  text: UIScalarExpression;
+  tone?: UITextTone;
+}
+interface UIHeadingNode {
+  kind: "heading";
+  id: string;
+  level: 2 | 3 | 4;
+  text: UIScalarExpression;
+}
+interface UIDividerNode {
+  kind: "divider";
+  id: string;
+}
+interface UIListNode {
+  kind: "list";
+  id: string;
+  ordered?: boolean;
+  items: UIScalar[];
+}
+interface UITableNode {
+  kind: "table";
+  id: string;
+  caption: string;
+  headers: string[];
+  rows: UIScalar[][];
+}
+interface UIKeyValueNode {
+  kind: "keyValue";
+  id: string;
+  items: UIKeyValueItem[];
+}
+interface UIFormNode {
+  kind: "form";
+  id: string;
+  children: UINode[];
+  submit: {
+    type: string;
+  };
+  submitLabel?: string;
+}
+interface UIFieldNode {
+  kind: "field";
+  id: string;
+  bind: string;
+  fieldType: UIFieldType;
+  label: string;
+  required?: boolean;
+  placeholder?: string;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  min?: number;
+  max?: number;
+  options?: UIOption[];
+}
+interface UIButtonNode {
+  kind: "button";
+  id: string;
+  label: string;
+  variant?: "primary" | "secondary" | "danger";
+  action: UIAction;
+}
+interface UICardNode {
+  kind: "card";
+  id: string;
+  type: string;
+  data: UIBoundJSON;
+}
+type UINode = UIStackNode | UIGridNode | UITextNode | UIHeadingNode | UIDividerNode | UIListNode | UITableNode | UIKeyValueNode | UIFormNode | UIFieldNode | UIButtonNode | UICardNode;
+interface UIDocument {
+  version: 1;
+  id: string;
+  state?: Record<string, UIScalar>;
+  root: UINode;
+}
+interface UILimits {
+  sourceBytes: number;
+  nodes: number;
+  depth: number;
+  children: number;
+  state: number;
+  string: number;
+  totalStrings: number;
+  tableRows: number;
+  tableColumns: number;
+  options: number;
+  boundJSONDepth: number;
+  boundJSONNodes: number;
+}
+type UILimitOverrides = Partial<UILimits>;
+interface UIValidationOptions {
+  registry: UICardRegistry;
+  actionRuntime: UIActionRuntime;
+  limits?: UILimitOverrides;
+}
+interface UIMountOptions {
+  actionRuntime: UIActionRuntime;
+  mountContext?: RenderMountContext;
+}
+interface UIPluginOptions extends UIValidationOptions {}
+interface UICardRegistry {
+  get(type: string): Readonly<CardDef> | undefined;
+  list(): Readonly<CardDef>[];
+  validate(type: string, data: unknown): boolean;
+}
+interface UIActionRuntime {
+  hasAction(type: string): boolean;
+  listActionTypes(): readonly string[];
+  dispatch<TResult = unknown>(request: ActionRequest, options?: ActionDispatchOptions): Promise<TResult>;
+}
+
+//#endregion
+//#region src/css.d.ts
+declare const uiCss = "\n[data-aigui-ui] { display: block; color: inherit; font: inherit; }\n[data-aigui-ui-stack=\"row\"] { display: flex; flex-direction: row; flex-wrap: wrap; }\n[data-aigui-ui-stack=\"column\"] { display: flex; flex-direction: column; }\n[data-aigui-ui-grid] { display: grid; grid-template-columns: repeat(var(--aigui-ui-columns, 1), minmax(0, 1fr)); }\n[data-aigui-ui-grid=\"2\"] { --aigui-ui-columns: 2; }\n[data-aigui-ui-grid=\"3\"] { --aigui-ui-columns: 3; }\n[data-aigui-ui-grid=\"4\"] { --aigui-ui-columns: 4; }\n[data-gap=\"sm\"] { gap: .5rem; } [data-gap=\"md\"] { gap: 1rem; } [data-gap=\"lg\"] { gap: 1.5rem; }\n[data-align=\"start\"] { align-items: flex-start; } [data-align=\"center\"] { align-items: center; } [data-align=\"end\"] { align-items: flex-end; } [data-align=\"stretch\"] { align-items: stretch; }\n[data-tone=\"muted\"] { color: color-mix(in srgb, currentColor 60%, transparent); }\n[data-tone=\"positive\"] { color: #18794e; } [data-tone=\"warning\"] { color: #9a6700; } [data-tone=\"critical\"] { color: #b42318; }\n[data-aigui-ui] table { border-collapse: collapse; width: 100%; }\n[data-aigui-ui] th, [data-aigui-ui] td { border: 1px solid currentColor; padding: .4rem .6rem; text-align: left; }\n[data-aigui-ui-field] { display: grid; gap: .25rem; }\n[data-aigui-ui-field-error], [data-aigui-ui-action-error] { color: #b42318; }\n";
+
+//#endregion
+//#region src/errors.d.ts
+declare class UIDocumentError extends Error {
+  readonly issues: readonly string[];
+  constructor(issues: readonly string[]);
+}
+declare class UILimitError extends UIDocumentError {
+  constructor(message: string);
+}
+
+//#endregion
+//#region src/limits.d.ts
+declare const DEFAULT_UI_LIMITS: Readonly<UILimits>;
+declare function resolveUILimits(overrides?: UILimitOverrides): UILimits;
+
+//#endregion
+//#region src/mount.d.ts
+declare function mountUIDocument(host: HTMLElement, document: UIDocument, options: UIMountOptions): () => void;
+
+//#endregion
+//#region src/prompt.d.ts
+declare function uiPromptSpec(registry: UICardRegistry, actionRuntime: UIActionRuntime, limits?: UILimitOverrides): string;
+
+//#endregion
+//#region src/validate.d.ts
+declare function parseUIDocument(source: string, options: UIValidationOptions): UIDocument;
+declare function validateUIDocument(value: unknown, options: UIValidationOptions): UIDocument;
+declare function resolveBoundJSON(value: UIBoundJSON, state: Record<string, UIScalar>): unknown;
+
+//#endregion
+//#region src/index.d.ts
+declare function ui(options: UIPluginOptions): AIGuiPlugin;
+
+//#endregion
+export { DEFAULT_UI_LIMITS, UIAction, UIActionRuntime, UIAlign, UIBoundJSON, UIButtonNode, UICardNode, UICardRegistry, UIDividerNode, UIDocument, UIDocumentError, UIFieldNode, UIFieldType, UIFormNode, UIGap, UIGridNode, UIHeadingNode, UIKeyValueItem, UIKeyValueNode, UILimitError, UILimitOverrides, UILimits, UIListNode, UIMountOptions, UINode, UIOption, UIPluginOptions, UIScalar, UIScalarExpression, UIStackNode, UIStateBinding, UITableNode, UITextNode, UITextTone, UIValidationOptions, mountUIDocument, parseUIDocument, resolveBoundJSON, resolveUILimits, ui, uiCss, uiPromptSpec, validateUIDocument };