Skip to content

docs(ui-merge): merge the 46 objectui field, Console-behaviour and schema pages into the objectstack docs (K2) - #27170

Merged
os-zhuang merged 11 commits into
mainfrom
claude/project-thread-yfxlcc
Oct 28, 2026
Merged

os-zhuang merged 11 commits into
mainfrom
claude/project-thread-yfxlcc

Conversation

@objectstack-fleet

Copy link
Copy Markdown
Contributor

Requested by Tesla · project thread

Fixes #27141

维护者速读

  • 改了什么:把 objectui 文档里 46 页(27 个字段页、14 个 Console/元数据行为页、5 个 schema 页)中 objectstack 文档缺的内容并入现有页面;新增 Console 和 Studio 两页,其余并入 field-types、apps、pages、actions、dashboards、forms、create-vs-edit-form、print-pages、react-pages、ai/skills。
  • 为什么改:objectui.org 将并入 objectstack 文档站(方案 B),作者以后只看 objectstack.ai/docs,字段和页面行为不能一半留在要下线的站点上。
  • 风险与回滚:纯文档,不动代码和 ui/content/docs;与 spec 冲突的说法(如 menu、grid 字段类型、${} 写的 visibleWhen、旧 report/action 组件形状)一律未搬。回滚即还原本 PR。
  • 先看:下方 46 行映射表(K4 据此做跳转),以及新页 content/docs/ui/console.mdx、content/docs/ui/studio.mdx。
  • 两分钟验证:pnpm --filter @objectstack/docs build 绿;打开 /docs/ui/console、/docs/ui/studio、/docs/data-modeling/field-types 看渲染。
  • 需要你做的:无需决策;CI 绿后按常规审阅合并。

What changes

Card K2 of the objectui.org docs fold. The 46 pages the card names are merged into the existing objectstack pages: only what the target lacked (widget and display behaviour, Console interaction, worked examples) was carried, rewritten as plain code blocks; what the target already says was dropped; where the two disagreed the target's wording was kept; and every carried claim was read against packages/spec, so an objectui claim that contradicts the spec was dropped or corrected, not merged.

  • data-modeling/field-types.mdx keeps one page with per-type In the Console paragraphs and a new How the Console renders a field section, so its existing anchors survive.
  • Two new pages: ui/console.mdx (how the Console renders metadata, per-user state, predicate failures) and ui/studio.mdx (access and package scope, drafts, object design, the Flow Designer, metadata diagnostics). Both are listed in ui/meta.json and the module index.
  • ui/print-pages.mdx and ui/react-pages.mdx are now the single page for their topic.
  • Nothing under ui/content/docs/, ui/apps/site or content/docs/sdk/ is touched; K4 retires the old pages and adds redirects from the table below.

Old path → target (46 rows)

