Skip to content

docs(extensibility): add plugin UI component catalog candidate - #183

Merged
Xuepoo merged 1 commit into
mainfrom
ctx-0090/docs-ui-component-catalog
Nov 3, 2026
Merged

Xuepoo merged 1 commit into
mainfrom
ctx-0090/docs-ui-component-catalog

Conversation

@Xuepoo

@Xuepoo Xuepoo commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

What this adds

New candidate page extensibility/ui-component-catalog-candidate.md, indexed in
extensibility/README.md: five named composition recipes over the accepted
Plugin API v1 declarative surface, plus the bar plugin mapping.

ID Pattern Surface status
C-1 Edge band Accepted v1
C-2 Pill row Accepted v1 (no radius, border, or padding field)
C-3 Tooltip / detail fallback Partially available
C-4 Modal sheet Not available in plugin API v1
C-5 Status strip Accepted v1

Each entry states its surface status first, then scene shape, style hooks,
interaction, accessibility notes, budget note, and a headed Lua example.

Availability is stated, not assumed

  • Accepted v1. C-1, C-2, and C-5 use only Text/Row/Column/List,
    fg/bg/bold, and on_click/on_scroll with region.
  • Partially available. C-3 is a four-rung ladder: inline text and
    bitty.notify are accepted; the presentation-only overlay (ui.present) is
    current host fact and is explicitly not in the accepted RFC; anchored tooltips
    do not exist.
  • Not available. C-4 has no scene shape. Plugin API v1 carries no modal
    authority, ui.present admits only a non-modal surface, and
    register_panel/PanelProvider stay excluded from v1. The page documents the
    substitutes and their limits instead of sketching a sheet.

No entry adds a node kind, slot, field, capability, budget, or error code, and no
candidate direction is presented as a contract.

Bar mapping

The bar plugin mapping records which pinned bar element matches which recipe
(band root row, capsules, marks, detail notification fallback, per-module
omission). It states explicitly that the bar does not import these recipes as
code, so no dogfood proof of shared implementation is claimed.

Verification

just check cannot complete in the authoring environment: bun/bunx
segfault (signal 11) on every invocation, so the fmt-check recipe dies with
exit 139 before the remaining gates run. Every gate was therefore run through the
pinned equivalents, all green:

  • prettier@3.9.6 --check . --ignore-unknown (0 issues)
  • markdownlint-cli2@0.23.1 (0 issues, 106 files)
  • check-docs.mjs links|metadata|language|agents|hygiene (each 0)
  • xmllint svg gate and actionlint 1.7.12 (0)

Issue

Related #2114, not Closes. Checklist item 1 (catalog the band, pill row,
tooltip/detail fallback, modal sheet, and status strip with contracts) and item 2
(scene shape, style hooks, accessibility notes, and a headed example per entry)
are covered by this page. Item 3, "Bar migrated onto catalog entries (dogfood
proof)", is not: this PR maps the bar's pinned behaviour but does not migrate the
bar plugin, which lives in its own repository.

…date

Catalogue the reusable plugin UI composition patterns requested by bitty#2114 as
documented recipes over the accepted v1 scene nodes: edge band, pill row,
tooltip/detail fallback, modal sheet, and status strip.

Each entry states its surface status first, then a scene shape, style hooks,
interaction and accessibility notes, a budget note, and a headed Lua example.
Availability is explicit: the band, pill row, and status strip use only accepted
v1 fields; the detail fallback is partially available; the modal sheet is marked
not available because plugin API v1 carries no modal authority.

The bar plugin mapping records which pinned bar element matches which recipe and
states that no shared implementation exists yet, so no dogfood claim is made.
@Xuepoo Xuepoo added this to the v0.1.0 milestone Nov 3, 2026
@Xuepoo Xuepoo added docs Documentation P2 Priority: medium area:plugins labels Nov 3, 2026
@Xuepoo
Xuepoo merged commit 1b04a63 into main Nov 3, 2026
4 checks passed
@Xuepoo
Xuepoo deleted the ctx-0090/docs-ui-component-catalog branch November 3, 2026 13:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:plugins docs Documentation P2 Priority: medium

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant