Skip to content

Commit c421bae

Browse files
committed
docs(skill): document auto status path + detail.stageField opt-out
The distributed objectstack-ui skill never mentioned that ObjectUI auto- synthesizes a detail page and auto-detects a status field for a top record:path stepper, nor the detail.stageField:false opt-out (objectstack-ai/objectui#2066). AI authors install framework's skills, so without this they re-hit the 'non-linear status rendered as an ordered path, can't disable it' trap. Adds, after the record:path example: the detectStatusField precedence and a detail:{ stageField:false } example, stressing it must live in the passthrough detail block (top-level unknown keys are rejected by ObjectSchema.create()). Closes #2452
1 parent 59576d0 commit c421bae

1 file changed

Lines changed: 29 additions & 0 deletions

File tree

skills/objectstack-ui/SKILL.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -709,6 +709,35 @@ export const LeadDetailPage = definePage({
709709
});
710710
```
711711

712+
> **Auto-synthesized detail pages & the status path.** When an object has **no
713+
> authored record page**, ObjectUI synthesizes a default detail page and
714+
> auto-detects a status field to drive a top `record:path` stepper. The stage
715+
> hint lives in the object def's `detail` block (`object.zod.ts` — a
716+
> `.passthrough()` block documented as "Detail-page UI hints consumed by
717+
> @object-ui/plugin-detail synth"). Detection precedence (`detectStatusField`):
718+
> (0) `detail.stageField === false | null` → explicit opt-out, no path;
719+
> (1) `detail.stageField` is a field name → use it; (2) else first field named
720+
> `status` / `stage` / `state` / `phase`; (3) else first field whose `type` is
721+
> `status` / `stage`; (4) else no path.
722+
>
723+
> **Opt out with `detail: { stageField: false }`.** Many objects carry a
724+
> `status` *select* that is a **non-linear** picklist (e.g. 正常 / 暂停 / 作废),
725+
> not an ordered pipeline — rendering it as an ordered stepper is wrong:
726+
>
727+
> ```typescript
728+
> ObjectSchema.create({
729+
> name: 'production_plan',
730+
> detail: { stageField: false }, // suppress the auto status path
731+
> fields: { status: Field.select({ options: [...] }) /**/ },
732+
> });
733+
> ```
734+
>
735+
> **Put it under `detail`, not top-level.** `ObjectSchema.create()` rejects
736+
> unknown *top-level* keys (a bare `stageField:` fails to compile and is rejected
737+
> at build). The `detail` block is `.passthrough()`, so author-facing synth hints
738+
> like `stageField` belong there. Use `detail: { stageField: 'my_field' }` to
739+
> pick which field drives the path.
740+
712741
> **Variable substitution** — `{first_name}`, `{current_user.first_name}`,
713742
> `{current_quarter_start}` etc. resolve from the page's `variables` block,
714743
> the bound record, and the runtime context. Declare `variables: [...]` at

0 commit comments

Comments
 (0)