Old page (ui/content/docs/…) Target (content/docs/…) Carried
fields/auto-number data-modeling/field-types.mdx#autonumber The Console assigns the number on insert (the create form shows it empty) and the format-token table
fields/boolean data-modeling/field-types.mdx#boolean Switch in forms; read-only and grid display reads Yes / No
fields/currency data-modeling/field-types.mdx#currency Input with the currency symbol; read-only and grid display
fields/date data-modeling/field-types.mdx#date, #deadlines-duelike-and-settledwhen A date is a calendar day shown the same in every timezone; the picker; the dueLike / settledWhen deadline rendering
fields/datetime data-modeling/field-types.mdx#datetime A datetime is an instant rendered in the viewer's timezone; the combined picker
fields/email data-modeling/field-types.mdx#email Email input; mailto: link when read-only and in grids
fields/file data-modeling/field-types.mdx#media-types, #file Value is the bare sys_file id(s); upload refusal; maxSize checked before upload; restricted files (metadataRefused) draw a lock; legacy inline objects still render; list display
fields/formula data-modeling/field-types.mdx#formula Read-only, drawn by returnType
fields/grid data-modeling/field-types.mdx#master_detail grid is not a spec FieldType, so the page's widget content went to the master_detail inline grid (InlineGridColumnSchema columns, derived columns, ordering). Dropped: grid as a field type
fields/image data-modeling/field-types.mdx#image Thumbnail grid in forms, three thumbnails plus a count in grids, accept defaults to image/*
fields/location data-modeling/field-types.mdx#location Latitude-then-longitude input and its display
fields/lookup data-modeling/field-types.mdx#lookup Typeahead and Record Picker, lookupColumns (string widths), lookupPageSize, displayField / descriptionField, quick create (allowCreate), dependent lookups. Dropped: reference_field, avatar_field, picker subtitle (not spec keys)
fields/number data-modeling/field-types.mdx#number, #what-a-number-input-silently-rewrites Stepper (step), the useGrouping table, what a native number input announces and silently rewrites
fields/object data-modeling/field-types.mdx#json json, composite and record share a JSON text editor; what it accepts and refuses
fields/password data-modeling/field-types.mdx#password Masked input with show/hide; stored value masked when read-only
fields/percent data-modeling/field-types.mdx#percent scale as displayed decimals and input step; the fraction-vs-whole storage rule
fields/phone data-modeling/field-types.mdx#phone tel input and link. Dropped: the input mask (the widget reads no format mask)
fields/rich-text data-modeling/field-types.mdx#richtext One shared editor for markdown / html / richtext, and what type changes
fields/select data-modeling/field-types.mdx#select Dropdown and colour badges, empty-label fallback, cascading options (visibleWhen / dependsOn), server enforcement of the option set
fields/summary data-modeling/field-types.mdx#summary Read-only roll-up drawn by one rule in form and grid
fields/text data-modeling/field-types.mdx#text Single-line input; placeholder
fields/textarea data-modeling/field-types.mdx#textarea rows as the editor height
fields/time data-modeling/field-types.mdx#time 24-hour HH:mm input
fields/url data-modeling/field-types.mdx#url URL input; only http(s) values become links
fields/user data-modeling/field-types.mdx#user Search-first people picker delegating to the lookup picker
fields/vector data-modeling/field-types.mdx#vector Read-only; the form previews the first values and the dimension count
fields/widget-props data-modeling/field-types.mdx#how-the-console-renders-a-field Metadata keys vs runtime widget props, widget, the shared empty-value affordance. Not carried: the FieldWidgetComponentProps API detail beyond one sentence (SDK)
guide/console ui/console.mdx (new), ui/studio.mdx (new) Configuration inputs, navigating, record overlay modes and the drawer stack, the Approvals tab, refused dashboards and list views; Studio access, package scope, read-only packages, flows in no package, Create app, copilot drafts, object design panels and why an action can be missing. Not carried: dev quick start and source layout (repo-internal), Setup Positions, the app creation wizard
guide/metadata-diagnostics ui/studio.mdx#metadata-diagnostics, ui/console.mdx#when-a-predicate-cannot-be-evaluated The _diagnostics envelope, the sweep endpoint and its response (stats includes locked), the four Studio surfaces, CEL lint on drafts, the runtime fail-open / fail-closed table, submit refusal, blank rules. Corrected: the /api/v1/meta/items/… paths (no such route) and os check (the command is os validate). Not carried: MetadataClient / useGlobalDiagnostics (SDK)
guide/flow-designer ui/studio.mdx#the-flow-designer Canvas gestures, the palette (search, categories, recents, server merge), the inspector (required markers, configSchema forms, approver values, decision branches, assignments), the four panels
guide/notifications ui/console.mdx#notifications The bell reads the server inbox through one shared feed. Not carried: the React notification API (SDK; NotificationSchema is not in the spec)
guide/slotted-pages ui/pages.mdx#record-pages The synthesized default (tab strip, relatedList: 'primary', Attachments, width-based layout), the slot table, the discussion panel and enable.feeds, related-list gating, paging and action ids, header action placement and the refresh button. Corrected: details + tabs are refused together (the spec), not "tabs wins". Dropped: relatedLayout (not a spec key) and the @object-ui/plugin-detail sub-builders (SDK)
guide/record-edit-modes ui/create-vs-edit-form.mdx#modal-or-page-editmode editMode (modal / page), the page routes, navigate_create / navigate_edit buttons with properties.params templates
guide/designing-app-navigation ui/apps.mdx#designing-the-navigation Landing-URL table for plain / viewName / filters / page entries, the rule of least power, label fallback. Dropped: "menu is deprecated legacy" (the spec refuses menu)
guide/dashboard-filters ui/dashboards.mdx#filter-controls-and-options, #in-the-console Control-type → condition table, static options and the refused string shorthand, optionsFrom, the object translation key, symbolic presets, page.dateRange shape, nested variable scopes, the Studio bindings inspector, Refresh All. Not carried: the tutorial steps the target already covers
guide/public-forms ui/forms.mdx#6-internal-forms-_consoleformsname /apps/:appName/forms/:name, heading resolution, Cancel. Not carried: EmbeddableForm (SDK component, its own security options)
guide/user-state-persistence ui/console.mdx#what-each-users-own-state-keeps Per-user favorites, pins, recents, list state and overlay width; keys and limits; list state never writes the view; Reset view. Not carried: the React hooks (SDK)
guide/expressions ui/pages.mdx#expression-holes-in-element-properties ${…} holes in element properties, their roots, locale maps, what an unresolved hole renders. Dropped: the JS-style ${…} visibleWhen / hidden / disabled examples (the spec makes those CEL predicates) and the PredicateScopeProvider / evaluator API (SDK)
guide/print-pages ui/print-pages.mdx#print-in-the-browser The Print button and browser print preview, the named record-page route, the key → print CSS table, blocks printing whole. Merged into the one page
guide/react-pages ui/react-pages.mdx, ui/pages.mdx#list-blocks-in-a-region <box> as the html-tier wrapper, no raw-HTML block; list-block sizing in regions and tab badges. The rest the target already says. Merged into the one page
guide/agent-skills ai/skills.mdx#the-skill-catalog The objectui skill ships in @objectstack/skills, its structure and its boundary. Dropped: the npx skills add objectstack-ai/objectui install (the catalog installs from npm)
core/app-schema ui/apps.mdx#action-navigation How the Console runs an action navigation item. Dropped: AppComponentSchema (menu, path, layout, hidden: '${…}'), which the spec's AppSchema refuses
core/report-schema ui/reports.mdx Nothing new. The page documents @object-ui/types' ReportComponentSchema (inline fields, filters, schedule, exportConfigs), which the spec's dataset-bound ReportSchema does not accept
core/enhanced-actions ui/actions.mdx#collect-input-and-shape-the-ux Param widgets, field-backed params on the selection bar, emitted value shapes, Confirm disabled during upload, param visible; successMessage {{ }} holes, outcomeMessages, onSuccess. Dropped: ajax / confirm / dialog action types, chain, condition, tracking, retry (the @object-ui/types ActionSchema, not the spec's)
core/theme-schema ui/apps.mdx#branding accentColor, the --primary / --accent mapping, the single logo asset, no theme document in metadata. Not carried: ThemeProvider / useTheme / the Theme document (React SDK; the spec retired its theme module)
layout/page-header ui/pages.mdx#the-page-header, ui/actions.mdx#permissions-and-visibility The props table, actions as the whole id set, the record chip, the one-<h1> rule; relation fields bind as their id and current_user.can / hasCapability gates. Not carried: Tailwind class lists and the React PageHeader export. Corrected: os.user examples to current_user

