@iyulab/u-widgets 0.9.2 → 0.11.0

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

@@ -0,0 +1,219 @@
+import { CSSResult } from 'lit';
+import { LitElement } from 'lit';
+import { nothing } from 'lit';
+import { TemplateResult } from 'lit-html';
+
+/** 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';
+
+/**
+ * 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.
+     *
+     * Chart widgets support an `echarts` sub-key for native ECharts option passthrough:
+     * ```json
+     * { "options": { "echarts": { "tooltip": { "trigger": "axis" } } } }
+     * ```
+     * All keys in `options.echarts` are deep-merged into the generated ECharts option.
+     * @see https://echarts.apache.org/en/option.html
+     */
+    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;
+}
+
+/**
+ * <uw-math> — LaTeX math expression renderer via KaTeX.
+ *
+ * Uses MathML output for zero-CSS rendering in Shadow DOM.
+ * Loaded via the `u-widgets/math` entry point. Requires `katex` as a peer dependency.
+ */
+export declare class UwMath extends LitElement {
+    static styles: CSSResult[];
+    spec: UWidgetSpec | null;
+    theme: string | null;
+    render(): typeof nothing | TemplateResult<1>;
+}
+
+export { }

package/dist/u-widgets-math.js

@@ -0,0 +1,95 @@
+import { css as m, LitElement as u, nothing as p, html as c } from "lit";
+import { property as d, customElement as h } from "lit/decorators.js";
+import { t as f } from "./tokens-byMop3gk.js";
+import g from "katex";
+var v = Object.defineProperty, y = Object.getOwnPropertyDescriptor, l = (o, t, a, r) => {
+  for (var e = r > 1 ? void 0 : r ? y(t, a) : t, s = o.length - 1, n; s >= 0; s--)
+    (n = o[s]) && (e = (r ? n(t, a, e) : n(e)) || e);
+  return r && e && v(t, a, e), e;
+};
+let i = class extends u {
+  constructor() {
+    super(...arguments), this.spec = null, this.theme = null;
+  }
+  render() {
+    if (!this.spec) return p;
+    const o = this.spec.data;
+    if (!o) return p;
+    const t = String(o.expression ?? "").trim();
+    if (!t) return p;
+    const r = !!((this.spec.options ?? {}).displayMode ?? !1);
+    try {
+      const e = g.renderToString(t, {
+        displayMode: r,
+        throwOnError: !0,
+        output: "mathml"
+      });
+      return c`
+        <div
+          class="math-block"
+          part="math"
+          data-display=${String(r)}
+          .innerHTML=${e}
+        ></div>
+      `;
+    } catch (e) {
+      const s = e instanceof Error ? e.message : "Invalid expression";
+      return c`
+        <div class="math-error" part="math-error">
+          ${s}
+          <code>${t}</code>
+        </div>
+      `;
+    }
+  }
+};
+i.styles = [f, m`
+    :host {
+      display: block;
+      font-family: system-ui, -apple-system, sans-serif;
+      container: uw-math / inline-size;
+    }
+
+    .math-block {
+      color: var(--u-widget-text, #1a1a2e);
+      overflow-x: auto;
+      font-size: 1rem;
+      line-height: 1.6;
+    }
+
+    .math-block[data-display="true"] {
+      text-align: center;
+      padding: 8px 0;
+      font-size: 1.2rem;
+    }
+
+    .math-error {
+      padding: 8px 12px;
+      border-radius: 4px;
+      border: 1px solid var(--u-widget-negative, #dc2626);
+      background: color-mix(in srgb, var(--u-widget-negative, #dc2626) 8%, var(--u-widget-bg, #fff));
+      font-size: 0.8125rem;
+      color: var(--u-widget-negative, #dc2626);
+    }
+
+    .math-error code {
+      display: block;
+      margin-top: 4px;
+      font-size: 0.75rem;
+      color: var(--u-widget-text-secondary, #64748b);
+      word-break: break-all;
+    }
+  `];
+l([
+  d({ type: Object })
+], i.prototype, "spec", 2);
+l([
+  d({ type: String, reflect: !0 })
+], i.prototype, "theme", 2);
+i = l([
+  h("uw-math")
+], i);
+export {
+  i as UwMath
+};
+//# sourceMappingURL=u-widgets-math.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"u-widgets-math.js","sources":["../src/elements/uw-math.ts"],"sourcesContent":["import { LitElement, html, css, nothing } from 'lit';\nimport { customElement, property } from 'lit/decorators.js';\nimport type { UWidgetSpec } from '../core/types.js';\nimport { themeStyles } from '../styles/tokens.js';\nimport katex from 'katex';\n\n/**\n * <uw-math> — LaTeX math expression renderer via KaTeX.\n *\n * Uses MathML output for zero-CSS rendering in Shadow DOM.\n * Loaded via the `u-widgets/math` entry point. Requires `katex` as a peer dependency.\n */\n@customElement('uw-math')\nexport class UwMath extends LitElement {\n  static styles = [themeStyles, css`\n    :host {\n      display: block;\n      font-family: system-ui, -apple-system, sans-serif;\n      container: uw-math / inline-size;\n    }\n\n    .math-block {\n      color: var(--u-widget-text, #1a1a2e);\n      overflow-x: auto;\n      font-size: 1rem;\n      line-height: 1.6;\n    }\n\n    .math-block[data-display=\"true\"] {\n      text-align: center;\n      padding: 8px 0;\n      font-size: 1.2rem;\n    }\n\n    .math-error {\n      padding: 8px 12px;\n      border-radius: 4px;\n      border: 1px solid var(--u-widget-negative, #dc2626);\n      background: color-mix(in srgb, var(--u-widget-negative, #dc2626) 8%, var(--u-widget-bg, #fff));\n      font-size: 0.8125rem;\n      color: var(--u-widget-negative, #dc2626);\n    }\n\n    .math-error code {\n      display: block;\n      margin-top: 4px;\n      font-size: 0.75rem;\n      color: var(--u-widget-text-secondary, #64748b);\n      word-break: break-all;\n    }\n  `];\n\n  @property({ type: Object })\n  spec: UWidgetSpec | null = null;\n\n  @property({ type: String, reflect: true })\n  theme: string | null = null;\n\n  render() {\n    if (!this.spec) return nothing;\n\n    const data = this.spec.data as Record<string, unknown> | undefined;\n    if (!data) return nothing;\n\n    const expression = String(data.expression ?? '').trim();\n    if (!expression) return nothing;\n\n    const options = (this.spec.options ?? {}) as Record<string, unknown>;\n    const displayMode = Boolean(options.displayMode ?? false);\n\n    try {\n      // SAFETY: output must be 'mathml' — pure MathML has no script/event vectors,\n      // making .innerHTML safe. Switching to 'html' or 'htmlAndMathml' would require\n      // KaTeX CSS and introduce potential XSS via custom macros.\n      const rendered = katex.renderToString(expression, {\n        displayMode,\n        throwOnError: true,\n        output: 'mathml',\n      });\n\n      return html`\n        <div\n          class=\"math-block\"\n          part=\"math\"\n          data-display=${String(displayMode)}\n          .innerHTML=${rendered}\n        ></div>\n      `;\n    } catch (e) {\n      const msg = e instanceof Error ? e.message : 'Invalid expression';\n      return html`\n        <div class=\"math-error\" part=\"math-error\">\n          ${msg}\n          <code>${expression}</code>\n        </div>\n      `;\n    }\n  }\n}\n\ndeclare global {\n  interface HTMLElementTagNameMap {\n    'uw-math': UwMath;\n  }\n}\n"],"names":["UwMath","LitElement","nothing","data","expression","displayMode","rendered","katex","html","msg","themeStyles","css","__decorateClass","property","customElement"],"mappings":";;;;;;;;;AAaO,IAAMA,IAAN,cAAqBC,EAAW;AAAA,EAAhC,cAAA;AAAA,UAAA,GAAA,SAAA,GAwCL,KAAA,OAA2B,MAG3B,KAAA,QAAuB;AAAA,EAAA;AAAA,EAEvB,SAAS;AACP,QAAI,CAAC,KAAK,KAAM,QAAOC;AAEvB,UAAMC,IAAO,KAAK,KAAK;AACvB,QAAI,CAACA,EAAM,QAAOD;AAElB,UAAME,IAAa,OAAOD,EAAK,cAAc,EAAE,EAAE,KAAA;AACjD,QAAI,CAACC,EAAY,QAAOF;AAGxB,UAAMG,IAAc,IADH,KAAK,KAAK,WAAW,CAAA,GACF,eAAe;AAEnD,QAAI;AAIF,YAAMC,IAAWC,EAAM,eAAeH,GAAY;AAAA,QAChD,aAAAC;AAAA,QACA,cAAc;AAAA,QACd,QAAQ;AAAA,MAAA,CACT;AAED,aAAOG;AAAA;AAAA;AAAA;AAAA,yBAIY,OAAOH,CAAW,CAAC;AAAA,uBACrBC,CAAQ;AAAA;AAAA;AAAA,IAG3B,SAAS,GAAG;AACV,YAAMG,IAAM,aAAa,QAAQ,EAAE,UAAU;AAC7C,aAAOD;AAAA;AAAA,YAEDC,CAAG;AAAA,kBACGL,CAAU;AAAA;AAAA;AAAA,IAGxB;AAAA,EACF;AACF;AArFaJ,EACJ,SAAS,CAACU,GAAaC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,GAoC7B;AAGDC,EAAA;AAAA,EADCC,EAAS,EAAE,MAAM,OAAA,CAAQ;AAAA,GAvCfb,EAwCX,WAAA,QAAA,CAAA;AAGAY,EAAA;AAAA,EADCC,EAAS,EAAE,MAAM,QAAQ,SAAS,IAAM;AAAA,GA1C9Bb,EA2CX,WAAA,SAAA,CAAA;AA3CWA,IAANY,EAAA;AAAA,EADNE,EAAc,SAAS;AAAA,GACXd,CAAA;"}

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

