docs: expand minimal-json-render into an all-components dashboard

- Rework the example spec into a project dashboard that exercises every
  base-catalog component (Stack, Card, Text, Badge, Button, Icon, Divider,
  TextInput, Switch, KeyValueTable, DataTable, CodeBlock, Progress, Tree),
  with live state, two-way bindings, and three actions (Refresh re-samples the
  Progress bars, Deploy toggles DataTable loading and appends a module, Save
  sends bound form params the server writes back).
- Make Button icons dependency-free: render the runtime-resolved Icon and a CSS
  spinner instead of static `i-ph:*` classes; use a text caret in Card so
  neither component requires an icon font in the consuming app.

Created with the help of an agent.

Author: antfubot

examples/minimal-json-render/README.md

@@ -2,16 +2,23 @@
 
 A standalone devframe that serves a **JSON-render view**: the server authors an
 `@json-render/core` spec once, and the browser renders it with the official
-`@devframes/json-render-ui` Vue frontend. It exercises the whole opt-in
-JSON-render stack end to end:
+`@devframes/json-render-ui` Vue frontend. The spec is a small **project
+dashboard** that exercises **every base-catalog component** — `Stack`, `Card`,
+`Text`, `Badge`, `Button`, `Icon`, `Divider`, `TextInput`, `Switch`,
+`KeyValueTable`, `DataTable`, `CodeBlock`, `Progress`, and `Tree` — end to end:
 
 - **`@devframes/json-render/node`** — `createJsonRenderView(ctx, { id, spec })`
   registers the spec as shared state, validates element props at ingress, and
   hands back a handle with `update` / `patchState` / `dispose`.
 - **live state** — the server ticks `uptime` every second via `patchState`, so
-  the view updates without replacing the whole spec.
-- **action bridge** — the `Refresh` button's `press` action is dispatched as an
-  RPC call of the same name; the handler bumps a counter and patches state.
+  bound values (`{ $state: '/…' }`) update without replacing the whole spec.
+- **two-way bindings** — the `Display name` input and the two switches write back
+  into state via `{ $bindState: '/form/…' }`.
+- **action bridge** — `Refresh` re-samples the coverage/bundle `Progress` bars;
+  `Deploy` flips the `DataTable` into a loading state and appends a module;
+  `Save` sends the bound form values as action params and the server writes the
+  name into the `KeyValueTable`. Each is dispatched as an RPC call of the same
+  name, with per-action loading and error surfacing.
 - **`@devframes/json-render-ui`** — the SPA (`src/client`) subscribes to the
   view's shared state and renders it with `JsonRenderView`. The app supplies the
   frontend lib; devframe serves the SPA.

examples/minimal-json-render/src/devframe.ts

@@ -4,36 +4,123 @@ import { createJsonRenderView } from '@devframes/json-render/node'
 import { defineRpcFunction } from 'devframe'
 import { defineDevframe } from 'devframe/types'
 import pkg from '../package.json' with { type: 'json' }
-import { REFRESH_ACTION, VIEW_ID } from './shared.ts'
+import { DEPLOY_ACTION, REFRESH_ACTION, SAVE_ACTION, VIEW_ID } from './shared.ts'
 
 const BASE_PATH = '/__minimal-json-render/'
 const distDir = fileURLToPath(new URL('../dist/client', import.meta.url))
 
