@synopackageland/ui 0.5.8 → 0.6.0

package/docs/json-ui.md

@@ -0,0 +1,154 @@
+# Declarative DSM UI (`@synopackageland/ui/json`)
+
+The JSON entry point is a curated AI/declarative surface over the normal Vue
+SDK. It is intentionally smaller than the full component library. Ordinary
+application structure, settings, forms, dialogs, resource tables and state
+bindings can stay declarative; domain-specific views and business logic remain
+normal Vue/TypeScript extensions.
+
+It also supports responsive `AppShell` and `ResponsiveView` alternatives:
+one JSON spec renders as a DSM window or a phone view, and as a wide Portal
+page when its `AppShell` sets `wideLayout: "web"`.
+See [adaptive-layout.md](adaptive-layout.md).
+
+## Boundary
+
+Use JSON for repeated application interaction patterns:
+
+- DSM app shell, sidebar, toolbar, page header and tabs
+- settings/forms and ordinary validation/state binding
+- dialogs, callouts, empty/loading states and progress
+- simple resource collections/tables
+- action dispatch into host-owned backend functions
+
+Keep these in application code and expose them as extension components/actions:
+
+- domain-specific visualizations (treemap, topology, terminal, media canvas)
+- rich table rows/cells with domain actions
+- filesystem/NAS pickers or native DSM bridges
+- polling, retries, transactions, authorization and other business workflows
+
+This gives the declarative layer an escape hatch instead of expanding the DSL
+until it becomes another programming language.
+
+## Basic renderer
+
+```vue
+<script setup lang="ts">
+import { SynoJsonRenderer } from '@synopackageland/ui/json'
+import type { Spec } from '@synopackageland/ui/json'
+
+const spec: Spec = {
+  root: 'root',
+  state: { enabled: true },
+  elements: {
+    root: { type: 'AppRoot', props: { modalScope: 'app' }, children: ['shell'] },
+    shell: { type: 'AppShell', props: { minHeight: '0' }, children: ['page'] },
+    page: { type: 'Page', props: { width: 'readable' }, children: ['settings'] },
+    settings: { type: 'SettingsSection', props: { title: 'General', collapsible: false }, children: ['enabled'] },
+    enabled: { type: 'SettingsField', props: { label: 'Enabled' }, children: ['switch'] },
+    switch: { type: 'Switch', props: { checked: { $bindState: '/enabled' } }, children: [] },
+  },
+}
+</script>
+
+<template><SynoJsonRenderer :spec="spec" /></template>
+```
+
+## Real applications: extend, do not fork
+
+An application normally declares its backend actions and only the special
+renderers it needs. Spread the SDK definitions/renderers into the app catalog:
+
+```ts
+import { h } from 'vue'
+import {
+  defineCatalog,
+  defineRegistry,
+  jsonRenderVueSchema,
+  synoJsonComponentDefinitions,
+  synoJsonRenderers,
+  z,
+} from '@synopackageland/ui/json'
+import DownloadTaskTable from './DownloadTaskTable.vue'
+
+export const catalog = defineCatalog(jsonRenderVueSchema, {
+  components: {
+    ...synoJsonComponentDefinitions,
+    DownloadTaskTable: {
+      props: z.object({ rows: z.array(z.unknown()) }),
+      description: 'Gopeed download rows with progress and per-row actions.',
+    },
+  },
+  actions: {
+    refreshDownloads: { description: 'Reload download tasks.' },
+    createDownload: {
+      params: z.object({ url: z.string(), folder: z.string(), filename: z.string().optional() }),
+      description: 'Create a download through the package backend.',
+    },
+  },
+})
+
+export const { registry } = defineRegistry(catalog, {
+  components: {
+    ...synoJsonRenderers,
+    DownloadTaskTable: ({ props }) => h(DownloadTaskTable, { rows: props.rows }),
+  },
+  actions: {
+    refreshDownloads: async () => { /* call existing app/store code */ },
+    createDownload: async (params) => { /* call existing app/store code */ },
+  },
+})
+```
+
+The same boundary works for Syno Reclaim: its app shell/settings/dialogs can be
+declarative while `Treemap`, `ReclaimGrid`, `ProgressRing` and the scan/cleanup
+state machines stay application-owned extensions.
+
+## AI tools
+
+The package ships a `syno-ui` command (`npx @synopackageland/ui <command>`, or
+`npx syno-ui` once installed) and the same functions from the JSON entry:
+
+| Command | Purpose | Function |
+| --- | --- | --- |
+| `catalog [--json]` | Components, required props, slots, events | `listSynoJsonComponents()` |
+| `describe <Component> [--json]` | Prop JSON Schemas and a minimal valid element | `describeSynoJsonComponent()` |
+| `schema` | Spec JSON Schema (draft 2020-12) generated from the catalog | `synoJsonSchema()` |
+| `prompt` | System prompt: catalog, rules and the self-check workflow | `synoJsonAiPrompt()` |
+| `validate <file...>` | Every problem at once, with JSON Pointer `path` and a `hint` | `validateSynoJsonSpec()` |
+| `render <file>` | Validate, screenshot 390/640/960/1350 px, report overflow by spec key | (Chrome, Node 22+) |
+
+`validate` checks the spec shape, unknown components/props/slots/events (with
+"did you mean"), required props, literal types and enum values, child
+references and cycles, state pointers, `$item` outside `repeat`, actions,
+`$computed` functions and i18n keys. Tell it what the host provides:
+
+```bash
+syno-ui validate ui.json --json --actions save,refresh --functions formatBytes \
+  --state host-state.json --messages messages/en.json
+```
+
+Exit codes: `0` valid, `1` spec errors (or warnings with `--strict`, or layout
+issues from `render`), `2` usage, unreadable files or browser failure.
+
+Localized text uses `{"$computed": "t", "args": {"key": "settings.title"}}`.
+Register `t` through the renderer's `functions` prop; `--messages` checks every
+key and warns about literal user-facing text.
+
+### Workflow for an AI
+
+1. Read `syno-ui prompt` once, then `syno-ui catalog` and `syno-ui describe` for
+   the components you plan to use.
+2. Write `{ "root", "elements", "state" }`, seeding every state path you bind.
+3. Run `syno-ui validate ui.json --json` with the host's actions, functions,
+   state and messages. Fix each error at its `path` using its `hint`; repeat.
+4. Run `syno-ui render ui.json --out shots`, look at the screenshots, and fix
+   every element named in an `outside_viewport` or `clipped_content` issue.
+5. Hand over the spec only when `validate` and `render` both exit 0.
+
+Builds also write `dist/json-catalog.schema.json` and `dist/json-ai-prompt.md`
+(exported as `@synopackageland/ui/json-catalog.schema.json` and
+`@synopackageland/ui/json-ai-prompt.md`) for constrained-generation pipelines.
+Give the model the prompt plus the application's own actions and extension
+components, not the Vue source tree.

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.5.8",
+  "version": "0.6.0",
   "description": "Shared Vue 3 UI component library with a DSM 7 inspired application theme",
   "license": "MIT",
   "type": "module",
@@ -11,7 +11,10 @@
     "LICENSE",
     "LICENSES",
     "README.md",
-    "docs/app-local-modal.md"
+    "docs/adaptive-layout.md",
+    "docs/app-local-modal.md",
+    "docs/component-defaults-0.5.7.md",
+    "docs/json-ui.md"
   ],
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -21,6 +24,12 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./json": {
+      "types": "./dist/json.d.ts",
+      "import": "./dist/json.js"
+    },
+    "./json-catalog.schema.json": "./dist/json-catalog.schema.json",
+    "./json-ai-prompt.md": "./dist/json-ai-prompt.md",
     "./theme.css": "./dist/theme.css",
     "./themes/dsm7.css": "./dist/themes/dsm7.css",
     "./themes/dsm7-embedded.css": "./dist/themes/dsm7-embedded.css",
@@ -32,7 +41,10 @@
   },
   "dependencies": {
     "@internationalized/date": "3.12.4",
-    "@lucide/vue": "1.48.0"
+    "@json-render/core": "0.21.0",
+    "@json-render/vue": "0.21.0",
+    "@lucide/vue": "1.48.0",
+    "zod": "^4.6.5"
   },
   "engines": {
     "node": ">=20"