Skip to content

Commit 9527df2

Browse files
committed
docs(sdk): move the Object UI SDK guide and renderer-type pages into content/docs/sdk
Claude-Session: https://claude.ai/code/session_01L9qibzngYyRjmvNxjkfVyd Co-authored-by: Claude <noreply@anthropic.com>
1 parent 5866877 commit 9527df2

114 files changed

Lines changed: 30247 additions & 0 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/meta.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
"permissions",
1414
"ai",
1515
"api",
16+
"sdk",
1617
"upgrading",
1718
"protocol-upgrade",
1819
"---Platform---",

‎content/docs/sdk/api/meta.json‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
{
2+
"title": "API Reference",
3+
"pages": [
4+
"schema-reference"
5+
]
6+
}

‎content/docs/sdk/api/schema-reference.mdx‎

Lines changed: 1443 additions & 0 deletions
Large diffs are not rendered by default.
Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
---
2+
title: "Button Group"
3+
description: "Group multiple buttons together with shared styling"
4+
---
5+
6+
The Button Group component groups multiple buttons together with consistent styling.
7+
8+
## Basic Usage
9+
10+
**Basic Button Group**
11+
12+
```json
13+
{
14+
"type": "button-group",
15+
"buttons": [
16+
{
17+
"label": "Left"
18+
},
19+
{
20+
"label": "Center"
21+
},
22+
{
23+
"label": "Right"
24+
}
25+
]
26+
}
27+
```
28+
29+
## Variants
30+
31+
**Outline Variant**
32+
33+
```json
34+
{
35+
"type": "button-group",
36+
"variant": "outline",
37+
"buttons": [
38+
{
39+
"label": "Day"
40+
},
41+
{
42+
"label": "Week"
43+
},
44+
{
45+
"label": "Month"
46+
}
47+
]
48+
}
49+
```
50+
51+
## Schema
52+
53+
```ts
54+
interface ButtonGroupButton {
55+
label: string; // Button label (required)
56+
variant?: 'default' | 'secondary' | 'destructive' | 'outline' | 'ghost' | 'link';
57+
size?: 'default' | 'sm' | 'lg' | 'icon';
58+
disabled?: boolean; // Whether this button is disabled
59+
onClick?: never; // RETIRED (objectui#6124) — author behaviour
60+
// as a node type, e.g. an action:button node
61+
className?: string; // Per-button CSS class
62+
}
63+
64+
interface ButtonGroupSchema {
65+
type: 'button-group';
66+
buttons?: ButtonGroupButton[]; // Button definitions
67+
68+
// Defaults applied to every button that does not set its own
69+
variant?: 'default' | 'secondary' | 'destructive' | 'outline' | 'ghost' | 'link';
70+
size?: 'default' | 'sm' | 'lg' | 'icon';
71+
72+
// States
73+
disabled?: boolean | string | { dialect?: string; source: string }; // boolean, predicate expression, or CEL envelope
74+
75+
// Styling
76+
className?: string;
77+
}
78+
```
79+
80+
## Examples
81+
82+
### Toolbar Actions
83+
84+
**Icon Toolbar**
85+
86+
```json
87+
{
88+
"type": "button-group",
89+
"variant": "outline",
90+
"size": "sm",
91+
"buttons": [
92+
{
93+
"label": "Copy"
94+
},
95+
{
96+
"label": "Cut"
97+
},
98+
{
99+
"label": "Paste"
100+
}
101+
]
102+
}
103+
```
Lines changed: 250 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,250 @@
1+
---
2+
title: "Div (Deprecated)"
3+
description: "Generic container element - use Shadcn components instead"
4+
---
5+
6+
<div className="rounded-lg border border-yellow-500/50 bg-yellow-50 p-4 dark:bg-yellow-950/50">
7+
<p className="font-semibold text-yellow-800 dark:text-yellow-200">⚠️ Deprecated Component</p>
8+
<p className="mt-2 text-sm text-yellow-700 dark:text-yellow-300">
9+
The Div component is deprecated. Please use Shadcn components instead:
10+
</p>
11+
<ul className="mt-2 list-inside list-disc text-sm text-yellow-700 dark:text-yellow-300">
12+
<li>For a plain wrapper: use <code>box</code> — the one drop-in swap (same element, your className verbatim, no layout of its own)</li>
13+
<li>When you want their layout: use <code>card</code>, <code>flex</code>, <code>container</code>, <code>stack</code>, or <code>grid</code> — each injects classes of its own, and <code>card</code> also moves children into an extra element</li>
14+
</ul>
15+
<p className="mt-2 text-sm text-yellow-700 dark:text-yellow-300">
16+
Move any content authored under the retired <code>body</code> key into <code>children</code> first:
17+
objectui#6771 retired that child-list spelling, so validation refuses it by name, and neither
18+
<code>div</code> nor any replacement listed above draws it.
19+
</p>
20+
</div>
21+
22+
The Div component is a generic container element. **It is now deprecated in favor of semantic Shadcn-based components** that provide better accessibility, consistency, and design system integration.
23+
24+
**Scope of this deprecation: both authoring surfaces.** A `kind:'html'` page is written
25+
as constrained JSX text that the engine compiles (parses, never executes) into nodes,
26+
tag name straight through. On that tier `<div>` is **refused**: the page fails to
27+
compile, and the error names `box` as the replacement. `os validate` gives the same
28+
verdict, since the published manifest does not declare `div` for the html tier, but its
29+
refusal is a plain `forbidden-tag` error that does not name `box`. Author `<box>` on an
30+
html page exactly where you would author `box` in JSON. The
31+
dev-build deprecation notice covers JSON-authored nodes, and the compile error covers
32+
html pages.
33+
34+
Styling on that tier is the blocks' own structured props (`<flex direction gap>`,
35+
`<grid columns>`) plus a JSON `style` object — **not** Tailwind utility classes, which
36+
produce no CSS at all when authored in page `source`. `os validate` reports that as
37+
`page-source-className-tailwind`. See the React Pages guide, §Styling.
38+
39+
## Migration Guide
40+
41+
Which replacement is right depends on whether you want layout or only a wrapper.
42+
Measured through the real renderer, on a node carrying an authored `className`:
43+
`box` reproduces `div` exactly, while `card`, `flex`, `container`, `stack` and
44+
`grid` each add classes of their own — and `card` additionally moves the children
45+
inside an extra element. So a mechanical `div` → `card`/`flex`/`grid` swap changes
46+
the page; a `div` → `box` swap does not.
47+
48+
One caveat for a node still authored in the retired `body` spelling: every
49+
option reads `children` and never `body` (objectui#6771 retired it across the
50+
protocol, `card` included), and so does `div` itself. Such a node must move that
51+
content into `children` as part of the swap. Until it does, validation refuses
52+
the key by name, and the content is missing from the page under `div` and under
53+
every replacement alike.
54+
55+
### For a Plain Wrapper → Use `box`
56+
57+
The mechanical swap. `box` renders `children` inside a plain block element with
58+
your `className` passed through verbatim and nothing injected, so retyping a
59+
`div` node to `box` is the one conversion that leaves the rendered result alone.
60+
61+
**Use Box Instead**
62+
63+
```json
64+
{
65+
"type": "box",
66+
"className": "max-w-sm rounded-lg border bg-card text-card-foreground shadow-sm",
67+
"children": [
68+
{
69+
"type": "box",
70+
"className": "p-6 space-y-2",
71+
"children": [
72+
{
73+
"type": "text",
74+
"content": "Card Title",
75+
"className": "text-2xl font-semibold"
76+
},
77+
{
78+
"type": "text",
79+
"content": "The same markup as the div example, retyped to box: className verbatim, no layout injected, no extra element.",
80+
"className": "text-sm text-muted-foreground"
81+
}
82+
]
83+
}
84+
]
85+
}
86+
```
87+
88+
### For Card-like Containers → Use `card`
89+
90+
**Use Card Instead**
91+
92+
```json
93+
{
94+
"type": "card",
95+
"children": [
96+
{
97+
"type": "text",
98+
"content": "Card Title",
99+
"className": "text-2xl font-semibold"
100+
},
101+
{
102+
"type": "text",
103+
"content": "Card content with proper semantic structure.",
104+
"className": "text-sm text-muted-foreground mt-2"
105+
}
106+
]
107+
}
108+
```
109+
110+
### For Flex Layouts → Use `flex`
111+
112+
**Flex Layout**
113+
114+
```json
115+
{
116+
"type": "flex",
117+
"properties": {
118+
"gap": 4,
119+
"children": [
120+
{
121+
"type": "card",
122+
"className": "w-20 h-20 bg-blue-500"
123+
},
124+
{
125+
"type": "card",
126+
"className": "w-20 h-20 bg-green-500"
127+
},
128+
{
129+
"type": "card",
130+
"className": "w-20 h-20 bg-purple-500"
131+
}
132+
]
133+
}
134+
}
135+
```
136+
137+
### For Grid Layouts → Use `grid`
138+
139+
**Grid Layout**
140+
141+
```json
142+
{
143+
"type": "grid",
144+
"columns": 2,
145+
"gap": 4,
146+
"children": [
147+
{
148+
"type": "card",
149+
"className": "h-20 bg-red-500"
150+
},
151+
{
152+
"type": "card",
153+
"className": "h-20 bg-yellow-500"
154+
},
155+
{
156+
"type": "card",
157+
"className": "h-20 bg-pink-500"
158+
},
159+
{
160+
"type": "card",
161+
"className": "h-20 bg-indigo-500"
162+
}
163+
]
164+
}
165+
```
166+
167+
## Old Examples (Deprecated)
168+
169+
Below are the old `div` examples. Please migrate to the alternatives shown above.
170+
171+
## Schema
172+
173+
```plaintext
174+
// ⚠️ DEPRECATED - Use Card, Flex, Grid, or other layout components instead
175+
interface DivSchema {
176+
type: 'div';
177+
178+
// Content
179+
children?: SchemaNode | SchemaNode[]; // Child components (the child key this component reads)
180+
181+
// Styling
182+
className?: string; // Tailwind CSS classes
183+
184+
// Base properties
185+
id?: string;
186+
visible?: boolean | string | { dialect?: string; source: string };
187+
testId?: string;
188+
}
189+
```
190+
191+
## Legacy Examples (For Reference Only)
192+
193+
### Old Card Layout Example
194+
195+
**Custom Card**
196+
197+
```json
198+
{
199+
"type": "div",
200+
"className": "max-w-sm rounded-lg border bg-card text-card-foreground shadow-sm",
201+
"children": [
202+
{
203+
"type": "div",
204+
"className": "p-6 space-y-2",
205+
"children": [
206+
{
207+
"type": "text",
208+
"content": "Card Title",
209+
"className": "text-2xl font-semibold"
210+
},
211+
{
212+
"type": "text",
213+
"content": "Card description goes here. This is a basic card layout using div containers.",
214+
"className": "text-sm text-muted-foreground"
215+
}
216+
]
217+
}
218+
]
219+
}
220+
```
221+
222+
### Nested Containers
223+
224+
**Nested Divs**
225+
226+
```json
227+
{
228+
"type": "div",
229+
"className": "p-6 border-2 border-dashed border-blue-300 rounded-lg",
230+
"children": [
231+
{
232+
"type": "div",
233+
"className": "p-4 border-2 border-dashed border-green-300 rounded",
234+
"children": [
235+
{
236+
"type": "div",
237+
"className": "p-3 border-2 border-dashed border-purple-300 rounded text-center",
238+
"children": [
239+
{
240+
"type": "text",
241+
"content": "Nested Content",
242+
"className": "font-mono text-sm"
243+
}
244+
]
245+
}
246+
]
247+
}
248+
]
249+
}
250+
```
Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"title": "Basic",
3+
"pages": [
4+
"separator",
5+
"button-group",
6+
"pagination",
7+
"navigation-menu",
8+
"sidebar",
9+
"div"
10+
]
11+
}

0 commit comments

Comments
 (0)