u-widgets

Declarative, data-driven widget system for visualization and input.

Define your data. Map it to visual channels. The renderer does the rest.

{
  "widget": "chart.bar",
  "data": [
    { "name": "A", "value": 30 },
    { "name": "B", "value": 70 },
    { "name": "C", "value": 45 }
  ]
}

That's a complete bar chart. Mapping is auto-inferred from data shape.

Installation

npm install @iyulab/u-widgets

<script type="module">
  import '@iyulab/u-widgets';
  // For chart support (requires echarts peer dependency):
  // import '@iyulab/u-widgets/charts';
  // For math expression support (requires katex peer dependency):
  // import '@iyulab/u-widgets/math';
</script>

<u-widget .spec=${{ widget: 'metric', data: { value: 42, unit: 'users' } }}></u-widget>

CDN

<script src="https://cdn.jsdelivr.net/npm/@iyulab/u-widgets/dist/u-widgets.global.js"></script>

Widget Types

| Widget | Purpose | |---|---| | chart.bar, chart.line, chart.area, chart.pie, chart.scatter, chart.radar | Data visualization | | metric, stat-group | KPI numbers | | gauge, progress | Value within range | | table, list, kv | Structured data | | code, citation, status, steps, rating, video, gallery | Content display | | math | LaTeX math expressions (requires katex) | | form, confirm | User input | | compose | Widget composition |

Quick Examples

// Metric
{ "widget": "metric", "data": { "value": 1284, "unit": "EA", "change": 12.5, "trend": "up" } }

// Table (columns auto-inferred)
{ "widget": "table", "data": [{ "name": "Alice", "role": "Engineer" }, { "name": "Bob", "role": "Designer" }] }

// Form
{ "widget": "form", "fields": [{ "field": "name", "type": "text", "required": true }], "actions": [{ "label": "Submit", "action": "submit" }] }

// Math (requires u-widgets/math entry point)
{ "widget": "math", "data": { "expression": "E = mc^2" } }

// Compose
{ "widget": "compose", "layout": "grid", "children": [{ "widget": "metric", "data": { "value": 42 } }, { "widget": "gauge", "data": { "value": 73 } }] }

Chart Options

XY charts (chart.bar, chart.line, chart.area, chart.scatter) support declarative options that eliminate the need for ECharts passthrough:

Reference Lines

{
  "widget": "chart.line",
  "data": [{ "month": "Jan", "rate": 82 }, { "month": "Feb", "rate": 105 }],
  "options": {
    "referenceLines": [
      { "axis": "y", "value": 100, "label": "Target", "color": "#16a34a", "style": "dashed" }
    ]
  }
}

Per-Series Styles

{
  "widget": "chart.line",
  "data": [{ "month": "Jan", "orders": 150, "qa": 80, "support": 45 }],
  "mapping": { "x": "month", "y": ["orders", "qa", "support"] },
  "options": {
    "series": [
      { "color": "#f97316" },
      { "color": "#8b5cf6" },
      { "color": "#3b82f6", "lineStyle": { "type": "dashed" } }
    ]
  }
}

Each entry in options.series maps 1:1 to the mapping.y array. Supported overrides: color, lineStyle, symbol, label, type, yAxisIndex.

The type override (and options.echarts.series[].type passthrough) may only request a registered series: bar, line, pie, scatter, radar, heatmap, boxplot, funnel, treemap, custom. Any other type (graph, sankey, gauge, sunburst, …) merges into the option but does not render — u-widgets emits a dev warning pointing to @iyulab/flex-chart for advanced chart types (this is the same tree-shakeable boundary as heavy interaction components like dataZoom/toolbox).

custom (ECharts custom series, e.g. Gantt/timeline) is registered and renders directly, but supply it via options.echarts passthrough, not options.series — the options.series per-entry override only carries the style keys listed above (color/lineStyle/symbol/label/type/yAxisIndex), so a custom series' renderItem/encode would be dropped:

{
  "widget": "chart.bar",
  "data": [{ "task": "Design", "start": 0, "end": 3 }],
  "options": { "echarts": { "series": [{ "type": "custom", "renderItem": "…" }] } }
}

Axis Label Format

{
  "widget": "chart.bar",
  "data": [{ "month": "Jan", "revenue": 12000000 }],
  "options": {
    "yFormat": { "type": "currency", "currency": "KRW" },
    "locale": "ko-KR"
  }
}

xFormat / yFormat accept: type (number, currency, percent, date, bytes), prefix, suffix, currency, decimals.

Events

widget.addEventListener('u-widget-event', (e) => {
  console.log(e.detail); // { type, widget, id?, action?, data? }
});

React

@iyulab/u-widgets/react 서브패스가 <u-widget>의 일급 React 래퍼 UWidget을 제공합니다. spec을 문자열로 직렬화(JSON.stringify)하지 않고 객체 prop으로 그대로 넘길 수 있으며, u-widget-event는 onWidgetEvent 콜백 prop으로 노출됩니다.

베이스 패키지를 별도로 import해 커스텀 엘리먼트를 등록해야 합니다. @lit/react·react는 peerDependency이므로 함께 설치합니다.

npm install @iyulab/u-widgets @lit/react react

import '@iyulab/u-widgets';                        // <u-widget> 등록 (side-effect)
import { UWidget } from '@iyulab/u-widgets/react';
import type { UWidgetSpec } from '@iyulab/u-widgets/react';

function Dashboard() {
  return (
    <UWidget
      spec={{ widget: 'stat-group', data: [{ label: 'Active', value: 42 }, { label: 'Errors', value: 3 }] }}
      onWidgetEvent={(e) => console.log(e.detail)} // e.detail: UWidgetEvent
    />
  );
}

• UWidgetSpec/UWidgetEvent/UWidgetAction 타입도 함께 re-export됩니다. onWidgetEvent은 CustomEvent를 받고 e.detail이 UWidgetEvent 페이로드입니다.
• 손수 <u-widget spec={JSON.stringify(spec)} /> 래퍼를 만들 필요가 없습니다 — 이 공식 래퍼가 객체 spec·타입드 이벤트를 처리합니다.

MCP Server

AI assistants can use u-widgets via MCP server:

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)

Wrap the official UWidget React wrapper (위 React 참고) in a client component so it registers the element and stays out of Server Components:

// components/widget.tsx
"use client";
import "@iyulab/u-widgets";                        // <u-widget> 등록
import { UWidget } from "@iyulab/u-widgets/react";
import type { UWidgetSpec } from "@iyulab/u-widgets/react";

export function Widget({ spec }: { spec: UWidgetSpec }) {
  return <UWidget spec={spec} />;
}

Use the wrapper from Server Components:

// 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:

import dynamic from "next/dynamic";
const Widget = dynamic(
  () => import("@/components/widget").then((m) => m.Widget),
  { ssr: false }
);

Documentation

• Widget Reference — Schema, mapping, options, theming
• MCP Server Guide — Setup for Claude Desktop, Claude Code, VS Code

License

MIT