From aeb32f1901c3f50a8f72e0325a8915dcd7b6586c Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 7 Aug 2026 15:53:21 +0000 Subject: [PATCH] =?UTF-8?q?docs(runner):=20=E5=88=A0=E6=8E=89=20runner.mdx?= =?UTF-8?q?=20=E7=9A=84=E5=B9=BD=E7=81=B5=E7=9B=AE=E5=BD=95=E4=B8=8E?= =?UTF-8?q?=E3=80=8C=E5=86=85=E7=BD=AE=E7=A4=BA=E4=BE=8B=20schema=E3=80=8D?= =?UTF-8?q?=E6=96=AD=E8=A8=80,=E9=87=8D=E5=86=99=20Package=20Information?= =?UTF-8?q?=20(#3577)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 三类结构性虚构,均对 origin/main 逐条复核后处理。范围是整页 8 处锚点, 不是正文列的 3 处 —— 只修 Directory Structure 会让全页继续自相矛盾。 1. 幽灵目录。`packages/runner/src` 下实测只有 App.tsx / LayoutRenderer.tsx / main.tsx / index.css / lib/ / 测试文件,没有 `schemas/`、没有 `components/`, 包根也没有 `public/`。按 #3534/#3539 先例(删手抄目录树,指真源)整块删掉 Directory Structure,换成一段实测过的 prose,并把承重信息落在唯一真实的 元数据目录 `src/app-data/` 上 —— 它由 `.gitignore` 排除、新检出下不存在, 布局与解析顺序由本页自己的 Metadata Loading 一节(#3581 补)承接。 其余 5 处 `src/schemas/` 引用(Use Cases 两处、Add Custom Schemas、 Best Practices 目录树)一并按 Metadata Loading 的真实契约改写为 `src/app-data/pages/*.json`;页文档形状取 App.tsx 兜底页的 `{ type: 'page', title, body: [] }`,与本页 Metadata Loading 表格里 「the page document (PageNodeSchema)」一致。 2. 「内置示例 schema」。这个包一个 schema 文件都不带:承载它们的 `src/app-data/` 在 `packages/runner/.gitignore:1` 里,缺该目录时 LocalBundleLoader 三个 `import.meta.glob` 编译为 `{}`,`/` 渲染内置兜底 `No index page found.`。What's Included 下那节列七类「Runner 包含的示例 schema」整节改写为读者实际要做的事(往 `src/app-data/` 放 JSON,或用 `?api=` 指后端);下方 `## Example Schemas` 改题为 Schemas to Start From, 并说明这些例子活在文档里、不在包里。 3. Package Information。`Version: 0.3.1` 直接删除,不改成 17.3.0 —— `@object-ui/runner` 在 `.changeset/config.json` 的 fixed 组里随 39 包同发, 手抄版本号必然再次漂移(分诊亦持此意见);当前版本改为指向 npm 页。 `Type: Application (not published to npm)` 与实测相反:package.json 是 `"private": false` + `publishConfig.access: "public"`,registry 上 `dist-tags.latest = 17.3.0`。改为不随版本漂移的措辞:已发布,但它是应用 不是库 —— package.json 不声明 main/module/exports/types,没有可 import 的 东西(与 PR #3602 刚给 README 定下的说法一致)。 `src/components/` 保留一处 —— Add Custom Components 的 `// src/components/ MyComponent.tsx`。那是让读者自己建的文件(下方注册片段的相对 import 必须与它 对齐),已在上一句明写「包里不带组件,这个目录你自己加」,不再是「它存在」的 断言。 越界发现另行开单,不在本 PR 修:Features 的「All official plugins included」、 Best Practices 的环境变量小节(#3538 删了 Environment Variables 整节却漏了它)、 Add Custom Routes 的 react-router-dom(runner 不依赖它,路由是手写 history.pushState)。#3604 是 README 的另一件事,未触碰。 Fixes #3577 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt --- content/docs/utilities/runner.mdx | 108 +++++++++++++++++------------- 1 file changed, 61 insertions(+), 47 deletions(-) diff --git a/content/docs/utilities/runner.mdx b/content/docs/utilities/runner.mdx index 04bda3e5a1..cff53c94c1 100644 --- a/content/docs/utilities/runner.mdx +++ b/content/docs/utilities/runner.mdx @@ -56,17 +56,14 @@ The Runner includes these plugins by default: - **@object-ui/plugin-kanban** - Kanban board with drag-and-drop - **@object-ui/plugin-charts** - Data visualization charts -### Example Schemas +### Metadata — Supplied by You -The Runner includes example schemas demonstrating: - -- Dashboard layouts -- Data tables and grids -- Form validation -- Kanban boards -- Chart visualizations -- Calendar views -- Timeline displays +The Runner ships **no** metadata of its own: the package contains no `.json` schema +files, so a fresh checkout renders nothing until you give it something to render. The +two ways to do that are covered under [Metadata Loading](#metadata-loading) — drop JSON +into `src/app-data/` (git-ignored, yours to create), or point the Runner at a backend +with `?api=`. With neither in place, `/` shows the built-in `No index page found.` +placeholder. ### Development Tools @@ -75,22 +72,19 @@ The Runner includes example schemas demonstrating: - **React DevTools** - Inspect component tree - **Network Inspector** - Monitor API calls -## Directory Structure +## Where the Code Lives -``` -packages/runner/ -├── src/ -│ ├── App.tsx # Main application -│ ├── main.tsx # Entry point -│ ├── schemas/ # Example schemas -│ │ ├── dashboard.json -│ │ ├── kanban.json -│ │ └── charts.json -│ └── components/ # Custom components -├── public/ # Static assets -├── package.json -└── vite.config.ts -``` +`packages/runner/src` is small and holds no metadata. `main.tsx` mounts the root +component; `App.tsx` is that root — it picks the metadata loader from the `api` query +parameter, imports the pre-installed plugins, handles routing, and hands the loaded page +to ``. `lib/MetadataLoader.ts` holds both loaders (`LocalBundleLoader` +and `NetworkLoader`), and `LayoutRenderer.tsx` draws the app chrome around the page. +Everything you actually see rendered comes from `@object-ui/react`, `@object-ui/components` +and the `@object-ui/plugin-*` packages, not from this one. + +The one directory worth knowing about is **`src/app-data/`** — the metadata the Runner +renders. It is git-ignored and absent from a fresh checkout; you create it. See +[Metadata Loading](#metadata-loading) for its layout and resolution order. ## Configuration @@ -222,10 +216,13 @@ Test new plugins in a full application context: // src/main.tsx import '@object-ui/plugin-myplugin' -// src/schemas/test.json +// src/app-data/pages/index.json — the page served at "/" { - "type": "my-component", - "message": "Testing my plugin" + "type": "page", + "title": "Plugin test", + "body": [ + { "type": "my-component", "message": "Testing my plugin" } + ] } ``` @@ -234,7 +231,7 @@ import '@object-ui/plugin-myplugin' Experiment with complex schemas: ```bash -# Edit schemas in src/schemas/ +# Edit the JSON under src/app-data/ # Changes are reflected immediately ``` @@ -265,7 +262,11 @@ pnpm dev --host # http://your-ip:5173 ``` -## Example Schemas +## Schemas to Start From + +These live here in the docs, not in the package — copy one, wrap it in a page document +(`{ "type": "page", "body": [ … ] }`), and save it as `src/app-data/pages/index.json`, or +serve it from your own backend and load it with `?api=`. ### Dashboard Example @@ -385,9 +386,11 @@ pnpm test ## Package Information -**Package Name:** `@object-ui/runner` -**Version:** 0.3.1 -**Type:** Application (not published to npm) +**Package Name:** `@object-ui/runner` — published on npm, see the +[npm page](https://www.npmjs.com/package/@object-ui/runner) for the current version +**Type:** Application, not a library. `package.json` declares no `main`, `module`, +`exports` or `types`, so there is nothing to `import` from it — you run it from a +checkout of this repository, as shown above. **License:** MIT ## Dependencies @@ -425,7 +428,8 @@ function App() { ### Add Custom Components -Create in `src/components/`: +The package ships no components of its own, so create the file wherever you like under +`src/` — this example uses a `components/` directory you add yourself: ```typescript // src/components/MyComponent.tsx @@ -445,16 +449,23 @@ ComponentRegistry.register('my-component', MyComponent) ### Add Custom Schemas -Add to `src/schemas/`: +Add a page document to `src/app-data/pages/`. The file name is the route: this one is +served at `/my-page`. ```json -// src/schemas/my-page.json +// src/app-data/pages/my-page.json { - "type": "div", - "className": "p-8", - "children": [ + "type": "page", + "title": "My Page", + "body": [ { - "type": "my-component" + "type": "div", + "className": "p-8", + "children": [ + { + "type": "my-component" + } + ] } ] } @@ -462,16 +473,19 @@ Add to `src/schemas/`: ## Best Practices -### 1. Modular Schemas +### 1. One File per Page -Keep schemas in separate files: +The loader globs `src/app-data/`, so a page is a file and nested routes are nested +directories — no index or barrel file to maintain: ``` -src/schemas/ -├── dashboard.json -├── kanban.json -├── charts.json -└── index.ts +src/app-data/ +├── app.json # app document: branding, navigation +└── pages/ + ├── index.json # route "/" + ├── customers.json # route "/customers" + └── crm/ + └── accounts.json # route "/crm/accounts" ``` ### 2. Environment Configuration