@iyulab/u-widgets 0.4.1

package/dist/u-widgets-forms.d.ts

@@ -0,0 +1,81 @@
+/** Supported input field types for form widgets. */
+declare type FieldType = 'text' | 'email' | 'password' | 'tel' | 'url' | 'textarea' | 'number' | 'select' | 'multiselect' | 'date' | 'datetime' | 'time' | 'toggle' | 'range' | 'radio' | 'checkbox';
+
+declare interface FormdownField {
+    name: string;
+    type: string;
+    label?: string;
+    required?: boolean;
+    placeholder?: string;
+    options?: string[];
+    attributes?: Record<string, string>;
+}
+
+export declare function mapActions(actions: FormdownField[]): UWidgetAction[];
+
+export declare function mapFields(fields: FormdownField[]): UWidgetFieldDefinition[];
+
+/**
+ * Action button definition.
+ *
+ * Reserved actions: `"submit"`, `"cancel"`, `"navigate"`.
+ * Custom action strings are forwarded to the host via the `u-widget-event`.
+ *
+ * @example
+ * ```json
+ * { "label": "Submit", "action": "submit", "style": "primary" }
+ * ```
+ */
+declare interface UWidgetAction {
+    /** Button display text. */
+    label: string;
+    /** Action identifier emitted in the widget event. */
+    action: string;
+    /** Visual style hint. */
+    style?: 'primary' | 'danger' | 'default';
+    /** Whether the button is disabled. */
+    disabled?: boolean;
+    /** URL for `"navigate"` actions. */
+    url?: string;
+}
+
+/**
+ * Field definition for form/confirm input widgets.
+ *
+ * @example
+ * ```json
+ * { "field": "email", "label": "Email", "type": "email", "required": true }
+ * ```
+ */
+declare interface UWidgetFieldDefinition {
+    /** Data field name (maps to `data[field]` for defaults and output). */
+    field: string;
+    /** Display label. Defaults to the field name. */
+    label?: string;
+    /** Input type. Defaults to `"text"`. */
+    type?: FieldType;
+    /** Whether the field must be filled before submit. */
+    required?: boolean;
+    /** Placeholder text shown when the field is empty. */
+    placeholder?: string;
+    /** Options for select, multiselect, radio, and checkbox types. */
+    options?: string[];
+    /** Minimum character length for text inputs. */
+    minLength?: number;
+    /** Maximum character length for text inputs. */
+    maxLength?: number;
+    /** Custom regex pattern for validation (e.g. `"^[A-Z]{3}$"`). */
+    pattern?: string;
+    /** Number of visible rows for textarea type. */
+    rows?: number;
+    /** Minimum value (number) or date string. */
+    min?: number | string;
+    /** Maximum value (number) or date string. */
+    max?: number | string;
+    /** Step increment for number and range inputs. */
+    step?: number;
+    /** Custom validation error message (overrides locale default). */
+    message?: string;
+}
+
+export { }

package/dist/u-widgets-forms.js

@@ -0,0 +1,59 @@
+import { FormManager as n } from "@formdown/core/form-manager";
+import { r as a } from "./formdown-BWJ6QGJs.js";
+const l = {
+  text: "text",
+  email: "email",
+  password: "password",
+  tel: "tel",
+  url: "url",
+  textarea: "textarea",
+  number: "number",
+  select: "select",
+  multiselect: "multiselect",
+  date: "date",
+  datetime: "datetime",
+  "datetime-local": "datetime",
+  time: "time",
+  toggle: "toggle",
+  range: "range",
+  radio: "radio",
+  checkbox: "checkbox"
+};
+function m(i) {
+  return l[i] ?? "text";
+}
+function o(i) {
+  return i.map((e) => {
+    const t = {
+      field: e.name,
+      type: m(e.type)
+    };
+    if (e.label && (t.label = e.label), e.required && (t.required = !0), e.placeholder && (t.placeholder = e.placeholder), e.options && e.options.length > 0 && (t.options = e.options), e.attributes) {
+      const r = e.attributes;
+      r.min != null && (t.min = isNaN(Number(r.min)) ? r.min : Number(r.min)), r.max != null && (t.max = isNaN(Number(r.max)) ? r.max : Number(r.max)), r.step != null && (t.step = Number(r.step)), r.maxlength != null && (t.maxLength = Number(r.maxlength)), r.rows != null && (t.rows = Number(r.rows));
+    }
+    return t;
+  });
+}
+function s(i) {
+  return i.map((e) => {
+    const t = {
+      action: e.name === "reset" ? "cancel" : e.name,
+      label: e.label || e.name
+    };
+    return e.name === "submit" ? t.style = "primary" : e.name === "reset" && (t.style = "default"), t;
+  });
+}
+function u(i, e) {
+  const t = new n();
+  return t.parse(i), e && t.setDefaults(e), {
+    fields: o(t.getInputFields()),
+    actions: s(t.getActions())
+  };
+}
+a(u);
+export {
+  s as mapActions,
+  o as mapFields
+};
+//# sourceMappingURL=u-widgets-forms.js.map