@@ -0,0 +1,265 @@
+import { CSSResult } from 'lit';
+import { EventName } from '@lit/react';
+import { LitElement } from 'lit';
+import { nothing } from 'lit';
+import { ReactWebComponent } from '@lit/react';
+import { TemplateResult } from 'lit-html';
+
+/** 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';
+
+export declare const UWidget: ReactWebComponent<UWidget_2, {
+onWidgetEvent: EventName<CustomEvent>;
+}>;
+
+/**
+ * <u-widget> — Entry point router element.
+ * Reads spec.widget and delegates to the appropriate sub-component.
+ *
+ * Supports theme attribute: theme="dark" | theme="light" | (auto via prefers-color-scheme)
+ */
+declare class UWidget_2 extends LitElement {
+    static styles: CSSResult[];
+    spec: UWidgetSpec | null;
+    /** Theme override: "dark" | "light" | null (auto via prefers-color-scheme). */
+    theme: string | null;
+    /** Locale tag (e.g. 'ko', 'en-US'). Propagated to sub-components via spec.options.locale. */
+    locale: string | null;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private _handleInternalEvent;
+    render(): typeof nothing | TemplateResult<1>;
+    private renderWidget;
+    /** Render standalone "actions" widget — a group of action buttons. */
+    private renderActionsWidget;
+    /** Render inline divider widget. */
+    private renderDivider;
+    /** Render inline header widget. */
+    private renderHeader;
+    /** Dispatch an action event from the global action bar or actions widget. */
+    private _dispatchAction;
+    private renderFallback;
+    private renderError;
+}
+
+/**
+ * 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" }
+ * ```
+ */
+export 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';
+}
+
+/**
+ * Event payload emitted by `<u-widget>` via the `u-widget-event` custom event.
+ *
+ * | type | trigger | payload |
+ * |---|---|---|
+ * | `submit` | Form submit button | Form field values |
+ * | `action` | Custom action button | Action data |
+ * | `change` | Input value change | Changed field and value |
+ * | `select` | Chart element click | Selected data point |
+ */
+export declare interface UWidgetEvent {
+    /** Event category. */
+    type: 'submit' | 'action' | 'change' | 'select';
+    /** The widget type that emitted this event. */
+    widget: string;
+    /** Widget instance `id` (if set in the spec). */
+    id?: string;
+    /** Action identifier (for `"action"` type events). */
+    action?: string;
+    /** Event payload data. */
+    data?: Record<string, unknown>;
+}
+
+/**
+ * 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' },
+ * };
+ * ```
+ */
+export 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.
+     *
+     * Chart widgets support an `echarts` sub-key for native ECharts option passthrough:
+     * ```json
+     * { "options": { "echarts": { "tooltip": { "trigger": "axis" } } } }
+     * ```
+     * All keys in `options.echarts` are deep-merged into the generated ECharts option.
+     * @see https://echarts.apache.org/en/option.html
+     */
+    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;
+}
+
+export { }

