Skip to content

Commit 773055d

Browse files
committed
docs(frontend): a Custom front-end entry for the Object UI SDK, trimmed to what only SDK readers need
The moved SDK pages leave content/docs/sdk for a new entry, content/docs/frontend (Custom front-end), placed after API & SDK. Its landing page routes three needs: a custom page inside the Console (React pages), data access from your own front-end (Client SDK), and rendering ObjectStack metadata in your own React app (the Object UI SDK). Pages that duplicated the site are cut or merged: - schema-overview and api/schema-reference are removed; the generated component reference and references/ui cover them. - core/schema-renderer is merged into schema-rendering; plugins/index into the UI plugins overview (plugins/index); plugin-report into ui/reports. - The 57 renderer-type pages become one renderer types page; none of the types is in sdui.manifest.json. - Plugin pages keep installation and React usage; their Schema API, catalog example galleries and metadata sections are removed, with a link to each type's generated entry. - Metadata behaviour the site lacked moves to the metadata pages: field drawing (referenceVia, registry pickers, heading faces) into data-modeling/field-types, element data-source keys per block into ui/pages, edit-save semantics into ui/forms, and three report sections into ui/reports. Claude-Session: https://claude.ai/code/session_01L9qibzngYyRjmvNxjkfVyd Co-authored-by: Claude <noreply@anthropic.com>
1 parent d426bd4 commit 773055d

132 files changed

Lines changed: 3223 additions & 19960 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎content/docs/data-modeling/field-types.mdx‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1058,6 +1058,83 @@ what the box accepts, and only one of the two outcomes is announced:
10581058
10591059
"No warning" therefore does not mean "the value is right".
10601060
1061+
### Polymorphic pointer pairs (`referenceVia`)
1062+
1063+
A `text` field that declares `referenceVia` holds a record id of the object its
1064+
sibling column names, row by row: `sys_approval_request.record_id` points at the
1065+
record `object_name` names, and `sys_activity.source_id` at the one
1066+
`source_object` names. The record details grid resolves the pair from the row
1067+
with `resolveRecordPointer(field, row)` and draws it with the renderer
1068+
registered under `RECORD_POINTER_CARD_TYPE`. The fields package's default draws
1069+
the record id as text; the console registers a record preview card there, so a
1070+
pointer field on a record page shows the record it points at. When the card
1071+
could read that record, its title links to the record's page in the current
1072+
app, built by the same record-link builder the page's lookup values use; a
1073+
record the reader cannot read is drawn with no link, and the card never says
1074+
why. Nothing is authored for this: the `referenceVia` declaration on the field
1075+
is the whole contract. List cells are not a call site yet.
1076+
1077+
When the platform deletes the record a pointer names, it can say so on the row.
1078+
A pointer field that also declares `referenceDeletedWhen: { field, value }`
1079+
names a sibling `select` field and the option the platform writes there, as
1080+
`sys_approval_request.record_id` declares
1081+
`{ field: 'cancel_reason', value: 'record_deleted' }`. On a row holding that
1082+
option the details grid draws a tombstone in the option's own label (localized
1083+
when the console's bundle localizes it), reads nothing and links nothing. A
1084+
record the card cannot read on any other row still gets the cause-free text:
1085+
only the declaration means deleted.
1086+
1087+
### Naming a registry item by name (`position-ref`, `permission-ref`)
1088+
1089+
A `text` field that stores the **machine name** of one item of a metadata
1090+
registry — a position, a permission set — declares the matching widget, and the
1091+
record form lists that registry instead of asking for a typed name:
1092+
1093+
```json
1094+
{
1095+
"position": {
1096+
"type": "text",
1097+
"label": "Position",
1098+
"required": true,
1099+
"maxLength": 100,
1100+
"widget": "position-ref"
1101+
}
1102+
}
1103+
```
1104+
1105+
| Widget | Lists | Stores |
1106+
|---|---|---|
1107+
| `position-ref` | the `position` registry (`GET /api/v1/meta/position`) | the position's `name` |
1108+
| `permission-ref` | the `permission` registry (`GET /api/v1/meta/permission`) | the permission set's `name` |
1109+
1110+
Like every `widget` value, the name is looked up as `field:<widget>`. Each item
1111+
reads as its label beside its name, and the value written is the name alone: no
1112+
label, no id. A stored name the registry does not list stays on screen, flagged
1113+
*not found*, so a renamed or removed item is visible rather than dropped.
1114+
`position-ref` leaves out the audience anchors, the spec's
1115+
`AUDIENCE_ANCHOR_POSITIONS` (`everyone`, `guest`), because the server refuses an
1116+
anchor as a grant target; a stored anchor still shows as its own option. The
1117+
list comes from the data source's `listMetadataItems(type)`. When the adapter
1118+
has none, the list is empty, or the load fails, the field is a text box that
1119+
takes the typed name; a failure is shown with its cause, and the box stays
1120+
editable.
1121+
1122+
### A widget's face on the record heading
1123+
1124+
A `text` field that declares `widget: 'recipient-picker'` or `widget: 'object-ref'` is drawn
1125+
in a list column through the read cell registered under that widget's key, which names what
1126+
the stored value references. When that field is also the object's `nameField`, the record
1127+
page heading draws the value through the same cell: a record share heads its page with the
1128+
recipient's name, not the user id it stores. Nothing is authored for this; the `widget`
1129+
declaration on the field is the whole contract.
1130+
1131+
The heading lives in `@object-ui/components`, which this package depends on and so cannot be
1132+
imported from here the other way round. `@object-ui/components` therefore owns a slot,
1133+
`setFieldReadFaceResolver` / `resolveFieldReadFace`, and this package fills it when it loads with the
1134+
lookup the list cells make. The widget's key draws the stored text until a host registers a
1135+
face under it (the console registers its own), and while it does, the heading prints the
1136+
stored value as before. So does a host that does not load `@object-ui/fields`.
1137+
10611138
## Choosing a Field Type
10621139
10631140
Not sure which type fits your data? Follow the [Field Type Decision Tree](/docs/data-modeling/field-type-decision-tree) — a flowchart, quick-reference tables, and a use-case mapping for every type in this gallery.
Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -301,6 +301,6 @@ The AppShell includes:
301301

