@iyulab/u-widgets 0.4.1 → 0.6.0

package/README.md

@@ -1,5 +1,10 @@
 # u-widgets
 
+[![npm](https://img.shields.io/npm/v/@iyulab/u-widgets)](https://www.npmjs.com/package/@iyulab/u-widgets)
+[![npm MCP](https://img.shields.io/npm/v/@iyulab/u-widgets-mcp?label=mcp)](https://www.npmjs.com/package/@iyulab/u-widgets-mcp)
+[![license](https://img.shields.io/npm/l/@iyulab/u-widgets)](LICENSE)
+[![jsdelivr](https://data.jsdelivr.com/v1/package/npm/@iyulab/u-widgets/badge)](https://www.jsdelivr.com/package/npm/@iyulab/u-widgets)
+
 Declarative, data-driven widget system for visualization and input.
 
 Define your data. Map it to visual channels. The renderer does the rest.
@@ -83,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/themes/shadcn.css

@@ -0,0 +1,36 @@
+/**
+ * u-widgets Shadcn/ui + Tailwind CSS v4 Theme Preset
+ *
+ * Usage (CSS/PostCSS):
+ *   @import "@iyulab/u-widgets/themes/shadcn.css";
+ *
+ * Or (JavaScript):
+ *   import "@iyulab/u-widgets/themes/shadcn.css";
+ *
+ * Apply AFTER your Shadcn globals.css.
+ * Requires Shadcn/ui globals.css to define --primary, --background, etc.
+ */
+
+:root {
+  --u-widget-bg: hsl(var(--background));
+  --u-widget-surface: hsl(var(--muted));
+  --u-widget-text: hsl(var(--foreground));
+  --u-widget-text-secondary: hsl(var(--muted-foreground));
+  --u-widget-border: hsl(var(--border));
+  --u-widget-primary: hsl(var(--primary));
+  --u-widget-negative: hsl(var(--destructive));
+  /* Shadcn does not define --success / --warning; u-widget defaults remain */
+  --u-widget-radius: var(--radius, 6px);
+}
+
+/* Dark mode: syncs with Shadcn .dark class */
+.dark {
+  --u-widget-bg: hsl(var(--background));
+  --u-widget-surface: hsl(var(--muted));
+  --u-widget-text: hsl(var(--foreground));
+  --u-widget-text-secondary: hsl(var(--muted-foreground));
+  --u-widget-border: hsl(var(--border));
+  --u-widget-primary: hsl(var(--primary));
+  --u-widget-negative: hsl(var(--destructive));
+  --u-widget-radius: var(--radius, 6px);
+}

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

@@ -206,7 +206,16 @@ 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[];

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

@@ -327,7 +327,16 @@ 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[];

package/dist/u-widgets-tools.js

@@ -6,6 +6,7 @@ const v = {
   value: "Value field (pie/funnel/heatmap)",
   color: "Color grouping field (scatter)",
   size: "Size encoding field (scatter bubble)",
+  opacity: "Opacity encoding field (scatter bubble)",
   axis: "Axis field (radar indicators)",
   columns: "Column definitions (table)",
   primary: "Primary text field (list)",
@@ -336,7 +337,7 @@ const y = [
   // Composition
   { widget: "compose", category: "composition", description: "Combine multiple widgets with layout hints", mappingKeys: [], dataShape: "none" }
 ];
-function E(e) {
+function O(e) {
   if (!e) return [...y];
   const i = y.find((o) => o.widget === e);
   if (i) return T(i);
@@ -1130,7 +1131,7 @@ function T(e) {
     examples: s
   };
 }
-function O(e) {
+function E(e) {
   const i = A[e];
   if (i)
     return JSON.parse(JSON.stringify(i));
@@ -1364,9 +1365,9 @@ export {
   N as WIDGET_OPTIONS,
   j as autoSpec,
   S as getWidgetEvents,
-  E as help,
+  O as help,
   I as specSurface,
   q as suggestMapping,
-  O as template
+  E as template
 };
 //# sourceMappingURL=u-widgets-tools.js.map