From ee994da9082d21fd67965bceb9c38c1dc2b9444c Mon Sep 17 00:00:00 2001 From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Date: Tue, 30 Jun 2026 14:39:02 +0800 Subject: [PATCH] docs: document the html/react page-authoring tiers (ADR-0080/0081) - layout-dsl.mdx: new 'Authoring Modes' section framing the structured mode vs the html (parsed) and react (executed, OS_PAGE_REACT-gated) source tiers, with a decision table and ADR cross-links. - objectstack-ui SKILL frontmatter: mention the source-authoring tiers; regenerate the skills catalog (skills.mdx + skills/README.md) via gen:skill-docs. Closes the last hand-written-doc gap; generated spec references (references/ui/page) self-refresh at docs build (gen:docs runs before next build). --- content/docs/guides/skills.mdx | 4 +-- content/docs/protocol/objectui/layout-dsl.mdx | 26 +++++++++++++++++++ skills/README.md | 2 +- skills/objectstack-ui/SKILL.md | 3 ++- 4 files changed, 31 insertions(+), 4 deletions(-) diff --git a/content/docs/guides/skills.mdx b/content/docs/guides/skills.mdx index 9fa40bc326..a3319a76e4 100644 --- a/content/docs/guides/skills.mdx +++ b/content/docs/guides/skills.mdx @@ -48,7 +48,7 @@ ObjectStack ships **9 domain-specific skills**. Each is self-contained — an AI | 1 | [Platform](#platform) | `platform` | `skills/objectstack-platform/` | Bootstrap, configure, extend, and operate ObjectStack runtimes. Covers project setup (`defineStack`, drivers, adapters, scaffolding), plugin and service development (PluginContext, DI, kernel hooks like `kernel:ready` and `data:*`), and operations (CLI commands, migrations, deployment, test harnesses via LiteKernel). | | 2 | [Data](#data) | `data` | `skills/objectstack-data/` | Design ObjectStack data schemas — objects, fields, field conditional rules, relationships, validations, indexes, lifecycle hooks, permissions, row-level security — and the seed datasets (`defineDataset()`) that load fixtures and reference data alongside them. | | 3 | [Query](#query) | `query` | `skills/objectstack-query/` | Construct ObjectQL queries — filters, sorting, pagination, aggregation, joins/expansion, window functions, and full-text search. | -| 4 | [UI](#ui) | `ui` | `skills/objectstack-ui/` | Author ObjectStack UI metadata — Views (list/form/kanban/calendar/gantt), Apps (navigation), Pages, Dashboards, Reports, Charts, Actions, and package Docs (`src/docs/*.md`). | +| 4 | [UI](#ui) | `ui` | `skills/objectstack-ui/` | Author ObjectStack UI metadata — Views (list/form/kanban/calendar/gantt), Apps (navigation), Pages (structured plus the HTML and React source-authoring tiers, ADR-0080/0081), Dashboards, Reports, Charts, Actions, and package Docs (`src/docs/*.md`). | | 5 | [Automation](#automation) | `automation` | `skills/objectstack-automation/` | Design ObjectStack automation — Flows (visual logic), Workflows (declarative rules), Triggers, Approvals, scheduled jobs, and webhooks. | | 6 | [AI](#ai) | `ai` | `skills/objectstack-ai/` | Design ObjectStack AI agents, tools, skills, conversations, model registry entries, and MCP integrations. | | 7 | [API](#api) | `api` | `skills/objectstack-api/` | Design the server-side API surface that an ObjectStack runtime exposes — REST/GraphQL endpoints, auth providers, realtime channels, error envelopes, batch/versioning contracts. | @@ -103,7 +103,7 @@ Do not use for defining objects / fields / relationships (see objectstack-data) **Domain** `ui` · **Path** `skills/objectstack-ui/` -Author ObjectStack UI metadata — Views (list/form/kanban/calendar/gantt), Apps (navigation), Pages, Dashboards, Reports, Charts, Actions, and package Docs (`src/docs/*.md`). +Author ObjectStack UI metadata — Views (list/form/kanban/calendar/gantt), Apps (navigation), Pages (structured plus the HTML and React source-authoring tiers, ADR-0080/0081), Dashboards, Reports, Charts, Actions, and package Docs (`src/docs/*.md`). Use when the user is adding `*.view.ts` / `*.app.ts` / `*.dashboard.ts` / `*.action.ts` / `src/docs/*.md` files or designing a Studio-rendered UI surface, including dataset-bound dashboard/report widgets. diff --git a/content/docs/protocol/objectui/layout-dsl.mdx b/content/docs/protocol/objectui/layout-dsl.mdx index e9687166b0..2c58728768 100644 --- a/content/docs/protocol/objectui/layout-dsl.mdx +++ b/content/docs/protocol/objectui/layout-dsl.mdx @@ -22,6 +22,32 @@ Instead of giving you infinite layout freedom (and infinite ways to break respon - **Accessibility:** Keyboard navigation and screen readers work automatically - **Maintainability:** Designers can't create 47 different button sizes +## Authoring Modes: Structured, HTML, and React + +A page's `kind` selects **how** it is authored. This document describes the +**structured** mode (regions + the 12-column grid below) — but for layouts the +fixed schema can't express, two *source-authoring* tiers let an author (or AI) +write the page body as a string. Pick by what the page needs: + +| `kind` | You write | JavaScript | Use when | +|:-------|:----------|:-----------|:---------| +| `full` / `slotted` *(this doc)* | structured `regions` / `slots` | — | record, detail, home, and app layouts from the component catalogue | +| `html` | constrained JSX = HTML + Tailwind + registered components, **parsed, never executed** | none | free-form layout, landing pages, or dashboards that *compose* blocks — no interactivity | +| `react` | **real React** (hooks, `.map`, `onClick`, expressions) | executed in the app | complex interactive business UIs — master/detail, wizards, state-driven filters | + +For `html` / `react`, the page body is the `source` string (it is the +source-of-truth; `regions` is ignored). `html` is **safe by construction** (it +is parsed into the same SDUI tree this document describes, never executed). +`react` executes author code, so it is gated by a host capability that is **ON +by default** and disabled per-deployment with the `OS_PAGE_REACT=off` env +variable. Both tiers can embed the platform's real data components +(``, ``, charts, metrics). + +> **Learn more:** [ADR-0080](https://github.com/objectstack-ai/framework/blob/main/docs/adr/0080-ai-authored-ui-jsx-source.md) +> (the `html` tier — parse ≠ execute; the registry is the contract) and +> [ADR-0081](https://github.com/objectstack-ai/framework/blob/main/docs/adr/0081-trusted-react-page-tier.md) +> (the trusted `react` tier). The rest of this page covers the structured mode. + ## Layout Hierarchy ``` diff --git a/skills/README.md b/skills/README.md index cdf30c7bf5..9cd2884b35 100644 --- a/skills/README.md +++ b/skills/README.md @@ -19,7 +19,7 @@ authoritative Zod sources in `node_modules/@objectstack/spec/src/...`. | [Platform](./objectstack-platform/SKILL.md) | `platform` | Bootstrap, configure, extend, and operate ObjectStack runtimes. Covers project setup (`defineStack`, drivers, adapters, scaffolding), plugin and service development (PluginContext, DI, kernel hooks like `kernel:ready` and `data:*`), and operations (CLI commands, migrations, deployment, test harnesses via LiteKernel). | | [Data](./objectstack-data/SKILL.md) | `data` | Design ObjectStack data schemas — objects, fields, field conditional rules, relationships, validations, indexes, lifecycle hooks, permissions, row-level security — and the seed datasets (`defineDataset()`) that load fixtures and reference data alongside them. | | [Query](./objectstack-query/SKILL.md) | `query` | Construct ObjectQL queries — filters, sorting, pagination, aggregation, joins/expansion, window functions, and full-text search. | -| [UI](./objectstack-ui/SKILL.md) | `ui` | Author ObjectStack UI metadata — Views (list/form/kanban/calendar/gantt), Apps (navigation), Pages, Dashboards, Reports, Charts, Actions, and package Docs (`src/docs/*.md`). | +| [UI](./objectstack-ui/SKILL.md) | `ui` | Author ObjectStack UI metadata — Views (list/form/kanban/calendar/gantt), Apps (navigation), Pages (structured plus the HTML and React source-authoring tiers, ADR-0080/0081), Dashboards, Reports, Charts, Actions, and package Docs (`src/docs/*.md`). | | [Automation](./objectstack-automation/SKILL.md) | `automation` | Design ObjectStack automation — Flows (visual logic), Workflows (declarative rules), Triggers, Approvals, scheduled jobs, and webhooks. | | [AI](./objectstack-ai/SKILL.md) | `ai` | Design ObjectStack AI agents, tools, skills, conversations, model registry entries, and MCP integrations. | | [API](./objectstack-api/SKILL.md) | `api` | Design the server-side API surface that an ObjectStack runtime exposes — REST/GraphQL endpoints, auth providers, realtime channels, error envelopes, batch/versioning contracts. | diff --git a/skills/objectstack-ui/SKILL.md b/skills/objectstack-ui/SKILL.md index afbd12808d..92f1320b28 100644 --- a/skills/objectstack-ui/SKILL.md +++ b/skills/objectstack-ui/SKILL.md @@ -2,7 +2,8 @@ name: objectstack-ui description: > Author ObjectStack UI metadata — Views (list/form/kanban/calendar/gantt), - Apps (navigation), Pages, Dashboards, Reports, Charts, Actions, and + Apps (navigation), Pages (structured plus the HTML and React source-authoring + tiers, ADR-0080/0081), Dashboards, Reports, Charts, Actions, and package Docs (`src/docs/*.md`). Use when the user is adding `*.view.ts` / `*.app.ts` / `*.dashboard.ts` / `*.action.ts` / `src/docs/*.md` files or designing a Studio-rendered UI