"""HaTchi-MaXchi Hyperpart registry — the copy-paste catalogue. A **Hyperpart** is the htmx-native unit of reuse: a *partial* (server- rendered markup + classes) plus its *exchange contract(s)* (the endpoint request/response the server must satisfy), plus an optional *controller* (vanilla JS, only where the platform lacks a primitive). It is NOT a React component — there is no client state graph; state lives on the server and htmx swaps the markup. Naming it distinctly is deliberate: it stops an agent coder importing React priors (client state, composition trees) into a server-owned partial. Single source for the static gallery AND the agent-facing reference. Each entry: a title, blurb, the canonical partial (rendered live AND shown as the copy-paste snippet — the same string, so docs can't drift from the demo), its exchange contracts, and optional wiring notes. Icon/SVG placeholders (``{icon:name}``) are expanded by the builder from the vendored Lucide registry so snippets stay readable. """ from __future__ import annotations from dataclasses import dataclass, field, replace @dataclass(frozen=True) class Exchange: """One hypermedia exchange contract. A partial carries *affordances* — the `hx-*` controls that initiate a request. An Exchange declares, for one affordance, the request the server must handle and the response fragment it must return. This is the "endpoint response contract" half of a Hyperpart: the thing shadcn never had to standardise (React resolves state on the client), and the thing that makes a component agent-buildable — the server side is a checkable contract, not prose. Vocabulary grounded in *Hypermedia Systems* (Gross/Stepanek/Akşimşek): the request/response round-trip is a "hypermedia exchange". The `method`/`endpoint` fields are machine-checked against the `hx-*` attributes in the partial's markup (a Hyperpart that makes a request it doesn't declare — or declares one it doesn't make — fails CI). The prose fields document the contract for the agent/developer consuming it. """ method: str # GET / POST / PUT / PATCH / DELETE — matches the hx- attr endpoint: str # the URL the affordance targets — matches hx-="…" trigger: str # what fires it (the hx-trigger semantics), human-readable response: str # the fragment contract the server MUST return swap: str # where/how the response lands (target selector + swap mode) # The states the endpoint must handle (loading/empty/populated/error). A # coding agent needs these enumerated, not implied — an endpoint-backed # component is under-specified without its empty/error behaviour. states: tuple[str, ...] = () # ADR-0054 / decision 0012 — **exchange envelope** (agent-visible): # what the response may re-emit relative to the persistent slot. # ``body_only`` | ``outer`` | ``none`` | ``host_owned`` | ``document``. # Empty → inferred from ``swap`` prose; remaining ``unspecified`` fails CI. envelope: str = "" # Optional FastAPI-shaped handler source for HTMX4 app authors / agents. # This is the *exchange* endpoint (what runs after the client affordance), # not a dual-lock module. Omit when the part is pure client chrome. # Do not use ``from __future__ import annotations`` in these snippets # (ADR-0014 — FastAPI needs runtime types in route files). server_example: str = "" @dataclass(frozen=True) class Guidance: """Structured, agent-optimised implementation guidance — replaces guidance-like prose in `notes` (narrative remarks stay in notes). Rendered on the part page for humans and serialised verbatim into agents/.md for agents. Controller-bearing parts must carry at least seams + pitfalls (tests/test_hyperpart_cohesion.py, with a shrink-only PENDING_GUIDANCE allowlist during migration).""" seams: tuple[str, ...] = () # extension/composition points, by name pitfalls: tuple[str, ...] = () # mistakes the design already rejected do_dont: tuple[tuple[str, str], ...] = () # (do, don't) pairs a11y_keys: tuple[str, ...] = () # keyboard/AT behaviours to preserve composes_with: tuple[str, ...] = () # Hyperpart ids (cross-checked) @dataclass(frozen=True) class NonComposition: """Explicit refusal: this part *resembles* ``other`` but does not use it. Local primitives that look like another Hyperpart (e.g. grid-edit's bare ``' '

' '' '

' # `status` is a FILTER-ONLY field: the table renders no Status column, yet # the filter narrows on it — filters (like scopes) target any queryable # server field, not just displayed columns. Only `plan` is shown-and-filtered. "" '

' '' '

" # Page size is a WINDOWING control (like a page click): it re-pages the # same matched set, so it lives outside the filter semantics — changing # it keeps an all-matching selection and resets to page 1. '

' '' '

' # Column-visibility menu (dz-grid-cols.js extension): a native

# disclosure — no open/close JS. Checked = visible; the hidden set is # projected onto every [data-dz-col] cell and persists per grid id. '" "" '

' '' "0 selected" # All-matching escalation (Gmail idiom): promote the *page* selection # to the whole *result set* for the current query (search + filters + # sort scope) — including rows on other pages. "Results" = rows that # match that query (footer data-dz-grid-total), not "visually similar". # CSS hides the button once the mode is active. '" # Two-request bulk pattern: the POST applies the action (JSON/204 # response, nothing swapped); data-dz-grid-bulk-refresh tells the # controller to re-fetch rows + footer for the current query after the # request settles — the same GET path every other state change uses. '' '' "

" '

' # Loading overlay (#972): pure-CSS, keyed off htmx's native `.htmx-request` # on any descendant — no controller flag for idiomorph to strip on morph. '' '

' '' # Per-column resize targets (dz-grid-resize.js): widths applied # to the col size header + cells together, and cols survive tbody swaps. "" '' '' '' "" "" '' # Each data header carries data-dz-col (column-visibility hides header # + cells + col in lock-step) and an in-th resize handle (decorative; # pointer drag resizes col[data-col] — a drag never fires the sort). '" '" '" '" "" # The tbody hydrates over the wire: hx-get on `load` fetches the rows, # innerMorph swaps them in (idiomorph keys on each row's stable `id`, so a # selection follows its ROW across a re-sort). Until then it holds a # skeleton placeholder (no data rows to select → no empty-state flash). '' '' '' '' '' '' '' '' '' '' '' '' '' '' '' '' '' '' '' "

' '	' '' '	' '' '	' '' '	' '' '

" # Empty-state sibling (CSS `:has(tbody tr td)`-driven, zero JS): shown only # when the hydrated tbody has no data cells. '

' '{svg:inbox}' '

No customers found

' '

Adjust the filters to widen your search.

' "

" "

" # close .dz-table-scroll-x + .dz-table-scroll # SR announcer: the footer is repainted wholesale, so screen readers # can't track it — dz-grid.js mirrors the result-window summary here # after every data change ("Showing 1-4 of 6"). Visually hidden. '' # Pagination footer — server-rendered (summary + prev/next/page buttons). # Empty until the `load` exchange fills it alongside the first page of rows. '' "", # close .dz-table (root) + .hm-stack notes="The tbody hydrates over the wire — hx-get on " "load fetches the rows, and innerMorph swaps them in. " "Each row carries a stable id (the idiomorph morph key) so a " "selection follows its row — not its DOM position — across a re-sort or " "paginate; data-dz-grid-row-id stays the bulk-action payload anchor, " "and the id encodes it so the two agree. Loading is pure-CSS " "(.htmx-request → the overlay, #972 — no controller flag idiomorph " "could strip). Selection is delegated + state-in-DOM: dz-grid.js counts " "the checked [data-dz-grid-select] boxes, writes the total to " "data-dz-bulk-count, and the CSS reveals the " ".dz-bulk-actions bar; the count / select-all tri-state re-sync on " "change and on htmx:afterSwap. Sorting is delegated + state-in-DOM " "too: a header button ([data-dz-grid-sort]) cycles its column " "none → ascending → descending → none (state on the th's aria-sort, " "one active column), rebuilds the tbody's request query, and fires " "dz-grid:refresh so the server returns the re-ordered rows " "— no client-side row rendering. Filters and search ride the same seam: a " "[data-dz-grid-filter] select (on change) and the " "[data-dz-grid-search] box (on input, debounced) each rebuild the " "query and compose with the active sort — all read from the DOM into one " "query; an empty result reveals the empty-state. Note the Status " "filter is a teaching case: the table renders no Status column, yet the filter " "narrows on it — filters (like scopes) can target any queryable server " "field, not only what's displayed (here only Plan is both shown " "and filtered). Bulk actions post the selection safely: the " "[data-dz-grid-bulk-action] Delete button (behind its confirm dialog) " "sends the action + selected ids + the current query — so the server " "re-scopes and re-validates rather than trusting client ids (§15). " "Select all N results escalates a page selection to the whole " "result set for the current query — search + filters + sort scope, including " "rows on other pages (not “visually similar” rows). State on the root: " "data-dz-grid-all-matching + a " "data-dz-grid-excluded JSON list of unchecked exceptions) — rows on " "other pages arrive selected, the count shows the server-stamped matched total " "(the footer's data-dz-grid-total), and a bulk action sends " "all_matching_selected=true + excluded_ids so the " "server applies it to the matched set minus exclusions. A filter or search " "change drops the mode (the matched set changed); sort and paging keep it. The footer is " "server-rendered: the client intercepts a page click, adds page= " "to the query, and the server returns that page's rows plus the repainted footer " "(row slice + total from one query, so they can't disagree); sort / filter / search " "reset to page 1. The Per page select is a windowing control on the " "same seam ([data-dz-grid-page-size] → page_size=): it " "re-pages the same matched set, resets to page 1, and — unlike a filter/search " "change — keeps an all-matching selection. State is URL-synced " "(data-dz-grid-url, opt-in): the grid's query mirrors into the " "address bar as the same human-readable params the server sees — deep links " "restore on load (before the hydration fetch, so no double fetch), discrete " "actions push history entries (Back walks grid states), the debounced search " "replaces, and foreign URL params survive (the grid only touches its own keys). " "The all-matching selection is ephemeral and deliberately NOT in the URL. " "The three extensions are opt-in per grid, keyed off their own " "seams. Column visibility (dz-grid-cols.js): the Columns " "<details> menu's checkboxes " "([data-dz-grid-col-toggle]) project a hidden set onto every " "[data-dz-col] cell — header, hydrated tds, and the colgroup's " "<col> — persisted per grid id in localStorage; re-fetched " "rows re-hide on swap; stale keys prune at init. Column resize " "(dz-grid-resize.js): a pointer drag on the in-th handle " "([data-dz-grid-resize]) widens col[data-dz-col] live " "(snap-8, clamp 80–800px), persists per grid, and never fires the header's " "sort; the table stays table-layout:auto, so a width is a strong " "hint. Inline edit (dz-grid-edit.js): dblclick a cell's " "display span ([data-dz-grid-edit] + " "data-dz-edit-kind/-value/-label/-options) to open an in-cell " "editor; Enter commits, Escape cancels, Tab advances — the commit is a " "single-field JSON PUT to the entity's standard update route " "(data-dz-grid-edit-url on the root; no bespoke field endpoint), " "and a dz-grid:refresh re-renders the row server-side. An " "in-flight edit survives a tbody swap: the buffer lives on the grid root, " "outside the morph path. " "(The gallery mock approximates the " "innerMorph swap with an innerHTML replace — copy the snippet into a " "real htmx4 app, with the idiomorph extension for hx-swap="innerMorph", " "for true morph-preserved selection.)", tags=("data", "interactive", "htmx"), exchanges=( Exchange( method="GET", endpoint="/app/{region}/rows?q=&sort=&dir=&page=&page_size=", trigger="the tbody, on `load` and on `dz-grid:refresh` (fired by a sort " "click, a filter change, a debounced search keystroke, or a page " "control) — with `page=` added for pagination", response="the current page's `` rows for the query — each a `dz-tr-row` " "carrying a stable `id` (the idiomorph morph key) plus " "`data-dz-grid-row-id` (the bulk-action payload anchor) — plus the repainted " "pagination footer (via an OOB `

` or a wrapping region swap); a " "zero-result query returns an empty tbody so the `:has(tbody tr td)`-driven " "empty-state shows", swap="innerMorph of the tbody (`[data-dz-grid-body]`) — idiomorph keys on " "each row's `id`, so a live selection follows its row across a re-sort — PLUS " "an out-of-band update of the pagination footer: append " '`` ' "to the response (the stamped total feeds the all-matching affordance) " "(or target a wrapping region that contains both the tbody and the footer in " 'one swap). The footer\'s current-page button carries `aria-current="page"` — ' "the client reads it back as the authoritative (possibly server-clamped) page", states=("loading", "empty", "populated", "error"), envelope="body_only", ), Exchange( method="POST", endpoint="/app/{region}/bulk", trigger="a bulk-action button (e.g. Delete), after the user approves its " "confirm dialog; the controller injects the selection on `htmx:configRequest`", response="the server RE-VALIDATES permissions and RE-SCOPES the action to " "the echoed query (never trusting the client `selected_ids` alone) and " "applies it. Two patterns: with `data-dz-grid-bulk-refresh` on the button " "(this demo), the response swaps NOTHING (JSON/204) and the controller " "re-fetches rows + footer via the normal GET; without it, put `hx-target` " "on the button and return the refreshed `` rows directly. " "When `all_matching_selected=true`, the action applies to " "the WHOLE matched query minus `excluded_ids` — the server re-runs the " "echoed query itself, and MUST strip `page`/`page_size` first (they window " "the display, not the matched set — re-running them verbatim would apply " "the action to one page only); `selected_ids` is informational (visible " "state) only. NB form encoding: with no exclusions the `excluded_ids` key " "is ABSENT from the POST (not sent empty) — default it to the empty list", swap="innerMorph of the tbody (`[data-dz-grid-body]`) plus the OOB footer " "(its `data-dz-grid-total` re-stamps the matched total)", states=("populated", "empty", "error"), ), Exchange( method="PUT", endpoint="/app/{entity}/{id}", trigger="the inline-edit extension (dz-grid-edit.js): dblclick an " "editable cell's display span opens an in-cell editor; Enter (or a " "change, for bool/select/date) commits a raw fetch PUT to " "`{data-dz-grid-edit-url}/{rowId}` — NOT an htmx exchange", response="this is the entity's STANDARD update route, not a bespoke " "field endpoint: the body is a single-field JSON object " '(`{"plan": "Pro"}`), so an all-optional update schema + ' "exclude-unset semantics make it a partial update, and the full " "update gate (permissions, scoping, validation) applies. Return " "2xx JSON on success; any non-2xx keeps the editor open with the " "response text as its error. The controller then fires " "`dz-grid:refresh` on the tbody, so the committed value renders " "SERVER-side (badges/dates re-render; no client patching)", swap="none (raw fetch) — the follow-up `dz-grid:refresh` re-fetches " "rows + footer via the tbody's normal GET", states=("populated", "error"), envelope="none", ), ), controller="controllers/dz-grid.js", # The optional extension controllers (promoted from Dazzle, 0.1.26): # column visibility, column resize, inline cell editing — each rides # the grid's seams; the core grid works without any of them. extensions=( "controllers/dz-grid-cols.js", "controllers/dz-grid-resize.js", "controllers/dz-grid-edit.js", ), mock="/mock/grid", contracts=( "contracts/grid.py", "contracts/grid_edit.py", "contracts/grid_cols.py", "contracts/grid_resize.py", ), guidance=Guidance( seams=( "column visibility: dz-grid-cols.js projects the hidden set onto " "[data-dz-col] cells after every swap — no per-cell bindings", "column resize: dz-grid-resize.js rides the header cells", "inline edit: dz-grid-edit.js reads the [data-dz-grid-edit] display " "span (kind/value/label/options) — contract in contracts/grid_edit.py", "kind=select cells open a bare native for density, morph " "survival (root._dzEdit + before/after-swap), and commit-on-change " "PUT — not the progressive-enhancement combobox overlay" ), require_substrings=("dz-inline-edit-select",), forbid_substrings=( "data-dz-combobox", "dz-combobox-input", "dz-combobox-listbox", ), spike="docs/spikes/combobox-in-grid-cell.md", ), ), ), # ── Overlays (interactive — need the mock htmx / dialog) ───────── Hyperpart( "command", "Command palette", "Overlays", "The hx-get palette — the htmx4 flagship. Press ⌘K.", '' # `closedby="any"` = native light-dismiss (backdrop tap + Esc) where # supported (recent Chromium); dz-command.js provides the cross-browser # floor. The close button is the always-visible dismiss affordance — # essential on touch, where there is no Esc key. '' # input + close share a flex bar; results follow. `next # .dz-command__results` resolves by DOM order (forward scan), so the # wrapper is fine. Flex layout (not absolute positioning) keeps the # close button reliably placed — abspos against a modal ', notes="In Dazzle the input's hx-get hits /app/command, which returns " "persona-scoped results as real links. The gallery mock returns " "<button type=button class=dz-command__item> rows so picking " "an option closes the palette without href=# scrolling the page " "to the top mid-browse. Shortcut chips (stem " "shortcut-hint-chrome): opener uses adjacent " "layout (button gap); result rows use trailing " "(margin-inline-start: auto on .dz-kbd).", tags=("interactive", "htmx"), exchanges=( Exchange( method="GET", endpoint="/app/command", trigger="the search input, on `input` (debounced 150ms) and first `focus`", response='zero or more result rows — ``/`', notes="**Pick:** request gating — yes/no before an existing " "hx-* runs (stem chrome-vs-protocol). Not a custom " "modal body (dialog = addressing). Protocol: dz-confirm.js " "intercepts htmx:confirm; message IS the " "hx-confirm string; accept issues the underlying request. " "No confirm Exchange / no POST /confirm. " "Gallery-only toast: MOCK_HTMX may flash " "Deleted (demo). — not Hyperpart surface; production returns " "the action Exchange fragment.", tags=("interactive", "htmx"), exchanges=( Exchange( method="DELETE", endpoint="/app/invoices/{id}", trigger="the button, after the user approves the designed confirm dialog", response="the server deletes the resource and returns the replacement markup " "for the affected region (e.g. the row's removal, or an empty-state). " "Not a toast — the gallery's 'Deleted (demo).' toast is MOCK_HTMX only", swap="per the button's `hx-target`/`hx-swap` (row removal by default)", envelope="host_owned", server_example=( "# This is the DELETE after confirm — not a “confirm API”.\n" "# The dialog is client-only (hx-confirm + dz-confirm.js).\n" "from fastapi import FastAPI\n" "from fastapi.responses import HTMLResponse\n" "\n" "app = FastAPI()\n" "\n" "\n" '@app.delete("/app/invoices/{invoice_id}", response_class=HTMLResponse)\n' "def delete_invoice(invoice_id: str) -> str:\n" " # delete_invoice_from_db(invoice_id)\n" " # Return whatever hx-target/hx-swap expect, e.g.:\n" " # - empty string with hx-swap='delete' on the trigger\n" " # - an empty-state partial for the list region\n" " # - OOB markup to refresh a sibling region\n" ' return ""\n' ), ), ), controller="controllers/dz-confirm.js", contracts=("contracts/confirm.py",), guidance=Guidance( seams=( "protocol: any hx-confirm → htmx:confirm → designed singleton dialog", "message text IS the hx-confirm attribute value (author the string, not a dialog partial)", "on accept: issueRequest on the underlying action; cancel: dropRequest", "pick-a-surface: request gating vs dialog addressing (chrome-vs-protocol)", ), pitfalls=( "hx-confirm is a client affordance — it needs no Exchange of its own " "(and no FastAPI route for “confirm”)", "do not re-implement confirm with window.confirm (loses the designed dialog)", "do not use confirm when you need a custom modal body — that is dialog (addressing)", "gallery toast 'Deleted (demo).' is MOCK_HTMX scaffolding in site/build_site.py — " "not Hyperpart surface; production returns the DELETE fragment from the Exchange", ), do_dont=( ( "put hx-confirm on the destructive action element; implement the DELETE " "(or other) endpoint as the Server exchange", "wire a bespoke dialog open/close for every delete button or invent a " "POST /confirm endpoint for the dialog itself", ), ( "fleet upgrade: every hx-confirm gets the same chrome (gating)", "author a full

`) — no JS for open state. A disclosure, " "not a full ARIA menu: no roving tabindex or typeahead.", '", notes="**Pick:** local actions from one control — not app File/Edit chrome " "(menubar) and not product/site go-to nav (navigation-menu). See " "docs/agent/pick-a-surface.md › Menus / panels / chrome strips. " "Trigger label is plain text; open-panel signal is CSS " "::after chevron. Light-dismiss (stem " "overlay-light-dismiss): default spatial " "(Esc + outside); optional temporal via " "data-dz-dismiss-ms. Configure " "data-dz-dismiss / data-dz-dismiss-ms on the " "details. Controller dz-details-light-dismiss.js.", tags=("interactive",), controller="controllers/dz-details-light-dismiss.js", contracts=("contracts/menu.py",), guidance=Guidance( seams=( "`details.dz-menu` + `summary` (usually `.dz-button`) + `.dz-menu__panel`", "disclosure chevron is presentation on summary::after — not label text", "data-dz-dismiss / data-dz-dismiss-ms — spatial vs temporal abandon", "pick-a-surface: local actions from one button → menu (not menubar / navigation-menu)", ), pitfalls=( "do not bake ▾/▼ into the summary text — house disclosure chrome is CSS/SVG", "not a full ARIA menu (no roving tabindex/typeahead) — do not invent role=menu half-contracts", "do not use menu for top product IA or File/Edit strips — wrong job", "native details do not Esc/outside-dismiss — ship the light-dismiss controller", "do not default-timeout action menus — temporal is opt-in for glance UIs only", ), do_dont=( ( "label text only + CSS chevron that rotates when [open]", "Actions ▾ as a single text string for the expand signal", ), ( "one Actions control with an item list on a host (toolbar/row)", "a horizontal multi-trigger strip (that is menubar or navigation-menu)", ), ( "spatial Esc+outside by default; data-dz-dismiss-ms only when intentional", "require re-tapping the summary as the only way to cancel", ), ), a11y_keys=( "details/summary carry expand; chevron is decorative", "Keyboard: Enter/Space opens; Escape light-dismisses (unless data-dz-dismiss=none)", "Touch: tap outside to abandon (no Esc key)", ), composes_with=("button",), ), ), Hyperpart( "popover", "Popover", "Overlays", "Disclosure popover (`

`) — free-content panel; body can " "lazy-load via htmx. Not a focus-trapped/positioned popover.", '', notes="**Pick:** free content under a trigger — not an action list (menu). " "Not a tooltip (no auto-timeout by default). Light-dismiss: " "spatial Esc+outside; optional " "data-dz-dismiss-ms for glance previews only. " "data-dz-dismiss=none for native toggle only. " "Controller dz-details-light-dismiss.js.", tags=("interactive",), controller="controllers/dz-details-light-dismiss.js", contracts=("contracts/popover.py",), guidance=Guidance( seams=( "`details.dz-popover` + summary + `.dz-popover__panel`", "data-dz-dismiss / data-dz-dismiss-ms — spatial vs temporal (stem overlay-light-dismiss)", "shared controller with menu (dz-details-light-dismiss.js)", ), pitfalls=( "not a modal dialog — no focus trap; use dialog when you need modal", "not a tooltip — do not put a default timeout on form/filter popovers", "native details do not Esc/outside-dismiss without the controller", "do not light-dismiss accordion/tree (in-flow structure)", ), do_dont=( ( "spatial Esc+outside by default; opt-in data-dz-dismiss-ms for glance only", "auto-close content the user is still editing", ), ( "data-dz-dismiss=none when the host owns dismiss", "assume a global timer on every popover instance", ), ), a11y_keys=( "Keyboard: Enter/Space on summary; Escape dismisses (if esc enabled)", "Touch: pointer outside dismisses (if outside enabled)", ), composes_with=("button",), ), ), Hyperpart( "tooltip", "Tooltip", "Overlays", "CSS-only visual hint (`data-dz-tooltip`) — zero JS. A hint, not an " "accessible tooltip: keep it non-critical (no touch/SR/keyboard path). " "Optional `data-dz-tooltip-open` forces the hint visible (capture/docs).", '', notes="Dual-lock root [data-dz-tooltip] (HMC-154). Force-open: data-dz-tooltip-open.", contracts=("contracts/tooltip.py",), ), Hyperpart( "dialog", "Dialog", "Overlays", "Modal on the native — one line of JS to open, close for free " "(Esc / backdrop / method=dialog submit). Focus-trapped by the platform.", '" '", notes="**Pick:** modal addressing — authored shell by id " "(stem chrome-vs-protocol). Not request gating (confirm = " "hx-confirm singleton). Opening is the only scripted behaviour " "(dz-dialog.js → showModal() for " "[data-dz-dialog-open]); closing is native. Put actions on " "footer buttons (hx-* / form submit / returnValue).", tags=("interactive",), composes=("button",), controller="controllers/dz-dialog.js", contracts=("contracts/dialog.py",), guidance=Guidance( seams=( "addressing: data-dz-dialog-open → showModal on dialog#id (N instances)", "author full dialog HTML (header/body/footer) — chrome you own", "confirm button may carry hx-delete / form submit; closing is native", "pick-a-surface: custom modal body → dialog; yes/no on hx-* → confirm", ), pitfalls=( "do not re-implement close with custom overlays — use " "

", notes="Opened by shared dz-dialog.js " "([data-dz-dialog-open]); close is native. " "Chrome shells: form_shell (one " "method=dialog wrap when body has no nested forms) vs " "exchange_shell (scoped close forms; body is HTMX target). " "Both keep drawer__header|body|footer as flex children " "(outer form is display:contents). " "Composition host: guests mount with their own DOM " "contracts (field triad, switch track, toggle-group without legend " "inside the fieldset, honest KPI cards). Peek: one click fires " "hx-get into the body and showModal. " "Peek vs full page: footer " "Open full page is a real link to the " "record-page Blueprint (owned URL) — not a CSS maximize. " "Expand / Restore toggles resting " "data-dz-width ↔ xl (honest next-action " "labels — not a multi-step cycle). Peek body content must be tall " "enough to show independent body scroll. See " "stems/host-chrome-symmetry.md and " "tools/composition_matrix.py.", tags=("interactive", "htmx"), composes=( "dialog", "button", "field", "badge", "card", "alert", "toggle-group", "switch", "controls", ), # Opener is shared dz-dialog.js (owned by dialog Hyperpart) — not re-declared. guidance=Guidance( seams=( "addressing: data-dz-dialog-open + dialog.dz-drawer (shares dz-dialog.js)", "chrome shells: form_shell (method=dialog wrap) vs exchange_shell " "(scoped close forms) — same header/body/footer BEM", "body is a composition host — nest field, toggle-group, switch, " "controls, badge, card, alert with honest guest DOM", "hypermedia peek: hx-get + data-dz-dialog-open on the same click " "(fragment into drawer__body; list stays underneath)", "peek → full page: real href to owned record URL " "(Blueprint record-page) — not type=button no-op", "expand/restore: data-dz-drawer-expand toggles resting width ↔ xl " "(aria-pressed + next-action label; not a multi-step cycle)", "data-dz-side / data-dz-width for placement presets", "demo must exercise behaviour: peek body tall enough to scroll " "independently of the host page", "composition matrix: tools/composition_matrix.py", ), pitfalls=( "do not invent a second open protocol — same addressing as dialog", "do not wrap exchange_shell body in method=dialog if the fragment " "may contain forms (nested form is invalid HTML)", "do not paint drawer__body muted — guests inherit colour", "do not put legend inside dz-toggle-group (breaks segment flex)", "do not use input.dz-switch when composing the switch Hyperpart " "(use label.dz-switch + track + data-dz-switch)", "do not use form-field as read-only meta (hint is help, not value)", "lazy body starts empty/skeleton; exchange fills #…-body, not the whole dialog", "do not label Expand/Restore “Open full page” — full page is navigation", "do not use type=button for full-page when the job is a new URL", "do not cycle multi-step widths under a unipolar verb (Widen→reset lies)", "do not leave pointer-open focus on header chrome (close, Expand, …) " "— settle to [autofocus] or the dialog shell (dz-dialog.js); " "close-only special-cases miss the next header button", "do not ship a scrollable body claim with content that never overflows", ), do_dont=( ( "compose existing Hyperparts inside drawer__body with their " "standalone DOM contracts", "rebuild field/badge/switch chrome as one-off drawer-only markup", ), ( "pick form_shell vs exchange_shell by whether the body may " "contain nested forms", "mix half-patterns (header element + whole-form wrap) without reason", ), ( "pair hx-get target with the scrollable body id", "swap the entire dialog element (loses open state / focus trap)", ), ( "use one KPI card per metric (or card-label + card-value meta)", "one card wrapping an auto-grid of overridden card-value sizes", ), ( "Open full page = to the record document " "(shareable / refreshable URL)", "Open full page = expand the dialog or a dead type=button", ), ( "Expand/Restore = 2-state data-dz-width toggle " "(next-action label + aria-pressed)", "cycle md→lg→xl→full under a single “Widen” label", ), ( "peek fragment tall enough that drawer__body scrolls (host page stays put)", "short demo content that never exercises body overflow", ), ), a11y_keys=( "native dialog focus trap + Esc/backdrop; body may be tabindex=0 for scroll", "pointer open: settle to [autofocus] else body else shell — never " "header chrome; re-settle after showModal (rAF) — single settle races", "Expand control: aria-pressed + aria-label for next action (Expand/Restore)", "label the body (aria-label) when it is the live region for peek loads", "toggle-group: external label + aria-labelledby (not legend inside)", ), composes_with=( "dialog", "field", "toggle-group", "switch", "controls", "badge", "card", "button", "alert", ), ), exchanges=( Exchange( method="GET", endpoint="/app/records/{id}?peek=1", trigger="the opener button's click — the SAME click also fires " "the dz-dialog.js opener (`data-dz-dialog-open`), so the drawer " "shows while the body loads", response="composed detail fragment (card, badge, meta stack, actions) " "swapped into the drawer's body target", swap="innerHTML", ), Exchange( method="GET", endpoint="/app/records/{id}", trigger="Open full page footer link (plain navigation — not hx-*)", response="full record document (tabs, KPI grid, edit actions) — " "gallery Blueprint `record-page`; not a fragment swap", swap="document (navigation)", envelope="document", ), ), mock="/mock/drawer/detail", contracts=("contracts/drawer.py",), ), # ── Forms ──────────────────────────────────────────────────────── Hyperpart( "controls", "Selection controls", "Forms", "Designed checkbox / radio / switch on native inputs — semantics free.", '

' ' Checkbox' ' Radio' ' Switch' "

", notes="Dual-lock roots .dz-checkbox / .dz-radio / .dz-switch (HMC-150). " "Switch also dual-locks via contracts/switch.py ([data-dz-switch]).", contracts=("contracts/controls.py", "contracts/switch.py"), ), Hyperpart( "field", "Field", "Forms", "The label + control + help + error triad as one accessible unit. Error " "state derives from aria-invalid; help/error bind via aria-describedby.", '

' '

' 'Billing email' '*' '' '

Receipts and renewal notices go here.

' "

" '

' 'Workspace slug' '' '

Use lowercase letters, numbers and hyphens only.

", notes="Reuses the dz-form-* family (label / hint / input / error). The " "invalid field needs no modifier class — the red border keys off " "aria-invalid="true", the same attribute assistive tech reads. " "The colour group uses data-dz-color-group so dz-color.js " "can mirror the swatch into the hex readout (contract: contracts/color.py). " "Dual-lock: form triad contracts/form_field.py + colour " "contracts/color.py (HMC-139).", tags=("forms",), # The colour widget's hex-readout mirror rides the field family # (delegated input listener on .dz-form-color-input; Tier F4e — # replaced the last inline Alpine x-data straggler). extensions=("controllers/dz-color.js",), # Dual-lock: form triad = form_field (.dz-form-field); colour swatch # = color (HMC-139). Gallery id "field" maps to form_field stem. contracts=("contracts/form_field.py", "contracts/color.py"), ), Hyperpart( "slider", "Slider", "Forms", "Native — styled track + thumb, both themes, with a " "live value readout via a tiny delegated controller.", '

' 'Volume' '

' '' '' "

", notes="The track + thumb are styled for both themes with a focus ring; the native " "range already announces its value to assistive tech, so the visible readout is " "aria-hidden. dz-slider.js writes the value into " "[data-dz-range-value] on input, scoped to each slider's own group so " "many coexist.", tags=("forms",), controller="controllers/dz-slider.js", contracts=("contracts/slider.py",), guidance=Guidance( seams=( "native is the value source; [data-dz-range-value] is the readout", "each slider group is scoped so many coexist on one page", ), pitfalls=( "the visible readout is aria-hidden — the range already announces to AT", "do not invent a custom thumb/track in JS; style the native control", ), do_dont=( ( "write the live value into [data-dz-range-value] on input", "replace the native range with a div-based slider", ), ), a11y_keys=( "Arrow keys adjust the native range (browser default)", "focus ring is theme-aware on the track/thumb", ), composes_with=("field",), ), ), Hyperpart( "confirm-panel", "Confirm panel", "Forms", "The irreversible-action consent gate: a checklist of obligations " "that must be ticked before the primary action arms, plus live and " "revoked summary states.", '

' '

' '' '' 'I have exported a backup of live data' 'Rollback needs a snapshot taken ' "today." "

" '

' '' '' 'The billing owner has approved this ' "change" "

" '

' '' '' 'Notify the team afterwards ' "(optional)" "

" '

' 'Save draft' 'Go live' "

" '

This action is recorded in the audit ' "log with your identity and timestamp.

" "

" '

' '

Currently live

' '

Enabled 12 May by ' "j.reyes.

" "

" '

' 'Revoke' "

" "

", notes="**Pick:** in-flow consent gate — not modal chrome (dialog) and not " "hx-confirm yes/no (confirm). Stem chrome-vs-protocol: no " "addressing/gating modal; state-in-DOM. Primary ships " "aria-disabled with destination in " "data-dz-confirm-href; dz-confirm-gate.js " "recounts data-dz-required=true vs " "data-dz-required-count and arms the primary. Optional " "boxes never gate. Live/revoked branches use " "dz-confirm-summary + data-dz-confirm-tone.", tags=("forms",), controller="controllers/dz-confirm-gate.js", contracts=("contracts/confirm_panel.py",), guidance=Guidance( seams=( "data-dz-confirm-gate root + data-dz-required=true checkboxes + data-dz-required-count", "primary anchor parks destination in data-dz-confirm-href until armed", "pick-a-surface: checklist consent → confirm-panel (not dialog / hx-confirm)", ), pitfalls=( "optional boxes never gate — only data-dz-required=true count", "zero required boxes means the gate is always armed", "not a modal — do not replace with dialog that only mirrors checkbox state in JS", ), do_dont=( ( "keep armed state in the DOM (aria-disabled + href promotion)", "mirror checked counts into a JS boolean a swap would orphan", ), ), a11y_keys=( "primary stays aria-disabled until required count is met", "live/revoked branches use data-dz-confirm-tone for tone, not colour alone", ), composes_with=("button", "field"), ), ), Hyperpart( "search-box", "Search box", "Forms", "The FTS search region: a debounced search input, an aria-live " "results panel, and a coaching line that hides — via pure CSS — " "the moment the user types.", '", notes="Dual-lock root is data-dz-search-box " "(contracts/search_box.py). No JS beyond htmx: the " "250ms debounce is " "hx-trigger="input changed delay:250ms, search", " "the results land in an aria-live="polite" " "region, and the coaching line is hidden by " ":has(input:not(:placeholder-shown)) — no client " "state. Results are server-rendered " "dz-search-box-result rows (title + per-field " "<mark>-highlighted snippets, count line above); " "the no-results state reuses dz-search-box-empty with " "the --no-results modifier.", contracts=("contracts/search_box.py",), tags=("forms", "htmx"), exchanges=( Exchange( method="GET", endpoint="/app/fts/{entity}?q=&html=1", trigger="the input, debounced 250ms (and the native " "`search` event — Esc/clear on type=search)", response="the results fragment: a `dz-search-box-result-count` " "line + a `dz-search-box-result-list` of linked rows with " "``-highlighted snippets; zero hits return the " "`--no-results` variant of the empty line (which the CSS " "toggle deliberately never hides). Empty queries aren't " "sent (min length 1)", swap="innerHTML", ), ), ), Hyperpart( "form-chrome", "Form chrome", "Forms", "The structural form pieces: titled sections, the validation-error " "summary, and the multi-section progress stepper.", '

' '

' '' '

' '

Validation Error

' '

Name is required
Start date must be before end date

" '

' '1' 'Details' '
' '2' 'Schedule' '
' '3' 'Review

" '

' '

Contact details

' '

Shown on invoices and receipts.

' '

' 'Full name' '' '

' "

" "

", notes="Sections are real <section>s with an " "h3 title + optional note; fields inside use the HM " "form primitives. The error summary is " "role="alert" (the server re-renders it on " "a failed submit). The stepper here shows RENDERED states " "(is-active/is-not-last, " "aria-current="step") — the live navigation " "behaviour is the wizard Hyperpart " "(dz-wizard.js; the dzWizard Alpine island retired in " "Tier F4d). Dual-lock: form_errors + form_stepper + form_section + " "form_field (HMC-143).", tags=("forms",), composes=("field",), contracts=( "contracts/form_errors.py", "contracts/form_stepper.py", "contracts/form_section.py", "contracts/form_field.py", ), ), Hyperpart( "wizard", "Wizard", "Forms", "Multi-stage form navigation: the stepper drives stage reveal — " "back freely, forward one validated step at a time.", '

' '

' '' '
' '' '
' '

" '

' '

' 'Project name' '' '

' '' '" "

", notes="State-in-DOM: the root's data-dz-step is the " "current stage; stages toggle via the native hidden " "attribute; stepper items carry " "data-dz-state="complete|current|pending" " "(the checkmark is pure CSS off the state). " "dz-wizard.js allows going BACK freely and FORWARD " "one step at a time — only after every required input in the " "current stage passes reportValidity(). No-JS renders " "stage one with numbered steps (the form still posts whole).", tags=("forms",), controller="controllers/dz-wizard.js", contracts=("contracts/wizard.py",), guidance=Guidance( seams=( "root data-dz-step is the current stage; stages use native hidden", "stepper items carry data-dz-state=complete|current|pending (CSS checkmark)", ), pitfalls=( "forward only after reportValidity() on the current stage's required inputs", "no-JS still posts the whole form — stage one is the visible path", ), do_dont=( ( "keep stage index in data-dz-step on the wizard root", "store step in a JS variable a morph would discard", ), ), a11y_keys=( "Back is always free; Forward is one step and validity-gated", "invalid inputs receive focus so the browser validity bubble appears", ), composes_with=("field", "button", "progress"), ), composes=("form-chrome", "field"), ), Hyperpart( "money", "Money field", "Forms", "Major-unit decimal input over a hidden minor-unit carrier — the " "form posts integer minor units, never floats.", '

' '

' '' '' "

" '' '' "

", notes="State-in-DOM: the root's data-dz-scale is the " "conversion factor; dz-money.js keeps the hidden " "*_minor carrier in sync on input, normalizes the " "display to toFixed(scale) on blur (empty clears the " "carrier), and — in selector mode — reads a currency " "<select>'s data-scale/" "data-symbol options to retune scale and prefix. The " "edit-mode display value is SERVER-computed from the minor " "carrier, so there is no client init pass.", tags=("forms",), controller="controllers/dz-money.js", contracts=("contracts/money.py",), guidance=Guidance( seams=( "root data-dz-scale is the conversion factor; hidden *_minor carrier is the submit value", "selector mode reads currency ' "" '' '' '' '' '' '' 'Download' "" '

' '

' '' "

" "", notes="The application renders the shell and CONTROLS ACCESS; " "PDF.js renders the document. dz-pdf.js lazy-loads " "the library as an ES module from data-dz-pdf-lib " "only when the viewer scrolls into view — no PDF bytes or engine " "in the bundle. In Dazzle, data-dz-pdf-src points at " "the scope-gated range proxy " "(/_dazzle/documents/{entity}/{id}/{field}/file — " "document access IS entity access), and PDF.js range-requests " "pages on demand. data-dz-pdf-state="url" " "opts a viewer into ?dzpdf-page/?dzpdf-zoom " "deep-links (replaceState — Back stays page navigation). Without " "JS the noscript download link is the whole experience. In " "production, VENDOR the PDF.js module — dynamic import() cannot " "carry SRI; the gallery's CDN pin is demo-only.", tags=("data", "htmx"), controller="controllers/dz-pdf.js", contracts=("contracts/pdf.py",), guidance=Guidance( seams=( "data-dz-pdf-src points at the document bytes (or range proxy)", "data-dz-pdf-lib lazy-loads PDF.js as an ES module on first intersect", "data-dz-pdf-state=url enables ?dzpdf-page / ?dzpdf-zoom deep-links", ), pitfalls=( "application controls ACCESS; PDF.js only renders — do not embed bytes in the bundle", "without JS the noscript download link IS the experience", ), do_dont=( ( "lazy-load the engine from data-dz-pdf-lib when the viewer enters view", "eager-import PDF.js on every page that might show a document", ), ), a11y_keys=( "toolbar page/zoom controls remain keyboard-operable", "noscript download is the progressive-enhancement floor", ), composes_with=("button",), ), composes=("button",), exchanges=( Exchange( method="GET", endpoint="/_dazzle/documents/{entity}/{id}/{field}/file", trigger="PDF.js fetching document bytes (initial + Range " "requests as the user pages)", response="the file field's bytes — 200 whole-body or " "206 partial with Content-Range; opaque 404 when the " "record is out of scope; 416 for unsatisfiable ranges", swap="none (bytes consumed by the rendering engine)", envelope="none", ), ), ), Hyperpart( "two-factor", "Two-factor panel", "Forms", "The 2FA enrolment/settings card: QR + manual secret, the " "big-digit code input, recovery-code grid, and factor status " "rows.", '

' '

Set Up 2FA

' '

Aurora Ops

' '

Authenticator App

' '

Scan this QR code with your ' "authenticator app.

" '

' '

" '

Or enter the secret manually: ' 'JBSW Y3DP EHPK 3PXP

' '" '

' '

Save Your Recovery Codes

' '

Store these codes in a safe ' "place. Each code can only be used once.

" '

' 'QK2M-8Y1D' 'HW7C-04RA' 'ZX3N-55PT' 'MB9E-71LQ' "

" '

' '

Authenticator app

' 'Enabled

' '

Email codes

' 'Off

' 'Back to App' "

", notes="In Dazzle the enrolment flow is driven by ID-anchored " "vanilla JS (dz-2fa-setup.js/-settings.js " "against JSON endpoints): the QR image lands CLASSLESS in " "dz-auth-qr-container (the container styles it), " "recovery pills and status rows are JS-created (shown here with status badges; the Dazzle settings JS renders dz-button action controls in that slot), and the " "error/success alerts toggle via the native hidden " "attribute on stable ids. The code input reserves letter-spacing for six " "digits. Wrap full pages in dz-auth-page for the " "centered layout. Dual-lock root .dz-auth-card (HMC-148).", tags=("forms",), composes=("button", "badge"), contracts=("contracts/two_factor.py",), ), Hyperpart( "search-select", "Search select", "Forms", "The FK typeahead: debounced remote search into a listbox, then a " "per-row select exchange that fills a hidden id. Domain data maps " "into a fixed result-row anatomy (name / secondary / optional media) " "— do not invent a new combobox per entity. " "Demo: focus the input (or type) to open; media is optional so some " "rows are text-only.", # Production-shaped shell: closed + prompt. Gallery mock seeds rich # rows on `load` (and keyup); open only on focus. Confirm dwell keeps # the select feedback visible after a row click. '

' '' '' '

", notes="One Hyperpart, two surfaces. (1) Shell — " "hidden FK + typeahead + listbox; dz-search-select.js " "opens/closes (data-dz-open / aria-expanded). " "Timing knobs on the root: " "data-dz-blur-grace-ms (default 200) — wait after blur so a " "result-row click can land; data-dz-confirm-hold-ms " "(default 1500; alias data-dz-confirm-dwell-ms) — how long " "to keep the panel open after a select exchange paints " ".dz-select-result-confirm (auto-dismiss hold; 0 = no hold). " "(2) Result rows — fixed micro-pattern: optional " ".dz-search-result-media + name + optional secondary. " "Different shapes in one list are intentional: media is " "optional — a company row without a badge and a person row with initials " "are the same Hyperpart. Map domain fields into slots; do not invent a " "picker per entity. Form posts the hidden input, never the visible text. " "contracts/search_select.py " "(SearchResultRow + render_result_row).", tags=("forms", "htmx"), controller="controllers/dz-search-select.js", contracts=("contracts/search_select.py",), guidance=Guidance( seams=( "shell: hidden FK + typeahead input + listbox panel " "(`data-dz-widget=search_select`)", "data-dz-blur-grace-ms (default 200) — blur→close delay so row " "clicks land; data-dz-confirm-hold-ms (default 1500, alias " "confirm-dwell-ms) — auto-dismiss hold after " ".dz-select-result-confirm paints", "search exchange returns N× fixed result-row fragments " "(or `.dz-search-result-empty`) — map domain into " "name / secondary / optional media (omit media for text-only rows)", "each row carries its own hx-get to the select exchange", "select exchange: confirm line (+ OOB hidden FK / label) — " "never client-side write of the id", ), pitfalls=( "blur grace is NOT confirm hold — without confirm-hold-ms the " "select feedback is hidden as soon as focus leaves (~200ms)", "form posts the hidden input, never the visible text", "do not invent a new combobox Hyperpart for 'users vs companies' — " "same row anatomy, different field mapping; missing media is valid", "media is optional free HTML inside `.dz-search-result-media` " "(img, initials, icon) — keep primary text in `.dz-search-result-name`", ), do_dont=( ( "map any record to SearchResultRow " "(id, name, secondary?, media_html?) and render_result_row", "build a bespoke listbox DOM per entity or return JSON for the client to paint", ), ( "set data-dz-confirm-hold-ms when the confirm line is user-facing", "rely on blur grace alone to show select feedback", ), ( "swap the panel with a confirmation fragment that fills the hidden FK server-side", "copy the visible label into a hidden field from client JS", ), ), a11y_keys=( "aria-expanded / data-dz-open flip on focusin/focusout for the results panel", "result rows are role=option with their own activatable hx-get", "media slot is aria-hidden when decorative (initials/icon)", ), composes_with=("field", "search-box", "avatar"), ), exchanges=( Exchange( method="GET", endpoint="/app/fragments/search?source={source}&q=", trigger="keyup on the combobox, debounced (`delay:{n}ms`)", response="HTML fragment: zero-or-more `.dz-search-result-row` " "options (fixed anatomy: optional media + name + optional " "secondary; each row hx-gets the select endpoint) OR one " "`.dz-search-result-empty` prompt — never JSON", swap="innerHTML into the listbox", states=("prompt/min-chars", "results", "empty", "error"), server_example="""# Search exchange — map domain → fixed row anatomy. # Do NOT invent a new picker per entity shape. from fastapi import FastAPI, Query from fastapi.responses import HTMLResponse app = FastAPI() @app.get("/app/fragments/search", response_class=HTMLResponse) def search(source: str, q: str = Query("")) -> str: # rows = query_domain(source, q) # return "".join(render_result_row(SearchResultRow( # id=r.id, name=r.title, secondary=r.meta, # media_html=r.avatar_html or "", # select_url=f"/app/fragments/select?source={source}&id={r.id}", # results_target="#search-results-company", # )) for r in rows) return ( '" ) """, ), Exchange( method="GET", endpoint="/app/fragments/select?source={source}&id={id}", trigger="click / activate on a result row", response="confirm fragment replacing the listbox " "(`dz-select-result-confirm`) and server-side fill of the " "hidden FK (and usually the typeahead label via OOB)", swap="innerHTML (listbox) + OOB for hidden/input as needed", states=("selected",), server_example="""# Select exchange — fill the hidden FK server-side. from fastapi import FastAPI from fastapi.responses import HTMLResponse app = FastAPI() @app.get("/app/fragments/select", response_class=HTMLResponse) def select(source: str, id: str) -> str: # label = load_label(source, id) return ( f'

' f"Selected {id}

" # + OOB: # + OOB: typeahead value=label hx-swap-oob ) """, ), ), ), Hyperpart( "combobox", "Combobox", "Forms", "Searchable single-select over a list of options — a native ' '' '' '' '' '' "" '' 'Department (growing list — type to add)' '" "", notes="Same Hyperpart, two recipes. Progressive " "enhancement: server renders a real " "<select data-dz-combobox> (placeholder option first). " "JS builds a filterable listbox; the native select remains the submit " "value. Fixed list (priority above): the set is " "authoritative and closed — filter and pick only (workflow priority, " "severity tiers, anything you do not let users invent). " "Growing list / mutable catalogue (department above): " "set data-dz-allow-create on the <select>. " 'When the typed query has no exact match, an Add "…" row ' "appears; Enter/click appends a new <option> and " "commits it (value = label string). That is the common " '"pick from our list, or add one" pattern — departments, cost centres, ' "queues, product lines — not a new Hyperpart. " "Server still owns persistence: on submit upsert the catalogue row if " "the value is new; the client only extends the option list for this page. " "Not this part: multi free-form chips → " "tags; remote FK typeahead → search-select. " "Do not invent a fourth picker. " "After select: " "data-dz-focus-after-select=blur|keep|select " "(default blur).", tags=("forms",), controller="controllers/dz-combobox.js", contracts=("contracts/combobox.py",), # Form-bound server contract (not an hx-* of this part — see exchange_empty). exchange_empty=( '

No dedicated htmx request of this ' "Hyperpart's own — the controller never issues one. The native " "<select> value rides the enclosing form " "(or any hx-* you put on that form). That form handler " "is the server contract for this part.

" "

Fixed list (default — no " "data-dz-allow-create): closed set. Accept only values that " "were in the seed <option> list.

" "

Growing list (data-dz-allow-create): the " "client may submit a value that was not in the seed options " '(Add "…" appends a local <option> with value = label ' "string). On form submit the server must accept that " "unknown string and upsert it into the catalogue, then " "store the field (FK or label per your model). The new option is page-local " "until that submit succeeds — do not treat client create as durable " "storage.

" "

If you put hx-* on a control that uses this markup, that " "action's exchange belongs to the action, not this part.

" ), guidance=Guidance( seams=( "server renders a real ', notes="Progressive enhancement: the server renders a plain " "<input type="text" data-dz-tags> whose " "value is a COMMA-JOINED tag string — usable and submittable with no " "JS (type a, b, c; the server splits on comma), native " "required intact. Seeded non-empty values enhance on " "DOM ready; empty fields enhance on first interaction. " "dz-tags.js wraps the input in a .dz-tags " "root — a role="list" of removable chips + a " "borderless entry — and hides the native input (kept in the DOM as " "the submitted value). Every add/remove rewrites the native input to " "the " "comma-joined chip list and fires change, so the submit " "shape never changes. Type + Enter or comma creates a chip " "(trim/dedup/skip-empty); paste splits on comma/newline; × or " "Backspace-on-empty removes a chip; add/remove is announced via a " "visually-hidden aria-live region.", tags=("forms",), controller="controllers/dz-tags.js", contracts=("contracts/tags.py",), guidance=Guidance( seams=( "native input value is a comma-joined tag string — the permanent submit shape", "chips UI rewrites the native input on every add/remove and fires change", ), pitfalls=( "JS off: type a, b, c — server splits on comma; do not require the chips UI", "dedupe/trim/skip-empty on add; paste splits on comma and newline", ), do_dont=( ( "keep the native input as the form value under the chips root", "post a JSON array the server has never seen from a plain field", ), ), a11y_keys=( "chips are role=list of listitem; each × is labelled Remove {tag}", "Enter or comma creates a chip; Backspace on empty entry removes the last", ), composes_with=("field",), ), ), Hyperpart( "date-range", "Date range", "Forms", "Two native date inputs driving one htmx exchange — the from/to " "filter bar for time-scoped regions.", '

' 'From' '' 'To' '' '' "

", notes="Dual-lock root is data-dz-date-range " "(contracts/date_range.py). Native " "type="date" inputs — no picker JS. Each " "input fires the region's hx-get on change and " "hx-include="closest .date-range-bar" sends " "BOTH bounds every time, so the server always sees the full range.", tags=("forms", "htmx"), contracts=("contracts/date_range.py",), exchanges=( Exchange( method="GET", endpoint="/app/{region}?date_from=&date_to=", trigger="either date input's change — hx-include sends both bounds", response="the re-rendered region body for the new range", swap="innerHTML", ), ), ), Hyperpart( "toggle-group", "Toggle group", "Navigation", "Segmented control on native radios.", '

' '{icon:list} List' '{icon:kanban} Board' '{icon:calendar} Calendar

', notes="Dual-lock root .dz-toggle-group (HMC-153).", contracts=("contracts/toggle_group.py",), ), Hyperpart( "switch", "Switch", "Forms", "On/off control — progressive enhancement over a native checkbox. " "State is the checkbox's checked attribute (DOM), not a JS store.", '

' '' '' '' "Email notifications" '' '' '' "Weekly digest" "

", notes="PLACEHOLDER — shadcn parity (HMC-031). No controller: native " "checkbox + CSS track/thumb. Label text is a sibling span so the " "whole control is a click target. Dual-lock root [data-dz-switch] " "(HMC-129); Dazzle form-field emit still optional.", tags=("form", "interactive"), contracts=("contracts/switch.py",), ), Hyperpart( "toggle", "Toggle", "Forms", "Single pressable mode control (Bold / Italic toolbar style). State is " "aria-pressed on the button — pair with toggle-group for exclusive segments.", '

' '" '" '' "

", notes="Distinct from switch (form boolean) and toggle-group (exclusive " "radios). Initial aria-pressed may come from SSR; dz-toggle.js flips " "it on click. Dual-lock root [data-dz-toggle] (HMC-130).", tags=("form", "interactive"), controller="controllers/dz-toggle.js", contracts=("contracts/toggle.py",), guidance=Guidance( seams=( "button root carries data-dz-toggle (gallery: data-toggle)", "aria-pressed is the live state; SSR may set the initial value", "dz-toggle.js flips aria-pressed on click (no round-trip)", ), pitfalls=( "do not use toggle for form booleans — use switch/checkbox", "do not invent exclusive group logic here — use toggle-group radios", "skip disabled / aria-disabled buttons and data-dz-widget bridges", ), do_dont=( ( "flip aria-pressed client-side for toolbar mode controls", "require a server exchange to press Bold/Italic", ), ( "pair multiple independent toggles in a toolbar row", "make one toggle uncheck siblings (that is toggle-group)", ), ), a11y_keys=( "aria-pressed announces the mode to AT", "Space/Enter activate the button (native button semantics)", ), composes_with=("toggle-group", "button", "toolbar"), ), ), Hyperpart( "kbd", "Keyboard key", "Primitives", "Shortcut chip for docs and command chrome — .", '' '⌘K' 'Esc' '↵' '⇧' "", notes="Stem shortcut-hint-chrome: keyboard chips are " "visually secondary (mono, small, muted keycap) and " "spatially secondary — layout roles " "adjacent (flex gap next to a label) vs trailing " "(row end via margin-inline-start: auto). Not disclosure " "iconography. Styles in hm-core.css; pure presentation. " "Dual-lock root .dz-kbd (HMC-151).", tags=("docs",), contracts=("contracts/kbd.py",), guidance=Guidance( seams=( '`` — always the house chip, never bare Unicode', "layout roles: adjacent (button:has kbd gap) vs trailing (list/menu auto)", ), pitfalls=( "0px gap between primary label and kbd under-signals secondary metadata", "do not apply affordance-disclosure-chrome (chevrons) rules to shortcuts", "do not put a kbd on every dense toolbar control (clutter)", ), do_dont=( ( "visually secondary chip + adjacent gap or trailing auto", "glue ⌘K to the action label or invent a Lucide keyboard as the only hint", ), ), a11y_keys=( "kbd is presentational hint; the control still needs its own accessible name", ), composes_with=("command", "button"), ), ), Hyperpart( "aspect-ratio", "Aspect ratio", "Primitives", "Media frame that locks width/height — images and embeds fill with object-fit cover.", '' '' '1:1' '' '16:9' '' '4:3' "", notes="PLACEHOLDER — shadcn parity (HMC-036). Pure CSS aspect-ratio + " "data-dz-ratio presets (1/1, 4/3, 16/9, 21/9). Dual-lock root " ".dz-aspect-ratio (HMC-132). No controller.", tags=("layout", "media"), contracts=("contracts/aspect_ratio.py",), ), Hyperpart( "item", "Item", "Data", "Generic list row — optional media, title, description, trailing actions. " "Compose into lists, pickers, and search results.", '' '' 'MR' '' 'Maya Reyes' 'Operations · North grid' "" '' '' '' 'JK' '' 'Jordan Kim' 'Support · Escalations' "" '' '', notes="PLACEHOLDER — shadcn parity (HMC-033). Flex row anatomy only; " "no controller. Actions stop at product buttons. Dual-lock root " ".dz-item (HMC-145).", tags=("data", "layout"), contracts=("contracts/item.py",), ), Hyperpart( "hover-card", "Hover card", "Overlays", "Rich preview on hover/focus/tap — progressive enhancement over a " "trigger link or button.", '' '' '' 'Maya Reyes' 'Operations lead · Online now' "", notes="shadcn parity (HMC-035). Opens on :hover / :focus-within " "(fine pointers + keyboard) and on click/tap via " "controllers/dz-hover-card.js (data-dz-open / " "gallery data-open) — iPadOS Safari does not keep " ":hover or button :focus after a tap, so CSS-only demos looked dead. " "Transparent ::before bridge covers the visual gap for desktop hover. " "Distinct from popover (details exclusive open). Dual-lock root " ".dz-hover-card (HMC-133). Canonical panel class is __content " "(__panel is a legacy alias).", tags=("overlay", "interactive"), contracts=("contracts/hover_card.py",), controller="controllers/dz-hover-card.js", guidance=Guidance( seams=( "open: CSS :hover/:focus-within OR data-dz-open from controller", "trigger click/tap toggles open; outside click + Escape close", "aria-expanded on the trigger mirrors open state", "death-zone bridge: __content::before covers margin-top gap", ), pitfalls=( "do not rely on focus-within alone for touch — load dz-hover-card.js", "do not use hover-card for multi-control forms (use popover/dialog)", "do not omit the trigger class — controller binds .dz-hover-card__trigger", ), do_dont=( ( "ship the controller with the partial on touch-first surfaces", "document 'tab for touch' as the only open path", ), ( "keep __content in the DOM (SSR); toggle visibility only", "fetch the panel on first hover (death zone + flash)", ), ), a11y_keys=( "Keyboard: Tab to trigger + Enter/Space activates button (toggle)", "Escape closes explicit open", "role=tooltip on the panel — keep content non-interactive", ), ), ), Hyperpart( "carousel", "Carousel", "Data", "Ordered peer slides in a stable stage — media and/or HTML fragments; " "DOM-local prev/next/dots (clamp or loop); optional autoplay.", # Decision 0009 + pragmatic-gallery-aesthetics. Full-bleed cover media # with source chips; hero overlay for hypermedia; ambient autoplay # without tabindex (focus-within was killing the timer). '' # ── Demo A: clamp · full-bleed cover + hero CTA ── "" '' "Clamp — ends disable. Media fills the stage " "(object-fit: cover); chips name the source aspect. " "Last slide is a hero overlay (hypermedia in the same visual language)." "" '' '' '' '' '' '' 'Source 16∶9 · cover' "" '' '' '' 'Source 3∶4 · cover' "" '' '' '' 'Source 1∶1 · cover' "" # Hero: same media stage + gradient CTA (not a floating card) '' '' '' "" '' 'Hypermedia slide' 'Adopt Mochi' '' "Same stage as media — CTA and live region ride the strip, not a " "separate admin card." "" '' '' "" "" '' '' '' '' '' '' '' "" '' "" 'Slide 1 of 4' "" # ── Demo B: loop + autoplay (no root tabindex — keeps timer alive) ── "" '' "Loop + autoplay — " 'data-dz-carousel-wrap="loop" · ' 'data-dz-carousel-interval="3000". ' "Advances every 3s; pauses while the pointer is over this strip; " "off under prefers-reduced-motion (status says so)." "" '' '' '' '' '' '' "" '' '' '' "" '' '' '' "" "" '' '' '' '' '' '' "" '' "" 'Slide 1 of 3' "" "", notes="Decision docs/decisions/0009-carousel-stage-and-motion.md. " "Only [data-dz-active] slides show. " "Clamp (default) disables ends; " "data-dz-carousel-wrap="loop" cycles. " "Autoplay via data-dz-carousel-interval " "(pause on hover/focus; off under reduced motion). " "Stage: viewport data-dz-ratio; " "media contain by default; cover via composed aspect-ratio. " "Hypermedia: slides are fragments; in-slide " "hx-* declares its own Exchange. shadcn/Embla parity job " "with DOM-carried state (HMC-037).", tags=("media", "interactive", "htmx"), controller="controllers/dz-carousel.js", contracts=("contracts/carousel.py",), composes=("aspect-ratio", "button", "card"), exchanges=( Exchange( method="GET", endpoint="/app/adoptions/request", trigger="Request visit CTA inside a rich (non-media) slide", response="confirmation fragment into the slide live region " "(badge / status line) — not a full strip re-render", swap="#hm-carousel-adopt innerHTML (gallery) / live region in the slide", states=("populated", "error"), server_example=( '@app.get("/app/adoptions/request")\n' "async def adoption_request():\n" ' return HTMLResponse(\'Visit requested\')\n' ), ), ), guidance=Guidance( seams=( "root [data-dz-carousel] + data-dz-carousel-index", "wrap: data-dz-carousel-wrap=none|loop (default none = clamp)", "autoplay: data-dz-carousel-interval=ms (absent = off; min 500)", "stage: .dz-carousel__viewport[data-dz-ratio] (1/1, 4/3, 16/9, 21/9)", "slides .dz-carousel__slide with data-dz-active on the visible one", "media full-bleed cover by default; chips name source aspect", "optional contain: .dz-carousel__media--contain; cover frame: " ".dz-carousel__media--cover + aspect-ratio", "hero hypermedia: .dz-carousel__slide--hero + .dz-carousel__hero overlay", "status: [data-dz-carousel-status] (“Slide N of M · Autoplay …”)", "prev / next / dots; keyboard when a control inside is focused", "decision 0009 + stem pragmatic-gallery-aesthetics", ), pitfalls=( "do not ship prev/next without a controller or server re-render", "do not loop by default — clamp is the honest task-UI default", "do not pause autoplay with document-level mouseenter on children " "(timer never re-arms) — pause only on root pointerenter/leave", "do not put tabindex=0 on autoplay roots unless required " "(focus-within kills ambient demos)", "do not teach mixed media with large letterbox gutters that look broken " "— full-bleed cover + chips; contain only when letterbox is the lesson", "do not drop a padded admin card into the stage as 'hypermedia' — " "use hero overlay language", "dots use role=group, not tablist", "in-slide hx-* needs its own Exchange", ), do_dont=( ( "update data-dz-active + aria-current + disabled ends in the DOM", "keep slide index only in a JS variable (orphaned on morph)", ), ( "full-bleed cover media with source-aspect chips for gallery polish", "leave uneven black bars that look like missing CSS", ), ( "hero overlay for CTAs inside the same stage as media", "orphan form/card that breaks the strip’s visual continuity", ), ( "show autoplay state in status (on / paused / reduced motion)", "silent timer that agents cannot observe", ), ), a11y_keys=( "aria-label on prev/next; aria-current on the active dot", "aria-live status including autoplay state; aria-roledescription=carousel", "ArrowLeft/Right when focus is on a control inside the root", "autoplay pauses while pointer is over the strip; off under reduced motion", "dot hit targets are 24×24", ), composes_with=("aspect-ratio", "button", "card", "badge"), ), ), Hyperpart( "menubar", "Menubar", "Navigation", "Horizontal app menus (File / Edit / View) — each item is a native " "details/summary so open state is DOM-native.", # role=navigation — not menubar: details/summary items are not # ARIA menuitems (axe aria-required-children). Native details open # state is the contract; menubar role would need menuitem children. '' '' 'File' '' 'New' 'Open…' '' "" '' 'Edit' '' '' '' "" '' 'View' '' '' '' "", notes="**Pick:** app chrome File/Edit/View — not product/site go-to " "(navigation-menu) and not a single Actions dropdown (menu). See " "docs/agent/pick-a-surface.md › Menus / panels / chrome strips. " "Open intent: exclusive + outside/Escape dismiss " "(details-open-intent). dz-menubar.js; probes " "menubar.exclusive_open, menubar.dismiss_outside. " "May compose denser item lists with menu patterns. shadcn parity (HMC-038).", tags=("navigation", "interactive"), controller="controllers/dz-menubar.js", contracts=("contracts/menubar.py",), guidance=Guidance( seams=( "`[data-dz-menubar]` / `.dz-menubar` root scopes exclusive open", "`details.dz-menubar__item` + `summary.dz-menubar__trigger` for panels", "pick-a-surface: File/Edit/View app chrome → menubar (not navigation-menu / menu)", ), pitfalls=( "Native details allow multi-open and ignore outside click — " "never ship menubar without dz-menubar.js", "Do not nest menubars; one root per chrome strip", "do not use menubar for marketing/product site IA — that is navigation-menu", ), do_dont=( ( "Let the controller close siblings on toggle and outside click", "Hand-roll per-item open flags in Alpine/React", ), ( "app command strip (File / Edit / View)", "top product nav with Home/Pricing links (navigation-menu)", ), ), a11y_keys=( "role=menubar / menuitem on panel actions", "Keyboard: Enter/Space toggles summary; Escape dismisses open panels", ), composes_with=("menu",), ), ), Hyperpart( "bubble", "Bubble", "Data", "Chat bubble shell — rounded content for inbound/outbound speech. " "Compose inside message rows.", '' '' "Can we reschedule the walkthrough to Thursday?" '' "Thursday 14:00 works — I'll send a calendar hold." "", notes="PLACEHOLDER — shadcn parity (HMC-040). " "data-dz-from=in|out picks surface colour. Prefer " "message Hyperpart for avatar + meta; bubble is the content shell only. " "Dual-lock root .dz-bubble (HMC-141).", tags=("media", "chat"), contracts=("contracts/bubble.py",), ), Hyperpart( "message", "Message", "Data", "Chat message row — media + author/time meta + bubble. " "Outbound rows reverse with data-dz-from=out.", '' '' 'MR' '' '' 'Maya Reyes' '10:02' "" '' "Can we reschedule the walkthrough to Thursday?" "" '' 'You' '' '' 'You' '10:04' "" '' "Thursday 14:00 works — I'll send a calendar hold." "", notes="PLACEHOLDER — shadcn parity (HMC-041). Composes " "bubble. Live chat = server re-render / OOB append into " "message-scroller, not client message state. Dual-lock root " ".dz-message (HMC-134).", tags=("media", "chat"), contracts=("contracts/message.py",), ), Hyperpart( "message-scroller", "Message scroller", "Data", "Chat transcript viewport — scrollable stack of message rows. " "Document order is chronological (newest last).", '' '' 'MR' '' '' 'Maya Reyes' '10:02' "" '' "Can we reschedule the walkthrough to Thursday?" "" '' 'You' '' '' 'You' '10:04' "" '' "Thursday 14:00 works — I'll send a calendar hold." "" '' 'MR' '' '' 'Maya Reyes' '10:05' "" '' "Perfect — see you then." "", notes="PLACEHOLDER — shadcn parity (HMC-042). " "role=log + aria-live=polite for " "assistive updates. Auto-scroll-to-bottom controller deferred; " "prefer append-at-end + optional host scrollIntoView. Dual-lock " "root .dz-message-scroller (HMC-147).", tags=("media", "chat", "interactive"), contracts=( "contracts/message_scroller.py", "contracts/message.py", "contracts/bubble.py", ), ), Hyperpart( "navigation-menu", "Navigation menu", "Navigation", "Top product/site nav with optional mega-menu panels — horizontal, " "not the app-shell sidebar. Triggers use native details.", '' '' '' 'Home' '' '' 'Product' '' '' 'Build' 'DSL appsShip CRUD + workflows' 'HyperpartsGallery + contracts' "" '' 'Operate' 'DeployPlan + target' 'ObservabilityPulse + fitness' "" '' '' 'Resources' '' '' 'Docs' 'Changelog' 'Community' "" '' 'Pricing' "", notes="**Pick:** product/site **go-to** top nav — not File/Edit app chrome " "(menubar), not a single Actions dropdown (menu), not left-rail shell " "(app-shell). See docs/agent/pick-a-surface.md › Menus / " "panels / chrome strips. Open intent: exclusive + outside/Escape dismiss. " "Disclosure chevron is CSS on the trigger (not Unicode). Mega layout via " "data-dz-layout=mega. dz-navigation-menu.js; " "probes exclusive_open + dismiss_outside. shadcn parity (HMC-039).", tags=("navigation", "interactive"), controller="controllers/dz-navigation-menu.js", contracts=("contracts/navigation_menu.py",), guidance=Guidance( seams=( "`[data-dz-navigation-menu]` / `.dz-navigation-menu` scopes exclusive open", "`details.dz-navigation-menu__branch` + `summary.dz-navigation-menu__trigger`", "Submenu affordance: CSS `::after` chevron on trigger (1rem, rotates open)", "pick-a-surface: top product/site go-to → navigation-menu (not menubar / menu / sidebar)", ), pitfalls=( "Native details allow multi-open and ignore outside click — " "ship dz-navigation-menu.js", "Do not confuse with menubar (app File/Edit) or app-shell sidebar", "Gallery: href=# is product-shaped stand-in; MOCK_HTMX inert-hash " "handler stops host scroll — do not 'fix' Copy this to void(0)", "Do not reintroduce Unicode ▾ spans or 0.65em carets — match " "accordion disclosure chrome (stem affordance-disclosure-chrome)", "do not use navigation-menu for local action lists — that is menu", ), do_dont=( ( "Let the controller close siblings on toggle and outside click", "Leave multi-open mega panels as bare multi-details", ), ( "CSS/SVG disclosure chevron at ~1rem control scale", "Tiny Unicode caret as the only submenu signal", ), ( "top nav with links + optional mega panels (go somewhere)", "File/Edit command strip (menubar) or one Actions dropdown (menu)", ), ), a11y_keys=( "aria-label on root nav", "Keyboard: Enter/Space toggles summary; Escape dismisses open panels", "Chevron is decorative (CSS); details/summary carry expand semantics", ), composes_with=("menubar", "app-shell"), ), ), Hyperpart( "marker", "Marker", "Data", "Map pin chrome + optional label — host owns map projection / placement.", '' '' '' 'HQ' '' '' 'Depot' '' '' 'Alert' "", notes="PLACEHOLDER — shadcn parity (HMC-043). No map SDK. " "Position with host CSS (absolute over a map/plan). Tones via " "data-dz-tone. Dual-lock root .dz-marker (HMC-146).", tags=("media",), contracts=("contracts/marker.py",), ), # ── Navigation / Data ──────────────────────────────────────────── Hyperpart( "breadcrumb", "Breadcrumb", "Navigation", "CSS-generated chevrons; clean list markup.", '' 'Home Invoices' 'INV-0042', notes="Dual-lock root .dz-breadcrumb (HMC-135).", contracts=("contracts/breadcrumb.py",), ), Hyperpart( "accordion", "Accordion", "Navigation", "Native group; single-open via the HTML name= attribute — " "opening one closes its siblings, zero JS.", '' '' 'What is a Hyperpart?' 'A server-rendered partial plus its exchange ' "contract — the htmx-native unit of reuse." '' 'Do I need a client framework?' 'No — state lives on the server and htmx swaps the markup.' '' 'Can two panels be open at once?' 'Not while they share a name=. Drop the attribute for an ' "independent, multi-open group.", notes="Open intent: exclusive via native " "name= on peer <details> " "(stem details-open-intent) — zero JS. Gallery probe " "accordion.exclusive_open. No " "aria-expanded wiring: details/summary carry it. " "Drop name= only when multi-open FAQ is intentional.", tags=("interactive",), contracts=("contracts/accordion.py",), guidance=Guidance( seams=( "`details.dz-accordion__item` + shared `name=` for exclusive group", "`summary.dz-accordion__trigger` — native toggle, no controller", ), pitfalls=( "Missing or mismatched name= → multi-open (not exclusive)", "Do not add exclusive-open JS here — browser name= is the contract", "Do not confuse with tree (multi_open forest) or menubar (controller chrome)", ), do_dont=( ( "Share one name= across peer items for single-open FAQ", "Copy menubar exclusive controller onto accordion panels", ), ), a11y_keys=( "details/summary expose expanded state natively", "Keyboard: Enter/Space on summary", ), composes_with=(), ), ), Hyperpart( "tabs", "Tabs", "Navigation", "A lazy tab strip — an honest link-strip (buttons + aria-current, no " "unkept role=tablist). Each panel hx-gets its content the first time it " "is shown.", '' '' '' '' '' "" '' 'Active on the Pro plan, renewing 1 August.' '' '{svg:loader-circle}' '' '{svg:loader-circle}' "", notes="Taxonomy: tab (__tab button), " "tab list (__list), panel " "(__panel). Stem selection-strip-honest: buttons " "because this is in-page state, not navigation; no role=tablist " "without roving-tabindex/arrows. Active indicator is a square bottom border " "(force border-radius: 0 — base button radius would curve the " "underline). dz-tabs.js + lazy intersect once panels.", tags=("interactive", "htmx"), exchanges=( Exchange( method="GET", endpoint="/app/{region}/{tab}", trigger="a panel, the first time it is revealed (`intersect once`); an eager panel on `load`", response="the panel's content fragment (rows, a form, a chart — whatever the tab shows)", swap="innerHTML of the panel itself (no hx-target)", states=("loading", "populated", "error"), ), ), controller="controllers/dz-tabs.js", contracts=("contracts/tabs.py",), guidance=Guidance( seams=( "tab (`__tab` button) + tab list (`__list`) + panel (`__panel`)", "aria-current marks the selected tab; panels toggle scoped to .dz-tabs", "hidden panels may carry intersect once lazy-load; first panel is eager", ), pitfalls=( "no role=tablist without the roving-tabindex/arrow-key contract — honest buttons", "do not use for in-page panel switches (wrong affordance)", "active underline must stay square — reset border-radius (base button is radius-sm)", "panel reveal is scoped to THIS root so multiple tab sets coexist", ), do_dont=( ( "mark the active tab with aria-current and show its panel", "fake tabs with links that reload the whole page for every panel", ), ( "square active underline (border-radius: 0 on strip tabs)", "inherit base button radius so the brand bar curves at the ends", ), ), a11y_keys=( "Tab reaches each tab button; activation is Enter/Space (button default)", "lazy panels load on first reveal via intersect once", ), composes_with=("button",), ), mock="/mock/tabs", ), Hyperpart( "avatar", "Avatar", "Data", "Initials or image; stacked groups.", '' 'JDAK+3' 'HM', notes="Dual-lock root .dz-avatar (HMC-149).", contracts=("contracts/avatar.py",), ), Hyperpart( "progress", "Progress", "Feedback", "Toned determinate bar.", '' '' '', ), Hyperpart( "skeleton", "Skeleton", "Feedback", "Loading placeholder with a lifecycle-driven sheen (TASTE-9) — drop it " "into a swap target while the request is in flight.", '" '' '' '' '' '' "" '', notes="Dual-lock root is data-dz-skeleton " "(contracts/skeleton.py) on the placeholder stack. Purely " "decorative, so the region is aria-hidden; announce " "“loading” on the live region that owns the swap. Shapes: " "data-dz-shape="text|circle|block". The sheen honours " "prefers-reduced-motion.", contracts=("contracts/skeleton.py",), ), Hyperpart( "empty-state", "Empty state", "Feedback", "Icon + one sentence + primary action — never a bare 'No X'.", '' '' '{svg:inbox}' 'No invoices yet' 'Create your first invoice to get started.' 'New Invoice', notes="Dual-lock root is data-dz-empty-state " "(contracts/empty_state.py). Icon + action markup are host-owned.", contracts=("contracts/empty_state.py",), ), Hyperpart( "code", "Code block", "Primitives", "Fenced code surface with optional language chip and copy control — " "server-emitted chrome for docs and samples. Syntax colour is build-time " "token spans (Python), not a browser highlighter.", '' '' 'python' '" "" '' '' "def greet(name: str) -> str:\n" ' """Return a friendly hello."""\n' ' return f"Hello, {name}"\n' "", notes="Use the code Hyperpart for any fenced sample in docs or app chrome. " "Required nesting: figure.dz-code[data-dz-code] → " "div.dz-code__meta (optional lang + optional copy) → " "pre.dz-code__pre → code.dz-code__source. " "Copy is pushed trailing by CSS (margin-inline-start: auto on the " "button) — do not absolute-position it (nested part-page flex/" "min-width:0 chains left-shift absolute children). " "The gallery builder runs a stdlib highlighter " "(site/highlight.py) for Python and HTML into " "dz-code__tok--* spans; copy uses textContent so " "spans never paste. " "Omit the lang span when there is no language; omit the copy button when " "display-only (keep the meta bar if a lang chip remains). " "Scheme: the surface follows the page theme via " "light-dark() (light code on light pages, dark on dark) — " "not always-dark, so dense docs stay scannable.", tags=("docs",), controller="controllers/dz-code.js", contracts=("contracts/code.py",), guidance=Guidance( seams=( "figure[data-dz-code] → div.dz-code__meta → pre.dz-code__pre > code.dz-code__source", "meta flex row: optional .dz-code__lang, optional [data-dz-code-copy] " "(CSS margin-inline-start:auto keeps copy trailing)", "build-time token spans (.dz-code__tok--*) for Python and HTML colour", "surface uses light-dark() — follows [data-theme], not always-dark", ), pitfalls=( "do not absolute-position .dz-code__copy — it drifts left inside nested " "min-width:0 containers (Hyperpart detail pages); use the meta flex row", "do not put copy/lang as direct children of the figure without .dz-code__meta", "do not ship a browser syntax engine for static docs — highlight at build " "(python + html/svg/xml only today)", "copy must read textContent (not innerHTML) so spans never paste", ), do_dont=( ( "emit figure > .dz-code__meta > (lang? + copy?) > pre > code", "absolute-position the copy control or invent a one-off toolbar", ), ), a11y_keys=( "pre is a keyboard-scrollable region (tabindex=0)", "copy button is a real button with aria-label", ), ), ), # ── Composites (Hyperparts built FROM other Hyperparts) ────────── Hyperpart( "toolbar", "Toolbar", "Composites", "Inline composition — real button, toggle-group and menu markup nested " "in a role=toolbar bar. No client tree, no props: composition is HTML.", '' '' '' 'List' 'Grid' "" # Label is plain text only — open-panel chevron is CSS ::after on # .dz-menu > summary (see components/alert.css). A literal ▾ here # doubles the affordance and looks like a rogue glyph. 'More' '' '' '' "", notes="The dependency chips aggregate what the children need (here: Sprite, " "from the menu/button icons). Copy the whole thing — it is just nested markup. " "Menu trigger labels stay plain text; the open-panel chevron is CSS " "::after (do not append ▾ / ▼ in the summary).", tags=("composite",), composes=("button", "toggle-group", "menu"), contracts=("contracts/toolbar.py",), ), Hyperpart( "master-detail", "Master–detail", "Composites", "Exchange composition — a list item hx-gets its detail card into the " "detail pane. The canonical htmx composite; two can coexist on a page.", '' '" '' "INV-001 · Acme" '' "INV-002 · Globex" '' "INV-003 · Initech" '' 'INV-001 · Acme' '£1,250.00' 'Paid · 2 days ago', notes="The detail pane loads a card fragment via hx-get; dz-master-detail.js " "sets aria-current on the chosen item, scoped to THIS root so two coexist.", tags=("composite", "htmx"), exchanges=( Exchange( method="GET", endpoint="/app/master-detail/{id}", trigger="a list item, on click", response='a detail card fragment — `…`', swap="innerHTML of the sibling `.dz-master-detail__detail` pane", states=("loading", "populated", "error"), ), ), controller="controllers/dz-master-detail.js", contracts=("contracts/master_detail.py",), guidance=Guidance( seams=( "detail pane loads a card fragment via hx-get from the selected item", "aria-current marks the chosen list item, scoped to THIS root", ), pitfalls=( "two master-detail roots must not share aria-current — controller is per-root", "detail content is a server fragment, not a client template", ), do_dont=( ( "hx-get the detail card into the detail pane on item activate", "stash all detail payloads in data-* attributes on every list row", ), ( "replace (`innerHTML`) the detail pane — it is disposable content " "that should fully reset on each selection (decision 0005)", "morph the detail pane by default when focus/edit state must not " "leak across selections (prefer explicit replace)", ), ), a11y_keys=( "aria-current=true on the active list item", "list items remain keyboard-activatable links/buttons", ), composes_with=("card", "list-region"), ), mock="/mock/master-detail", composes=("card",), ), # ── Layout ─────────────────────────────────────────────────────── # The Every-Layout vocabulary as CSS-only Hyperparts: intrinsic, # media-query-free responsiveness. Variants ride data-dz-* attributes; # the consumer-set knobs (--dz-sidebar-width, --dz-grid-min) are # PUBLIC_CSS_PROPS, so they follow the namespace prefix. Hyperpart( "stack", "Stack", "Layout", "Vertical rhythm: children flow top-to-bottom with one gap token. " "The workhorse — most page sections are a stack of stacks.", '' 'One' 'Two' 'Three' "", notes="Flex column + gap — margins stay on the children's " "insides, so any fragment composes without margin-collapse surprises. " "data-dz-gap takes xs|sm|md|lg|xl (the spacing " "token scale); unset = md. Nest freely: a stack inside a " "stack is the normal way to vary rhythm between groups.", tags=("layout",), contracts=("contracts/stack.py",), ), Hyperpart( "cluster", "Cluster", "Layout", "A wrapping horizontal group — buttons, chips, metadata rows. Items " "keep their size and wrap when the line runs out.", '' '' '' 'Draft' "", notes="Flex row + flex-wrap + gap. " "data-dz-gap as on stack. data-dz-align " "(center|start|end|baseline, default center) sets " "cross-axis alignment; data-dz-justify " "(start|end|between|center, default start) distributes " "the line. Never fixes widths — that's what makes it safe for " "translation-length and zoom changes.", tags=("layout",), contracts=("contracts/cluster.py",), ), Hyperpart( "sidebar-layout", "Sidebar", "Layout", "Two panes: a fixed-ish side and a fluid content pane that wraps " "UNDER the side when it would get too narrow — responsive without a " "media query.", '' 'Side (12rem)' 'Content — wraps under the side when ' "narrower than its minimum comfortable width." "", notes="The Every-Layout sidebar: flex + wrap; the side gets " "flex-basis: var(--dz-sidebar-width) (a PUBLIC knob — " "set it inline or at :root), the content gets " "flex-grow: 999 with " "min-inline-size: var(--dz-sidebar-content-min, 50%) — " "when the content can't hold that minimum on the line, it wraps to a " 'full-width row. data-dz-side="end" puts the side ' "after the content. No media query: the breakpoint is the CONTENT'S " "minimum, so the same markup works in a page, a card, or a drawer. " "Dual-lock root .dz-sidebar-layout (HMC-152).", tags=("layout",), contracts=("contracts/sidebar_layout.py",), ), Hyperpart( "auto-grid", "Auto grid", "Layout", "A responsive card grid with no breakpoints: columns pack to fit, " "each at least the minimum width, all equal.", '' 'A B' 'C D' 'E' "", notes="grid-template-columns: repeat(auto-fit, " "minmax(min(var(--dz-grid-min, 14rem), 100%), 1fr)) — the " "inner min() stops overflow when the container is " "narrower than the minimum (the classic auto-fit footgun). " "--dz-grid-min is a PUBLIC knob; gap rides " "data-dz-gap as on stack. Dual-lock root " ".dz-auto-grid (HMC-136).", tags=("layout",), contracts=("contracts/auto_grid.py",), ), Hyperpart( "center", "Center", "Layout", "A measure-capped, centred column — reading width for prose and forms.", '' 'A comfortable reading measure tops out ' "around 65 characters; this block centres itself and caps its width " "so lines stay scannable on any screen." "", notes="margin-inline: auto + max-inline-size. " "data-dz-measure: prose (65ch), " "wide (90ch), full (no cap, still a " "centring context). This is the published form of the measure the " "gallery's own chrome uses. Dual-lock root .dz-center (HMC-137).", tags=("layout",), contracts=("contracts/center.py",), ), Hyperpart( "app-shell", "App shell", "Composites", "The SaaS/admin application frame: persistent left navigation, an " "optional sticky top bar, a routed main workspace, and a " "responsive/collapsible sidebar whose state the server renders.", # The FULL motif (routed navigation, whole sidebar anatomy) lives on # the saas-shell Blueprint; the builder frames this demo (framed=True). '' '' '' 'Acme Ops' '' '' '' '{svg:layout-dashboard}' 'Dashboard' '' '{svg:receipt}' 'Invoices' "" '' '' '' '' '' "" 'Dashboard' '' '" "" # a here, NOT : this demo embeds in the gallery page, # which already has its own (one visible main per document). # In a real app the workspace slot IS — # the saas-shell Blueprint (its own document) shows the true form. '' 'The routed workspace. The hamburger collapses ' "the sidebar; the state persists via a cookie so the server renders it " "correctly on the next request." "", notes="The shell root carries data-dz-sidebar="open|closed" " "— SERVER-rendered from the dz_sidebar cookie, so first " "paint is correct with no flash; dz-app-shell.js flips the " "attribute and re-writes the cookie when " "[data-dz-sidebar-toggle] is clicked (and mirrors " "aria-expanded). Desktop (≥64rem): the sidebar is " "persistent and the content pane pads around it; narrow: it slides " "off-canvas and overlays (this component owns that media query " "deliberately — viewport policy, not intrinsic wrapping — the layout " "primitives inside stay media-query-free). The demo above is a " "standalone page embedded via iframe (its own browsing context, so " "the fixed sidebar behaves exactly as shipped) — the snippet below " "is the pure, copyable " "shell markup, with one embedding concession: the workspace slot is " "a <div> here because this demo lives inside the " "gallery's own <main>; in your app it is " "<main id="main-content"> (one visible " "main per document — the Blueprint shows the true form). The full " "motif — routed " "navigation swapping the main slot — is the " 'saas-shell Blueprint.', tags=("composite", "shell"), controller="controllers/dz-app-shell.js", contracts=("contracts/app_shell.py",), guidance=Guidance( seams=( "root data-dz-sidebar=open|closed is SERVER-rendered from the dz_sidebar cookie", "[data-dz-sidebar-toggle] flips state and rewrites the cookie (1y, SameSite=Lax)", ), pitfalls=( "cookie not localStorage — the server must paint the correct first state", "the component owns the ≥64rem media query (viewport policy); layout primitives stay MQ-free", ), do_dont=( ( "SSR data-dz-sidebar from the cookie so first paint has no flash", "default open in HTML and fix it client-side after load", ), ), a11y_keys=( "toggle mirrors aria-expanded to the open/closed state", "narrow viewports: sidebar overlays; desktop: persistent rail", ), composes_with=("button", "sidebar-layout"), ), framed=True, ), Hyperpart( "status-list", "Status list", "Data", "System / check states as an icon + title + caption list — tone rides " "data-dz-state per row, never colour alone.", '' '' '' '{svg:circle-check}' '' 'Payments API' 'Operational · 99.99% this month' 'positive' '' '{svg:triangle-alert}' '' 'Webhooks' 'Elevated retries since 09:20' 'warning' '' '' '' 'Nightly export' 'Scheduled 02:00' "", notes="Per-row state is data-dz-state on the entry (the " "pill repeats it as text for WCAG 1.4.1); dual-lock root is " "data-dz-status-entry (contracts/status_list.py). " "Vocabulary: neutral / positive / warning / destructive / accent " "(not success). A neutral row has no pill and an icon " "SPACER keeps the text column aligned. The wrapper's " "data-dz-entry-count is the server's row count — " "handy for e2e assertions without counting DOM.", tags=("data",), contracts=("contracts/status_list.py",), ), Hyperpart( "action-grid", "Action grid", "Data", "Tone-tinted CTA cards with a count badge — the dashboard's " "'what needs doing' surface. Cards with a URL are anchors; the grid " "packs intrinsically.", '' '' '' '' '{svg:triangle-alert}' '3' 'Overdue invoices' '' '' '{svg:receipt}' '12' 'Awaiting approval' '' '' '' 'Nothing else today' "", notes="Tone tints the card surface via data-dz-tone and " "the count badge via data-dz-tone-badge. Dual-lock root " "is data-dz-action-card (contracts/action_grid.py). " "A URL makes the card an <a> (whole card = the target); " "without one it renders a static <div>. An icon " "SPACER holds the row height when a card has no icon.", tags=("data",), contracts=("contracts/action_grid.py",), ), Hyperpart( "queue", "Queue", "Data", "The worklist: a count, roll-up metrics, and attention-flagged rows — " "the triage surface for SLA-driven work.", '' '' '7open items' '' '' '2' 'breaching today' '' '4h' 'median age' '' '' '' '' 'Refund request — Acme' 'SLA breaches at 16:00 — assign now.' '2h left' '' '' '' 'KYC review — Globex' 'due tomorrow' "", notes="Dual-lock root is data-dz-queue-row " "(contracts/queue.py). Attention rows also carry " "data-dz-attn plus a human message " "(dz-queue-row-attn) — the flag is never colour-only. " "Counts and metrics are SERVER-rendered rollups (the same query " "that produced the rows, so they can't disagree).", tags=("data",), contracts=("contracts/queue.py",), ), Hyperpart( "kanban", "Kanban", "Data", "Status columns of cards — the flow view. Columns show a count; " "overflowing boards offer a server-rendered Load-all.", # tabindex=0 + role=region: overflow-x:auto is intentional (columns # scroll horizontally). After the gallery main track was constrained # (minmax(0,1fr)), the board actually scrolls and axe requires keyboard # access to the scrollable region (scrollable-region-focusable). # Linear-class rearrange demo (gallery mock): mutator board only. # /mock/kanban/* is offline demo — product hosts stamp the same # attrs only when UPDATE is permitted (see agent Server exchange). '' '' '' '' 'Open' '2' '' '' '' 'Refund request — Acme' '£1,250 · assigned to Ada' 'SLA breaches at 16:00' '' 'Move card' '" "" '' '' 'KYC review — Globex' 'due tomorrow' '' 'Move card' '" "" '' '' 'In progress' '1' '' '' '' 'Chargeback — Initech' 'evidence uploaded' '' 'Move card' '" "" '' '' '' '{svg:circle-check}Done' '0' '' 'Nothing here yet.' "", notes="Cards are SERVER-rendered — dual-lock root is " "data-dz-kanban-card (contracts/kanban.py). " "Linear-class rearrange: when the host stamps " 'data-dz-kanban-rearrange="status" (UPDATE only), ' "dz-kanban.js moves cards via PUT (envelope none) then " "GET-refresh of data-dz-kanban-src with " "outerMorph/outerHTML of the region " "(prefer morph so the announce live-region identity survives); " "per-card data-dz-allowed-to lists legal edges. " "Read-only boards omit rearrange attrs entirely. Gallery " "/mock/kanban/* is demo-only. Attention text carries " "data-dz-attn (critical/warning/notice).", tags=("data", "interactive", "htmx"), contracts=("contracts/kanban.py",), controller="controllers/dz-kanban.js", # Controller uses raw fetch (not hx-* on the partial). Declaring # the board attrs + Exchange table is the agent-visible swap contract. exchanges=( Exchange( method="PUT", endpoint="/api/{entity}/{id}", trigger="dz-kanban.js: drag-drop onto a column stack or change " "`select[data-dz-kanban-move]` when the host stamped " "`data-dz-kanban-rearrange` (UPDATE only). Raw `fetch` PUT — " "not an htmx attribute on the card", response="this is the entity's STANDARD update route: JSON body " "includes the status field named by `data-dz-kanban-status-field` " '(e.g. `{"status": "in_progress"}`) and, when ' "`data-dz-kanban-rank-field` is set, the rank key for in-column " "order (midpoint between neighbours). Server MUST re-validate SM " "edges and permissions — client `data-dz-allowed-to` is a hint. " "Return 2xx JSON on success; non-2xx aborts the optimistic move " "and the board reverts on the following GET refresh failure path", swap="none (raw fetch) — controller then GETs `data-dz-kanban-src` " "to re-render the board from the server (same bulk-refresh pattern " "as grid PUT + `dz-grid:refresh`)", states=("populated", "error"), envelope="none", server_example=( "# FastAPI sketch — product entity update (not a kanban-only API)\n" "@router.put('/api/tickets/{ticket_id}')\n" "async def update_ticket(\n" " ticket_id: str,\n" " body: TicketUpdate, # status + optional rank fields\n" " user: User = Depends(current_user),\n" ") -> TicketOut:\n" " # gate UPDATE; validate status transition (SM);\n" " # persist rank when present; return JSON entity\n" " ...\n" ), ), Exchange( method="GET", endpoint="/api/workspaces/{ws}/regions/{region}", trigger="after a successful PUT move, `dz-kanban.js` fetches " "`data-dz-kanban-src` (the workspace region URL the host stamped). " "Also used when a host otherwise refreshes the region", response="the full kanban region fragment: root " "`[data-dz-kanban-board]` (or host region wrapper) with columns, " "stacks, and server-rendered cards (dual-lock " "`data-dz-kanban-card`). Counts and order come from the server — " "do not return a single card as the board settle. Empty columns " "keep the stack + empty state markup", swap="outerMorph / outerHTML of the region root (or innerMorph of " "the board host if the host keeps a stable outer region shell). " "Prefer morph so announce live-region identity survives", states=("loading", "empty", "populated", "error"), envelope="outer", server_example=( "# Region GET — same endpoint the workspace uses for the board\n" "@router.get('/api/workspaces/{ws}/regions/{region}')\n" "async def region_html(ws: str, region: str) -> HTMLResponse:\n" " # render SSR kanban board for current filters/persona\n" " return HTMLResponse(board_html)\n" ), ), ), guidance=Guidance( seams=( "rearrange: host stamps data-dz-kanban-rearrange=status only when " "UPDATE is permitted — never CSS-only drag", "per-card data-dz-allowed-to lists manual SM edges; empty = not draggable", "PUT entity update then GET data-dz-kanban-src (region refresh) — " "same bulk-refresh pattern as the grid", "keyboard: select[data-dz-kanban-move] offers the same targets as drag", "swap contract: PUT envelope=none (JSON); GET envelope=outer " "(full board/region fragment) — see Swap contract section", ), pitfalls=( "do not invent a second rearrange API — reuse entity UPDATE + SM validation", "do not stamp rearrange attrs for read-only personas (chrome leak)", "do not use dashboard personal-layout drag as the product model", "client allowed_to is a hint — server re-validates every drop", "do not return a single card HTML as the POST/PUT swap — settle via region GET", "do not claim presentation-only when rearrange attrs are stamped — " "declare the PUT+GET exchanges", ), do_dont=( ( "gate rearrange chrome on UPDATE like queue transitions", "show grab cursors for everyone and 403 on drop", ), ( "refresh the board from the region endpoint after PUT", "optimistically reorder the DOM without a server settle", ), ( "document PUT none + GET outer in the swap contract", "leave Server exchange as n/a while the controller fetches", ), ), a11y_keys=( "Move select is keyboard parity for drag", "aria-live announce region reports move result", "title hub drills stay clickable — drag starts off links/controls", ), composes_with=("queue",), ), ), Hyperpart( "timeline", "Timeline", "Data", "Dated events on a vertical line — bullets carry the attention " "contract, dates keep a fixed column so titles align.", '' '' '' '' '' '' 'Today' '' 'Payment failed — retry scheduled' 'Card declined (insufficient funds)' "" '' '' '' '' 'Mon' '' 'Invoice sent' "" "", notes="Dual-lock root is data-dz-timeline-item " "(contracts/timeline.py). The bullet is an inline SVG " "on currentColor, toned by dz-attn-tone-* " "(critical/warning/notice/default). Overflowing timelines append a " "dz-timeline-overflow count line.", tags=("data",), contracts=("contracts/timeline.py",), ), Hyperpart( "activity-feed", "Activity feed", "Data", "Who-did-what rows on a dotted spine — actor, time, and a message bubble.", '' '' '' '' '' '' '09:41' '' 'Ada approved the refund.' "" '' '' '' '' '09:12' '' 'System flagged the account ' "for review." "", notes="Dual-lock root is data-dz-activity-row " "(contracts/activity_feed.py). Rows are server-rendered " "newest-first; an empty feed renders dz-activity-empty. " "The dot column and bubble keep alignment without a grid — the row " "is the flex unit.", tags=("data",), contracts=("contracts/activity_feed.py",), ), Hyperpart( "related-tables", "Related records", "Data", "A detail view's companions: tabbed groups of related records — " "status cards, a compact table, or a file list — each tab counted.", '' '' '' '' '' "" '' '' '' '' '' 'INV-001 · £1,250' 'due 12 Jul' '' 'Paid' "" '' '' '' 'INV-002 · £980' 'due 28 Jul' '' '' '{svg:triangle-alert}Overdue' "" '' '' '' '' '' 'contract.pdf' 'uploaded 3 Jul' "" "", notes="One dz-related-group per related entity. The tab " "strip IS the tabs Hyperpart (dz-tabs__tab + " "data-dz-tab-target, driven by dz-tabs.js) with a " "related-specific count chip; panels are native-hidden " "toggles. Three body shapes share the chrome: the status-card grid " "(shown), a compact dz-related-table, and a " "dz-related-file-list. In Dazzle these render from the " "detail view's related groups — the same shared cell core as list " "rows, so badges/dates match.", tags=("data",), composes=("tabs", "badge"), contracts=("contracts/related_group.py",), ), Hyperpart( "metrics", "Metric tiles", "Data", "The KPI strip: label + value tiles in a packing grid, optionally " "toned. The server stamps the tile count for e2e anchors.", '' '' 'Outstanding' '£12,450' '' 'Paid this month' '£48,900' '' 'Overdue' '3' "", notes="Each tile carries data-dz-metric-key (dual-lock " "root; contracts/metrics.py) and an optional " "data-dz-tone. In Dazzle one scope-aware GROUP BY query " "fills the whole strip — the tiles can never disagree with each other.", tags=("data", "chart"), contracts=("contracts/metrics.py",), ), Hyperpart( "sparkline", "Sparkline", "Data", "A headline number with its recent shape — the smallest chart: a " "current value, its bucket label, and an area glyph.", '' '' '184ms' 'this hour' '", notes="Dual-lock root is data-dz-sparkline " "(contracts/sparkline.py). Headline stacks above the " "glyph. SVG uses preserveAspectRatio=none so the trend fills the " "host width. aria-label carries points/latest/peak. Empty → " "dz-sparkline-empty; single point → headline only.", tags=("data", "chart"), contracts=("contracts/sparkline.py",), ), Hyperpart( "funnel", "Funnel", "Data", "Stage-by-stage narrowing — each bar's width is the stage's share, " "with a total summary line.", '' '' '' '' 'Visited' ' (1,204)' '' '' 'Signed up' ' (746)' '' '' 'Subscribed' ' (338)' "" '1,204 total' "", notes="Dual-lock root is data-dz-funnel " "(contracts/funnel.py). Widths are SERVER-computed " "percentages on inline style — the one place inline style is the " "contract (a per-row datum, like the progress knob). " "data-dz-funnel-step tones the stages in sequence.", tags=("data", "chart"), contracts=("contracts/funnel.py",), ), Hyperpart( "bar-chart", "Bar chart", "Data", "Label / track / value rows — the workhorse categorical chart, " "server-computed and scope-safe.", '' '' '' 'API' '' '' '126' '' 'Dashboard' '' '' '84' '' 'Billing' '' '' '35' "", notes="Dual-lock root is data-dz-bar-chart " "(contracts/bar_chart.py). In Dazzle every bar chart " "compiles to ONE scope-aware GROUP BY — the bucket " "list and the counts come from the same query, so they cannot " "disagree (the #847-class bug this design retired). Fill widths " "are server-computed percentages of the max bucket.", tags=("data", "chart"), contracts=("contracts/bar_chart.py",), ), Hyperpart( "chart-legend", "Chart legend", "Data", "The shared tail of every multi-series chart: swatch + series-name " "chips and a sample/series summary line.", '' '' '' '' 'Revenue' '' '' 'Costs' "" '12 buckets · 2 series · peak £48,900' "", notes="Every SVG chart (line / area / radar / box-plot) ends with " "this pair instead of restyling it per chart: a " "<ul> of swatch + mono series-name items, and a " "mono summary line of bucket/series counts and the peak. The swatch " "background is the series colour the chart body uses for its " "strokes — inline, per series, server-assigned. Dual-lock root " ".dz-chart-legend (HMC-142).", tags=("data", "chart"), contracts=("contracts/chart_legend.py",), ), Hyperpart( "radar", "Radar", "Data", "Polar multi-axis profile — spokes share a scale; the polygon is server-rendered SVG.", '' '' '5 spokes · 1 series · peak 90' "", notes="Dual-lock root is data-dz-radar " "(contracts/radar.py). Geometry rides trusted " "svg_html from dazzle.render.svg.radar_svg; " "the summary carries spoke count and peak.", tags=("data", "chart"), contracts=("contracts/radar.py",), ), Hyperpart( "time-series", "Time series", "Data", "Line or area sequential chart — one series of (label, value) points, " "or multi-series overlays with a shared legend.", '14 buckets · peak 91', notes="Dual-lock root is data-dz-time-series " "(contracts/time_series.py). Wrapper class stays " "view-specific (dz-line-chart-region / " "dz-area-chart-region). Multi-series charts append a " "trusted legend; SVG geometry comes from " "dazzle.render.svg.time_series_svg.", tags=("data", "chart"), contracts=("contracts/time_series.py",), ), Hyperpart( "heatmap", "Heatmap", "Data", "A two-dimensional grid of toned cells — rows × buckets, thresholds " "driving good/warn/bad tones, never colour alone (the value is IN " "the cell).", '' '' '' "" "" '' '' '' '' "" '' '' '' '' " Mon Tue Wed API 99.9 99.7 97.2 Webhooks 96.1 89.4 99.2 ", notes="Dual-lock root is data-dz-heatmap " "(contracts/heatmap.py). Cell tones ride " "data-dz-heatmap-tone="good|warn|bad", resolved " "server-side against the declared thresholds — and the numeric value " "always renders inside the cell, so tone is reinforcement, not the " "only signal. Overflowing grids append a " "dz-heatmap-overflow count line; the scroll wrapper keeps " "wide grids inside their card.", tags=("data", "chart"), contracts=("contracts/heatmap.py",), ), Hyperpart( "bullet", "Bullet chart", "Data", "Actual vs target on qualitative bands — the KPI-with-context bar. " "All geometry is server-computed inline percentages.", '' '' '' 'Revenue' '' '' '' '' '' '' "" '72 / 80' "" '1 rows · scale 0–100' "", notes="Dual-lock root is data-dz-bullet " "(contracts/bullet.py). Bands, the actual bar, and the " "target tick are absolutely positioned by SERVER-computed inline " "percentages (per-row data, the same contract as the funnel widths); " "each carries a title with its numeric range. Band fills " "come from the server's reference-band colour map. The value (and " "target, when set) renders as text beside the track; the mono summary " "line carries row count and scale.", tags=("data", "chart"), contracts=("contracts/bullet.py",), ), Hyperpart( "pivot", "Pivot table", "Data", "Two group-bys crossed into a matrix — row labels × column buckets, " "empty intersections rendered as explicit nulls.", '' '' '' "" '' "" "" '' '' "" '' '' "System Severity Count API ' '{svg:circle-x}Critical 3 Dashboard — 9" '2 rows' "", notes="Dual-lock root is data-dz-pivot " "(contracts/pivot.py). One scope-aware two-dimensional " "GROUP BY fills the whole matrix: dimension columns " "lead (status values render as badges, FK values as their label " "text), then measure columns — " "class="is-measure" on the measure th/td pair " "drives the mono right-aligned numeric treatment. Empty " "intersections render dz-pivot-null em-dashes rather " "than blanks (absence is data). The scroll wrapper keeps wide " "matrices inside their card. Cell HTML is host-trusted SSR so " "badges stay on the Dazzle side.", tags=("data", "chart"), contracts=("contracts/pivot.py",), ), Hyperpart( "bar-track", "Bar track", "Data", "Value-against-capacity rows with real progressbar semantics — the " "resource-usage sibling of the bar chart.", '' '' '' 'Storage' '' '' '62%' '' 'Compute' '' '' '38%' "" '2 rows0–100' "", notes="Dual-lock root is data-dz-bar-track " "(contracts/bar_track.py). Each track is a real " "role="progressbar" with numeric aria values " "— the fill width is presentation, the aria is the content. Labels " "and fills both carry title for hover detail.", tags=("data", "chart"), contracts=("contracts/bar_track.py",), ), Hyperpart( "histogram", "Histogram", "Data", "Value-distribution buckets as a server-rendered SVG plus a mono summary line.", '' '" '6 buckets · 120 samples' "", notes="Dual-lock root is data-dz-histogram " "(contracts/histogram.py). The SVG body is " "SERVER-computed (this demo is schematic — the real geometry comes " "from dazzle.render.svg.histogram_svg) with the numeric " "story in aria-label and the mono summary line. Bin " "geometry rides trusted svg_html so HM need not import " "Dazzle SVG helpers.", tags=("data", "chart"), contracts=("contracts/histogram.py",), ), Hyperpart( "box-plot", "Box plot", "Data", "Distribution five-number summaries per bucket — a server-rendered " "SVG with the counts in the summary line.", '3 groups · 282 samples', notes="Dual-lock root is data-dz-box-plot " "(contracts/box_plot.py). Schematic demo — real " "whisker/quartile geometry is server-computed via " "dazzle.render.svg.box_plot_svg and rides trusted " "svg_html. The summary line carries group count and " "sample total.", tags=("data", "chart"), contracts=("contracts/box_plot.py",), ), Hyperpart( "progress-region", "Progress stages", "Data", "A native progress bar with stage chips — where the work is, stage " "by stage, with completion tones.", '' '' '' "33%" "" '' 'Draft (4)' 'Review (2)' 'Published (0)' "" '1 of 3 complete' "", notes="Dual-lock root is data-dz-progress-region " "(contracts/progress.py). The bar is a NATIVE " "<progress> (styled via " "data-dz-progress) with its percent readout as a plain " "<span> beside it in the header; chips are plain " "text (Name (count)) toned by " "data-dz-stage-tone="complete|active|empty"; " "the summary paragraph follows the stages.", tags=("data",), contracts=("contracts/progress.py",), ), Hyperpart( "profile-card", "Profile card", "Data", "The identity panel: avatar or initials beside name and meta, a " "KPI stats strip (value above label), and optional facts.", '' '' '' 'MR' '' 'Maya Reyes' 'Operations lead · North grid' "" '' '' 'Orders' '7' '' 'Sites' '3' '' 'On call' '—' "" '' '' '·' 'Certified for HV switching' '' '·' 'Joined March 2024' "", notes="Dual-lock root is data-dz-profile-card " "(contracts/profile_card.py). Avatar prefers " "<img class="dz-profile-avatar">, else " "initials; empty stats render an em-dash. Stats are a real " "<dl> KPI strip — value above label, " "auto-fit columns (not a fixed 3-col table). Prefer " "short labels; longer ones wrap under the number. Facts bullets " "are decorative and hidden from assistive tech.", tags=("data",), contracts=("contracts/profile_card.py",), ), Hyperpart( "grid-list", "Cell grid", "Data", "A responsive grid of plain record cells — title plus label: value " "lines, 1 → 2 → 3 columns as the container widens.", '' '' '' 'Aurora Substation' '' 'Region: North' '' 'Load: 82%' "" '' 'Beacon Substation' '' 'Region: East' '' 'Load: 47%' "" '' 'Cinder Substation' '' 'Region: West' '' 'Load: 91%' "" "", notes="Cells are deliberately chrome-free — the surrounding card " "owns borders and title. The column count is a viewport response " "(1 column, then 2 at 40rem, 3 at 64rem). The " "is-clickable hover/cursor affordance is styled but " "currently a LEGACY reserve — the substrate grid emitter does not " "yet wire cell drill URLs (follow-up on the Dazzle side). Dual-lock " "root .dz-grid-list (HMC-144).", tags=("data",), contracts=("contracts/grid_list.py",), ), Hyperpart( "list-region", "List region", "Data", "The in-card data table: CSV export, sortable headers, a scrollable " "table body, and an overflow count.", # Gallery: sort headers hx-get the mock list-region (server owns # ORDER BY); CSV downloads sample-list-export.csv via dz.downloadCsv. '' '' '' '' "" '' '' "" '' '' '' "" "" '' "" '' "" '' "" '' "" '' "" "Name▲ Owner Status Capacity review J. Dias Active Load study K. Novak Draft Quarterly audit M. Reyes Active Site walkdown M. Reyes Closed Vendor renewal A. Osei Draft" 'Showing 5 of 5' "", notes="Dual-lock root is data-dz-list-region " "(contracts/list_region.py). CSV export is wired with " "data-dz-csv-endpoint + data-dz-csv-filename " "and window.dz.downloadCsv (gallery serves " "sample-list-export.csv as the downloadable artifact). " "Sortable headers are dz-list-sort-link anchors with " "hx-get ?sort=&dir= — the host re-renders the " "region; the active column shows a caret. Rows with a drill URL " "carry is-clickable. For selection/filters/pagination " "use the grid Hyperpart.", tags=("data",), contracts=("contracts/list_region.py",), exchanges=( Exchange( method="GET", endpoint="/mock/list-region", trigger="click on a sort header", response=( "Full list-region outerHTML reordered by ?sort=&dir=; " "active column caret ▲/▼" ), swap="closest [data-dz-list-region] outerHTML", envelope="outer", states=("populated",), ), Exchange( method="GET", endpoint="sample-list-export.csv", trigger="click Export CSV (via dz.downloadCsv)", response="text/csv file body (download, not a DOM swap)", swap="n/a — Blob download", envelope="none", states=("populated", "error"), ), ), ), Hyperpart( "task-inbox", "Task inbox", "Data", "The personal worklist: filter chips over urgency-flagged items, " "each a drill link with title and meta.", '' '' '' '' '6' 'All' '' '2' 'Overdue' "" '' '' '' '{svg:inbox}' '' 'Approve refund — Acme' 'due in 2h · assigned to you' "" '' '' '{svg:inbox}' '' 'Review KYC — Globex' 'due tomorrow' "" "", notes="Dual-lock root is data-dz-task-inbox " "(contracts/task_inbox.py) on the region. Items carry " "data-dz-urgency="overdue|due|soon|later" " "(the server clamps anything else to later) + a stable " "data-dz-item-id; the whole row is one link, leading " "with its icon. Chips render count THEN label " "(data-dz-chip-id anchors a filter exchange in Dazzle).", tags=("data",), contracts=("contracts/task_inbox.py",), ), Hyperpart( "tree", "Tree", "Data", "Hierarchy on native / for branches; leaves are " "plain rows. Chevron is CSS chrome (not summary content). No JS.", '' '' '' '' 'Engineering' '2' "" '' # Two sibling branches (multi_open probe) each with leaf children. '' '' 'Platform' '1' "" '' '' 'Build tooling' "" "" '' '' 'Design systems' '1' "" '' '' 'Tokens' "" "" "" "", notes="Open intent: multi_open " "(stem details-open-intent) — sibling branches stay " "open; do not add exclusive-open. Dual-lock root " "data-dz-tree (contracts/tree.py). " "Summary holds content (label + count); the rotating chevron is " "CSS ::before on " ".dz-tree-node:has(> .dz-tree-children) — never an " "SVG/span in the summary. Leaves are .dz-tree-leaf " "(no expand affordance). Count chip only when children exist. " "Gallery probe tree.multi_open (scope " ".hm-preview).", tags=("data",), contracts=("contracts/tree.py",), guidance=Guidance( seams=( "`[data-dz-tree]` / `.dz-tree` forest root (dual-lock)", "`details.dz-tree-node` + `summary.dz-tree-summary` for branches " "(label + count only; chevron is CSS)", "`.dz-tree-leaf` for nodes with no children", ), pitfalls=( "Do not put chevron SVG/span in the summary — disclosure chrome " "belongs in CSS (::before on branches)", "Do not wrap leaves in empty — that still shows a " "rotating arrow UX with nothing to expand", "Do not ship exclusive-open or name= exclusivity on tree peers", "Gallery may mount a second forest under .hm-contract-live__preview — " "interaction checks use .hm-preview only", "Not menubar/nav chrome — no outside-dismiss controller", ), do_dont=( ( "Leave multi-open native details for sibling branches; " "emit leaves as .dz-tree-leaf", "Port dz-menubar exclusive-open onto the tree forest; " "or put chevron markup in every summary", ), ), a11y_keys=( "Native details/summary expand/collapse", "Keyboard: Enter/Space on summary", ), composes_with=(), ), ), Hyperpart( "diagram", "Diagram", "Data", "A horizontal-scroll wrapper for server-emitted Mermaid source — " "the library replaces the with rendered SVG.", '' '' "erDiagram\n" " CUSTOMER ||--o{ ORDER : places\n" " ORDER ||--|{ LINE_ITEM : contains" "" "", notes="Dual-lock root is data-dz-diagram " "(contracts/diagram.py). The gallery part page loads " "Mermaid from a CDN module (build_site gallery-only bootstrap) so " "the live demo renders SVG the same way Dazzle does when the host " "emitter appends the Mermaid loader. The library swaps the " "<pre class=mermaid> for SVG at runtime — source " "styling only matters for the initial paint flash. The wrapper owns " "overflow; dz-diagram-empty is the no-data paragraph.", tags=("data",), contracts=("contracts/diagram.py",), ), # ── Primitives ─────────────────────────────────────────────────── Hyperpart( "separator", "Separator", "Primitives", "A hairline divider on the border token — horizontal (``) or " "vertical (`role=separator`).", '' 'Account details' '' 'Billing and invoices' '' 'Draft' '' 'Published' '' 'Archived' "", notes="The horizontal rule is a native <hr> (implicitly " "role=separator); the vertical divider is a zero-width element with an " "explicit role=separator + aria-orientation="vertical". " "Dual-lock root .dz-separator (HMC-138).", contracts=("contracts/separator.py",), ), Hyperpart( "icon", "Icon", "Primitives", "Inline SVG from a vendored Lucide registry — currentColor, decorative " "by default. Shown here as the sprite form (one sheet per page).", '' '' '' '' '' '' "", notes="Two delivery forms, one registry. Sprite " '(<svg class="icon"><use href="#name"/></svg>) ' "is short and legible but needs the icon sheet inlined once per page — " "use it when an icon repeats. Inline (the full " "<svg> with path data) is self-contained — use it when " "you want no sheet dependency. Both inherit text colour via " "currentColor and are aria-hidden by default; " "pass a label for a meaningful, non-decorative icon. Sizes: " "icon--size-xs … icon--size-xl.", tags=("icon", "svg", "sprite", "a11y"), ), ] )

Delete workspace?

Filters

Record detail

No invoices yet

Refund request — Acme

KYC review — Globex

Chargeback — Initech

Maya Reyes

Aurora Substation

Beacon Substation

Cinder Substation