package/dist/u-widgets-forms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"u-widgets-forms.js","sources":["../src/adapters/formdown-adapter.ts","../src/forms.ts"],"sourcesContent":["// @formdown/core Field → u-widgets type adapter\n// Uses structural typing so @formdown/core install is not required at compile time.\n\nimport type { UWidgetFieldDefinition, UWidgetAction, FieldType } from '../core/types.js';\n\n// Structural interface matching @formdown/core Field shape\nexport interface FormdownField {\n  name: string;\n  type: string;\n  label?: string;\n  required?: boolean;\n  placeholder?: string;\n  options?: string[];\n  attributes?: Record<string, string>;\n}\n\nconst FIELD_TYPE_MAP: Record<string, FieldType> = {\n  text: 'text',\n  email: 'email',\n  password: 'password',\n  tel: 'tel',\n  url: 'url',\n  textarea: 'textarea',\n  number: 'number',\n  select: 'select',\n  multiselect: 'multiselect',\n  date: 'date',\n  datetime: 'datetime',\n  'datetime-local': 'datetime',\n  time: 'time',\n  toggle: 'toggle',\n  range: 'range',\n  radio: 'radio',\n  checkbox: 'checkbox',\n};\n\nexport function mapFieldType(type: string): FieldType {\n  return FIELD_TYPE_MAP[type] ?? 'text';\n}\n\nexport function mapFields(fields: FormdownField[]): UWidgetFieldDefinition[] {\n  return fields.map((f) => {\n    const def: UWidgetFieldDefinition = {\n      field: f.name,\n      type: mapFieldType(f.type),\n    };\n    if (f.label) def.label = f.label;\n    if (f.required) def.required = true;\n    if (f.placeholder) def.placeholder = f.placeholder;\n    if (f.options && f.options.length > 0) def.options = f.options;\n\n    // Extract numeric/string attributes\n    if (f.attributes) {\n      const a = f.attributes;\n      if (a.min != null) def.min = isNaN(Number(a.min)) ? a.min : Number(a.min);\n      if (a.max != null) def.max = isNaN(Number(a.max)) ? a.max : Number(a.max);\n      if (a.step != null) def.step = Number(a.step);\n      if (a.maxlength != null) def.maxLength = Number(a.maxlength);\n      if (a.rows != null) def.rows = Number(a.rows);\n    }\n\n    return def;\n  });\n}\n\nexport function mapActions(actions: FormdownField[]): UWidgetAction[] {\n  return actions.map((a) => {\n    const action: UWidgetAction = {\n      action: a.name === 'reset' ? 'cancel' : a.name,\n      label: a.label || a.name,\n    };\n    if (a.name === 'submit') action.style = 'primary';\n    else if (a.name === 'reset') action.style = 'default';\n    return action;\n  });\n}\n","/**\n * @module u-widgets/forms\n *\n * Integration entry point for `@formdown/core`. Import this module to replace\n * the built-in formdown parser with the full `@formdown/core` parser, enabling\n * richer form syntax support.\n *\n * @example\n * ```ts\n * import 'u-widgets';\n * import 'u-widgets/forms';\n *\n * el.spec = { widget: 'form', formdown: '@name*(Name): []\\\\n@email: @[]' };\n * ```\n */\n\nimport { FormManager } from '@formdown/core/form-manager';\nimport { registerFormdownParser } from './core/formdown.js';\nimport { mapFields, mapActions } from './adapters/formdown-adapter.js';\nimport type { FormdownResult } from './core/formdown.js';\n\nfunction parseWithFormdownCore(input: string, data?: Record<string, unknown>): FormdownResult {\n  const fm = new FormManager();\n  fm.parse(input);\n  if (data) fm.setDefaults(data);\n  return {\n    fields: mapFields(fm.getInputFields()),\n    actions: mapActions(fm.getActions()),\n  };\n}\n\nregisterFormdownParser(parseWithFormdownCore);\n\nexport { mapFields, mapActions } from './adapters/formdown-adapter.js';\n"],"names":["FIELD_TYPE_MAP","mapFieldType","type","mapFields","fields","f","def","a","mapActions","actions","action","parseWithFormdownCore","input","data","fm","FormManager","registerFormdownParser"],"mappings":";;AAgBA,MAAMA,IAA4C;AAAA,EAChD,MAAM;AAAA,EACN,OAAO;AAAA,EACP,UAAU;AAAA,EACV,KAAK;AAAA,EACL,KAAK;AAAA,EACL,UAAU;AAAA,EACV,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,aAAa;AAAA,EACb,MAAM;AAAA,EACN,UAAU;AAAA,EACV,kBAAkB;AAAA,EAClB,MAAM;AAAA,EACN,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,OAAO;AAAA,EACP,UAAU;AACZ;AAEO,SAASC,EAAaC,GAAyB;AACpD,SAAOF,EAAeE,CAAI,KAAK;AACjC;AAEO,SAASC,EAAUC,GAAmD;AAC3E,SAAOA,EAAO,IAAI,CAACC,MAAM;AACvB,UAAMC,IAA8B;AAAA,MAClC,OAAOD,EAAE;AAAA,MACT,MAAMJ,EAAaI,EAAE,IAAI;AAAA,IAAA;AAQ3B,QANIA,EAAE,UAAOC,EAAI,QAAQD,EAAE,QACvBA,EAAE,aAAUC,EAAI,WAAW,KAC3BD,EAAE,gBAAaC,EAAI,cAAcD,EAAE,cACnCA,EAAE,WAAWA,EAAE,QAAQ,SAAS,MAAGC,EAAI,UAAUD,EAAE,UAGnDA,EAAE,YAAY;AAChB,YAAME,IAAIF,EAAE;AACZ,MAAIE,EAAE,OAAO,SAAMD,EAAI,MAAM,MAAM,OAAOC,EAAE,GAAG,CAAC,IAAIA,EAAE,MAAM,OAAOA,EAAE,GAAG,IACpEA,EAAE,OAAO,SAAMD,EAAI,MAAM,MAAM,OAAOC,EAAE,GAAG,CAAC,IAAIA,EAAE,MAAM,OAAOA,EAAE,GAAG,IACpEA,EAAE,QAAQ,WAAU,OAAO,OAAOA,EAAE,IAAI,IACxCA,EAAE,aAAa,WAAU,YAAY,OAAOA,EAAE,SAAS,IACvDA,EAAE,QAAQ,WAAU,OAAO,OAAOA,EAAE,IAAI;AAAA,IAC9C;AAEA,WAAOD;AAAA,EACT,CAAC;AACH;AAEO,SAASE,EAAWC,GAA2C;AACpE,SAAOA,EAAQ,IAAI,CAACF,MAAM;AACxB,UAAMG,IAAwB;AAAA,MAC5B,QAAQH,EAAE,SAAS,UAAU,WAAWA,EAAE;AAAA,MAC1C,OAAOA,EAAE,SAASA,EAAE;AAAA,IAAA;AAEtB,WAAIA,EAAE,SAAS,WAAUG,EAAO,QAAQ,YAC/BH,EAAE,SAAS,YAASG,EAAO,QAAQ,YACrCA;AAAA,EACT,CAAC;AACH;ACtDA,SAASC,EAAsBC,GAAeC,GAAgD;AAC5F,QAAMC,IAAK,IAAIC,EAAA;AACf,SAAAD,EAAG,MAAMF,CAAK,GACVC,KAAMC,EAAG,YAAYD,CAAI,GACtB;AAAA,IACL,QAAQV,EAAUW,EAAG,gBAAgB;AAAA,IACrC,SAASN,EAAWM,EAAG,WAAA,CAAY;AAAA,EAAA;AAEvC;AAEAE,EAAuBL,CAAqB;"}