-// A server-authored spec. Values marked `{ $state: '/...' }` resolve from the
-// view's live state at render time, so patching state updates the UI without a
-// whole-spec replacement.
+const VITE_CONFIG = `import { defineConfig } from 'vite'
+
+export default defineConfig({
+  base: './',
+  build: { outDir: 'dist/client' },
+})
+`
+
+// Initial state model. Every value the spec reads via \`{ $state: '/…' }\`
+// resolves from here and updates live as the server patches it.
+const initialState = {
+  project: { name: 'acme-app', version: '1.4.2', license: 'MIT', repository: 'github.com/acme/app' },
+  metrics: { coverage: 82, bundle: 64 },
+  modules: [
+    { name: '@acme/core', size: '42 kB', status: 'ok' },
+    { name: '@acme/ui', size: '88 kB', status: 'ok' },
+    { name: '@acme/cli', size: '17 kB', status: 'stale' },
+  ],
+  deps: {
+    runtime: { vue: '^3.5', birpc: '^4.0' },
+    dev: { vite: '^8.1', tsdown: '^0.22', vitest: '^4.1' },
+  },
+  form: { name: '', darkMode: true, notifications: false },
+  building: false,
+  uptime: 0,
+}
+
+// A server-authored spec exercising every base-catalog component. Values marked
+// `{ $state: '/…' }` resolve from live state; `{ $bindState: '/…' }` are
+// two-way inputs that write back into it.
 const spec: DevframeJsonRenderSpec = {
   root: 'root',
   elements: {
-    root: { type: 'Stack', props: { gap: 14 }, children: ['title', 'card', 'actions'] },
-    title: { type: 'Text', props: { text: 'JSON-render demo', variant: 'heading' }, children: [] },
-    card: { type: 'Card', props: { title: 'Live metrics' }, children: ['metrics'] },
-    metrics: { type: 'Stack', props: { gap: 8 }, children: ['uptimeRow', 'refreshRow'] },
-    uptimeRow: { type: 'Stack', props: { direction: 'row', gap: 8 }, children: ['uptimeLabel', 'uptimeValue'] },
-    uptimeLabel: { type: 'Text', props: { text: 'Uptime (s)', variant: 'caption' }, children: [] },
-    uptimeValue: { type: 'Text', props: { text: { $state: '/uptime' }, variant: 'body' }, children: [] },
-    refreshRow: { type: 'Stack', props: { direction: 'row', gap: 8 }, children: ['refreshLabel', 'refreshValue'] },
-    refreshLabel: { type: 'Text', props: { text: 'Manual refreshes', variant: 'caption' }, children: [] },
-    refreshValue: { type: 'Text', props: { text: { $state: '/refreshes' }, variant: 'body' }, children: [] },
-    actions: { type: 'Stack', props: { direction: 'row', gap: 8 }, children: ['refresh'] },
-    refresh: {
+    root: { type: 'Stack', props: { gap: 16 }, children: ['header', 'overview', 'settings', 'modules', 'config', 'tree', 'footerDivider', 'footer'] },
+
+    // ── Header ────────────────────────────────────────────────────────────
+    header: { type: 'Stack', props: { direction: 'row', gap: 10, align: 'center', justify: 'between' }, children: ['headLeft', 'headRight'] },
+    headLeft: { type: 'Stack', props: { direction: 'row', gap: 8, align: 'center' }, children: ['logo', 'headTitle'] },
+    logo: { type: 'Icon', props: { name: 'ph:cube-duotone', size: 26 }, children: [] },
+    headTitle: { type: 'Text', props: { text: 'Acme Dashboard', variant: 'heading' }, children: [] },
+    headRight: { type: 'Stack', props: { direction: 'row', gap: 8, align: 'center' }, children: ['status', 'refreshBtn', 'deployBtn'] },
+    status: { type: 'Badge', props: { text: 'healthy', variant: 'success' }, children: [] },
+    refreshBtn: {
       type: 'Button',
-      props: { label: 'Refresh', variant: 'primary', icon: 'arrow-clockwise' },
+      props: { label: 'Refresh', variant: 'ghost', icon: 'ph:arrow-clockwise' },
       on: { press: { action: REFRESH_ACTION } },
       children: [],
     },
+    deployBtn: {
+      type: 'Button',
+      props: { label: 'Deploy', variant: 'primary', icon: 'ph:rocket-launch' },
+      on: { press: { action: DEPLOY_ACTION } },
+      children: [],
+    },
+
+    // ── Overview: KeyValueTable + Progress ────────────────────────────────
+    overview: { type: 'Card', props: { title: 'Overview' }, children: ['overviewBody'] },
+    overviewBody: { type: 'Stack', props: { gap: 14 }, children: ['meta', 'coverage', 'bundle'] },
+    meta: { type: 'KeyValueTable', props: { data: { $state: '/project' } }, children: [] },
+    coverage: { type: 'Progress', props: { label: 'Test coverage', value: { $state: '/metrics/coverage' }, max: 100 }, children: [] },
+    bundle: { type: 'Progress', props: { label: 'Bundle budget', value: { $state: '/metrics/bundle' }, max: 100 }, children: [] },
+
+    // ── Settings: TextInput + Switch + Divider + Button ───────────────────
+    settings: { type: 'Card', props: { title: 'Settings', collapsible: true }, children: ['settingsBody'] },
+    settingsBody: { type: 'Stack', props: { gap: 10 }, children: ['nameInput', 'greeting', 'prefsDivider', 'darkSwitch', 'notifSwitch', 'saveBtn'] },
+    nameInput: { type: 'TextInput', props: { label: 'Display name', placeholder: 'Type your name…', value: { $bindState: '/form/name' } }, children: [] },
+    greeting: { type: 'Text', props: { text: { $state: '/form/name' }, variant: 'caption', color: 'primary' }, children: [] },
+    prefsDivider: { type: 'Divider', props: { label: 'preferences' }, children: [] },
+    darkSwitch: { type: 'Switch', props: { label: 'Dark mode', value: { $bindState: '/form/darkMode' } }, children: [] },
+    notifSwitch: { type: 'Switch', props: { label: 'Email notifications', value: { $bindState: '/form/notifications' } }, children: [] },
+    saveBtn: {
+      type: 'Button',
+      props: { label: 'Save settings', variant: 'secondary', icon: 'ph:floppy-disk' },
+      // Bound values are resolved into the action params before dispatch, so the
+      // server receives whatever the user typed/toggled.
+      on: { press: { action: SAVE_ACTION, params: { name: { $state: '/form/name' } } } },
+      children: [],
+    },
+
+    // ── Modules: DataTable (loading bound to /building) ───────────────────
+    modules: { type: 'Card', props: { title: 'Modules' }, children: ['modulesTable'] },
+    modulesTable: {
+      type: 'DataTable',
+      props: {
+        columns: [
+          { key: 'name', label: 'Module' },
+          { key: 'size', label: 'Size' },
+          { key: 'status', label: 'Status' },
+        ],
+        rows: { $state: '/modules' },
+        height: 180,
+        loading: { $state: '/building' },
+      },
+      children: [],
+    },
+
+    // ── Config: CodeBlock ─────────────────────────────────────────────────
+    config: { type: 'Card', props: { title: 'Config' }, children: ['code'] },
+    code: { type: 'CodeBlock', props: { filename: 'vite.config.ts', language: 'ts', code: VITE_CONFIG }, children: [] },
+
+    // ── Dependency tree: Tree ─────────────────────────────────────────────
+    tree: { type: 'Card', props: { title: 'Dependency tree', collapsible: true, defaultCollapsed: true }, children: ['depTree'] },
+    depTree: { type: 'Tree', props: { data: { $state: '/deps' }, defaultExpanded: true }, children: [] },
+
+    // ── Footer ────────────────────────────────────────────────────────────
+    footerDivider: { type: 'Divider', props: {}, children: [] },
+    footer: { type: 'Stack', props: { direction: 'row', gap: 6 }, children: ['footerLabel', 'footerValue', 'footerSuffix'] },
+    footerLabel: { type: 'Text', props: { text: 'Rendered from a JSON-render spec · uptime', variant: 'caption', color: 'faint' }, children: [] },
+    footerValue: { type: 'Text', props: { text: { $state: '/uptime' }, variant: 'caption', color: 'faint' }, children: [] },
+    footerSuffix: { type: 'Text', props: { text: 's', variant: 'caption', color: 'faint' }, children: [] },
   },
-  state: { uptime: 0, refreshes: 0 },
+  state: initialState,
 }
 
 export default defineDevframe({
@@ -50,25 +137,65 @@ export default defineDevframe({
     port: 9877,
     distDir,
     // Single-user localhost demo — skip the trust handshake so the served SPA
-    // can call the action RPC without an OTP round-trip.
+    // can call the action RPCs without an OTP round-trip.
     auth: false,
   },
   spa: { loader: 'none' },
   setup(ctx) {
     const view = createJsonRenderView(ctx, { id: VIEW_ID, spec })
 
     // The action bridge dispatches a spec action as an RPC call of the same
-    // name. Register the handler for the Button's `press` action; it bumps a
-    // counter and patches the view state (which broadcasts to the SPA).
-    let refreshes = 0
+    // name. `Refresh` re-samples the metrics.
     ctx.rpc.register(defineRpcFunction({
       name: REFRESH_ACTION,
       type: 'query',
       jsonSerializable: true,
       handler: () => {
-        refreshes += 1
-        view.patchState([{ op: 'replace', path: '/refreshes', value: refreshes }])
-        return { refreshes }
+        const coverage = 70 + Math.floor(Math.random() * 30)
+        const bundle = 40 + Math.floor(Math.random() * 55)
+        view.patchState([
+          { op: 'replace', path: '/metrics/coverage', value: coverage },
+          { op: 'replace', path: '/metrics/bundle', value: bundle },
+        ])
+        return { coverage, bundle }
+      },
+    }))
+
+    // `Deploy` flips the DataTable into a loading state, then appends a module —
+    // demonstrating the per-action loading + a live spec/state change.
+    let deployed = 0
+    ctx.rpc.register(defineRpcFunction({
+      name: DEPLOY_ACTION,
+      type: 'query',
+      jsonSerializable: true,
+      handler: () => {
+        view.patchState([{ op: 'replace', path: '/building', value: true }])
+        setTimeout(() => {
+          deployed += 1
+          const modules = [
+            ...(view.value().state?.modules as unknown[] ?? []),
+            { name: `@acme/edge-${deployed}`, size: '9 kB', status: 'ok' },
+          ]
+          view.patchState([
+            { op: 'replace', path: '/modules', value: modules },
+            { op: 'replace', path: '/building', value: false },
+          ])
+        }, 1200)
+        return { building: true }
+      },
+    }))
+
+    // `Save` receives the bound form values as params (resolved client-side from
+    // `$state`) and writes the display name into the project metadata.
+    ctx.rpc.register(defineRpcFunction({
+      name: SAVE_ACTION,
+      type: 'query',
+      jsonSerializable: true,
+      handler: (params?: { name?: string }) => {
+        const name = params?.name?.trim()
+        if (name)
+          view.patchState([{ op: 'replace', path: '/project/name', value: name }])
+        return { saved: true }
       },
     }))
 

examples/minimal-json-render/src/shared.ts

@@ -1,7 +1,7 @@
 // Shared constants used by both the node devframe and the browser SPA.
 
 /** Author-supplied, stable view id. */
-export const VIEW_ID = 'demo'
+export const VIEW_ID = 'dashboard'
 
 /**
  * The view's shared-state key. `createJsonRenderView` derives it as
@@ -11,5 +11,8 @@ export const VIEW_ID = 'demo'
  */
 export const STATE_KEY = `devframe:json-render:global:${VIEW_ID}`
 
-/** The action the demo Button dispatches — an RPC method the server registers. */
+// Spec action names dispatched by the bridge — each is an RPC method the server
+// registers.
 export const REFRESH_ACTION = 'minimal-json-render:refresh'
+export const DEPLOY_ACTION = 'minimal-json-render:deploy'
+export const SAVE_ACTION = 'minimal-json-render:save'

packages/json-render-ui/src/components/controls.ts

@@ -1,10 +1,12 @@
 import type { JrComponent } from './_shared'
 import { useBoundProp } from '@json-render/vue'
 import { h } from 'vue'
+import { Icon } from './icon'
 
 interface ButtonProps {
   label?: string
   variant?: 'primary' | 'secondary' | 'ghost' | 'danger'
+  /** Icon name resolved at runtime (e.g. `ph:arrow-clockwise`). */
   icon?: string
   disabled?: boolean
   loading?: boolean
@@ -33,10 +35,12 @@ export const Button: JrComponent<ButtonProps> = ({ props, on }) => {
       },
     },
     [
+      // Dependency-free CSS spinner (no icon font needed); the dynamic Icon
+      // resolves the button's icon at runtime, like the standalone Icon.
       busy
-        ? h('span', { class: 'i-ph:spinner animate-spin' })
+        ? h('span', { class: 'inline-block h-3.5 w-3.5 rounded-full border-2 border-current border-t-transparent animate-spin' })
         : props.icon
-          ? h('span', { class: `i-ph:${props.icon}` })
+          ? Icon({ props: { name: props.icon, size: 16 } } as Parameters<typeof Icon>[0])
           : null,
       props.label ? h('span', props.label) : null,
     ],

packages/json-render-ui/src/components/layout.ts

@@ -62,7 +62,7 @@ export const Card: JrComponent<CardProps> = ({ props, children, loading }) => {
       h(
         'summary',
         { class: 'flex items-center justify-between px2 py1.5 border-b border-base color-base font-medium text-sm cursor-pointer select-none list-none' },
-        [h('span', props.title ?? ''), h('span', { class: 'i-ph:caret-down color-faint' })],
+        [h('span', props.title ?? ''), h('span', { class: 'color-faint text-xs' }, '▾')],
       ),
       h('div', { class: 'p2' }, [body]),
     ])