@iyulab/u-widgets 0.5.0 → 0.6.0

package/README.md

@@ -88,6 +88,46 @@ AI assistants can use u-widgets via [MCP server](docs/mcp-server.md):
 npx @iyulab/u-widgets-mcp
 ```
 
+## Framework Integration
+
+u-widgets is a browser-only Web Component library — it requires DOM APIs (`customElements`, `HTMLElement`) and cannot run in Node.js or server-side environments.
+
+### Next.js (App Router)
+
+Create a client-side wrapper component:
+
+```tsx
+// components/widget.tsx
+"use client";
+import "@iyulab/u-widgets";
+
+export function Widget({ spec }: { spec: object }) {
+  return <u-widget spec={JSON.stringify(spec)} />;
+}
+```
+
+Use the wrapper from Server Components:
+
+```tsx
+// app/dashboard/page.tsx
+import { Widget } from "@/components/widget";
+
+export default async function Page() {
+  const data = await fetchData();
+  return <Widget spec={{ widget: "stat-group", data }} />;
+}
+```
+
+For pages where SSR hydration mismatch is a concern, use dynamic import:
+
+```tsx
+import dynamic from "next/dynamic";
+const Widget = dynamic(
+  () => import("@/components/widget").then((m) => m.Widget),
+  { ssr: false }
+);
+```
+
 ## Documentation
 
 - [Widget Reference](docs/widgets.md) — Schema, mapping, options, theming

package/dist/u-widgets.d.ts

@@ -2,7 +2,6 @@ import { CSSResult } from 'lit';
 import { LitElement } from 'lit';
 import { nothing } from 'lit';
 import { TemplateResult } from 'lit-html';
-import { UWidgetElementProps } from './types/jsx.js';
 
 /**
  * Chart widget type identifiers using dot notation (`chart.<variant>`).
@@ -283,7 +282,18 @@ export declare interface UWidgetColumnDefinition {
     align?: 'left' | 'center' | 'right';
 }
 
-export { UWidgetElementProps }
+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.
@@ -518,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;
+        }
+    }
+}

package/dist/u-widgets.js

@@ -1,10 +1,10 @@
-import { g as ve } from "./formdown-BWJ6QGJs.js";
+import { g as be } from "./formdown-BWJ6QGJs.js";
 import { p as Nt, r as Ft } from "./formdown-BWJ6QGJs.js";
-import { i as be } from "./infer-CNOiD2dS.js";
-import { t as b, n as we } from "./tokens-x1kDxgG8.js";
+import { i as we } from "./infer-CNOiD2dS.js";
+import { t as b, n as ye } from "./tokens-x1kDxgG8.js";
 import { css as w, LitElement as y, nothing as l, html as o } from "lit";
 import { property as h, customElement as x, state as S } from "lit/decorators.js";
-const ye = /* @__PURE__ */ new Set([
+const xe = /* @__PURE__ */ new Set([
   "text",
   "email",
   "password",
@@ -21,7 +21,7 @@ const ye = /* @__PURE__ */ new Set([
   "range",
   "radio",
   "checkbox"
-]), ie = 10, xe = /* @__PURE__ */ new Set([
+]), ie = 10, $e = /* @__PURE__ */ new Set([
   "stat-group",
   "table",
   "list",
@@ -38,7 +38,7 @@ const ye = /* @__PURE__ */ new Set([
   "chart.funnel",
   "chart.waterfall",
   "chart.treemap"
-]), $e = /* @__PURE__ */ new Set(["metric", "gauge", "progress", "header", "code", "rating", "video"]);
+]), _e = /* @__PURE__ */ new Set(["metric", "gauge", "progress", "header", "code", "rating", "video"]);
 function Y(e, t = 0) {
   const a = [], r = [];
   if (t > ie)
@@ -49,7 +49,7 @@ function Y(e, t = 0) {
   if (typeof i.widget != "string" || i.widget.length === 0)
     return a.push('Required field "widget" must be a non-empty string'), { valid: !1, errors: a, warnings: r };
   const s = i.widget;
-  if (i.type !== void 0 && i.type !== "u-widget" && a.push('"type" must be "u-widget" if specified'), i.fields !== void 0 && i.formdown !== void 0 && a.push('"fields" and "formdown" are mutually exclusive'), i.data !== void 0 && (xe.has(s) && !Array.isArray(i.data) && a.push(`"${s}" expects "data" to be an array, got ${typeof i.data}`), $e.has(s) && (Array.isArray(i.data) || typeof i.data != "object") && a.push(`"${s}" expects "data" to be an object, got ${Array.isArray(i.data) ? "array" : typeof i.data}`)), s === "compose") {
+  if (i.type !== void 0 && i.type !== "u-widget" && a.push('"type" must be "u-widget" if specified'), i.fields !== void 0 && i.formdown !== void 0 && a.push('"fields" and "formdown" are mutually exclusive'), i.data !== void 0 && ($e.has(s) && !Array.isArray(i.data) && a.push(`"${s}" expects "data" to be an array, got ${typeof i.data}`), _e.has(s) && (Array.isArray(i.data) || typeof i.data != "object") && a.push(`"${s}" expects "data" to be an object, got ${Array.isArray(i.data) ? "array" : typeof i.data}`)), s === "compose") {
     if (!Array.isArray(i.children))
       a.push('"compose" widget requires a "children" array');
     else
@@ -70,11 +70,11 @@ function Y(e, t = 0) {
   if (Array.isArray(i.fields))
     for (let n = 0; n < i.fields.length; n++) {
       const d = i.fields[n];
-      d == null || typeof d != "object" || typeof d.field != "string" ? a.push(`fields[${n}] must have a "field" string property`) : d.type != null && !ye.has(d.type) && r.push(`fields[${n}].type "${d.type}" is not a recognized field type`);
+      d == null || typeof d != "object" || typeof d.field != "string" ? a.push(`fields[${n}] must have a "field" string property`) : d.type != null && !xe.has(d.type) && r.push(`fields[${n}].type "${d.type}" is not a recognized field type`);
     }
   if (typeof i.formdown == "string" && i.formdown.length > 0 && !i.fields)
     try {
-      ve()(i.formdown);
+      be()(i.formdown);
     } catch {
       r.push("formdown string could not be parsed — check syntax");
     }
@@ -84,7 +84,7 @@ function Y(e, t = 0) {
       (d == null || typeof d != "object" || typeof d.label != "string" || typeof d.action != "string") && a.push(`actions[${n}] must have "label" and "action" string properties`);
     }
   if (i.mapping && typeof i.mapping == "object" && i.data) {
-    const n = i.mapping, d = _e(i.data);
+    const n = i.mapping, d = ke(i.data);
     if (d)
       for (const c of ["x", "y", "label", "value", "color", "size", "axis", "primary", "secondary", "icon", "avatar", "trailing"]) {
         const p = n[c];
@@ -95,7 +95,7 @@ function Y(e, t = 0) {
   }
   return { valid: a.length === 0, errors: a, warnings: r };
 }
-function _e(e) {
+function ke(e) {
   if (Array.isArray(e) && e.length > 0 && e[0] && typeof e[0] == "object")
     return new Set(Object.keys(e[0]));
   if (e && typeof e == "object" && !Array.isArray(e))
@@ -104,7 +104,7 @@ function _e(e) {
 function Dt(e) {
   return Y(e).valid;
 }
-const se = ["B", "KB", "MB", "GB", "TB"], ke = /* @__PURE__ */ new Set([
+const se = ["B", "KB", "MB", "GB", "TB"], ze = /* @__PURE__ */ new Set([
   "KRW",
   "JPY",
   "VND",
@@ -124,7 +124,7 @@ const se = ["B", "KB", "MB", "GB", "TB"], ke = /* @__PURE__ */ new Set([
   "XOF",
   "XPF"
 ]);
-function ze(e, t, a) {
+function pe(e, t, a) {
   if (e == null) return "";
   const [r, i] = t?.split(":") ?? [];
   switch (r) {
@@ -153,7 +153,7 @@ function Ae(e, t, a) {
   if (isNaN(r)) return String(e);
   const i = t || "USD";
   try {
-    const s = ke.has(i.toUpperCase());
+    const s = ze.has(i.toUpperCase());
     return new Intl.NumberFormat(a, {
       style: "currency",
       currency: i,
@@ -322,7 +322,7 @@ const R = {
 function jt(e, t) {
   L.set(e.toLowerCase(), { ...R, ...t });
 }
-function pe(e) {
+function ue(e) {
   if (!e) return R;
   const t = e.toLowerCase();
   if (L.has(t)) return L.get(t);
@@ -351,14 +351,15 @@ function Ie(e) {
   if (typeof document < "u" && document.documentElement?.lang)
     return document.documentElement.lang;
 }
-var Ne = Object.defineProperty, Fe = Object.getOwnPropertyDescriptor, ue = (e, t, a, r) => {
+var Ne = Object.defineProperty, Fe = Object.getOwnPropertyDescriptor, ge = (e, t, a, r) => {
   for (var i = r > 1 ? void 0 : r ? Fe(t, a) : t, s = e.length - 1, n; s >= 0; s--)
     (n = e[s]) && (i = (r ? n(t, a, i) : n(i)) || i);
   return r && i && Ne(t, a, i), i;
 };
-function ne(e) {
+function ne(e, t) {
+  const a = e.value, r = e.format;
   return {
-    value: e.value ?? 0,
+    value: r ? pe(a, r, t) : a ?? 0,
     label: e.label,
     unit: e.unit,
     prefix: e.prefix,
@@ -366,7 +367,9 @@ function ne(e) {
     change: e.change,
     trend: e.trend,
     icon: e.icon,
-    description: e.description
+    description: e.description,
+    format: e.format,
+    variant: e.variant
   };
 }
 let B = class extends y {
@@ -374,20 +377,22 @@ let B = class extends y {
     super(...arguments), this.spec = null;
   }
   render() {
-    return this.spec?.data ? this.spec.widget === "stat-group" ? this.renderStatGroup() : this.renderMetric(ne(this.spec.data)) : l;
+    if (!this.spec?.data) return l;
+    const e = this.spec.options?.locale;
+    return this.spec.widget === "stat-group" ? this.renderStatGroup(e) : this.renderMetric(ne(this.spec.data, e));
   }
-  renderStatGroup() {
-    const e = this.spec.data;
-    return Array.isArray(e) ? o`
+  renderStatGroup(e) {
+    const t = this.spec.data;
+    return Array.isArray(t) ? o`
       <div class="stat-group" part="stat-group">
-        ${e.map((t) => this.renderMetric(ne(t)))}
+        ${t.map((a) => this.renderMetric(ne(a, e)))}
       </div>
     ` : l;
   }
   renderMetric(e) {
     const t = e.trend === "up" ? "↑" : e.trend === "down" ? "↓" : e.trend === "flat" ? "→" : "", a = e.label ? `${e.label}: ${e.prefix ?? ""}${e.value}${e.unit ?? ""}${e.suffix ?? ""}` : void 0;
     return o`
-      <div class="metric" part="metric" aria-label=${a ?? l}>
+      <div class="metric" part="metric" aria-label=${a ?? l} data-variant=${e.variant ?? l}>
         ${e.icon ? o`<div class="metric-icon" part="icon">${e.icon}</div>` : l}
         ${e.label ? o`<div class="metric-label" part="label">${e.label}</div>` : l}
         <div class="metric-value" part="value">
@@ -464,6 +469,12 @@ B.styles = [b, w`
     .metric-icon { font-size: 1.25rem; line-height: 1; margin-bottom: 2px; }
     .metric-description { font-size: 0.75rem; color: var(--u-widget-text-secondary, #64748b); margin-top: 2px; line-height: 1.3; }
 
+    /* ── variant colors ── */
+    .metric[data-variant="success"] .metric-value { color: var(--u-widget-positive, #16a34a); }
+    .metric[data-variant="danger"] .metric-value { color: var(--u-widget-negative, #dc2626); }
+    .metric[data-variant="warning"] .metric-value { color: var(--u-widget-warning, #d97706); }
+    .metric[data-variant="info"] .metric-value { color: var(--u-widget-info, #2563eb); }
+
     /* ── stat-group ── */
     .stat-group {
       display: flex;
@@ -501,13 +512,13 @@ B.styles = [b, w`
       }
     }
   `];
-ue([
+ge([
   h({ type: Object })
 ], B.prototype, "spec", 2);
-B = ue([
+B = ge([
   x("u-metric")
 ], B);
-var Me = Object.defineProperty, Te = Object.getOwnPropertyDescriptor, ge = (e, t, a, r) => {
+var Me = Object.defineProperty, Te = Object.getOwnPropertyDescriptor, fe = (e, t, a, r) => {
   for (var i = r > 1 ? void 0 : r ? Te(t, a) : t, s = e.length - 1, n; s >= 0; s--)
     (n = e[s]) && (i = (r ? n(t, a, i) : n(i)) || i);
   return r && i && Me(t, a, i), i;
@@ -703,10 +714,10 @@ W.styles = [b, w`
       }
     }
   `];
-ge([
+fe([
   h({ type: Object })
 ], W.prototype, "spec", 2);
-W = ge([
+W = fe([
   x("u-gauge")
 ], W);
 var qe = Object.defineProperty, Be = Object.getOwnPropertyDescriptor, C = (e, t, a, r) => {
@@ -780,7 +791,7 @@ let z = class extends y {
   }
   get _locale() {
     const e = this.spec?.options?.locale;
-    return pe(typeof e == "string" ? e : void 0);
+    return ue(typeof e == "string" ? e : void 0);
   }
   renderTable() {
     const e = this.spec.data, t = this.getColumns(e), a = this._locale, r = this.spec.options?.sortable !== !1, i = !!this.spec.options?.searchable, s = !!this.spec.options?.compact, n = Number(this.spec.options?.pageSize) || 0, d = this._searchQuery ? this.filterData(e, t) : e, c = this._sortField && this._sortDir ? this.sortData(d) : d, p = n > 0 ? Math.max(1, Math.ceil(c.length / n)) : 1, g = Math.min(this._page, p - 1), f = n > 0 ? c.slice(g * n, (g + 1) * n) : c, u = i ? o`
@@ -835,7 +846,7 @@ let z = class extends y {
                 >
                   ${t.map(
         (_) => o`<td data-align=${_.align ?? "left"} part="td"
-                        >${ze(v[_.field], _.format, typeof this.spec.options?.locale == "string" ? this.spec.options.locale : void 0)}</td
+                        >${pe(v[_.field], _.format, typeof this.spec.options?.locale == "string" ? this.spec.options.locale : void 0)}</td
                       >`
       )}
                 </tr>
@@ -1498,7 +1509,7 @@ let j = class extends y {
   }
   get _locale() {
     const e = this.spec?.options?.locale;
-    return pe(typeof e == "string" ? e : void 0);
+    return ue(typeof e == "string" ? e : void 0);
   }
   _validate() {
     const e = this.spec?.fields ?? [], t = {}, a = this._locale;
@@ -1943,7 +1954,7 @@ Z([
 I = Z([
   x("u-compose")
 ], I);
-var Ge = Object.defineProperty, Xe = Object.getOwnPropertyDescriptor, fe = (e, t, a, r) => {
+var Ge = Object.defineProperty, Xe = Object.getOwnPropertyDescriptor, he = (e, t, a, r) => {
   for (var i = r > 1 ? void 0 : r ? Xe(t, a) : t, s = e.length - 1, n; s >= 0; s--)
     (n = e[s]) && (i = (r ? n(t, a, i) : n(i)) || i);
   return r && i && Ge(t, a, i), i;
@@ -2193,13 +2204,13 @@ K.styles = [b, w`
       }
     }
   `];
-fe([
+he([
   h({ type: Object })
 ], K.prototype, "spec", 2);
-K = fe([
+K = he([
   x("u-content")
 ], K);
-var Je = Object.defineProperty, Ye = Object.getOwnPropertyDescriptor, he = (e, t, a, r) => {
+var Je = Object.defineProperty, Ye = Object.getOwnPropertyDescriptor, me = (e, t, a, r) => {
   for (var i = r > 1 ? void 0 : r ? Ye(t, a) : t, s = e.length - 1, n; s >= 0; s--)
     (n = e[s]) && (i = (r ? n(t, a, i) : n(i)) || i);
   return r && i && Je(t, a, i), i;
@@ -2329,10 +2340,10 @@ H.styles = [b, w`
       }
     }
   `];
-he([
+me([
   h({ type: Object })
 ], H.prototype, "spec", 2);
-H = he([
+H = me([
   x("u-kv")
 ], H);
 var Ze = Object.defineProperty, Qe = Object.getOwnPropertyDescriptor, G = (e, t, a, r) => {
@@ -2400,7 +2411,7 @@ function D(e, t) {
 `).map((r) => `<span class="hl-${t}">${r}</span>`).join(`
 `) : `<span class="hl-${t}">${a}</span>`;
 }
-function me(e, t, a) {
+function ve(e, t, a) {
   let r = t + 1;
   for (; r < e.length; ) {
     if (e[r] === "\\") {
@@ -2435,7 +2446,7 @@ function it(e, t) {
     }
     const f = e[p];
     if (f === '"' || f === "'" || f === "`" && d) {
-      const u = me(e, p, f);
+      const u = ve(e, p, f);
       c += D(e.slice(p, u), "s"), p = u;
       continue;
     }
@@ -2476,7 +2487,7 @@ function st(e) {
   for (; a < r; ) {
     const i = e[a];
     if (i === '"') {
-      const n = me(e, a, '"'), d = e.slice(a, n), c = e.slice(n).trimStart();
+      const n = ve(e, a, '"'), d = e.slice(a, n), c = e.slice(n).trimStart();
       t += D(d, c[0] === ":" ? "k" : "s"), a = n;
       continue;
     }
@@ -3731,11 +3742,11 @@ let E = class extends y {
     const e = Y(this.spec);
     if (!e.valid)
       return this.renderError(e.errors);
-    const t = we(this.spec);
+    const t = ye(this.spec);
     return this.renderWidget(t);
   }
   renderWidget(e) {
-    const t = e.widget, a = e.mapping ?? be(t, e.data);
+    const t = e.widget, a = e.mapping ?? we(t, e.data);
     let r = a ? { ...e, mapping: a } : e;
     const i = Ie(this.locale);
     i && !r.options?.locale && (r = {
@@ -4100,14 +4111,14 @@ E = J([
 export {
   E as UWidget,
   A as formatTemplate,
-  ze as formatValue,
+  pe as formatValue,
   Ot as getDefaultLocale,
   Et as getEffectiveLocale,
-  ve as getFormdownParser,
-  pe as getLocaleStrings,
-  be as infer,
+  be as getFormdownParser,
+  ue as getLocaleStrings,
+  we as infer,
   Dt as isWidgetSpec,
-  we as normalize,
+  ye as normalize,
   Nt as parseFormdown,
   Ft as registerFormdownParser,
   jt as registerLocale,