scripts/docs-audit/handwritten-docs.json gains the two new pages, which check:docs-audit-scope requires of any new hand-written page.

Why

objectui.org folds into the objectstack docs site (Tesla's option B on the fold evaluation). Metadata authors and Console users read objectstack.ai/docs, and today half of a field's or a page's behaviour lives on a site that goes away with the fold.

Tests

Docs only: no code, no test changes. The carried claims were checked by reading packages/spec (Zod schemas and their descriptions) and, for routes and commands, the server and CLI sources; the corrections are named in the rows above.

Verification

  • pnpm --filter @objectstack/docs build: exit 0.
  • node scripts/pm/dispatch-gates.mjs --commands derives 53 command families for this diff; all 53 ran locally with exit 0 (--ran reconciliation: 53 derived, 53 run, 0 NOT-MEASURED, 0 UNRUN), including check:docs, check:doc-authoring, check:doc-anchors, check:doc-frontmatter, check:docs-redirects, check:docs-single-h1, check:docs-spec-enumerations, check:doc-formula-expressions, check:doc-security-posture and check:skill-examples (270 prose examples type-check).
  • The first sweep found three things, fixed in this branch: the audit-scope list lacked the two new pages, a table cell used a reserved word, and the editMode example object declared no sharingModel.

Acceptance notes

Clause-②: no
Metadata-protocol: none

Human Minimum

  • 1. Schemas start as Zod; packages/spec holds no runtime logic. (Not touched.)
  • 2. Every name I added uses the casing for its kind.
  • 3. No formatter ran. (pnpm lint was not run locally; this diff is MDX, JSON and one audit list, and CI runs the lint lanes.)
  • 4. One issue, one branch off an up-to-date main, one pull request.
  • 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset. (Docs only: skip-changeset.)
  • 6. packages/spec touched: its generated artifacts are regenerated and committed. (Not touched.)
  • 7. No hand edits to content/docs/references/, packages/*/CHANGELOG.md or content/docs/releases/.
  • 8. Title, body and comments are in English.
  • The Before Submitting list in CONTRIBUTING.md is done.

Generated by Claude Code

claude added 11 commits October 28, 2026 08:21
…tui field pages into field-types

Claude-Session: https://claude.ai/code/session_01L9qibzFEhNgS8KGkqBsQFu
Co-authored-by: Claude <noreply@anthropic.com>
…e, notification and predicate-failure guides

Claude-Session: https://claude.ai/code/session_01L9qibzFEhNgS8KGkqBsQFu
Co-authored-by: Claude <noreply@anthropic.com>
…data-diagnostics and Studio console guides

Claude-Session: https://claude.ai/code/session_01L9qibzFEhNgS8KGkqBsQFu
Co-authored-by: Claude <noreply@anthropic.com>
…d branding into apps

Claude-Session: https://claude.ai/code/session_01L9qibzFEhNgS8KGkqBsQFu
Co-authored-by: Claude <noreply@anthropic.com>
…etails into dashboards, print-pages and react-pages

Claude-Session: https://claude.ai/code/session_01L9qibzFEhNgS8KGkqBsQFu
Co-authored-by: Claude <noreply@anthropic.com>
…nd list-block behaviour into pages

Claude-Session: https://claude.ai/code/session_01L9qibzFEhNgS8KGkqBsQFu
Co-authored-by: Claude <noreply@anthropic.com>
…skill into forms, create-vs-edit-form and ai/skills

Claude-Session: https://claude.ai/code/session_01L9qibzFEhNgS8KGkqBsQFu
Co-authored-by: Claude <noreply@anthropic.com>
…tes into actions

Claude-Session: https://claude.ai/code/session_01L9qibzFEhNgS8KGkqBsQFu
Co-authored-by: Claude <noreply@anthropic.com>
…pe, and drop a reserved word from the page-header table

Claude-Session: https://claude.ai/code/session_01L9qibzFEhNgS8KGkqBsQFu
Co-authored-by: Claude <noreply@anthropic.com>
@objectstack-fleet objectstack-fleet Bot added documentation Improvements or additions to documentation skip-changeset PR has no user-facing published change; bypasses the changeset gate labels Oct 28, 2026
@github-actions

Copy link
Copy Markdown
Contributor

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 0 changed package(s)), so this run has no opinion about the docs.

What this run could not see

Coarse fallback — 0 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 0f1045bcc7a3e424def90abcc70dc849944b00bd → packageMentionDocs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation size/xl skip-changeset PR has no user-facing published change; bypasses the changeset gate

Projects

None yet

3 participants