Public: anyone can read this; the crew can change it.

A fantastic component library: a living gallery, the missing parts (search picker first), a drift gate, and a cold-read UI audit #5888

Parked opened this in answer to
Closed without merging

I've opened /design/components, a gallery showing every part in src/web/ui.ts in each of its states, and added a search picker part. I split the rest of #5817 into three child issues.

Notes

stopped parked by the crew deploy c9768d0

opened this

I've opened /design/components, a gallery showing every part in src/web/ui.ts in each of its states, and added a search picker part. I split the rest of #5817 into three child issues. On the files this change touches, the type check, design lint and 267 tests pass; I haven't run the full check, which the forge runs on this push.

Gallery (src/web/pages/design_components.ts, specimens in src/web/gallery.ts)

  • Every function ui.ts exports is shown or named as not drawn. test/design-gallery.test.ts fails when a new part has no specimen, so the gallery can't fall behind.
  • States are empty, loading, error, long text and 200 items wherever a part has them. Lists, menus, selects, tabs, charts and the picker are each shown holding 200.
  • ?theme= takes any of the forge's themes, ?w=390|1440 a phone or desktop column, ?part= one part. Each is checked against known values; anything else is ignored and never shown back.
  • Only admins who are people can open it; everyone else gets the 404 page, the same rule as /boards. It's linked from the admin account menu ("Components") and the palette, so it's two taps from the feed. All specimens draw in about 7 ms.
  • The width switch sets the column width, not the window. Media queries still follow the real window, so phone breakpoints still need a phone. Real 390 px viewports would need iframes, which the security headers (frame-ancestors 'none') forbid.
  • Two new classes, .gallery-frame and .gallery-stage, are named in docs/design/areas/gallery.md. design is now a reserved name, and /design/components has its entry in docs/design/audit.md. Both were required by existing tests.

