Skip to content

Commit 5d8e559

Browse files
docs(skills): type-check more objectstack-ui examples with os:check (#31706)
<!-- claude-projects-attribution: {"github_login":"zhuangjianguo"} --> _Requested by **Steedos** · [project thread](https://claude.ai/code/project/chan_018ETKaNwMZCNRYD7D8Q9Ubb?thread=cmsg_018ETKaNwMZCNRYD7D8Q9UbbMte2M4pEgfqrXNwg6KKjWH)_ Refs #31112 (slice 3 of a per-skill split: item 4, objectstack-ui; the card stays open) Clause-②: no Metadata-protocol: none ## 维护者速读 - 改了什么:objectstack-ui 技能包里又有 10 段 TypeScript 示例接入了示例编译检查(33 段中由 15 段变为 25 段),涉及动作、页面、仪表盘和看板/甘特视图的示例;没有发现写错的示例。 - 为什么改:AI 编写界面元数据时最先照抄这些示例;接入检查后,规范一旦改名或收紧,示例会在 CI 里立刻变红,而不是悄悄教错。 - 风险与回滚:只改发布技能包的文档文字,不动任何运行时代码;四个文件的 token 上限都未抬高,新增字节靠同文件删减重复说明支付(每处删减的规则都在同文件另有出处)。回滚即 revert 本 PR。 - 先看:`skills/objectstack-ui/rules/dashboards.md`(4 段新接入、删减最多)、`skills/objectstack-ui/rules/list-views.md`(看板与甘特示例改为带类型的 `ListView`)、`skills/objectstack-ui/rules/pages.md`(3 段新接入)。 - 两分钟验证:`pnpm --filter @objectstack/spec check:skill-examples`,预期最后一行为 332 段示例全部通过类型检查。 - 需要你做的:作为受管面审批人审阅并批准本 PR(skills/** 属 Tier H)。 ## What changes `skills/objectstack-ui` had 15 of its 33 fenced `ts`/`typescript` blocks under `check:skill-examples` (measured on `main` 8210894, all `*.md` outside `evals/`; `references/_index.md` and the generator-owned `references/react-blocks.md`, which holds no ts block, excluded). It now has 25. Every new mark is the os:check marker on the line above the fence; each wrapper is one import line plus a typed `const` on the existing first line (and, for the two arrays, one opening and one closing line), never more than three lines. | File | marked before → after / blocks | tokens before → after / ceiling | lines before → after | |:--|:--|:--|:--| | `rules/actions.md` | 4 → 5 / 5 | 2258 → 2257 / 2259 | 181 → 184 | | `rules/dashboards.md` | 4 → 8 / 9 | 6232 → 6231 / 6232 | 462 → 473 | | `rules/list-views.md` | 3 → 5 / 11 | 3451 → 3446 / 3451 | 329 → 334 | | `rules/pages.md` | 1 → 4 / 4 | 5648 → 5668 / 5669 | 426 → 432 | | untouched: `SKILL.md`, `navigation.md`, `record-page.md` | 0/1, 2/2, 1/1 | headroom 0, 0, 0 | unchanged | Skills bundle reading: no `SKILL.md` changed, so the sum of every published `SKILL.md` stays 4592 lines. - **`rules/actions.md`**: the `opensInNewTab` + `newTabUrl` action gains its `defineAction` import and is marked. - **`rules/pages.md`**: the `kind: 'html'` page gains its `definePage` import; the styled pricing card becomes `const card: PageComponent = { … };` and the doc navigation item `const navigation: NavigationItem[] = [ … ];`. The orphan-looking marker above the master/detail block is over a `tsx` fence and was already counted by the gate, not by this ts tally. - **`rules/dashboards.md`**: the dataset-bound widget becomes `const widget: DashboardWidget`; the two `filterBindings` widgets and the two `compareTo` widgets become `const widgets: DashboardWidget[] = [ … ];` (the second pair gains the comma between its two objects); the `options` line becomes `const options: DashboardWidget['options']`. The two bare `compareTo:` lines stay a fragment and the file says so once. - **`rules/list-views.md`**: the kanban and gantt examples become `const board: ListView` and `const timeline: ListView`, so a top-level `groupBy` or a missing `gantt.startDateField` now fails the gate. The bare-key blocks (`data`, `columns`, `filter`, `userFilters`, `sort`, `grouping`) stay fragments and the file says so once. ## Why #31112 item 4 (ruling B of #22059): published examples are guarded by the opt-in type check, and every defect the P0 text-fix card found sat in an unmarked block. This slice brings objectstack-ui's self-contained examples under it. ### Example fixes None. Every candidate block was probed in isolation with its wrapper (TS API, syntactic then semantic pass, with a planted unknown key per file as the control leg) and compiled as written. ### Trims that paid the marks (each cut and where its rule survives) - `rules/actions.md` §Action body context: "— the blessed name (same axes and `undefined` cases as hooks, objectstack-data)" became "(as in hooks, objectstack-data)". The blessed-name rule survives at `skills/objectstack-data/references/data-hooks.md:584` ("the single blessed name") and the same read at `:619`. - `rules/actions.md` new-tab warning: "builds and draws a checkbox in the dialog" became "draws a checkbox"; the rule (never express new-tab via `params`) is unchanged. - `rules/pages.md` `kind:'html'`: "; use `kind:'react'` for those" cut; survives in the tier table's `react` row (hooks, `onClick`, expressions). - `rules/pages.md` styling block: its comment "every block carries responsiveStyles + tokens" cut; survives in the Rules list above it (stable `id` on every styled node, values as design tokens). - `rules/pages.md` routing: "; that gives one doc many addresses and breaks cross-references" cut; survives as "so a doc has exactly one URL" in the same paragraph. - `rules/pages.md` live instances: "(one source, never a stale copy)" cut; survives at "Write business concepts" ("has no producer and drifts; the self-describing metadata is the one source"). - `rules/dashboards.md` §compareTo: "The renderer derives the comparison automatically; no second `filter` is required." cut; survives at **Requirements** ("The shifted query reuses the original `filter` shape and replaces only the date-bound clauses"). ", so what a widget declares is exactly what runs" cut; the same-shape statement it followed stays. - `rules/dashboards.md` KPI example comments: the metric's "renderer fetches the prior quarter and surfaces a secondary value + delta arrow" survives at **Metric widgets** ("a delta arrow plus a trend label"); the chart's "(M2). The renderer issues a second query … overlays it as a muted/dashed series" survives at the §compareTo opening and at **Cartesian charts** (dashed, reduced opacity). - `rules/dashboards.md`: the metric comment "(binds the crm_task_metrics dataset; filter = runtimeFilter)" survives in the block's own `dataset:` key and at §Dataset-Bound Widgets ("presentation-scope `filter` flows into the query as the runtime filter"); "for this widget only" in the options comment survives in the `dateGranularity` table row ("for this widget only"); the pie/donut rationale clause cut, the rule ("`compareTo` is silently ignored") stays. - `rules/list-views.md`: "Every view lives under `list` / `form` / `listViews` / `formViews`, as above." survives in §The `defineView` container's first sentence; the `lanes` comment "option VALUES to draw, in this order" survives in the note under the block ("`lanes` chooses the lanes and their order … not one of the field's inline options"); "— past the right edge of a narrow screen —" survives in hand-over item (a) ("scroll right"); "; declare `searchableFields` to choose the set" survives in the table row "declares `searchableFields` | that list, verbatim"; ": nothing ever drew it", "(the block above)" and "(CRUD, live updates, filtering, pagination)" carried no rule. ## Tests <details><summary>check:skill-examples, before and after, and the reverse check</summary> - Before (`main` 8210894): `✅ 322 prose examples type-check across 3 surface(s)`. - After (head 3bc338e; 0de24c0 adds only a merge of `main` touching no `skills/**` or `packages/spec` path): `pnpm --filter @objectstack/spec check:skill-examples` exited 0 with `✅ 332 prose examples type-check across 3 surface(s) — every marked block parsed, so tsc ran the SEMANTIC pass on all of them` (skills + docs surface 288 → 298). - Reverse check, after the commit: planted one wrong key per touched file: `newTabTarget` (`rules/actions.md:165`), `docName` on the doc nav item (`rules/pages.md:365`), the retired widget `position` (`rules/dashboards.md:52`) and a top-level kanban `groupBy` (`rules/list-views.md:264`). The checker exited 1 with TS2353 at exactly those four lines. Restored with `git checkout HEAD -- skills/objectstack-ui`; `git diff HEAD` and `git status --porcelain` were empty after. </details> <details><summary>Derived gate sweep (head 3bc338e)</summary> `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` derived 44 commands. 43 exited 0. `pnpm check:dual-build-cjs-loads` exited 3 (PREREQUISITE NOT MET: needs every package's dist; CI runs it). `dispatch-gates --ran` exited 0: 44 derived, 43 run, 1 NOT-MEASURED, 0 unrun. Re-run on the merged head 0de24c0: `check-skills-token-ratchet`, `check-changeset-no-major --base origin/main`, `check:skill-links`, `check-empty-changeset --base origin/main`, all exit 0. </details> ## Acceptance notes - `check:skill-examples` is not in the derived gate list for a `skills/**` diff, so it was run by hand. - Unmarked, and why: `SKILL.md`'s `subforms` block is indented three spaces inside a numbered list item, and the gate's fence pattern only reads a fence at column 0, so a marker there would be an orphan; moving it out of the list would break the list and costs bytes `SKILL.md` does not have (headroom 0). In `rules/list-views.md`, `filter`, `sort` and `grouping` would compile with a three-line wrapper (probed green), but each costs about 100 bytes and the file has 5 tokens left after the kanban and gantt marks; `data` (a `[...]` placeholder), `columns` (two statements) and `userFilters` + `appearance` are true fragments. In `rules/dashboards.md` the two bare `compareTo:` lines are a fragment. - No ceiling was raised or lowered; the ratchet printed no lowering instruction. - This build ran on the default tier: `dispatch-gates --tier` mandates Fable for `skills/**`, and the claim records the no-Fable-build exit; the contract review is the seat's, on the lane's isolated reviewer. ## Verification `pnpm --filter @objectstack/spec check:skill-examples` (needs `@objectstack/spec` and `@objectstack/client-react` built) prints 332 examples green; `node scripts/check-skills-token-ratchet.mjs` exits 0 with every `skills/objectstack-ui` file within its ceiling. ## Human Minimum A governed approver reviews and approves (Tier H). 🤖 Generated with [Claude Code](https://claude.com/claude-code) --- _Generated by [Claude Code](https://claude.ai/code/session_01QsR2jUzyjnwuhUWHpExHXT)_ Co-authored-by: Claude <noreply@anthropic.com>
1 parent 2a32bd4 commit 5d8e559

5 files changed

Lines changed: 81 additions & 46 deletions

File tree

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
'@objectstack/skills': patch
3+
---
4+
5+
docs(skills): more of objectstack-ui's self-contained examples are type-checked by `check:skill-examples`
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
Ten more fenced TypeScript blocks in `skills/objectstack-ui` carry the opt-in check marker, so 25 of its 33 are now compiled against the spec: the new-tab `defineAction` in `rules/actions.md` and the `kind: 'html'` page in `rules/pages.md` gain their import; the styled pricing card and the doc navigation item in `rules/pages.md` are typed as `PageComponent` and `NavigationItem[]`; four widget examples in `rules/dashboards.md` are typed as `DashboardWidget` (or its `options`); and the kanban and gantt examples in `rules/list-views.md` are typed as `ListView`, all from `@objectstack/spec/ui`. No example was wrong. The rest stay unmarked: bare-key fragments, the blocks whose file had no token headroom left for a wrapper, and the `SKILL.md` subform example, whose fence is indented inside a list item where the gate does not read it. No rule's teaching changes.

‎skills/objectstack-ui/rules/actions.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@ export const AddToCampaignAction = defineAction({
114114
A server-side `body` (or a registered `handler`) receives `ctx` with `input` (the dialog params), `record` (the target row, when a
115115
`recordId` is in scope), `api` (scoped cross-object CRUD) and the caller. Read
116116
the active organization as `ctx.user?.organizationId ?? ctx.session?.organizationId`
117-
— the blessed name (same axes and `undefined` cases as hooks, objectstack-data).
117+
(as in hooks, objectstack-data).
118118
Bodies execute **trusted** (`ctx.api` /
119119
`ctx.engine` bypass RLS/FLS). `ctx.session.positions` (absent when the caller holds none) is
120120
**not an authorization input** — ask the security service for privilege (ADR-0095).
@@ -150,7 +150,10 @@ path starting with `/` (`{recordId}` placeholder; an external URL is refused, us
150150
`openIn`), valid only with `opensInNewTab: true`; the endpoint enforces its own
151151
auth (the tab carries no in-app session).
152152

153+
<!-- os:check -->
153154
```typescript
155+
import { defineAction } from '@objectstack/spec/ui';
156+
154157
export const OpenInvoicePdfAction = defineAction({
155158
name: 'crm_open_invoice_pdf',
156159
label: 'Open PDF',
@@ -166,8 +169,8 @@ export const OpenInvoicePdfAction = defineAction({
166169
> A printable document (an invoice) is a page that declares `print` — [Print pages](./pages.md#print-pages).
167170
168171
> ⚠️ **Never express new-tab behavior via `params`** — it is `ActionParam[]` for
169-
> **user input** only: `params: [{ name: 'newTab', type: 'checkbox' }]` builds and
170-
> draws a checkbox in the dialog.
172+
> **user input** only: `params: [{ name: 'newTab', type: 'checkbox' }]` draws a
173+
> checkbox.
171174
172175
## Action Parameter Patterns
173176

‎skills/objectstack-ui/rules/dashboards.md‎

Lines changed: 29 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -43,16 +43,19 @@ fails `os validate`.
4343
A widget's presentation-scope `filter` flows into the query as the runtime
4444
filter; keep `filter` on the widget when binding a dataset.
4545

46+
<!-- os:check -->
4647
```typescript
47-
{
48+
import type { DashboardWidget } from '@objectstack/spec/ui';
49+
50+
const widget: DashboardWidget = {
4851
id: 'revenue_by_region',
4952
type: 'bar',
5053
title: 'Revenue by Region',
5154
dataset: 'crm_sales',
5255
dimensions: ['region'],
5356
values: ['revenue'],
5457
layout: { x: 0, y: 0, w: 6, h: 4 },
55-
}
58+
};
5659
```
5760

5861
**The real decision is not "inline vs dataset" — it is "can a dataset express
@@ -175,14 +178,10 @@ export const SalesDashboard: Dashboard = {
175178
filter: { stage: { $nin: ['closed_won', 'closed_lost'] } },
176179
layout: { x: 0, y: 0, w: 3, h: 2 },
177180
colorVariant: 'success', // the accent only
178-
// Period-over-period: renderer fetches the prior quarter and
179-
// surfaces a secondary value + delta arrow automatically.
180181
compareTo: { kind: 'previousPeriod' },
181182
},
182183

183-
// Chart widget with comparison overlay (M2). The renderer issues a
184-
// second query with the time window shifted by `compareTo` and
185-
// overlays it as a muted/dashed series. The date axis is a dataset
184+
// Chart widget with comparison overlay. The date axis is a dataset
186185
// dimension whose monthly bucketing lives on the dataset (`dateGranularity`).
187186
{
188187
id: 'revenue_vs_last_year', type: 'line',
@@ -212,30 +211,35 @@ vocabularies.
212211
| `filterBindings: { filterName: false }` | a widget | Opt out — the honest binding when the vocabularies are disjoint and no field can be re-targeted. |
213212
| absent | a widget | Default binding: the filter's own `field`; for the reserved `dateRange`, `dateRange.field ?? 'created_at'`. |
214213

214+
<!-- os:check -->
215215
```typescript
216+
import type { DashboardWidget } from '@objectstack/spec/ui';
217+
216218
// One control, two objects: re-target on one widget, opt the other out.
219+
const widgets: DashboardWidget[] = [
217220
{ id: 'revenue_by_region', dataset: 'crm_order_metrics', values: ['total_sum'],
218221
filterBindings: { region: 'sales_region' } },
219222
{ id: 'projects_at_risk', dataset: 'crm_project_metrics', values: ['project_count'],
220223
filterBindings: { task_status: false } },
224+
];
221225
```
222226

223227
### Period-over-period — `compareTo`
224228

225229
Set `compareTo` on any data-bound widget to add a second query against a
226-
shifted time window. The renderer derives the comparison automatically;
227-
no second `filter` is required.
230+
shifted time window.
228231

229232
`compareTo` is `{ kind, dimension? }` — the same shape the analytics executor
230-
reads (`DatasetSelection.compareTo`), so what a widget declares is exactly what
231-
runs.
233+
reads (`DatasetSelection.compareTo`).
232234

233235
| Key | Value | Behaviour |
234236
|:--|:--|:--|
235237
| `kind` | `'previousPeriod'` | The equal-length window immediately before the resolved one. |
236238
| `kind` | `'previousYear'` | The same window shifted back one calendar year. |
237239
| `dimension` | dimension name, **optional** | Which time dimension's window to shift. Omit it when the selection dates exactly one — the executor resolves it. With zero or several it errors, naming the candidates; it never guesses. |
238240

241+
The two bare `compareTo:` lines are a fragment, so `check:skill-examples` skips them.
242+
239243
```typescript
240244
compareTo: { kind: 'previousPeriod' } // one dated dimension
241245
compareTo: { kind: 'previousYear', dimension: 'close_date' } // several — say which
@@ -250,26 +254,30 @@ compareTo: { kind: 'previousYear', dimension: 'close_date' } // several —
250254
with `variant: 'comparison'`, muted per family (dashed `'4 4'` on
251255
line/area only; reduced opacity on all). That muting is the renderer's
252256
default; `chartConfig.colors` is the one palette channel that remains.
253-
* **Pie / donut / funnel** — `compareTo` is silently ignored; there is no
254-
meaningful "two-period" composition for part-of-whole charts.
257+
* **Pie / donut / funnel** — `compareTo` is silently ignored.
255258
* **Requirements** — a comparison needs a **dated window** to shift. When the
256259
selection carries no time dimension with a date range (no resolvable date
257260
macro in the widget `filter`, no dashboard `dateRange`), the executor says so
258261
rather than rendering a silently empty comparison column. The shifted query
259262
reuses the original `filter` shape and replaces only the date-bound clauses.
260263

264+
<!-- os:check -->
261265
```typescript
262-
// Metric — WoW delta (binds the crm_task_metrics dataset; filter = runtimeFilter)
266+
import type { DashboardWidget } from '@objectstack/spec/ui';
267+
268+
const widgets: DashboardWidget[] = [
269+
// Metric — WoW delta
263270
{ id: 'done_this_week', type: 'metric', dataset: 'crm_task_metrics', values: ['task_count'],
264271
filter: { assignee: '{current_user_id}', status: 'done',
265272
completed_at: { $gte: '{week_start}' } },
266-
compareTo: { kind: 'previousPeriod' } }
273+
compareTo: { kind: 'previousPeriod' } },
267274

268275
// Bar — YoY overlay on a stable category set
269276
{ id: 'headcount_by_dept', type: 'bar', dataset: 'crm_employee_metrics',
270277
dimensions: ['department'], values: ['headcount'],
271278
filter: { status: { $ne: 'terminated' } },
272-
compareTo: { kind: 'previousYear' } }
279+
compareTo: { kind: 'previousYear' } },
280+
];
273281
```
274282

275283
### Server-side date bucketing — `dateGranularity` (ADR-0021)
@@ -342,9 +350,12 @@ These five change the dataset SQL; a typo (`sortDirection`) parses too, and draw
342350
| `limit` | positive integer | Max rows, applied **after** ordering — so "top 10 accounts" is `limit` **plus** `sortBy`. Without `sortBy` the runtime orders by the selected dimensions: deterministic, but not the top of anything. |
343351
| `stageOrder` | array of **stored** values | Explicit stage order for `funnel`; no other type reads it. Stored values, not display labels; omit to inherit the field's picklist order. |
344352

353+
<!-- os:check -->
345354
```typescript
346-
// Top 10 accounts by revenue, bucketed monthly for this widget only
347-
options: { sortBy: 'revenue_sum', sortOrder: 'desc', limit: 10, dateGranularity: 'month' }
355+
import type { DashboardWidget } from '@objectstack/spec/ui';
356+
357+
// Top 10 accounts by revenue, bucketed monthly
358+
const options: DashboardWidget['options'] = { sortBy: 'revenue_sum', sortOrder: 'desc', limit: 10, dateGranularity: 'month' };
348359
```
349360

350361
### Drilldown

‎skills/objectstack-ui/rules/list-views.md‎

Lines changed: 20 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -31,20 +31,19 @@ export const CaseViews = defineView({
3131
```
3232

3333
> **Never export a bare flat view object** (`{ name, label, type, columns }`
34-
> at top level): nothing registers and no view appears in the switcher. Every
35-
> view lives under `list` / `form` / `listViews` / `formViews`, as above.
34+
> at top level): nothing registers and no view appears in the switcher.
3635
3736
### Data Source (`data`)
3837

39-
Every view connects to data via one of two providers:
38+
Bare-key blocks in this file are fragments, so `check:skill-examples` skips
39+
them. Every view connects to data via one of two providers:
4040

4141
```typescript
4242
data: { provider: 'object', object: 'support_case' }
4343
data: { provider: 'value', items: [...] }
4444
```
4545

46-
> Use `provider: 'object'` for an ObjectStack-managed object (CRUD, live
47-
> updates, filtering, pagination). A view never calls an API: an API read is a
46+
> Use `provider: 'object'` for an ObjectStack-managed object. A view never calls an API: an API read is a
4847
> page element's `dataSource` binding.
4948
5049
### Columns
@@ -137,15 +136,15 @@ Rules:
137136
- Every `field` MUST exist on the source object — reference diagnostics
138137
(`_diagnostics`) flag unknown fields; treat `valid: false` as a failed write.
139138
- **A list view has no `tabs` key** — it was removed (a parse error that
140-
names the fix): nothing ever drew it. Each named preset is a `listViews`
139+
names the fix). Each named preset is a `listViews`
141140
entry, rendered as a tab in the object's saved-view switcher.
142141
- **On an object list view (`*.view.ts` `list` / `listViews`), only
143142
`element: 'dropdown'` (value chips) is allowed — `tabs` is page-only**
144143
(ADR-0047 amendment): the saved-view switcher already owns the tab bar, so
145144
`ObjectUserFiltersSchema` **rejects** `tabs` at parse (not dropped) and the
146145
`validate` list-view-mode lint reports it. The full
147146
`dropdown | tabs | toggle` range applies only to **page lists** /
148-
`interfaceConfig.userFilters` (the block above).
147+
`interfaceConfig.userFilters`.
149148
- **Omit `userFilters` when unsure — omission means a clean toolbar.** Nothing
150149
is auto-derived.
151150
- `userFilters: { element: 'dropdown' }` (no `fields`) is valid shorthand:
@@ -183,7 +182,7 @@ export const CaseViews = defineView({
183182
| declares `searchableFields` | **that list, verbatim** — any stored field type |
184183
| declares nothing | the auto-default: the name field + the text-like columns (`text` / `email` / `phone` / `url` / `autonumber` / `textarea` / `markdown` / `select`) + every field marked `searchable: true`, of any type except `secret` / `password` / `vector` or a virtual `formula` |
185184

186-
`searchable: false`, the default, removes nothing the type default scans; declare `searchableFields` to choose the set.
185+
`searchable: false`, the default, removes nothing the type default scans.
187186

188187
Modelling side: **objectstack-data → Search Fields**. Query side
189188
(`search.fields` over the API): **objectstack-query → Full-Text Search**.
@@ -256,19 +255,22 @@ grouping: { fields: [
256255
Board settings nest under `kanban:` (`KanbanConfigSchema`) — there is **no
257256
top-level `groupBy`**; the top-level `columns` stays required.
258257

258+
<!-- os:check -->
259259
```typescript
260-
{
260+
import type { ListView } from '@objectstack/spec/ui';
261+
262+
const board: ListView = {
261263
type: 'kanban',
262264
data: { provider: 'object', object: 'project_task' },
263265
columns: ['title', 'assignee', 'priority'],
264266
kanban: {
265267
groupByField: 'status', // a select field — one lane per option
266-
lanes: ['todo', 'in_progress', 'review'], // option VALUES to draw, in this order
268+
lanes: ['todo', 'in_progress', 'review'],
267269
summarizeField: 'estimate_hours', // optional — summed at the top of each column
268270
columns: ['title', 'assignee', 'priority'], // fields shown on each card
269271
},
270272
sort: [{ field: 'priority', order: 'desc' }],
271-
}
273+
};
272274
```
273275

274276
> `lanes` chooses the lanes and their order, not the records: a record whose
@@ -290,8 +292,8 @@ says to convert or replace THAT view.
290292
**A board over a field added in the same change opens empty.** Adding a field
291293
writes nothing into existing rows, so when `kanban.groupByField` is a `select`
292294
created in this change every pre-existing record lands in the trailing
293-
`Uncategorized` lane: one empty lane per option, the populated lane last —
294-
past the right edge of a narrow screen — under a non-zero record count. That
295+
`Uncategorized` lane: one empty lane per option, the populated lane last,
296+
under a non-zero record count. That
295297
is the renderer's correct fallback, not lost data, and the hand-over says so
296298
instead of "the board is ready": (a) the existing records are all in the last
297299
`Uncategorized` lane, scroll right; (b) dragging a card out of it onto a real
@@ -309,8 +311,11 @@ just-added field.
309311
Timeline settings nest under `gantt:` (`GanttConfigSchema`);
310312
`startDateField` / `endDateField` / `titleField` are required in it.
311313

314+
<!-- os:check -->
312315
```typescript
313-
{
316+
import type { ListView } from '@objectstack/spec/ui';
317+
318+
const timeline: ListView = {
314319
type: 'gantt',
315320
data: { provider: 'object', object: 'project_task' },
316321
columns: ['name', 'assigned_to', 'status'], // left-pane tree columns
@@ -322,7 +327,7 @@ Timeline settings nest under `gantt:` (`GanttConfigSchema`);
322327
dependenciesField: 'depends_on', // FS dependency arrows
323328
parentField: 'parent', // builds the summary-bar tree
324329
},
325-
}
330+
};
326331
```
327332

328333
Rows with children (or `type: 'summary'`) are **summary bars**: dragged as a

‎skills/objectstack-ui/rules/pages.md‎

Lines changed: 16 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -143,11 +143,14 @@ Tags are the **registered components** (bare names: `<flex>`, `<grid>`, `<card>`
143143
set** (`<h1>`–`<h6>`, `<p>`, `<a>`, `<ul>/<ol>/<li>`, `<img>`, `<blockquote>`, `<strong>`,
144144
…). Props come from each component's registry `inputs` (e.g. `<text content=…>`,
145145
`<badge label=…>`). **No JavaScript** — `onClick`, `{expr}` logic and `.map()` are NOT
146-
available; use `kind:'react'` for those. `os build` parses the source and fails loudly
146+
available. `os build` parses the source and fails loudly
147147
on unknown tags / missing required props / forbidden constructs (event handlers,
148148
`dangerouslySetInnerHTML`).
149149

150+
<!-- os:check -->
150151
```typescript
152+
import { definePage } from '@objectstack/spec/ui';
153+
151154
export const ReleaseNotesPage = definePage({
152155
name: 'crm_release_notes', label: 'Release Notes', type: 'home', kind: 'html',
153156
source: `
@@ -254,9 +257,11 @@ Rules:
254257
`element:button` — and style each block's root. (`page:card` etc. are fine for
255258
structure but style what you control.)
256259

260+
<!-- os:check -->
257261
```typescript
258-
// A styled pricing card — every block carries responsiveStyles + tokens.
259-
{
262+
import type { PageComponent } from '@objectstack/spec/ui';
263+
264+
const card: PageComponent = {
260265
id: 'plan_solo', type: 'flex',
261266
responsiveStyles: {
262267
large: {
@@ -277,7 +282,7 @@ Rules:
277282
properties: { label: 'Upgrade', variant: 'primary', size: 'large' } },
278283
],
279284
},
280-
}
285+
};
281286
```
282287

283288
**In the source tiers (`kind:'html'` / `kind:'react'`) the same rule holds — no
@@ -344,26 +349,27 @@ behind the screen is not.
344349
The viewer is **platform-level**: one global `/docs/<name>` route
345350
resolves any doc regardless of which app you came from. The URL is
346351
**single-coordinate** — no package or app prefix — so a doc has exactly
347-
one URL. Do **not** design per-app or per-package doc URLs; that gives one
348-
doc many addresses and breaks cross-references.
352+
one URL. Do **not** design per-app or per-package doc URLs.
349353

350354
To surface a doc inside an app, add a `doc` navigation item (a `url` item is
351355
for an external or custom URL): `doc: '<name>'` opens that page,
352356
`book: '<book>'` opens the book at its first readable page (both: that page
353357
in that book). It inherits the docs audience gate, and `os build` refuses a
354358
target the package lacks (`docs/nav-target`):
355359

360+
<!-- os:check -->
356361
```typescript
357-
navigation: [
362+
import type { NavigationItem } from '@objectstack/spec/ui';
363+
364+
const navigation: NavigationItem[] = [
358365
{ id: 'nav_help', type: 'doc', doc: 'crm_user_guide',
359366
label: 'User Guide', icon: 'book-open' },
360-
]
367+
];
361368
```
362369

363370
> **Live instances.** For a *live, interactive
364371
> instance* — a dashboard, a report, a record table — **don't embed it**:
365-
> link to it by URL and let the platform render it (one source, never a
366-
> stale copy).
372+
> link to it by URL and let the platform render it.
367373
368374
### Inline metadata views — the `metadata` fence (ADR-0051)
369375

0 commit comments

Comments
 (0)