package/dist/u-widgets-react.js

@@ -0,0 +1,15 @@
+import e from "react";
+import { createComponent as t } from "@lit/react";
+import { UWidget as o } from "@iyulab/u-widgets";
+const n = t({
+  tagName: "u-widget",
+  elementClass: o,
+  react: e,
+  events: {
+    onWidgetEvent: "u-widget-event"
+  }
+});
+export {
+  n as UWidget
+};
+//# sourceMappingURL=u-widgets-react.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"u-widgets-react.js","sources":["../src/react.ts"],"sourcesContent":["/**\n * @module u-widgets/react\n *\n * React wrapper for `<u-widget>` custom element.\n * Uses `@lit/react` to bridge Lit properties and React props.\n *\n * Requires the base package to be imported separately to register the element:\n *\n * @example\n * ```tsx\n * import '@iyulab/u-widgets';             // registers <u-widget>\n * import { UWidget } from '@iyulab/u-widgets/react';\n *\n * function App() {\n *   return (\n *     <UWidget\n *       spec={{ widget: 'metric', data: { value: 42 } }}\n *       onWidgetEvent={(e) => console.log(e.detail)}\n *     />\n *   );\n * }\n * ```\n */\nimport React from 'react';\nimport { createComponent, type EventName } from '@lit/react';\nimport { UWidget as UWidgetElement } from '@iyulab/u-widgets';\n\nexport const UWidget = createComponent({\n  tagName: 'u-widget',\n  elementClass: UWidgetElement,\n  react: React,\n  events: {\n    onWidgetEvent: 'u-widget-event' as EventName<CustomEvent>,\n  },\n});\n\n// Re-export core types for convenience\nexport type { UWidgetSpec, UWidgetEvent, UWidgetAction } from '@iyulab/u-widgets';\n"],"names":["UWidget","createComponent","UWidgetElement","React"],"mappings":";;;AA2BO,MAAMA,IAAUC,EAAgB;AAAA,EACrC,SAAS;AAAA,EACT,cAAcC;AAAAA,EACd,OAAOC;AAAA,EACP,QAAQ;AAAA,IACN,eAAe;AAAA,EAAA;AAEnB,CAAC;"}