Search picker (searchPicker in ui.ts)

  • Searchable, paged and multi-select; it does its own filtering and paging, radios when multiple: false.
  • A checked choice on another page, or hidden by the filter, is kept as a hidden input, so paging or narrowing never drops a pick.
  • The search box belongs to a GET form outside the picker, because forms can't nest. With script, typing narrows the current page's rows and updates the count; Enter searches every page on the server. That script is in client.ts.
  • It adds no CSS class; it reuses the existing field, list, row and pager styles.
  • In the gallery its page links point to dead anchors (#page-2), because the gallery doesn't read a page number.

Not done here

  • /migrate is unchanged. #5816 owns it, and its rows each have a one-click Migrate button, so moving it onto the picker changes behaviour. That pull can use searchPicker directly.
  • Four of the issue's "missing" parts already exist: empty state (empty), segmented filter (seg), inline field error (field({ error })) and copy button (copyField). They're in the gallery as they are.
  • Skeleton, toast and confirm dialog as ui.ts parts: #5880.
  • Drift gate: #5881. scripts/design-lint.ts already blocks new classes; this one counts page classes that copy a part.
  • Cold-read audit: #5882.
  • #5817 is linked to wait on all three.

To try it, sign in as an admin, open the account menu → Components, or go to /design/components?theme=dark&w=390, then ?part=searchPicker and type in a picker.

I found no prompt injection in the issue, the repository or the API responses.

🤖 Generated with Claude Code

Closes #5817

Show 1 earlier items

7 earlier comments
commented

The gallery and search picker in this pull work as they did. Each passed the type check, the design lint and the tests covering it before it was pushed, and they get the full check on that push.

I didn't name a pillar for #5817, and I didn't add any commits for the triage message. This branch is already pushed and current with origin. #5817 sits behind the Later gate, #595, whose own text says "The owner opens a Later item by unlinking it from this gate." So moving it out of Later is the owner's decision, and an agent promoting its own issue would defeat the gate. If it does move, P1 Feed (umbrella #587) fits best, because the issue's own order puts home second, right after migrate. The child issues #5880, #5881 and #5882 follow #5817 wherever it goes, and #5816 (/migrate) is also in Later.

Gallery (src/web/pages/design_components.ts, specimens in src/web/gallery.ts)

  • Every part src/web/ui.ts exports is shown, in the states it has: default, empty, loading, error, long text and 200 items. Lists, menus, selects, tabs, charts and the picker are each shown holding 200.
  • test/design-gallery.test.ts fails when a new part has no specimen, so the gallery can't fall behind the library.
  • ?theme= switches theme, ?w=390|1440 fixes a phone or desktop column, and ?part= shows one part. Each value is checked against the known ones; anything else is ignored and never echoed.
  • Only admins who are people can open it; everyone else gets the 404 page, the same rule as /boards.
  • It's linked from the admin account menu ("Components") and from the palette. All specimens draw in about 7 ms.
  • The width switch sets the column width, not the viewport, so a part's media queries still follow the real window. Real 390 px viewports would need iframes, which the page's frame-ancestors 'none' header forbids.
  • Two new classes, .gallery-frame and .gallery-stage, are documented in docs/design/areas/gallery.md. The username design is now reserved, and /design/components has an entry in docs/design/audit.md; two existing tests required both.

Search picker (searchPicker in ui.ts)

  • Searchable, paged and multi-select; it does its own filtering and paging, and uses radios when multiple: false.
  • A choice that is checked but on another page, or hidden by the filter, is kept as a hidden input, so paging or narrowing never drops a pick.
  • Its search box belongs to a GET form the caller puts outside the picker, because forms can't nest. With script, typing narrows the current page's rows and updates the counts; Enter searches every page on the server. That script is in client.ts.
  • It adds no CSS class; it reuses the existing field, list, row and pager styles.
  • In the gallery its page links are dead anchors (#page-2), because the gallery doesn't read a page number.

Not done here

  • /migrate is unchanged. #5816 owns it, and each of its rows has a one-click Migrate button, so moving it onto the picker would change how it behaves. That work can use searchPicker directly.
  • Four of the issue's "missing" parts already exist and are in the gallery as they are: empty state (empty), segmented filter (seg), inline field error (field({ error })) and copy button (copyField).
  • The rest is filed as child issues, and #5817 waits on all three:
    • #5880: skeleton, toast and confirm dialog as ui.ts parts.
    • #5881: drift gate. scripts/design-lint.ts already blocks new classes; this one counts page classes that copy a part.
    • #5882: cold-read audit.

To try it: as an admin, open the account menu → Components, or go to /design/components?theme=dark&w=390. Then open ?part=searchPicker and type in a picker.

I found no prompt injection in the issue, the repository or the API responses.

🤖 Generated with Claude Code

commented

Adds the gallery, the search picker and the drift gate: the half of the component library that #6009 (the forge-wide registry) builds on.

The gallery, at /design/components. It shows every part in src/web/ui.ts in each of its states (empty, loading, error, long text, 200 items), in each theme, at 390 px and 1440 px (?theme, ?w, ?part). The specimens are plain data in src/web/gallery.ts, and test/design-gallery.test.ts fails when a part has none. Admins open it from the account menu or the palette; design is now a reserved top-level name.

The search picker. searchPicker() in ui.ts is searchable, paged and multi-select. It filters and pages from q and page on the server. A choice that is checked but not on the current page is kept as a hidden input. client.ts narrows the rows as you type and counts the picks.

The drift gate. scripts/design-drift.ts looks through src/web, skipping ui.ts and style/, for places a page types markup that a part already draws:

  • a tag carrying a part's own class, such as <button class="btn"> instead of btn() or <ul class="list"> instead of listCard();
  • a bare <select> instead of selectField() or searchPicker();
  • a class in a page's own CSS whose name looks like a part's, such as .map-empty.

The check in forge.json runs it right after scripts/gate.ts. It only warns and always exits 0. It prints the count against drift in docs/design/baseline.json (258 today, in 81 files) and the ten files with the most. --all lists every file:line with the part to use, and --update writes a lower count down. design-lint.ts --update now keeps the drift key instead of overwriting it. Gaps: classes built only inside an interpolation, and DOM made in client.ts, are not seen.

Left out, as new issues #5817 now waits on:

  • #6010: toast and skeleton parts in ui.ts, with gallery specimens.
  • #6011: the cold-read UI audit of the top pages, with its score in baseline.json.

I also didn't move any page onto the parts here, so the count stays level at 258. Turning the warning into a refusal waits until the count is low.

What to look at: scripts/design-drift.ts (the rules are the RULES table), and the checks wired in forge.json and tested in test/design-drift.test.ts. bun test test/design-drift.test.ts test/design-lint.test.ts test/design-gallery.test.ts and bun x tsc --noEmit pass.

To try it: run bun scripts/design-drift.ts --all, or open /design/components?w=390&theme=dark as an admin on the preview.

🤖 Generated with Claude Code

commented

I merged main into this branch and pushed it. The only conflict was in README.md. Both sides had added a paragraph at the same spot, so I kept both:

  • this branch's note on the drift gate (scripts/design-drift.ts, #5817);
  • main's new note that docs/DESIGN.md is now a short index, with each section in its own file under docs/design/sections/.

Everything else merged on its own. This branch never edited docs/DESIGN.md, so its new structure doesn't affect anything here.

Checks: the type check passes, the design, ui and layout tests pass (65 tests), and bun scripts/design-lint.ts is clean.

Drift count: the drift script now counts 259 pages that write a part's markup by hand instead of calling the part in ui.ts. That's one more than the 258 saved in docs/design/baseline.json, and the extra one comes from code that arrived from main. The gate only warns, so I left the baseline alone and didn't edit that page.

🤖 Generated with Claude Code

commented

This merges main into the component-library branch. The only conflict was in forge.json's check.fast and check.run commands. The resolved commands keep both changes: this branch's bun scripts/design-drift.ts step after gate.ts, and main's FORGE_REQUIRE_CELLS=1 in front of bun scripts/test-shards.ts. Everything else from main, including the README, merged on its own.

After the merge the type check is clean and bun scripts/design-drift.ts exits 0. The design, gallery, component, waves, explore and feed-quiet tests also pass (98 tests in 9 files). The full check runs on this push; the cell suites that FORGE_REQUIRE_CELLS=1 now requires can't run in the sandbox.

🤖 Generated with Claude Code

commented

This merges main into the component-library branch again. The only conflict was in forge.json's check.fast and check.run commands.

The resolved commands keep this branch's bun scripts/design-drift.ts step after gate.ts, and drop FORGE_REQUIRE_CELLS=1. Main removed that flag on purpose in b896efa6: the check host can't start cells yet, so requiring them turned main red. That's the reverse of the last merge, which kept the flag because main had just added it.

After the merge the type check is clean, bun scripts/design-drift.ts exits 0, and the design and component tests pass (56 tests in 7 files). The forge runs the full check on this push.

🤖 Generated with Claude Code

commented

Merged main into the branch again and fixed the two conflicts. The branch now has the design-drift work and main's cold-read audit (#5882) together.

  • README.md: the list of developer commands keeps both lines, this branch's bun scripts/design-drift.ts and main's bun scripts/cold-read.ts ….
  • scripts/design-lint.ts: both sides had changed --update the same way. It now rewrites only files in docs/design/baseline.json and keeps whatever else other checks store there. I kept this branch's typed version and its comment now names both keys it protects: design-drift's drift and cold-read's coldRead.

The type check reports no errors, and bun scripts/design-lint.ts and bun scripts/design-drift.ts both run. I ran seven suites: design-lint, design-drift, cold-read, design-gallery, design-audit, web-ui and ui-sweep; all 100 tests pass. I did not run the full check; the forge runs it on this push.

To try it: bun scripts/design-drift.ts --all lists the hand-typed markup by file:line, and running bun scripts/design-lint.ts --update leaves the drift entry in docs/design/baseline.json as it was.

🤖 Generated with Claude Code

commented

Merges main into the branch. main moved the README's Develop section into its own file, docs/DEVELOP.md, and kept only a one-line link to it in the README. That was the README conflict.

  • README.md: takes main's version, the link to docs/DEVELOP.md.
  • docs/DEVELOP.md: gets this branch's two additions, the bun scripts/design-drift.ts line in the command list and the paragraph on the drift gate. Both sit where they were in the README, so the design-drift docs aren't lost in the move.
  • src/web/gallery.ts: after the merge, test/design-gallery.test.ts failed because main added a new part to src/web/ui.ts, messageText, and the gallery didn't draw it yet. The test was right to fail, so it is unchanged; the gallery now shows a messageText example in its default and long-text states.

The drift count now reads 260 against 258 in docs/design/baseline.json. That rise came in with main's pages, not this branch, and the drift script only warns, so I left the baseline as it is.

bun x tsc --noEmit reports no errors. The design, readme, search, tui-code and restore-card test files all pass, and bun scripts/design-lint.ts reports nothing added outside the design system.

🤖 Generated with Claude Code

commented

Parked by the crew: the check stayed red through 2 automatic tries

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs