@iyulab/u-widgets 0.4.1

package/dist/u-widgets.d.ts

@@ -0,0 +1,478 @@
+import { CSSResult } from 'lit';
+import { LitElement } from 'lit';
+import { nothing } from 'lit';
+import { TemplateResult } from 'lit-html';
+
+/**
+ * Chart widget type identifiers using dot notation (`chart.<variant>`).
+ *
+ * @example
+ * ```json
+ * { "widget": "chart.bar", "data": [...] }
+ * ```
+ */
+export declare type ChartType = 'chart.bar' | 'chart.line' | 'chart.area' | 'chart.pie' | 'chart.scatter' | 'chart.radar' | 'chart.heatmap' | 'chart.box' | 'chart.funnel' | 'chart.waterfall' | 'chart.treemap';
+
+/** Supported input field types for form widgets. */
+export declare type FieldType = 'text' | 'email' | 'password' | 'tel' | 'url' | 'textarea' | 'number' | 'select' | 'multiselect' | 'date' | 'datetime' | 'time' | 'toggle' | 'range' | 'radio' | 'checkbox';
+
+/**
+ * Format a template string by replacing {key} placeholders.
+ */
+export declare function formatTemplate(template: string, params: Record<string, string | number>): string;
+
+/**
+ * Format a value according to a format hint string.
+ *
+ * Supported formats: `"number"`, `"currency"`, `"currency:EUR"`, `"percent"`,
+ * `"date"`, `"datetime"`, `"bytes"`. Returns `String(value)` for unknown formats.
+ *
+ * @param value - The value to format (coerced to number where needed).
+ * @param format - Format hint, optionally with a parameter after `:` (e.g., `"currency:USD"`).
+ * @param locale - BCP 47 locale tag for number/currency formatting. Falls back to browser default.
+ * @returns Formatted string, or empty string if value is null/undefined.
+ *
+ * @example
+ * ```ts
+ * formatValue(1234.5, 'number')       // "1,234.5"
+ * formatValue(1234.5, 'currency:EUR') // "€1,234.50"
+ * formatValue(73, 'percent')          // "73%"
+ * formatValue(1536000, 'bytes')       // "1.5 MB"
+ * ```
+ */
+export declare function formatValue(value: unknown, format?: string, locale?: string): string;
+
+export declare type FormdownParser = (input: string, data?: Record<string, unknown>) => FormdownResult;
+
+/**
+ * Parse a formdown string into fields and actions.
+ *
+ * Formdown syntax (subset):
+ *   @fieldName*(Label){opt1,opt2}: type[]
+ *   @[action "Label"]
+ *
+ * Type markers:
+ *   []     text       @[]    email      #[]    number
+ *   ?[]    password   %[]    tel        &[]    url
+ *   T{n}[] textarea   d[]    date       dt[]   datetime
+ *   t[]    time       s[]    select     r[]    radio
+ *   c[]    checkbox   ^[]    toggle     R[]    range
+ *   ms[]   multiselect
+ *
+ *   * = required, (Label) = display label, {a,b,c} = options
+ */
+export declare interface FormdownResult {
+    fields: UWidgetFieldDefinition[];
+    actions: UWidgetAction[];
+}
+
+/**
+ * Get the English defaults (for testing / reference).
+ */
+export declare function getDefaultLocale(): UWidgetLocaleStrings;
+
+export declare function getFormdownParser(): FormdownParser;
+
+/**
+ * Resolve locale strings for the given language tag.
+ *
+ * Resolution order:
+ *   1. Exact match (e.g. 'ko-KR')
+ *   2. Base language (e.g. 'ko')
+ *   3. English fallback
+ */
+export declare function getLocaleStrings(lang?: string): UWidgetLocaleStrings;
+
+/**
+ * Auto-infer a mapping from data shape and widget type.
+ *
+ * Inference rules:
+ * - **chart.bar/line/area:** first string field → `x`, number fields → `y`
+ * - **chart.pie/funnel:** first string → `label`, first number → `value`
+ * - **chart.scatter:** first two number fields → `x`, `y`
+ * - **chart.radar:** first string → `axis`, number fields → `y`
+ * - **chart.heatmap:** two string fields + number → `x`, `y`, `value`
+ * - **chart.box:** string → `x`, five number fields (min/q1/median/q3/max) → `y`
+ * - **table:** all keys → `columns`
+ * - **list:** first string → `primary`, second string → `secondary`
+ * - **metric/gauge/progress/form:** no mapping needed (returns `undefined`)
+ *
+ * @param widget - Widget type identifier.
+ * @param data - The spec's `data` field (object or array of records).
+ * @returns Inferred mapping, or `undefined` if not applicable.
+ *
+ * @example
+ * ```ts
+ * infer('chart.bar', [{ name: 'A', value: 30 }]);
+ * // → { x: 'name', y: 'value' }
+ * ```
+ */
+export declare function infer(widget: string, data: Record<string, unknown> | Record<string, unknown>[] | undefined): UWidgetMapping | undefined;
+
+/**
+ * Type guard that checks if a value is a valid {@link UWidgetSpec}.
+ *
+ * Equivalent to `validate(value).valid`, but narrows the TypeScript type.
+ *
+ * @param value - The value to check.
+ * @returns `true` if the value passes validation.
+ */
+export declare function isWidgetSpec(value: unknown): value is UWidgetSpec;
+
+/**
+ * Normalize a spec for internal processing.
+ *
+ * Transformations applied:
+ * 1. Deprecated `mapping.fields` → top-level `fields`
+ * 2. `formdown` string → parsed `fields` + `actions`
+ *
+ * Returns a shallow copy; the original spec is not mutated.
+ *
+ * @param spec - The widget spec to normalize.
+ * @returns A normalized copy of the spec.
+ */
+export declare function normalize(spec: UWidgetSpec): UWidgetSpec;
+
+export declare function parseFormdown(input: string, _data?: Record<string, unknown>): FormdownResult;
+
+export declare function registerFormdownParser(parser: FormdownParser): void;
+
+/**
+ * Register a locale for u-widgets chrome strings.
+ * Partial overrides are merged with English defaults.
+ */
+export declare function registerLocale(lang: string, strings: Partial<UWidgetLocaleStrings>): void;
+
+/**
+ * Widget name suggestion for typo detection.
+ *
+ * Compares an unrecognized widget name against all known types
+ * using Levenshtein distance and returns the closest match.
+ */
+/**
+ * Suggest a known widget name for a potentially mistyped input.
+ *
+ * Returns the closest match if the Levenshtein distance is within
+ * a reasonable threshold (max 3, and less than half the input length).
+ * Returns `undefined` if no good match is found.
+ *
+ * @param input - The unrecognized widget name.
+ * @returns The suggested widget name, or `undefined`.
+ *
+ * @example
+ * ```ts
+ * suggestWidget('chart.barr') // → 'chart.bar'
+ * suggestWidget('metrc')      // → 'metric'
+ * suggestWidget('xyzabc')     // → undefined
+ * ```
+ */
+export declare function suggestWidget(input: string): string | undefined;
+
+/**
+ * <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)
+ */
+export declare class UWidget 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.
+ */
+export 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" }
+ * ```
+ */
+export 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 }
+ * ```
+ */
+export 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;
+}
+
+/**
+ * Lightweight locale registry for u-widgets.
+ *
+ * Scope: library-internal chrome strings only (validation messages,
+ * pagination labels, ARIA labels). NOT a general i18n framework.
+ *
+ * English is the built-in default. Consumers register other locales:
+ *   registerLocale('ko', { prev: '이전', next: '다음', ... });
+ */
+export declare interface UWidgetLocaleStrings {
+    prev: string;
+    next: string;
+    searchPlaceholder: string;
+    searchTable: string;
+    previousPage: string;
+    nextPage: string;
+    tablePagination: string;
+    dataTable: string;
+    required: string;
+    minLength: string;
+    maxLength: string;
+    minValue: string;
+    maxValue: string;
+    invalidEmail: string;
+    invalidUrl: string;
+    invalidPattern: 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.
+ */
+export 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. */
+    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;
+}
+
+/**
+ * Validate a u-widget spec.
+ *
+ * Checks structural correctness: required fields, data type expectations,
+ * compose children, field/action definitions. Also validates that mapping
+ * fields exist in the data (produces warnings, not errors).
+ *
+ * @param spec - The spec object to validate (any type accepted for safety).
+ * @returns Validation result with `valid`, `errors`, and `warnings`.
+ *
+ * @example
+ * ```ts
+ * const result = validate({ widget: 'metric', data: { value: 42 } });
+ * console.log(result.valid); // true
+ * ```
+ */
+export declare function validate(spec: unknown, _depth?: number): ValidationResult;
+
+/** Result of spec validation via {@link validate}. */
+export declare interface ValidationResult {
+    /** Whether the spec passed all validation checks. */
+    valid: boolean;
+    /** Error messages — issues that prevent correct rendering. */
+    errors: string[];
+    /** Warning messages — non-fatal issues or recommendations. */
+    warnings: string[];
+}
+
+/**
+ * All supported widget type identifiers.
+ *
+ * - **Display:** chart.*, metric, stat-group, gauge, progress, table, list
+ * - **Input:** form, confirm
+ * - **Composition:** compose
+ * - **Content:** markdown, image, callout
+ */
+export declare type WidgetType = ChartType | 'metric' | 'stat-group' | 'gauge' | 'progress' | 'table' | 'list' | 'form' | 'confirm' | 'compose' | 'markdown' | 'image' | 'callout' | 'kv' | 'code' | 'citation' | 'status' | 'steps' | 'rating' | 'video' | 'gallery' | 'actions' | 'divider' | 'header';
+
+export { }