302302
## Related
303303

304-
- [SidebarNav](/docs/sdk/layout/sidebar-nav) - Sidebar navigation component
304+
- [SidebarNav](/docs/frontend/sidebar-nav) - Sidebar navigation component
305305
- [PageHeader](/docs/ui/pages) - Page header component
306-
- [Page](/docs/sdk/components/layout/page) - Page layout component
306+
- [Page](/docs/frontend/renderers) - Page layout component

content/docs/sdk/guide/architecture-overview.mdx renamed to content/docs/frontend/architecture-overview.mdx

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@ description: Deep dive into the ObjectUI 3-layer architecture, data flow, plugin
55

66
ObjectUI is a **Server-Driven UI (SDUI) engine** that transforms JSON schemas into fully interactive React interfaces built on Shadcn/Tailwind. This document covers the internal architecture, data flow, and extension points.
77

8+
It is the architecture of the SDK's own packages. Where ObjectUI sits among ObjectStack's protocol layers (data, kernel, view) is covered in [Protocol architecture](/docs/concepts/architecture).
9+
810
## The 3-Layer Architecture
911

1012
ObjectUI enforces a strict separation across three layers. Each layer has clear constraints on what it may import and what it may contain.
@@ -328,9 +330,9 @@ packages/
328330

329331
## Further Reading
330332

331-
- [Schema Overview](/docs/sdk/guide/schema-overview) — JSON schema structure
332-
- [Schema Rendering](/docs/sdk/guide/schema-rendering) — How schemas become UI
333-
- [Component Registry](/docs/sdk/guide/component-registry) — Registering components
334-
- [Plugin Development](/docs/sdk/guide/plugin-development) — Building plugins
333+
- [Schema Overview](/docs/frontend) — JSON schema structure
334+
- [Schema Rendering](/docs/frontend/schema-rendering) — How schemas become UI
335+
- [Component Registry](/docs/frontend/component-registry) — Registering components
336+
- [Plugin Development](/docs/frontend/plugin-development) — Building plugins
335337
- [Expressions](/docs/ui) — Expression syntax reference
336-
- [Theming](/docs/sdk/guide/theming) — Theme configuration
338+
- [Theming](/docs/frontend/theming) — Theme configuration

