Skip to content

layout-DSL: modernize flex-shaped JSDoc @examples + list-box docs example #112

Description

@blendsdk

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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationeffort: MMedium — one focused plangood first issueGood for newcomerspriority: lowNice to have / defer

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions