Skip to content

feat(web): build the catalogue cards from one field list, with search and filter pills or dropdowns - #201

Merged
harenome merged 18 commits into
ThinkFlowLab:mainfrom
harenome:refactor/card-toolkit
Nov 18, 2026
Merged

harenome merged 18 commits into
ThinkFlowLab:mainfrom
harenome:refactor/card-toolkit

Conversation

@harenome

@harenome harenome commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

Closes #200

What

The four catalogue pages (Benchmarks, Agents, Capabilities, Kits) now build their cards with a card toolkit, _cards.html, from the same field list as the table toolkit. A field's card key names the slot it fills. A field without card is not on the card, and table false keeps a card-only field off a table. Each page builds its items in Python (web/catalogue.py, web/agents.py) as dicts of display values, so the template only says where each value goes.

The slots, in order:

Slot Holds How many
status, tag, meta, check the top row: pills, a version, a checkbox tags any, the others one
icon, title the icon and the name, a link stretched over the card one title, required
text the description one
badge, note runner pills, notes with an optional icon any
stat label first, then value (<dt>, <dd>), below a line up to three
alert, action a blocker line, buttons or links one alert, any actions

A page that breaks a limit fails to render. A click anywhere on a card opens it, except on a control of its own. The pills and notes with a tooltip sit above the card's link to keep their tooltips, so a script follows the link for them. A middle click or a Ctrl, Cmd or Shift click opens a new tab or window, and a click that ends a text selection opens nothing. A stat label wraps between words only: a stat column is at least as wide as its longest word.

Icon rule. When one item of the page has an icon, the items without one show their initials. When no item has an icon, no card shows one.

Controls. The cards use the table toolkit's controls row: the search box at the left, the buttons at the right, no Sort by. Agents and Capabilities now have a search. Search and filters hide the cards that do not match. A Benchmarks shelf with no visible card hides, and its count follows the visible cards. After a search or a filter, one live region tells a screen reader how many cards show, 300 ms after the last change, in the page's word: "9 of 12 benchmarks". It says nothing on load. Cards and tables share this code (NulliusTable.cards, narrow, voice).

Filter forms. A column's filter puts its choices in one or more forms:

  • button (default): the global Filter menu.
  • dropdown: a menu of its own in the controls row. Its button ends in a chevron that turns while the menu is open. Under reduced motion, it changes without animation.
  • pills: a row of toggles under the controls row.

Every form shows the same state. A pill toggles its value. All clears its column, and Clear filters clears every column. An only preset shows in each form. A column narrows when it does not show every value. The Filter button or a dropdown that holds such a column is marked as narrowed and shows a count: the Filter button its narrowed columns, a dropdown its chosen values. After None, a dropdown shows a 0 beside that mark. A card filter compares a value's value when it has one, else its text, so a label can differ from its value. A field's filter_icon leads its dropdown button and its pill row. Tables get the same forms.

Pages.

  • Benchmarks: category pills, an Origin dropdown and a Runs with dropdown, each with a new sprite icon (i-origin, i-runner). No Filter button. The Find box and the chips are gone.
  • Kits: family pills, and the search.
  • Agents and Capabilities: the search.

Visible changes outside the lists.

  • Capabilities lose their letter mark, by the icon rule: no capability has a logo.
  • Agents without a logo show two-letter initials instead of one letter.
  • The Benchmarks filters take several choices: categories, origins and runners are toggles, not one choice each.
  • The outlined tags (std-tag, run-tag) have the same 5 px corners as the filled ones, everywhere they appear: the lists, the detail pages and the Add dialog.

The Getting started step for Benchmarks now points at the controls row (app/nullius/onboarding.py). The agent mark URL has one source, agent_mark_url (web/filters.py), for the agent_mark macro and the Agents cards. The UI sweep's clipped-text check reads the card stats and text. catalogue.js drops its chip filter. It keeps the hash links that open an entry's page and the dataset tabs. AGENTS.md names _cards.html.

Out of scope: a toggle between a table and cards.

Touches

backend (onboarding, one string) · routes (web/catalogue, web/agents, web/filters) · templates and static (_cards.html, _tables.html, tables.js, catalogue/benchmarks.html, agents/standard.html, agents/kits.html, base.html, style.css, catalogue/catalogue.css, catalogue/catalogue.js) · skills (ui-sweep/scripts/sweep.py) · docs (AGENTS.md)

Before and after

Seeded data as in #199, with the bundled catalogue. Before is main, after is this branch, same width.

Before After
Benchmarks, 1280 px, light 01-before-benchmarks-1280-light 01-after-benchmarks-1280-light
Benchmarks, the Origin dropdown open 02-before-benchmarks-dropdown-open-1280-light 02-after-benchmarks-dropdown-open-1280-light
Benchmarks, filtered to Coding 03-before-benchmarks-filtered-1280-light 03-after-benchmarks-filtered-1280-light
Benchmarks, 390 px, dark 04-before-benchmarks-390-dark 04-after-benchmarks-390-dark
A card's stats, label first 05-before-card-stats-1280-light 05-after-card-stats-1280-light
Agents: logos, and initials for the agent without one 06-before-agents-1280-light 06-after-agents-1280-light
Agents, "code" typed in the search 07-before-agents-search-1280-light 07-after-agents-search-1280-light
Capabilities, "mem" typed in the search, 390 px, dark 08-before-capabilities-search-390-dark 08-after-capabilities-search-390-dark
Kits, the Capabilities family pill 09-before-kits-family-1280-light 09-after-kits-family-1280-light
Kits, 1280 px, dark 10-before-kits-1280-dark 10-after-kits-1280-dark

Verified

In throwaway rootless containers (python:3.12 with Node.js, which the script tests need, and a clone of the branch):

  • python3 app/tests/parallel.py: 2240 tests in 126 modules, OK.
  • pip install -r app/requirements.txt, then python3 app/tests/parallel.py app/ui_tests: 595 tests in 48 modules, OK.
  • New: app/ui_tests/test_cards.py. It renders the macros and checks the slot order, the slot limits, empty slots, the icon rule and escaped values. It also checks controls without Sort by, two collections with every filter form on one page, and a filter value that differs from its label. Under Node.js, it runs tables.js on cards and checks:
    • Search and filters hide cards and their empty groups.
    • The announcement waits for changes to stop, says nothing on load and names its cards.
    • A click on a card opens it, and a modified or middle click opens a new tab. A click on a control, or at the end of a selection, does not.
  • test_tables.py checks the filter forms: each column in its forms, the forms in step, and a preset in every form. It also checks the filter icon, no Filter button without button columns, and the narrowed mark and counts after None and All.
  • The catalogue route tests read the new markup.

Browser check, Chromium (Playwright 1.49), on the seeded data: the views in the table above, before and after. No page JavaScript error and no console error on Launches, Workspaces, All runs, Benchmarks, Agents, Capabilities and Kits. Also, on this branch:

  • A click on a run-with pill or a needs note opens the benchmark, and the pills keep their tooltips. A click on the example tag opens the agent. A Ctrl click opens a new tab.
  • After None, the Origin dropdown is marked narrowed and shows 0.
  • The live regions are empty after load. A search on Benchmarks reads "3 of 9 benchmarks".
  • At 1280 and 390 px, no stat label or value is cut, and no stats row passes its card.

Not checked: other browsers, and a screen reader. A click that ends a text selection is checked in the script test only: the card's link covers its text, so a drag in the browser selects nothing.

Risk