content/docs/sdk/guide/building-crud-app.mdx renamed to content/docs/frontend/building-crud-app.mdx

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -201,7 +201,7 @@ export class RestDataSource implements DataSource {
201201
}
202202
```
203203

204-
> **Tip:** For the ObjectStack backend, use the official `@object-ui/data-objectstack` adapter instead of writing your own. See the [Data Connectivity](/docs/sdk/guide/data-source) guide for details.
204+
> **Tip:** For the ObjectStack backend, use the official `@object-ui/data-objectstack` adapter instead of writing your own. See the [Data Connectivity](/docs/frontend/data-source) guide for details.
205205
206206
## Step 5: Render a CRUD Grid View
207207

@@ -421,7 +421,7 @@ class AuthenticatedDataSource extends RestDataSource {
421421

422422
## Next Steps
423423

424-
- Explore the [Schema Overview](/docs/sdk/guide/schema-overview) for advanced schema features
425-
- Add a Kanban board view using `@object-ui/plugin-kanban` (see the [Kanban Plugin](/docs/sdk/plugins/plugin-kanban) reference for runnable board schemas)
426-
- Connect to a production backend with the [Data Connectivity](/docs/sdk/guide/data-source) guide
424+
- Explore the [Schema Overview](/docs/frontend) for advanced schema features
425+
- Add a Kanban board view using `@object-ui/plugin-kanban` (see the [Kanban Plugin](/docs/frontend/plugins/plugin-kanban) reference for runnable board schemas)
426+
- Connect to a production backend with the [Data Connectivity](/docs/frontend/data-source) guide
427427
- Build multi-object apps with relationships using `lookup` / `master_detail` fields (see the [Lookup Field](/docs/data-modeling/field-types) reference)
Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -292,7 +292,7 @@ by this CLI:
292292
npm create @object-ui/plugin my-awesome-widget
293293
```
294294

295-
See [Create Plugin](/docs/sdk/utilities/create-plugin) for where to run it and what
295+
See [Create Plugin](/docs/frontend/create-plugin) for where to run it and what
296296
it writes.
297297

298298
## Schema file format
@@ -411,12 +411,12 @@ The CLI is built on:
411411

412412
## Next steps
413413

