Part of the layout-DSL adoption epic #108.
Scope may expand with #113: if the hardening lands a blessed absolute at() builder (S2), the absolute-canvas docs examples currently left raw could also be modernized to at(). Until then this issue covers only the flex-shaped examples below.
A documentation-only pass: modernize the JSDoc @example blocks and docs-site example snippets that hand-write new Group() + .layout = {…} so they instead showcase the layout DSL — where the example is a flex shape. This is teaching material, so the payoff is didactic (agents and humans read these to learn the recommended idiom). Not a runtime code change.
Do — flex-shaped examples that read best with the DSL
packages/ui/src/view/group.ts — the @example at lines 47/51/53 already demonstrates flex ({ direction:'row' } + { size:{fr} }); re-show it with row() / grow().
packages/ui/src/editor/indicator.ts — the @example at lines 38/39/40 demonstrates a column ({ direction:'col' } + { size:{fr} } / { size:{fixed} }); re-show with col() / grow() / fixed().
packages/docs-site/examples/containers/list-box.ts — the single cleanest col-shaped docs example (list + echo line → col(grow(list), spacer(1), fixed(text, 1))). Optional: it teaches ListBox, not layout, so keep the DSL rewrite minimal.
Don't — absolute-position examples that should stay raw
The remaining ~50 @example blocks across the control/dialog/surface/scroll widgets place a single view (or a 2-D form grid) at fixed position:'absolute' rects. The DSL has no absolute form, so rewriting them would only add layout noise to widget-focused snippets. Leave them. Likewise the docs-site 2-D form examples (input.ts, preset-gallery.ts, form-dialog.ts, button.ts, data-grid.ts, file-dialog.ts) — at() is the right tool there.
Note
Public @examples must stay copy-pasteable and correct (they're an API contract per the repo docs standard), and check:docs/check-jsdoc.mjs must stay green.
Acceptance
- Only the flex-shaped examples above are changed; each still compiles/paints.
yarn verify green (incl. check:docs); yarn lint:fix run before the PR.
Part of the layout-DSL adoption epic #108.
A documentation-only pass: modernize the JSDoc
@exampleblocks and docs-site example snippets that hand-writenew Group()+.layout = {…}so they instead showcase the layout DSL — where the example is a flex shape. This is teaching material, so the payoff is didactic (agents and humans read these to learn the recommended idiom). Not a runtime code change.Do — flex-shaped examples that read best with the DSL
packages/ui/src/view/group.ts— the@exampleat lines 47/51/53 already demonstrates flex ({ direction:'row' }+{ size:{fr} }); re-show it withrow()/grow().packages/ui/src/editor/indicator.ts— the@exampleat lines 38/39/40 demonstrates a column ({ direction:'col' }+{ size:{fr} }/{ size:{fixed} }); re-show withcol()/grow()/fixed().packages/docs-site/examples/containers/list-box.ts— the single cleanest col-shaped docs example (list + echo line →col(grow(list), spacer(1), fixed(text, 1))). Optional: it teaches ListBox, not layout, so keep the DSL rewrite minimal.Don't — absolute-position examples that should stay raw
The remaining ~50
@exampleblocks across the control/dialog/surface/scroll widgets place a single view (or a 2-D form grid) at fixedposition:'absolute'rects. The DSL has no absolute form, so rewriting them would only add layout noise to widget-focused snippets. Leave them. Likewise the docs-site 2-D form examples (input.ts,preset-gallery.ts,form-dialog.ts,button.ts,data-grid.ts,file-dialog.ts) —at()is the right tool there.Note
Public
@examples must stay copy-pasteable and correct (they're an API contract per the repo docs standard), andcheck:docs/check-jsdoc.mjsmust stay green.Acceptance
yarn verifygreen (incl.check:docs);yarn lint:fixrun before the PR.