package/dist/u-widgets-tools.d.ts

@@ -0,0 +1,400 @@
+/** Action property descriptions (from schema $defs/action). */
+export declare const ACTION_PROP_DOCS: Readonly<Record<string, string>>;
+
+/**
+ * Generate a complete spec suggestion from data.
+ *
+ * Convenience wrapper: picks the top suggestion and returns a ready-to-use spec.
+ *
+ * @param data - The data to analyze.
+ * @returns A complete spec, or `undefined` if no suggestion could be made.
+ */
+export declare function autoSpec(data: Record<string, unknown> | Record<string, unknown>[]): UWidgetSpec | undefined;
+
+/**
+ * Well-known data field descriptions.
+ * Unlike schema-bound registries, these cover common keys used across widgets.
+ * Not enforced by schema tests — new keys appear with type only until added here.
+ */
+export declare const DATA_FIELD_DOCS: Readonly<Record<string, string>>;
+
+/** Data field descriptor for well-known widget data properties. */
+export declare interface DataFieldInfo {
+    readonly key: string;
+    readonly type: string;
+    readonly desc: string;
+    readonly required?: boolean;
+}
+
+/** Field definition property descriptions (from schema $defs/fieldDefinition). */
+export declare const FIELD_PROP_DOCS: Readonly<Record<string, string>>;
+
+/** Supported input field types for form widgets. */
+declare type FieldType = 'text' | 'email' | 'password' | 'tel' | 'url' | 'textarea' | 'number' | 'select' | 'multiselect' | 'date' | 'datetime' | 'time' | 'toggle' | 'range' | 'radio' | 'checkbox';
+
+/** Get the event types emitted by a widget. Resolves `chart.*` → `chart`. */
+export declare function getWidgetEvents(widget: string): readonly string[];
+
+/**
+ * Get the widget catalog.
+ *
+ * - No argument → list all widgets (`WidgetInfo[]`).
+ * - Exact widget name → full detail (`WidgetDetail`).
+ * - Category or prefix → filtered list (`WidgetInfo[]`).
+ *
+ * @example
+ * ```ts
+ * help()              // → all widget descriptions
+ * help('chart')       // → all chart types (WidgetInfo[])
+ * help('chart.bar')   // → full detail (WidgetDetail)
+ * ```
+ */
+export declare function help(): WidgetInfo[];
+
+export declare function help(widget: string): WidgetInfo[] | WidgetDetail;
+
+/** Mapping key descriptions (from schema $defs/mapping.properties). */
+export declare const MAPPING_DOCS: Readonly<Record<string, string>>;
+
+/** A widget + mapping recommendation. */
+export declare interface MappingSuggestion {
+    /** Recommended widget type. */
+    widget: string;
+    /** Suggested mapping for the widget. */
+    mapping?: UWidgetMapping;
+    /** Confidence score (0–1). Higher means better fit. */
+    confidence: number;
+    /** Human-readable reason for this suggestion. */
+    reason: string;
+}
+
+/**
+ * Well-known options descriptions.
+ * Covers widget-specific rendering options used across the catalog.
+ */
+export declare const OPTION_DOCS: Readonly<Record<string, string>>;
+
+/**
+ * Runtime spec scanner that extracts the full property surface from widget specs.
+ *
+ * `specSurface()` is the single function shared by both the MCP server and
+ * the demo props panel — it scans an array of spec objects and returns every
+ * key actually used, merged with descriptions from `widget-meta.ts`.
+ *
+ * Structural guarantee: if a spec uses a property, `specSurface()` reports it.
+ */
+/** A single discovered property with its inferred type and optional description. */
+export declare interface PropInfo {
+    key: string;
+    /** Inferred runtime type: `"number"`, `"string"`, `"boolean"`, `"object[]"`, etc. */
+    type: string;
+    /** Description from the registry when available. */
+    desc?: string;
+}
+
+/** The full property surface extracted from a set of specs. */
+export declare interface SpecSurface {
+    /** Top-level spec keys used (data, mapping, options, …). */
+    specKeys: string[];
+    /** `data.*` keys with inferred types. */
+    dataFields: PropInfo[];
+    /** `mapping.*` keys with schema descriptions. */
+    mappingKeys: PropInfo[];
+    /** `options.*` keys with inferred types. */
+    optionKeys: PropInfo[];
+    /** `fields[].*` keys with schema descriptions. */
+    fieldProps: PropInfo[];
+    /** Distinct `fields[].type` values used. */
+    fieldTypes: string[];
+    /** Distinct `actions[].style` values used. */
+    actionStyles: string[];
+    /** Events emitted by this widget category. */
+    events: readonly string[];
+}
+
+/**
+ * Scan an array of spec objects and collect their full property surface.
+ *
+ * @param specs  - Array of widget spec objects (e.g. variant values).
+ * @param widget - Optional widget type string for event lookup.
+ * @returns The collected {@link SpecSurface}.
+ */
+export declare function specSurface(specs: object[], widget?: string): SpecSurface;
+
+/**
+ * Suggest widget type and mapping from data alone.
+ *
+ * Analyzes data structure (keys, types, shape) and returns
+ * ranked suggestions. If a widget type is provided, only suggests
+ * a mapping for that specific widget.
+ *
+ * @param data - The data to analyze (object or array of records).
+ * @param widget - Optional widget type to constrain the suggestion.
+ * @returns Array of suggestions sorted by confidence (highest first).
+ *
+ * @example
+ * ```ts
+ * suggestMapping([{ name: 'A', value: 30 }, { name: 'B', value: 70 }])
+ * // → [{ widget: 'chart.bar', mapping: { x: 'name', y: 'value' }, confidence: 0.9, ... }, ...]
+ * ```
+ */
+export declare function suggestMapping(data: Record<string, unknown> | Record<string, unknown>[], widget?: string): MappingSuggestion[];
+
+/**
+ * Generate a minimal template spec for a widget type.
+ *
+ * Returns a complete, valid spec with sample data that can be
+ * used as a starting point. Returns `undefined` for unknown types.
+ *
+ * @param widget - Widget type identifier (e.g., `"chart.bar"`, `"metric"`).
+ * @returns A deep-copied template spec, or `undefined`.
+ *
+ * @example
+ * ```ts
+ * template('metric')
+ * // → { widget: 'metric', data: { value: 1284, unit: 'users', ... } }
+ * ```
+ */
+export declare function template(widget: string): UWidgetSpec | undefined;
+
+/**
+ * Action button definition.
+ *
+ * Reserved actions: `"submit"`, `"cancel"`, `"navigate"`.
+ * Custom action strings are forwarded to the host via the `u-widget-event`.
+ *
+ * @example
+ * ```json
+ * { "label": "Submit", "action": "submit", "style": "primary" }
+ * ```
+ */
+declare interface UWidgetAction {
+    /** Button display text. */
+    label: string;
+    /** Action identifier emitted in the widget event. */
+    action: string;
+    /** Visual style hint. */
+    style?: 'primary' | 'danger' | 'default';
+    /** Whether the button is disabled. */
+    disabled?: boolean;
+    /** URL for `"navigate"` actions. */
+    url?: string;
+}
+
+/**
+ * Child widget spec inside a compose widget.
+ * Inherits `type` and `version` from the parent — no need to repeat them.
+ */
+declare interface UWidgetChildSpec extends Omit<UWidgetSpec, 'type' | 'version'> {
+    /** Grid column span within the parent compose layout. */
+    span?: number;
+    /** When true, the child is initially collapsed (uses native `<details>`). */
+    collapsed?: boolean;
+}
+
+/**
+ * Column definition for table widgets.
+ *
+ * @example
+ * ```json
+ * { "field": "price", "label": "Price", "format": "currency", "align": "right" }
+ * ```
+ */
+declare interface UWidgetColumnDefinition {
+    /** Data field name to display in this column. */
+    field: string;
+    /** Display header label. Defaults to the field name. */
+    label?: string;
+    /** Value formatting hint (e.g., `"currency"`, `"currency:EUR"`, `"percent"`). */
+    format?: 'number' | 'currency' | 'percent' | 'date' | 'datetime' | 'bytes';
+    /** Text alignment within the column. */
+    align?: 'left' | 'center' | 'right';
+}
+
+/**
+ * Field definition for form/confirm input widgets.
+ *
+ * @example
+ * ```json
+ * { "field": "email", "label": "Email", "type": "email", "required": true }
+ * ```
+ */
+declare interface UWidgetFieldDefinition {
+    /** Data field name (maps to `data[field]` for defaults and output). */
+    field: string;
+    /** Display label. Defaults to the field name. */
+    label?: string;
+    /** Input type. Defaults to `"text"`. */
+    type?: FieldType;
+    /** Whether the field must be filled before submit. */
+    required?: boolean;
+    /** Placeholder text shown when the field is empty. */
+    placeholder?: string;
+    /** Options for select, multiselect, radio, and checkbox types. */
+    options?: string[];
+    /** Minimum character length for text inputs. */
+    minLength?: number;
+    /** Maximum character length for text inputs. */
+    maxLength?: number;
+    /** Custom regex pattern for validation (e.g. `"^[A-Z]{3}$"`). */
+    pattern?: string;
+    /** Number of visible rows for textarea type. */
+    rows?: number;
+    /** Minimum value (number) or date string. */
+    min?: number | string;
+    /** Maximum value (number) or date string. */
+    max?: number | string;
+    /** Step increment for number and range inputs. */
+    step?: number;
+    /** Custom validation error message (overrides locale default). */
+    message?: string;
+}
+
+/**
+ * Mapping connects data fields to visual channels.
+ *
+ * Which keys are relevant depends on the widget type:
+ * - **chart.bar/line/area:** `x`, `y`
+ * - **chart.pie/funnel:** `label`, `value`
+ * - **chart.scatter:** `x`, `y`, `color`, `size`
+ * - **chart.radar:** `axis`, `value`
+ * - **table:** `columns`
+ * - **list:** `primary`, `secondary`, `avatar`, `icon`, `trailing`
+ *
+ * When omitted, mapping is auto-inferred from the data shape.
+ */
+declare interface UWidgetMapping {
+    /** Category axis field (chart x-axis). */
+    x?: string;
+    /** Value axis field(s). A string for single series, string[] for multi-series. */
+    y?: string | string[];
+    /** Label field (pie/funnel charts). */
+    label?: string;
+    /** Value field (pie/funnel/heatmap). */
+    value?: string;
+    /** Color grouping field (scatter). */
+    color?: string;
+    /** Size encoding field (scatter bubble). */
+    size?: string;
+    /** Opacity encoding field (scatter). Maps data values to point opacity (0.1–1.0). */
+    opacity?: string;
+    /** Axis field (radar chart indicators). */
+    axis?: string;
+    /** Explicit column definitions for table widgets. */
+    columns?: UWidgetColumnDefinition[];
+    /** Primary text field (list widget). */
+    primary?: string;
+    /** Secondary/subtitle text field (list widget). */
+    secondary?: string;
+    /** Icon letter field (list widget fallback when no avatar). */
+    icon?: string;
+    /** Avatar image URL field (list widget). */
+    avatar?: string;
+    /** Trailing value field displayed on the right (list widget). */
+    trailing?: string;
+    /** Badge/tag field (list widget). */
+    badge?: string;
+}
+
+/**
+ * The u-widget spec envelope — a single, consistent structure for all widgets.
+ *
+ * Only `widget` is required. All other fields are optional or auto-inferred.
+ *
+ * @example
+ * ```ts
+ * const spec: UWidgetSpec = {
+ *   widget: 'chart.bar',
+ *   data: [{ name: 'A', value: 30 }, { name: 'B', value: 70 }],
+ *   mapping: { x: 'name', y: 'value' },
+ * };
+ * ```
+ */
+declare interface UWidgetSpec {
+    /** Widget type identifier (e.g., `"chart.bar"`, `"metric"`, `"form"`). */
+    widget: string;
+    /** Unique identifier for event correlation and compose children. */
+    id?: string;
+    /** Optional display title rendered above the widget. */
+    title?: string;
+    /** Optional description text rendered below the title. */
+    description?: string;
+    /** Inline data — an object (metric/gauge) or array of records (chart/table). */
+    data?: Record<string, unknown> | Record<string, unknown>[];
+    /** Maps data fields to visual channels. Auto-inferred when omitted. */
+    mapping?: UWidgetMapping;
+    /** Field definitions for form/confirm widgets. */
+    fields?: UWidgetFieldDefinition[];
+    /** Formdown shorthand syntax for form fields (mutually exclusive with `fields`). */
+    formdown?: string;
+    /** Widget-specific rendering options. */
+    options?: Record<string, unknown>;
+    /** Action buttons displayed below the widget. */
+    actions?: UWidgetAction[];
+    /** Interchange format type marker. Always `"u-widget"` if present. */
+    type?: 'u-widget';
+    /** Interchange format version string. */
+    version?: string;
+    /** Layout mode for compose widget: `"stack"` (default), `"row"`, or `"grid"`. */
+    layout?: 'stack' | 'row' | 'grid';
+    /** Number of grid columns for compose `"grid"` layout. Default: 2. */
+    columns?: number;
+    /** Child widget specs for compose widget. */
+    children?: UWidgetChildSpec[];
+    /** Grid column span for children inside a compose `"grid"` layout. */
+    span?: number;
+}
+
+/**
+ * Well-known data fields per widget type.
+ * Charts/table/list use user-defined fields so they are omitted.
+ */
+export declare const WIDGET_DATA_FIELDS: Readonly<Record<string, readonly DataFieldInfo[]>>;
+
+/** Events emitted per widget category. */
+export declare const WIDGET_EVENTS: Readonly<Record<string, readonly string[]>>;
+
+/** Auto-inference hints — tells LLM what can be omitted. */
+export declare const WIDGET_INFERENCE: Readonly<Record<string, string>>;
+
+/** Relevant option keys per widget type. Only lists keys from OPTION_DOCS. */
+export declare const WIDGET_OPTIONS: Readonly<Record<string, readonly string[]>>;
+
+/** Extended detail returned when `help()` is called with an exact widget name. */
+export declare interface WidgetDetail extends WidgetInfo {
+    /** One-line hint telling LLM what can be omitted via auto-inference. */
+    autoInference: string;
+    /** Well-known data fields (display/content widgets). Empty for user-defined data. */
+    dataFields: DataFieldInfo[];
+    /** Mapping key descriptions relevant to this widget. */
+    mappingDocs: Record<string, string>;
+    /** Option key descriptions relevant to this widget. */
+    optionDocs: Record<string, string>;
+    /** Field definition property docs (form/confirm only). */
+    fieldDocs?: Record<string, string>;
+    /** Action property docs (form/confirm only). */
+    actionDocs?: Record<string, string>;
+    /** Event types emitted by this widget. */
+    events: readonly string[];
+    /** Example specs (minimal template + feature-rich). */
+    examples: {
+        label: string;
+        spec: UWidgetSpec;
+    }[];
+}
+
+/** Describes a single widget type in the catalog. */
+export declare interface WidgetInfo {
+    /** Widget type identifier (e.g., `"chart.bar"`). */
+    widget: string;
+    /** Human-readable category. */
+    category: 'chart' | 'display' | 'input' | 'content' | 'composition';
+    /** Short description of the widget's purpose. */
+    description: string;
+    /** Which mapping keys are relevant for this widget. */
+    mappingKeys: string[];
+    /** Expected data shape. */
+    dataShape: 'object' | 'array' | 'none';
+}
+
+export { }