The change rewrites the markup of the four catalogue pages. A script or test that reads the old ids and classes (#bench-find, .bench-cat, [data-filter] on the chip rows) no longer finds them. The Getting started target moves with them. The card filters now compare values, not labels: on Benchmarks, the origin and runner values are official, community, standard and harbor. To undo, revert this pull request's commit. Nothing is migrated, and no stored data changes.

The table toolkit's field dicts gain a `card` role naming the slot a
field fills (status, tag, meta, check, icon, title, text, badge, note,
stat, alert, action), and `table` false for a field on cards only; a
page's items are dicts of display values, so the field list only says
where each goes. `_cards.html` renders them: an <article> whose title
link is stretched over the card, labels before values in up to three
stats, initials beside real icons only, and the slot limits checked.
NulliusTable.cards runs the controls row's search and Filter over the
cards, sharing them with the tables through `narrow`; a controls row
can leave out Sort by, and shows no buttons group when it has none.
Benchmarks, Agents, Capabilities and Kits build their cards' values in
Python and give the card toolkit one field list each. Their search and
filters are the toolkit's controls row: the category, runs-with and
origin chips and the kits' family chips become its Filter menu, and
Agents and Capabilities gain a search. Stats show their label first.
Benchmarks without a mark of their own and agents without a logo show
initials; capabilities, which have no logos, show no icon. The shelves
stay, each hidden when its cards are, with its count following them.
A card collection gets the toolkit's one debounced live region, as a table's
pager has; both now share NulliusTable.voice.
"Benchmarks it runs" ran into the next stat on the Agents cards at 1280 px:
a label now breaks, hyphenated where the browser can, rather than overflow.
A column's `filter` puts its choices in the Filter menu (the default), a
dropdown of its own in the controls row, a row of pills under it, or several
of these. Every form shows one state per column: a pill toggles its value,
All clears the column, Clear filters clears them all, and an `only` preset
shows in each. The Filter button counts only its own columns, a dropdown the
values chosen.
…pills

Benchmarks: a row of pills for the category, a dropdown each for the origin
and what runs it, and no Filter button. Kits: a row of pills for the family.
…ry an icon

A per-category dropdown button ends in the sprite's chevron, turned up while its menu is open (a swap under reduced motion). A field's filter_icon leads its dropdown button and its pill row. Benchmarks' Origin and Runs with get two new sprite symbols, i-origin (a verified badge) and i-runner (stacked layers).
The agent_mark macro and the Agents cards each split a mark into its file and sprite symbol; agent_mark_url does it for both.
Cards do not sort, so type='num' on the Tasks, Datasets and Checks stats did nothing.
A stat column is as wide as its longest word at least, so "Benchmarks it runs" wraps at its spaces instead of breaking inside "Benchmarks".
The cards no longer have the strong and p elements the sweep looked for; it now checks each stat's label and value and the card's text, except a summary clamped on purpose.
A card's data-f-<field> took each value's text, so a filter whose value differs from its label matched nothing. It takes the value's `value` when it has one; the Benchmarks origin and Runs with filters use their keys as values, shown by their labels.
…rowed

One rule for the Filter button and a dropdown: a column narrows when it does not show every value, and a button holding one is marked narrowed and shows its count. After None a dropdown counts 0 values chosen beside that mark, while the Filter button counts 1 column.
…eir own word

The cards' live region spoke their count about 300 ms after every page load. As a table's pages now do, it speaks only after a search or a filter, and names what it counts: "9 of 12 benchmarks". The live region skips its first text, the page's own drawing, for both.
The run-with pills, the needs note and the example tag sit above the card's stretched link to keep their tooltips, so a click on them did nothing. A click inside a card, but on a control of its own, now follows the card's link; a middle click or a Ctrl, Cmd or Shift click opens it in a new tab or window, and a click that ends a text selection does not open it.
@harenome
harenome merged commit 11cff16 into ThinkFlowLab:main Nov 18, 2026
2 checks passed
@harenome
harenome deleted the refactor/card-toolkit branch November 18, 2026 09:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

One card toolkit for the catalogue pages, with search and filters as pills or dropdowns

1 participant