414-
- **[Create Plugin](/docs/sdk/utilities/create-plugin)** — author your own plugins
415-
- **[Schema Overview](/docs/sdk/guide/schema-overview)** — learn the schema format
416-
- **[Plugins](/docs/sdk/plugins)** — explore available plugins
414+
- **[Create Plugin](/docs/frontend/create-plugin)** — author your own plugins
415+
- **[Schema Overview](/docs/frontend)** — learn the schema format
416+
- **[Plugins](/docs/frontend/plugins)** — explore available plugins
417417
- **[Examples](https://github.com/objectstack-ai/objectstack/tree/main/ui/examples)** — see example projects
418418

419419
## Need help?
420420

421421
- [GitHub Issues](https://github.com/objectstack-ai/objectstack/issues)
422-
- [Documentation](/docs/sdk)
422+
- [Documentation](/docs/frontend)

content/docs/sdk/guide/component-registry.mdx renamed to content/docs/frontend/component-registry.mdx

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -447,11 +447,11 @@ export { RatingComponent }
447447
## Next Steps
448448

449449
- [Expression System](/docs/ui) - Learn about dynamic expressions
450-
- [Schema Rendering](/docs/sdk/guide/schema-rendering) - Understand the rendering engine
451-
- [Custom Plugin Development](/docs/sdk/guide/plugin-development) - Deep dive into component creation
450+
- [Schema Rendering](/docs/frontend/schema-rendering) - Understand the rendering engine
451+
- [Custom Plugin Development](/docs/frontend/plugin-development) - Deep dive into component creation
452452

453453
## Related Documentation
454454

455455
- [`@object-ui/core` README](https://github.com/objectstack-ai/objectstack/tree/main/ui/packages/core) - Component registry API
456456
- [`@object-ui/react` README](https://github.com/objectstack-ai/objectstack/tree/main/ui/packages/react) - React integration
457-
- [Schema Type Reference](/docs/sdk/api/schema-reference) - Component metadata reference
457+
- [Schema Type Reference](/docs/ui/components) - Component metadata reference

content/docs/sdk/utilities/create-plugin.mdx renamed to content/docs/frontend/create-plugin.mdx

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ without asking:
4343
- the directory it writes into, `packages/plugin-<name>`;
4444
- the package name, `@object-ui/plugin-<name>`;
4545
- the `type` key the plugin registers itself under in the
46-
[Component Registry](/docs/sdk/guide/component-registry) — the cleaned name itself, so
46+
[Component Registry](/docs/frontend/component-registry) — the cleaned name itself, so
4747
`awesome` in the example above;
4848
- the PascalCase component name, and the name of the file implementing it.
4949

@@ -103,7 +103,7 @@ notes on what to expect from them:
103103
To use the plugin from an app in the same workspace, add it as a `workspace:*` dependency
104104
and import the package for its side effect: importing it is what registers the component,
105105
which is what makes its `type` key usable in a schema. See
106-
[Plugin Concepts](/docs/sdk/guide/plugins).
106+
[Plugin Concepts](/docs/frontend/plugins).
107107

108108
To publish it, use `pnpm publish`. pnpm rewrites the `workspace:*` links into real ranges
109109
as it packs; a plain `npm publish` would ship the literal `workspace:*` and the resulting
@@ -175,13 +175,13 @@ no write access outside the npm cache.
175175

176176
## Next Steps
177177

178-
- **[Plugin Concepts](/docs/sdk/guide/plugins)** - Learn how plugins work
179-
- **[Plugin Development Guide](/docs/sdk/guide/plugin-development)** - The full authoring guide
180-
- **[Component Registry](/docs/sdk/guide/component-registry)** - Register components
181-
- **[CLI](/docs/sdk/utilities/cli)** - Test your plugin with the CLI
178+
- **[Plugin Concepts](/docs/frontend/plugins)** - Learn how plugins work
179+
- **[Plugin Development Guide](/docs/frontend/plugin-development)** - The full authoring guide
180+
- **[Component Registry](/docs/frontend/component-registry)** - Register components
181+
- **[CLI](/docs/frontend/cli)** - Test your plugin with the CLI
182182

183183
## Need Help?
184184

185185
- [GitHub Issues](https://github.com/objectstack-ai/objectstack/issues)
186-
- [Plugin Development Guide](/docs/sdk/guide/plugin-development)
186+
- [Plugin Development Guide](/docs/frontend/plugin-development)
187187
- [Examples](https://github.com/objectstack-ai/objectstack/tree/main/ui/packages)

content/docs/sdk/utilities/data-objectstack.mdx renamed to content/docs/frontend/data-objectstack.mdx

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ describes *how to reach the backend*:
100100
The binding accepts `object`, `view`, `filter`, `sort` and `limit`. `view` names
101101
a saved view whose columns, filter, sort and page size are applied to the render;
102102
`filter` is *additional* criteria that AND-combines with the view's rather than
103-
replacing it. See [Per-element data binding](/docs/sdk/guide/data-source) for the
103+
replacing it. See [Per-element data binding](/docs/frontend/data-source) for the
104104
full table of which blocks honour which keys.
105105

106106
## API Reference
@@ -274,7 +274,7 @@ interface ElementDataSource {
274274
The spec schema is **strict**: a key outside this list is rejected rather than
275275
silently ignored. `SchemaRenderer` also strips this key from the props it
276276
spreads, so the metadata can never shadow the injected adapter. Full per-block
277-
support table: [Per-element data binding](/docs/sdk/guide/data-source).
277+
support table: [Per-element data binding](/docs/frontend/data-source).
278278

279279
## Usage Examples
280280

@@ -499,9 +499,9 @@ Many plugins support ObjectStack data sources:
499499
## Next Steps
500500

501501
- **[ObjectStack Documentation](https://docs.objectstack.ai)** - Learn about ObjectStack
502-
- **[Data Sources Guide](/docs/sdk/guide/data-source)** - Learn about data sources
503-
- **[Plugins](/docs/sdk/plugins)** - Explore plugins with data support
504-
- **[Schema Overview](/docs/sdk/guide/schema-overview)** - Learn the schema format
502+
- **[Data Sources Guide](/docs/frontend/data-source)** - Learn about data sources
503+
- **[Plugins](/docs/frontend/plugins)** - Explore plugins with data support
504+
- **[Schema Overview](/docs/frontend)** - Learn the schema format
505505

506506
## Troubleshooting
507507

@@ -551,4 +551,4 @@ Check browser console and network tab for errors. Verify:
551551

552552
- [ObjectStack Documentation](https://docs.objectstack.ai)
553553
- [GitHub Issues](https://github.com/objectstack-ai/objectstack/issues)
554-
- [ObjectUI Documentation](/docs/sdk)
554+
- [ObjectUI Documentation](/docs/frontend)

0 commit comments

Comments
 (0)