@iyulab/u-widgets 0.4.1 → 0.6.0

package/dist/u-widgets.d.ts

@@ -71,6 +71,12 @@ export declare interface FormdownResult {
  */
 export declare function getDefaultLocale(): UWidgetLocaleStrings;
 
+/**
+ * Get the active global default locale set via setDefaultLocale().
+ * Returns undefined if not set.
+ */
+export declare function getEffectiveLocale(): string | undefined;
+
 export declare function getFormdownParser(): FormdownParser;
 
 /**
@@ -143,6 +149,30 @@ export declare function registerFormdownParser(parser: FormdownParser): void;
  */
 export declare function registerLocale(lang: string, strings: Partial<UWidgetLocaleStrings>): void;
 
+/**
+ * Resolve the locale to use for a widget.
+ *
+ * Priority: widgetLocale > setDefaultLocale() > document.lang > undefined
+ */
+export declare function resolveLocale(widgetLocale?: string | null): string | undefined;
+
+/**
+ * Set the global default locale for all u-widgets.
+ *
+ * Resolution order (highest priority first):
+ *   1. Per-widget `locale` attribute/property
+ *   2. setDefaultLocale() value
+ *   3. document.documentElement.lang (browser only)
+ *   4. English fallback
+ *
+ * @example
+ * ```ts
+ * import { setDefaultLocale } from '@iyulab/u-widgets';
+ * setDefaultLocale('ko-KR');
+ * ```
+ */
+export declare function setDefaultLocale(lang: string | undefined): void;
+
 /**
  * Widget name suggestion for typo detection.
  *
@@ -252,6 +282,19 @@ export declare interface UWidgetColumnDefinition {
     align?: 'left' | 'center' | 'right';
 }
 
+export declare interface UWidgetElementProps {
+    /** Widget spec — object (via property binding) or JSON string (via attribute). */
+    spec?: UWidgetSpec | string;
+    /** Theme override. Omit for prefers-color-scheme auto-detection. */
+    theme?: 'light' | 'dark';
+    /** BCP 47 locale tag, e.g. 'ko-KR'. */
+    locale?: string;
+    id?: string;
+    class?: string;
+    style?: string;
+    [key: string]: unknown;
+}
+
 /**
  * Event payload emitted by `<u-widget>` via the `u-widget-event` custom event.
  *
@@ -419,7 +462,16 @@ export declare interface UWidgetSpec {
     fields?: UWidgetFieldDefinition[];
     /** Formdown shorthand syntax for form fields (mutually exclusive with `fields`). */
     formdown?: string;
-    /** Widget-specific rendering options. */
+    /**
+     * 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[];
@@ -476,3 +528,22 @@ export declare interface ValidationResult {
 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 { }
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'u-widget': import('@iyulab/u-widgets').UWidget;
+    }
+    namespace JSX {
+        interface IntrinsicElements {
+            'u-widget': UWidgetElementProps;
+        }
+    }
+}
+
+declare module "react" {
+    namespace JSX {
+        interface IntrinsicElements {
+            "u-widget": UWidgetElementProps;
+        }
+    }
+}