@krizaka/ui 3.72.0 → 3.74.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -4
- package/dist/{RotatingWord-COSabR2c.d.ts → RotatingWord-D3tpDLE4.d.ts} +1 -1
- package/dist/account-menu.d.ts +1 -1
- package/dist/account-menu.js +1 -1
- package/dist/account-settings.d.ts +1 -1
- package/dist/account-settings.js +1 -1
- package/dist/app-frame.d.ts +2 -5
- package/dist/avatar/defaults.d.ts +2 -2
- package/dist/avatar/defaults.js +1 -5
- package/dist/avatar/defaults.js.map +1 -1
- package/dist/{avatar-B_na7r1U.d.ts → avatar-CNV6ld8l.d.ts} +2 -2
- package/dist/avatar.d.ts +2 -2
- package/dist/avatar.js +1 -5
- package/dist/avatar.js.map +1 -1
- package/dist/blocks.css +4 -4
- package/dist/chat.js +1 -1
- package/dist/{chunk-5MPPIGCB.js → chunk-E46AEUPH.js} +1 -5
- package/dist/chunk-E46AEUPH.js.map +1 -0
- package/dist/{chunk-GRVIZTT2.js → chunk-GSQRSWOE.js} +2 -2
- package/dist/{chunk-TISDOZH3.js → chunk-IOTY5HYG.js} +1 -5
- package/dist/chunk-IOTY5HYG.js.map +1 -0
- package/dist/{chunk-T5NZSKWT.js → chunk-KF7UB3LM.js} +29 -34
- package/dist/chunk-KF7UB3LM.js.map +1 -0
- package/dist/chunk-PGPNYYE2.js +286 -0
- package/dist/chunk-PGPNYYE2.js.map +1 -0
- package/dist/{chunk-Y5YBTHVD.js → chunk-SG3QJJXE.js} +6 -12
- package/dist/chunk-SG3QJJXE.js.map +1 -0
- package/dist/{chunk-4JO5GSSD.js → chunk-VA4NPCUQ.js} +2 -2
- package/dist/chunk-VA4NPCUQ.js.map +1 -0
- package/dist/collection-switcher.d.ts +1 -1
- package/dist/data-table.js +2 -2
- package/dist/{default-avatar-BL0nJFti.d.ts → default-avatar-Bh4atFDo.d.ts} +2 -2
- package/dist/elephant.d.ts +2 -2
- package/dist/elephant.js +2 -3
- package/dist/elephant.js.map +1 -1
- package/dist/engine-flow.js +29 -21
- package/dist/engine-flow.js.map +1 -1
- package/dist/entity-header.d.ts +1 -1
- package/dist/filter-bar.js +1 -1
- package/dist/genui.js +2 -2
- package/dist/index.d.ts +7 -51
- package/dist/index.js +2 -12
- package/dist/index.js.map +1 -1
- package/dist/language-switch.d.ts +9 -9
- package/dist/map.js +0 -120
- package/dist/map.js.map +1 -1
- package/dist/match-dialog.js +1 -1
- package/dist/media-grid.d.ts +2 -2
- package/dist/media-grid.js +1 -1
- package/dist/motion.css +2 -95
- package/dist/motion.d.ts +1 -1
- package/dist/motion.js +1 -1
- package/dist/native/map.js +0 -120
- package/dist/native/map.js.map +1 -1
- package/dist/native.d.ts +7 -59
- package/dist/native.js +920 -1272
- package/dist/native.js.map +1 -1
- package/dist/nav-bar.d.ts +1 -1
- package/dist/nav-bar.js +2 -2
- package/dist/rail-nav.d.ts +2 -5
- package/dist/retro-tv-playlist.d.ts +148 -0
- package/dist/retro-tv-playlist.js +234 -0
- package/dist/retro-tv-playlist.js.map +1 -0
- package/dist/retro-tv.js +4 -160
- package/dist/retro-tv.js.map +1 -1
- package/dist/site-cahier.d.ts +3 -11
- package/dist/site-cahier.js +126 -367
- package/dist/site-cahier.js.map +1 -1
- package/dist/site-footer.d.ts +1 -1
- package/dist/site-footer.js +2 -2
- package/dist/{sites-CEnywB89.d.ts → sites-CVNSirrg.d.ts} +3 -11
- package/dist/sites.d.ts +7 -15
- package/dist/sites.js +4 -10
- package/dist/sites.js.map +1 -1
- package/dist/tag-selector.js +12 -11
- package/dist/tag-selector.js.map +1 -1
- package/dist/vertical-video.js +1 -1
- package/package.json +17 -34
- package/registry/account-menu.json +4 -2
- package/registry/account-settings.json +4 -2
- package/registry/achievement.json +4 -2
- package/registry/action-bar.json +4 -2
- package/registry/action-sheet.json +2 -0
- package/registry/activity-feed.json +4 -2
- package/registry/agenda.json +4 -2
- package/registry/alert.json +4 -2
- package/registry/analysis-report.json +4 -2
- package/registry/anatomy-plate.json +4 -2
- package/registry/app-frame.json +9 -39
- package/registry/app-header.json +4 -2
- package/registry/app-shell.json +4 -2
- package/registry/argument-card.json +4 -2
- package/registry/audio-player.json +4 -2
- package/registry/auth-layout.json +4 -2
- package/registry/avatar.json +5 -3
- package/registry/badge.json +4 -2
- package/registry/bird-plate.json +4 -2
- package/registry/button.json +4 -2
- package/registry/captcha.json +4 -2
- package/registry/card-grid.json +4 -2
- package/registry/card.json +4 -2
- package/registry/catalogue-page.json +4 -2
- package/registry/changelog-page.json +4 -2
- package/registry/chapter.json +4 -2
- package/registry/chat.json +4 -2
- package/registry/checkbox.json +4 -2
- package/registry/chip-link.json +4 -2
- package/registry/chip-row.json +4 -2
- package/registry/chip.json +4 -2
- package/registry/choice-grid.json +4 -2
- package/registry/cn.json +2 -0
- package/registry/code-block.json +4 -2
- package/registry/collection-switcher.json +4 -2
- package/registry/combobox.json +4 -2
- package/registry/command.json +4 -2
- package/registry/comparison-table.json +4 -2
- package/registry/component-page.json +4 -2
- package/registry/confirm-button.json +4 -2
- package/registry/contact-page.json +4 -2
- package/registry/continue-prompt.json +4 -2
- package/registry/copy-button.json +4 -2
- package/registry/countdown.json +4 -2
- package/registry/cover-hero.json +4 -2
- package/registry/cta-panel.json +4 -2
- package/registry/dashboard-layout.json +4 -2
- package/registry/data-table.json +4 -2
- package/registry/date-picker.json +4 -2
- package/registry/decision-list.json +4 -2
- package/registry/description-list.json +4 -2
- package/registry/desktop-window.json +5 -3
- package/registry/detail-layout.json +4 -2
- package/registry/dialog.json +4 -2
- package/registry/docs-article-page.json +4 -2
- package/registry/docs-hub-page.json +4 -2
- package/registry/docs-layout.json +4 -2
- package/registry/docs-nav.json +4 -2
- package/registry/document-viewer.json +4 -2
- package/registry/doodle.json +4 -2
- package/registry/drop-overlay.json +4 -2
- package/registry/dropdown-menu.json +4 -2
- package/registry/elephant.json +6 -6
- package/registry/embed-facade.json +4 -2
- package/registry/empty-state.json +4 -2
- package/registry/engine-flow.json +5 -4
- package/registry/entity-header.json +4 -2
- package/registry/environment-notice.json +4 -2
- package/registry/error-page.json +4 -2
- package/registry/examples/media-grid/feed.js +3 -4
- package/registry/examples/media-grid/feed.tsx +3 -4
- package/registry/examples/media-grid/uniform.js +2 -2
- package/registry/examples/media-grid/uniform.tsx +2 -2
- package/registry/fab.json +2 -0
- package/registry/field.json +4 -2
- package/registry/file-upload.json +4 -2
- package/registry/filter-bar.json +5 -3
- package/registry/flock.json +4 -2
- package/registry/footnote.json +4 -2
- package/registry/force-update-screen.json +4 -2
- package/registry/form-flow.json +3 -1
- package/registry/form.json +4 -2
- package/registry/gallery-page.json +4 -2
- package/registry/genui.json +4 -2
- package/registry/glossary-term.json +4 -2
- package/registry/glossary.json +4 -2
- package/registry/glow-card.json +4 -2
- package/registry/goal-gauge.json +4 -2
- package/registry/grade-stamp.json +4 -2
- package/registry/grid.json +2 -0
- package/registry/header.json +2 -0
- package/registry/how-it-works-page.json +4 -2
- package/registry/image-cropper.json +4 -2
- package/registry/image-viewer.json +2 -0
- package/registry/index.json +18 -78
- package/registry/kanban.json +4 -2
- package/registry/kbd.json +4 -2
- package/registry/kind-config-editor.json +4 -2
- package/registry/kpi-explained.json +4 -2
- package/registry/landing-page.json +4 -2
- package/registry/landscape.json +4 -2
- package/registry/language-switch.json +4 -2
- package/registry/legal-page.json +4 -2
- package/registry/link-card.json +4 -2
- package/registry/list-detail.json +2 -0
- package/registry/list.json +4 -2
- package/registry/loader.json +4 -2
- package/registry/longform-page.json +4 -2
- package/registry/maintenance-screen.json +4 -2
- package/registry/map.json +5 -3
- package/registry/margin-layout.json +4 -2
- package/registry/markdown.json +4 -2
- package/registry/marketing-layout.json +4 -2
- package/registry/marquee.json +4 -2
- package/registry/mascot-quote.json +4 -2
- package/registry/mascot-state.json +4 -2
- package/registry/mascots.json +4 -2
- package/registry/match-dialog.json +5 -3
- package/registry/media-capture.json +4 -2
- package/registry/media-gallery.json +4 -2
- package/registry/media-grid.json +7 -5
- package/registry/media-picker.json +2 -0
- package/registry/meter.json +4 -2
- package/registry/money-input.json +5 -3
- package/registry/nav-bar.json +9 -39
- package/registry/next-actions.json +4 -2
- package/registry/notification-preferences.json +4 -2
- package/registry/number-ticker.json +4 -2
- package/registry/onboarding.json +2 -0
- package/registry/opening-hours.json +5 -4
- package/registry/otp-input.json +2 -0
- package/registry/page-header.json +4 -2
- package/registry/page-hero.json +4 -2
- package/registry/page-index.json +4 -2
- package/registry/page.json +4 -2
- package/registry/pagination.json +4 -2
- package/registry/permission-prompt.json +2 -0
- package/registry/photo-grid.json +4 -2
- package/registry/pointer-light.json +4 -2
- package/registry/popover.json +4 -2
- package/registry/price-catalogue-editor.json +5 -3
- package/registry/pricing-page.json +4 -2
- package/registry/product-page.json +4 -2
- package/registry/profile-card.json +4 -2
- package/registry/progress.json +4 -2
- package/registry/promise-card.json +4 -2
- package/registry/promo-code-field.json +5 -3
- package/registry/proposal.json +5 -3
- package/registry/pull-to-refresh.json +2 -0
- package/registry/qr-code.json +4 -2
- package/registry/quota-meter.json +4 -2
- package/registry/radio-group.json +4 -2
- package/registry/rail-nav.json +9 -39
- package/registry/recipes.json +4 -2
- package/registry/retro-tv.json +9 -3
- package/registry/reviews.json +4 -2
- package/registry/router.json +4 -2
- package/registry/schema-form.json +5 -3
- package/registry/screen.json +2 -0
- package/registry/scroll-stage.json +4 -2
- package/registry/search-field.json +4 -2
- package/registry/section-backdrop.json +4 -2
- package/registry/segmented.json +2 -0
- package/registry/separator.json +4 -2
- package/registry/service-card.json +4 -2
- package/registry/settings-layout.json +4 -2
- package/registry/shop-composer.json +4 -2
- package/registry/shop-gallery.json +5 -3
- package/registry/shop.json +5 -3
- package/registry/showcase.json +4 -2
- package/registry/signature.json +4 -2
- package/registry/site-cahier.json +4 -2
- package/registry/site-footer.json +9 -39
- package/registry/sites.json +6 -4
- package/registry/skeleton.json +4 -2
- package/registry/skip-link.json +4 -2
- package/registry/slider.json +4 -2
- package/registry/slot-picker.json +4 -2
- package/registry/slot.json +4 -2
- package/registry/specimen-tag.json +4 -2
- package/registry/speed-lines.json +4 -2
- package/registry/spinner.json +4 -2
- package/registry/splash-handoff.json +2 -0
- package/registry/split-view.json +4 -2
- package/registry/stage-banner.json +4 -2
- package/registry/stat.json +4 -2
- package/registry/state-screen.json +3 -1
- package/registry/status-chip.json +4 -2
- package/registry/status-page.json +4 -2
- package/registry/step-progress.json +4 -2
- package/registry/step-showcase.json +4 -2
- package/registry/stepper.json +4 -2
- package/registry/sticky-action.json +4 -2
- package/registry/stuck.json +4 -2
- package/registry/swipe-deck.json +5 -3
- package/registry/swipeable-row.json +2 -0
- package/registry/switch.json +4 -2
- package/registry/tab-bar.json +2 -0
- package/registry/tabs.json +4 -2
- package/registry/tag-input.json +4 -2
- package/registry/tag-selector.json +5 -3
- package/registry/taped-photo.json +4 -2
- package/registry/terminal-replay.json +4 -2
- package/registry/text-style.json +4 -2
- package/registry/theme.json +4 -2
- package/registry/toast.json +4 -2
- package/registry/toc.json +4 -2
- package/registry/tooltip.json +4 -2
- package/registry/tree-view.json +4 -2
- package/registry/txt.json +2 -0
- package/registry/update-prompt.json +4 -2
- package/registry/upload-queue.json +4 -2
- package/registry/usage.json +5 -3
- package/registry/verified-badge.json +4 -2
- package/registry/versus-card.json +4 -2
- package/registry/vertical-video.json +4 -2
- package/registry/video-player.json +4 -2
- package/registry/video-trimmer.json +4 -2
- package/registry/virtual.json +4 -2
- package/registry/wall.json +4 -2
- package/registry/waveform.json +4 -2
- package/dist/chunk-4JO5GSSD.js.map +0 -1
- package/dist/chunk-5MPPIGCB.js.map +0 -1
- package/dist/chunk-B2HS5EAH.js +0 -527
- package/dist/chunk-B2HS5EAH.js.map +0 -1
- package/dist/chunk-T5NZSKWT.js.map +0 -1
- package/dist/chunk-TISDOZH3.js.map +0 -1
- package/dist/chunk-Y5YBTHVD.js.map +0 -1
- package/dist/iso.d.ts +0 -401
- package/dist/iso.js +0 -363
- package/dist/iso.js.map +0 -1
- package/dist/meta-row.d.ts +0 -55
- package/dist/meta-row.js +0 -35
- package/dist/meta-row.js.map +0 -1
- package/registry/examples/iso/compose.d.ts +0 -4
- package/registry/examples/iso/compose.js +0 -22
- package/registry/examples/iso/compose.tsx +0 -19
- package/registry/examples/iso/creator-hero.d.ts +0 -4
- package/registry/examples/iso/creator-hero.js +0 -29
- package/registry/examples/iso/creator-hero.tsx +0 -23
- package/registry/examples/iso/orazaka-hero.d.ts +0 -4
- package/registry/examples/iso/orazaka-hero.js +0 -26
- package/registry/examples/iso/orazaka-hero.tsx +0 -21
- package/registry/examples/iso/still.d.ts +0 -4
- package/registry/examples/iso/still.js +0 -21
- package/registry/examples/iso/still.tsx +0 -15
- package/registry/examples/meta-row/native/video.d.ts +0 -4
- package/registry/examples/meta-row/native/video.dark.png +0 -0
- package/registry/examples/meta-row/native/video.js +0 -11
- package/registry/examples/meta-row/native/video.light.png +0 -0
- package/registry/examples/meta-row/native/video.tsx +0 -5
- package/registry/examples/meta-row/status.d.ts +0 -4
- package/registry/examples/meta-row/status.js +0 -12
- package/registry/examples/meta-row/status.tsx +0 -7
- package/registry/examples/meta-row/video.d.ts +0 -4
- package/registry/examples/meta-row/video.js +0 -12
- package/registry/examples/meta-row/video.tsx +0 -7
- package/registry/iso.json +0 -1369
- package/registry/meta-row.json +0 -216
- /package/dist/{chunk-GRVIZTT2.js.map → chunk-GSQRSWOE.js.map} +0 -0
package/registry/data-table.json
CHANGED
|
@@ -7,6 +7,8 @@
|
|
|
7
7
|
"status": "beta",
|
|
8
8
|
"deprecated": null,
|
|
9
9
|
"category": "data-display",
|
|
10
|
+
"domain": "data-display",
|
|
11
|
+
"adoption": null,
|
|
10
12
|
"platforms": "web",
|
|
11
13
|
"parity": {
|
|
12
14
|
"web": {
|
|
@@ -801,7 +803,7 @@
|
|
|
801
803
|
},
|
|
802
804
|
{
|
|
803
805
|
"path": "data-table/meta.ts",
|
|
804
|
-
"content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n title: \"Data table\",\n summary:\n \"A table of records on TanStack Table v9 — sort, filters and facets, groups, details, pages, selection, column visibility, pinning and resizing — in the browser or on the server, cards on a phone, windowing for long lists.\",\n status: \"beta\",\n category: \"data-display\",\n platforms: \"web\",\n parity: { native: { status: \"n/a\", reason: \"On a phone the rows are a list of cards, each with its fields as a description list — not a table to scroll sideways.\", use: \"list\" }, desktop: \"web\" },\n whenToUse: [\n \"To compare records on the same columns: jobs, videos of a studio, users of an admin, invoices, payouts.\",\n \"When people sort, filter, group, select several rows for a bulk action, or export what they see.\",\n \"In server mode (`manual` + `onStateChange`) when the list lives in a database: the API sorts, filters and pages.\",\n \"With `virtualized` for a long list loaded at once (logs, 50,000 events) that must stay smooth.\",\n ],\n whenNotToUse: [\n { when: \"For a few figures side by side: stats.\", use: \"stat\" },\n { when: \"For a gallery of media where the picture matters more than the columns.\", use: \"virtual\" },\n { when: \"For a list on a phone app: FlashList, through the native list.\", use: \"list\" },\n ],\n bestPractices: [\n \"Bulk actions are the product's: `bulkActions` draws the bar (count, your buttons, « Clear selection »); say what happened in `bulkResult` (« 3 moved, 1 skipped »), pass `bulkMax` when the service takes a limited number (200), and offer an undo (a toast) after a change that can be undone.\",\n \"Give the table a `routeKey` (`routeKey=\\\"clients\\\"`) so its sort, filters and page are in the address: back, reload and a shared link all work.\", \n \"Keep `rows` and `columns` stable (module scope, state, a query's data, `useMemo`): a new array at each render recomputes every model.\",\n \"Give every column a `header` (it labels the value in a card and names its filter) and the row's name a `card: \\\"title\\\"` column.\",\n \"Put `DataTableFilters` in `toolbar`; mark the columns it filters with `filter: \\\"text\\\" | \\\"facet\\\" | \\\"range\\\"`, and give a server table's facets their `options`.\",\n \"Server mode: keep the `DataTableQuery` from `onStateChange` in state (or the address), put it in the query key, and pass `rowCount` — `placeholderData: keepPreviousData` keeps the page while the next one loads.\",\n \"Say what failed in `error` with a way to retry; say what to do next in `empty` (an `EmptyState` with an action).\",\n \"Type the columns (`type`: title · badge · status · number · date · link · text) and give the secondary ones a `priority` (2 to 7): the table then never scrolls sideways — columns leave the row for its detail, then the rows become cards. Scrolling is an opt-in (`scroll`).\",\n \"A `title` column takes the slack and truncates (full value on hover); badges, statuses, numbers and dates are as wide as their content. Do not give a title column a `maxWidth`.\",\n \"A professional list on a phone reads as list rows, not cards: `phone=\\\"list\\\"` draws each row as the title (give it `href`: the whole row is its link), its `priority: 2` columns joined as one line of facts, and the `status` column at the end; the other columns go to the row's detail. Keep it to one or two facts.\",\n \"Align amounts and counts to the end (`align: \\\"end\\\"`) in tabular numbers; pin the name column of a wide table.\",\n \"Need something the props do not cover? `useDataTable()` gives the TanStack instance — never import `@tanstack/*` in a product.\",\n ],\n accessibility: {\n keyboard: [\n { keys: \"Tab\", action: \"Reaches the toolbar, the sort buttons of the headers, the resize handles, the checkboxes, the expand buttons and the links of the cells.\" },\n { keys: \"Space\", action: \"Toggles the focused checkbox, sorts by the focused header, or opens the focused row or group.\" },\n { keys: \"Arrow keys\", action: \"On a focused resize handle, narrow or widen the column (Shift for larger steps).\" },\n ],\n notes: [\n \"A `table` with a `caption` (hidden unless `showCaption`) and `scope=\\\"col\\\"` headers; the roles are written out, so the cards and the list rows keep the table's semantics.\",\n \"In the list rows the facts are read inside the title's cell (their own cells are hidden at that width, never read twice); the checkbox and the title's link stay in the tab order, above the row's stretched link.\",\n \"The sorted column carries `aria-sort`; a sortable header is a button that says its state with `aria-pressed`.\",\n \"An expand button (a row's details, a group, a tree) says its state with `aria-expanded` and names the row; a group's button says its value and its count.\",\n \"A resize handle is a focusable `separator` named after its column, with its width as `aria-valuenow`.\",\n \"The filters' bar is a named group; the count of results is announced politely when it changes; each filter in force is a chip with a remove button.\",\n \"While loading the table is `aria-busy` and its caption says so; an error is announced (`role=\\\"alert\\\"`).\",\n \"Windowed rows carry `aria-rowindex` and the table `aria-rowcount`: a screen reader knows where it is in the whole list; the scrolling body is a focusable region.\",\n ],\n },\n related: [\"filter-bar\", \"pagination\", \"virtual\", \"checkbox\", \"empty-state\"],\n web: {\n imports: [\"DataTable\", \"DataTableFilters\", \"DataTableColumnsMenu\", \"DataTableExport\", \"SelectionBar\", \"useDataTable\"],\n examples: [\n { name: \"catalogue\", title: \"Models catalogue\", description: \"Eight typed columns that never overflow: priorities move the maker, licence, context and date into the row's detail as the table narrows, then cards under 36 rem.\" },\n { name: \"invoices\", title: \"Invoice list\", description: \"Title, status and amount always in the row; dates and contact in the detail on a narrow screen; sticky header and zebra rows.\" },\n { name: \"runs\", title: \"Admin runs\", description: \"An admin console: filters, columns menu and CSV export in the toolbar, selection, a range filter on the duration, the error in the detail.\" },\n { name: \"jobs\", title: \"Jobs\", description: \"Sortable columns, a status badge, row selection for a bulk action.\" },\n { name: \"filters\", title: \"Filters, columns, export\", description: \"A search, facets with their counts, a range; the filters as chips; hide columns; export the rows shown as CSV.\" },\n { name: \"server\", title: \"Server mode\", description: \"Sort, filters and page go to the API through `krizakaFetch` and `defineKeys` of @krizaka/query; the previous page stays while the next one loads.\" },\n { name: \"bulk\", title: \"Bulk actions\", description: \"`selectable` + `bulkActions`: the bar of the selection — the count, the actions the product gives, « Clear selection », and what the last change did (« 2 tagged ») announced politely; sticky, docked above the tab bar on a phone.\" },\n { name: \"paginated\", title: \"Pages\", description: \"Client pagination under the table, with the rows per page to choose.\" },\n { name: \"grouped\", title: \"Groups\", description: \"`groupBy`: a row per group with its count and its total (`aggregate`), opened to see its rows.\" },\n { name: \"details\", title: \"Details\", description: \"`renderDetail`: a button per row opens a panel under it.\" },\n { name: \"pinned\", title: \"Pinned and resizable\", description: \"A wide table: the name pinned at the start, columns resized by drag or by the arrow keys.\" },\n { name: \"cards\", title: \"Cards on a phone\", description: \"`layout=\\\"cards\\\"`: each row a card, the title on top — what `auto` does in a narrow container.\" },\n { name: \"checks\", title: \"List rows on a phone\", description: \"`phone=\\\"list\\\"`: under 36 rem each check is a list row — the selection, the document as the row's link, « Lease · Oct 23 » as one line of facts, the result at the end; a table above.\" },\n { name: \"applicant-files\", title: \"Applicant files\", description: \"`layout=\\\"cards\\\" phone=\\\"list\\\"`: a landlord's files as list rows at every width — the name and unit, the documents and the date as one line, the status.\" },\n { name: \"loading\", title: \"Loading\", description: \"Skeleton rows while the first page loads, the table busy.\" },\n { name: \"empty\", title: \"Empty\", description: \"No record yet: an empty state with the next step.\" },\n { name: \"error\", title: \"Error\", description: \"The request failed: an alert with a retry, in place of the rows.\" },\n { name: \"virtualized\", title: \"50,000 rows\", description: \"`virtualized`: only the rows in view are rendered and measured, the header stays.\" },\n ],\n },\n} satisfies ComponentMeta;\n"
|
|
806
|
+
"content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n title: \"Data table\",\n summary:\n \"A table of records on TanStack Table v9 — sort, filters and facets, groups, details, pages, selection, column visibility, pinning and resizing — in the browser or on the server, cards on a phone, windowing for long lists.\",\n status: \"beta\",\n category: \"data-display\",\n domain: \"data-display\",\n platforms: \"web\",\n parity: { native: { status: \"n/a\", reason: \"On a phone the rows are a list of cards, each with its fields as a description list — not a table to scroll sideways.\", use: \"list\" }, desktop: \"web\" },\n whenToUse: [\n \"To compare records on the same columns: jobs, videos of a studio, users of an admin, invoices, payouts.\",\n \"When people sort, filter, group, select several rows for a bulk action, or export what they see.\",\n \"In server mode (`manual` + `onStateChange`) when the list lives in a database: the API sorts, filters and pages.\",\n \"With `virtualized` for a long list loaded at once (logs, 50,000 events) that must stay smooth.\",\n ],\n whenNotToUse: [\n { when: \"For a few figures side by side: stats.\", use: \"stat\" },\n { when: \"For a gallery of media where the picture matters more than the columns.\", use: \"virtual\" },\n { when: \"For a list on a phone app: FlashList, through the native list.\", use: \"list\" },\n ],\n bestPractices: [\n \"Bulk actions are the product's: `bulkActions` draws the bar (count, your buttons, « Clear selection »); say what happened in `bulkResult` (« 3 moved, 1 skipped »), pass `bulkMax` when the service takes a limited number (200), and offer an undo (a toast) after a change that can be undone.\",\n \"Give the table a `routeKey` (`routeKey=\\\"clients\\\"`) so its sort, filters and page are in the address: back, reload and a shared link all work.\", \n \"Keep `rows` and `columns` stable (module scope, state, a query's data, `useMemo`): a new array at each render recomputes every model.\",\n \"Give every column a `header` (it labels the value in a card and names its filter) and the row's name a `card: \\\"title\\\"` column.\",\n \"Put `DataTableFilters` in `toolbar`; mark the columns it filters with `filter: \\\"text\\\" | \\\"facet\\\" | \\\"range\\\"`, and give a server table's facets their `options`.\",\n \"Server mode: keep the `DataTableQuery` from `onStateChange` in state (or the address), put it in the query key, and pass `rowCount` — `placeholderData: keepPreviousData` keeps the page while the next one loads.\",\n \"Say what failed in `error` with a way to retry; say what to do next in `empty` (an `EmptyState` with an action).\",\n \"Type the columns (`type`: title · badge · status · number · date · link · text) and give the secondary ones a `priority` (2 to 7): the table then never scrolls sideways — columns leave the row for its detail, then the rows become cards. Scrolling is an opt-in (`scroll`).\",\n \"A `title` column takes the slack and truncates (full value on hover); badges, statuses, numbers and dates are as wide as their content. Do not give a title column a `maxWidth`.\",\n \"A professional list on a phone reads as list rows, not cards: `phone=\\\"list\\\"` draws each row as the title (give it `href`: the whole row is its link), its `priority: 2` columns joined as one line of facts, and the `status` column at the end; the other columns go to the row's detail. Keep it to one or two facts.\",\n \"Align amounts and counts to the end (`align: \\\"end\\\"`) in tabular numbers; pin the name column of a wide table.\",\n \"Need something the props do not cover? `useDataTable()` gives the TanStack instance — never import `@tanstack/*` in a product.\",\n ],\n accessibility: {\n keyboard: [\n { keys: \"Tab\", action: \"Reaches the toolbar, the sort buttons of the headers, the resize handles, the checkboxes, the expand buttons and the links of the cells.\" },\n { keys: \"Space\", action: \"Toggles the focused checkbox, sorts by the focused header, or opens the focused row or group.\" },\n { keys: \"Arrow keys\", action: \"On a focused resize handle, narrow or widen the column (Shift for larger steps).\" },\n ],\n notes: [\n \"A `table` with a `caption` (hidden unless `showCaption`) and `scope=\\\"col\\\"` headers; the roles are written out, so the cards and the list rows keep the table's semantics.\",\n \"In the list rows the facts are read inside the title's cell (their own cells are hidden at that width, never read twice); the checkbox and the title's link stay in the tab order, above the row's stretched link.\",\n \"The sorted column carries `aria-sort`; a sortable header is a button that says its state with `aria-pressed`.\",\n \"An expand button (a row's details, a group, a tree) says its state with `aria-expanded` and names the row; a group's button says its value and its count.\",\n \"A resize handle is a focusable `separator` named after its column, with its width as `aria-valuenow`.\",\n \"The filters' bar is a named group; the count of results is announced politely when it changes; each filter in force is a chip with a remove button.\",\n \"While loading the table is `aria-busy` and its caption says so; an error is announced (`role=\\\"alert\\\"`).\",\n \"Windowed rows carry `aria-rowindex` and the table `aria-rowcount`: a screen reader knows where it is in the whole list; the scrolling body is a focusable region.\",\n ],\n },\n related: [\"filter-bar\", \"pagination\", \"virtual\", \"checkbox\", \"empty-state\"],\n web: {\n imports: [\"DataTable\", \"DataTableFilters\", \"DataTableColumnsMenu\", \"DataTableExport\", \"SelectionBar\", \"useDataTable\"],\n examples: [\n { name: \"catalogue\", title: \"Models catalogue\", description: \"Eight typed columns that never overflow: priorities move the maker, licence, context and date into the row's detail as the table narrows, then cards under 36 rem.\" },\n { name: \"invoices\", title: \"Invoice list\", description: \"Title, status and amount always in the row; dates and contact in the detail on a narrow screen; sticky header and zebra rows.\" },\n { name: \"runs\", title: \"Admin runs\", description: \"An admin console: filters, columns menu and CSV export in the toolbar, selection, a range filter on the duration, the error in the detail.\" },\n { name: \"jobs\", title: \"Jobs\", description: \"Sortable columns, a status badge, row selection for a bulk action.\" },\n { name: \"filters\", title: \"Filters, columns, export\", description: \"A search, facets with their counts, a range; the filters as chips; hide columns; export the rows shown as CSV.\" },\n { name: \"server\", title: \"Server mode\", description: \"Sort, filters and page go to the API through `krizakaFetch` and `defineKeys` of @krizaka/query; the previous page stays while the next one loads.\" },\n { name: \"bulk\", title: \"Bulk actions\", description: \"`selectable` + `bulkActions`: the bar of the selection — the count, the actions the product gives, « Clear selection », and what the last change did (« 2 tagged ») announced politely; sticky, docked above the tab bar on a phone.\" },\n { name: \"paginated\", title: \"Pages\", description: \"Client pagination under the table, with the rows per page to choose.\" },\n { name: \"grouped\", title: \"Groups\", description: \"`groupBy`: a row per group with its count and its total (`aggregate`), opened to see its rows.\" },\n { name: \"details\", title: \"Details\", description: \"`renderDetail`: a button per row opens a panel under it.\" },\n { name: \"pinned\", title: \"Pinned and resizable\", description: \"A wide table: the name pinned at the start, columns resized by drag or by the arrow keys.\" },\n { name: \"cards\", title: \"Cards on a phone\", description: \"`layout=\\\"cards\\\"`: each row a card, the title on top — what `auto` does in a narrow container.\" },\n { name: \"checks\", title: \"List rows on a phone\", description: \"`phone=\\\"list\\\"`: under 36 rem each check is a list row — the selection, the document as the row's link, « Lease · Oct 23 » as one line of facts, the result at the end; a table above.\" },\n { name: \"applicant-files\", title: \"Applicant files\", description: \"`layout=\\\"cards\\\" phone=\\\"list\\\"`: a landlord's files as list rows at every width — the name and unit, the documents and the date as one line, the status.\" },\n { name: \"loading\", title: \"Loading\", description: \"Skeleton rows while the first page loads, the table busy.\" },\n { name: \"empty\", title: \"Empty\", description: \"No record yet: an empty state with the next step.\" },\n { name: \"error\", title: \"Error\", description: \"The request failed: an alert with a retry, in place of the rows.\" },\n { name: \"virtualized\", title: \"50,000 rows\", description: \"`virtualized`: only the rows in view are rendered and measured, the header stays.\" },\n ],\n },\n} satisfies ComponentMeta;\n"
|
|
805
807
|
},
|
|
806
808
|
{
|
|
807
809
|
"path": "data-table/route-codec.ts",
|
|
@@ -829,7 +831,7 @@
|
|
|
829
831
|
},
|
|
830
832
|
{
|
|
831
833
|
"path": "meta.ts",
|
|
832
|
-
"content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n | \"notification-preferences\"\n | \"quota-meter\"\n | \"environment-notice\"\n | \"embed-facade\"\n | \"reviews\"\n | \"margin-layout\"\n | \"analysis-report\"\n | \"status-chip\"\n | \"kind-config-editor\"\n | \"agenda\"\n | \"account-settings\"\n | \"drop-overlay\"\n | \"upload-queue\"\n | \"achievement\"\n | \"anatomy-plate\"\n | \"bird-plate\"\n | \"taped-photo\"\n | \"stuck\"\n | \"doodle\"\n | \"signature\"\n | \"grade-stamp\"\n | \"versus-card\"\n | \"speed-lines\"\n | \"site-cahier\"\n | \"text-style\"\n | \"flock\"\n | \"elephant\"\n | \"footnote\"\n | \"page-index\"\n | \"chapter\"\n | \"specimen-tag\"\n | \"action-bar\"\n | \"action-sheet\"\n | \"activity-feed\"\n | \"alert\"\n | \"app-frame\"\n | \"desktop-window\"\n | \"form-flow\"\n | \"grid\"\n | \"list-detail\"\n | \"state-screen\"\n | \"app-header\"\n | \"app-shell\"\n | \"argument-card\"\n | \"audio-player\"\n | \"auth-layout\"\n | \"avatar\"\n | \"badge\"\n | \"button\"\n | \"captcha\"\n | \"card\"\n | \"card-grid\"\n | \"catalogue-page\"\n | \"changelog-page\"\n | \"chat\"\n | \"checkbox\"\n | \"chip\"\n | \"chip-link\"\n | \"chip-row\"\n | \"choice-grid\"\n | \"cn\"\n | \"code-block\"\n | \"combobox\"\n | \"comparison-table\"\n | \"command\"\n | \"component-page\"\n | \"confirm-button\"\n | \"copy-button\"\n | \"money-input\"\n | \"price-catalogue-editor\"\n | \"promo-code-field\"\n | \"contact-page\"\n | \"continue-prompt\"\n | \"countdown\"\n | \"cover-hero\"\n | \"cta-panel\"\n | \"dashboard-layout\"\n | \"data-table\"\n | \"date-picker\"\n | \"decision-list\"\n | \"description-list\"\n | \"detail-layout\"\n | \"dialog\"\n | \"docs-article-page\"\n | \"docs-hub-page\"\n | \"docs-layout\"\n | \"docs-nav\"\n | \"document-viewer\"\n | \"dropdown-menu\"\n | \"empty-state\"\n | \"engine-flow\"\n | \"error-page\"\n | \"fab\"\n | \"field\"\n | \"file-upload\"\n | \"filter-bar\"\n | \"force-update-screen\"\n | \"form\"\n | \"gallery-page\"\n | \"genui\"\n | \"glossary\"\n | \"glossary-term\"\n | \"glow-card\"\n | \"goal-gauge\"\n | \"header\"\n | \"how-it-works-page\"\n | \"image-cropper\"\n | \"image-viewer\"\n | \"iso\"\n | \"kanban\"\n | \"kbd\"\n | \"kpi-explained\"\n | \"landing-page\"\n | \"landscape\"\n | \"legal-page\"\n | \"link-card\"\n | \"list\"\n | \"loader\"\n | \"longform-page\"\n | \"maintenance-screen\"\n | \"map\"\n | \"markdown\"\n | \"meta-row\"\n | \"waveform\"\n | \"proposal\"\n | \"qr-code\"\n | \"entity-header\"\n | \"collection-switcher\"\n | \"marketing-layout\"\n | \"marquee\"\n | \"mascot-quote\"\n | \"mascot-state\"\n | \"mascots\"\n | \"match-dialog\"\n | \"media-capture\"\n | \"media-grid\"\n | \"language-switch\"\n | \"media-gallery\"\n | \"media-picker\"\n | \"meter\"\n | \"nav-bar\"\n | \"number-ticker\"\n | \"onboarding\"\n | \"opening-hours\"\n | \"otp-input\"\n | \"page\"\n | \"page-header\"\n | \"page-hero\"\n | \"pagination\"\n | \"permission-prompt\"\n | \"photo-grid\"\n | \"pointer-light\"\n | \"popover\"\n | \"pricing-page\"\n | \"product-page\"\n | \"profile-card\"\n | \"progress\"\n | \"promise-card\"\n | \"pull-to-refresh\"\n | \"retro-tv\"\n | \"shop-gallery\"\n | \"radio-group\"\n | \"router\"\n | \"rail-nav\"\n | \"recipes\"\n | \"screen\"\n | \"scroll-stage\"\n | \"search-field\"\n | \"section-backdrop\"\n | \"segmented\"\n | \"separator\"\n | \"service-card\"\n | \"shop\"\n | \"shop-composer\"\n | \"schema-form\"\n | \"settings-layout\"\n | \"account-menu\"\n | \"showcase\"\n | \"step-showcase\"\n | \"site-footer\"\n | \"sites\"\n | \"skeleton\"\n | \"skip-link\"\n | \"slider\"\n | \"slot-picker\"\n | \"slot\"\n | \"spinner\"\n | \"sticky-action\"\n | \"splash-handoff\"\n | \"split-view\"\n | \"stage-banner\"\n | \"stat\"\n | \"usage\"\n | \"status-page\"\n | \"step-progress\"\n | \"stepper\"\n | \"swipe-deck\"\n | \"swipeable-row\"\n | \"switch\"\n | \"tab-bar\"\n | \"tabs\"\n | \"tag-input\"\n | \"tag-selector\"\n | \"terminal-replay\"\n | \"theme\"\n | \"toast\"\n | \"toc\"\n | \"tooltip\"\n | \"tree-view\"\n | \"txt\"\n | \"update-prompt\"\n | \"verified-badge\"\n | \"vertical-video\"\n | \"video-player\"\n | \"video-trimmer\"\n | \"virtual\"\n | \"wall\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/**\n * Why a component is not on a platform — a decision, never a silence (the parity matrix of ui.krizaka.com/platforms):\n * - `gap` (✗): it belongs there and is not built yet; `issue` is the issue that tracks it (`krizaka/krizaka-ui#275`);\n * - `n/a`: it is not meant for that platform (a site's page block on a phone, a swipe on a desktop); `use` names the\n * component that answers there, when one does.\n */\nexport type Absence =\n | { readonly status: \"gap\"; readonly issue: string; readonly reason: string; readonly use?: undefined }\n | { readonly status: \"n/a\"; readonly reason: string; readonly use?: ComponentName; readonly issue?: undefined };\n\n/**\n * Desktop is the Orazaka Mac app (Tauri 2: the system WebView renders the web components — ADR-002). `web`: the web\n * component runs there as it is; `desktop`: it also has a desktop form (a window's title bar, a denser layout…), said in\n * its documentation; otherwise the absence and why.\n */\nexport type DesktopSupport = \"web\" | \"desktop\" | Absence;\n\n/**\n * The three platforms of Krizaka UI — web · native (React Native, Expo) · desktop — for one component. The side a\n * component has is `platforms`; the side it lacks says why here: `native` is required for (and only for) a web-only\n * component, `web` for a native-only one; `desktop` always. `scripts/registry.test.mjs` fails on a missing decision.\n */\nexport interface Parity {\n readonly web?: Absence;\n readonly native?: Absence;\n readonly desktop: DesktopSupport;\n}\n\n/**\n * `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"stable\" | \"beta\" | \"deprecated\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n /** The version that deprecated it (`3.6.0`). */\n readonly since: string;\n /** The major that removes it (`4.0.0`). */\n readonly removedIn: string;\n /** What replaces it, when a component does. */\n readonly use?: ComponentName;\n /** Why it goes: no product uses it, no planned work needs it. */\n readonly reason: string;\n}\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\ninterface ExampleBase {\n /** The file name, kebab-case (`primary`, `icon-button`). */\n readonly name: string;\n /** A short title (`Primary`, `Icon button`). */\n readonly title: string;\n /** One or two sentences: when this variant is the right one. */\n readonly description: string;\n}\n\n/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n | (ExampleBase & {\n /**\n * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n */\n readonly template: true;\n /** The intent that groups it: why you need this block. */\n readonly purpose: TemplatePurpose;\n /** Why this layout: the user goal it serves, in one sentence. */\n readonly why: string;\n });\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n readonly imports: readonly string[];\n /** The examples, in reading order; the first one is the component's preview. */\n readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n /**\n * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n */\n readonly entry?: string;\n /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n readonly differences: readonly string[];\n /** The React Native entry alone is deprecated while the web one stays (ADR-006 §7); a deprecated component says it once, above. */\n readonly deprecated?: Deprecation;\n}\n\nexport interface KeyboardInteraction {\n /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n readonly keys: string;\n /** What they do. */\n readonly action: string;\n}\n\nexport interface ComponentMeta {\n /** The display name: `Button`, `Dropdown menu`. */\n readonly title: string;\n /** One sentence: what it is. */\n readonly summary: string;\n readonly status: Status;\n /** Required for, and only for, a `deprecated` component. */\n readonly deprecated?: Deprecation;\n readonly category: Category;\n /** Must match the sides below: `both` ⇔ `web` and `native`. */\n readonly platforms: Platform;\n /** The platforms it is not on, and why; and its desktop form (see `Parity`). */\n readonly parity: Parity;\n /** When to reach for it: concrete situations, one per item. */\n readonly whenToUse: readonly string[];\n /** When not to — and what to use instead (`use`), when another component is the answer. */\n readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n /** How to use it well: wording, placement, composition. */\n readonly bestPractices: readonly string[];\n readonly accessibility: {\n /** The keyboard, when it does more than Tab and Enter. */\n readonly keyboard: readonly KeyboardInteraction[];\n /** Roles, names and announcements: what the component does, what the app must provide. */\n readonly notes: readonly string[];\n };\n /** The components a reader of this page should know about. */\n readonly related: readonly ComponentName[];\n readonly web?: PlatformDocs;\n readonly native?: NativeDocs;\n}\n"
|
|
834
|
+
"content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n | \"notification-preferences\"\n | \"quota-meter\"\n | \"environment-notice\"\n | \"embed-facade\"\n | \"reviews\"\n | \"margin-layout\"\n | \"analysis-report\"\n | \"status-chip\"\n | \"kind-config-editor\"\n | \"agenda\"\n | \"account-settings\"\n | \"drop-overlay\"\n | \"upload-queue\"\n | \"achievement\"\n | \"anatomy-plate\"\n | \"bird-plate\"\n | \"taped-photo\"\n | \"stuck\"\n | \"doodle\"\n | \"signature\"\n | \"grade-stamp\"\n | \"versus-card\"\n | \"speed-lines\"\n | \"site-cahier\"\n | \"text-style\"\n | \"flock\"\n | \"elephant\"\n | \"footnote\"\n | \"page-index\"\n | \"chapter\"\n | \"specimen-tag\"\n | \"action-bar\"\n | \"action-sheet\"\n | \"activity-feed\"\n | \"alert\"\n | \"app-frame\"\n | \"desktop-window\"\n | \"form-flow\"\n | \"grid\"\n | \"list-detail\"\n | \"state-screen\"\n | \"app-header\"\n | \"app-shell\"\n | \"argument-card\"\n | \"audio-player\"\n | \"auth-layout\"\n | \"avatar\"\n | \"badge\"\n | \"button\"\n | \"captcha\"\n | \"card\"\n | \"card-grid\"\n | \"catalogue-page\"\n | \"changelog-page\"\n | \"chat\"\n | \"checkbox\"\n | \"chip\"\n | \"chip-link\"\n | \"chip-row\"\n | \"choice-grid\"\n | \"cn\"\n | \"code-block\"\n | \"combobox\"\n | \"comparison-table\"\n | \"command\"\n | \"component-page\"\n | \"confirm-button\"\n | \"copy-button\"\n | \"money-input\"\n | \"price-catalogue-editor\"\n | \"promo-code-field\"\n | \"contact-page\"\n | \"continue-prompt\"\n | \"countdown\"\n | \"cover-hero\"\n | \"cta-panel\"\n | \"dashboard-layout\"\n | \"data-table\"\n | \"date-picker\"\n | \"decision-list\"\n | \"description-list\"\n | \"detail-layout\"\n | \"dialog\"\n | \"docs-article-page\"\n | \"docs-hub-page\"\n | \"docs-layout\"\n | \"docs-nav\"\n | \"document-viewer\"\n | \"dropdown-menu\"\n | \"empty-state\"\n | \"engine-flow\"\n | \"error-page\"\n | \"fab\"\n | \"field\"\n | \"file-upload\"\n | \"filter-bar\"\n | \"force-update-screen\"\n | \"form\"\n | \"gallery-page\"\n | \"genui\"\n | \"glossary\"\n | \"glossary-term\"\n | \"glow-card\"\n | \"goal-gauge\"\n | \"header\"\n | \"how-it-works-page\"\n | \"image-cropper\"\n | \"image-viewer\"\n | \"kanban\"\n | \"kbd\"\n | \"kpi-explained\"\n | \"landing-page\"\n | \"landscape\"\n | \"legal-page\"\n | \"link-card\"\n | \"list\"\n | \"loader\"\n | \"longform-page\"\n | \"maintenance-screen\"\n | \"map\"\n | \"markdown\"\n | \"waveform\"\n | \"proposal\"\n | \"qr-code\"\n | \"entity-header\"\n | \"collection-switcher\"\n | \"marketing-layout\"\n | \"marquee\"\n | \"mascot-quote\"\n | \"mascot-state\"\n | \"mascots\"\n | \"match-dialog\"\n | \"media-capture\"\n | \"media-grid\"\n | \"language-switch\"\n | \"media-gallery\"\n | \"media-picker\"\n | \"meter\"\n | \"nav-bar\"\n | \"number-ticker\"\n | \"onboarding\"\n | \"opening-hours\"\n | \"otp-input\"\n | \"page\"\n | \"page-header\"\n | \"page-hero\"\n | \"pagination\"\n | \"permission-prompt\"\n | \"photo-grid\"\n | \"pointer-light\"\n | \"popover\"\n | \"pricing-page\"\n | \"product-page\"\n | \"profile-card\"\n | \"progress\"\n | \"promise-card\"\n | \"pull-to-refresh\"\n | \"retro-tv\"\n | \"shop-gallery\"\n | \"radio-group\"\n | \"router\"\n | \"rail-nav\"\n | \"recipes\"\n | \"screen\"\n | \"scroll-stage\"\n | \"search-field\"\n | \"section-backdrop\"\n | \"segmented\"\n | \"separator\"\n | \"service-card\"\n | \"shop\"\n | \"shop-composer\"\n | \"schema-form\"\n | \"settings-layout\"\n | \"account-menu\"\n | \"showcase\"\n | \"step-showcase\"\n | \"site-footer\"\n | \"sites\"\n | \"skeleton\"\n | \"skip-link\"\n | \"slider\"\n | \"slot-picker\"\n | \"slot\"\n | \"spinner\"\n | \"sticky-action\"\n | \"splash-handoff\"\n | \"split-view\"\n | \"stage-banner\"\n | \"stat\"\n | \"usage\"\n | \"status-page\"\n | \"step-progress\"\n | \"stepper\"\n | \"swipe-deck\"\n | \"swipeable-row\"\n | \"switch\"\n | \"tab-bar\"\n | \"tabs\"\n | \"tag-input\"\n | \"tag-selector\"\n | \"terminal-replay\"\n | \"theme\"\n | \"toast\"\n | \"toc\"\n | \"tooltip\"\n | \"tree-view\"\n | \"txt\"\n | \"update-prompt\"\n | \"verified-badge\"\n | \"vertical-video\"\n | \"video-player\"\n | \"video-trimmer\"\n | \"virtual\"\n | \"wall\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/**\n * Why a component is not on a platform — a decision, never a silence (the parity matrix of ui.krizaka.com/platforms):\n * - `gap` (✗): it belongs there and is not built yet; `issue` is the issue that tracks it (`krizaka/krizaka-ui#275`);\n * - `n/a`: it is not meant for that platform (a site's page block on a phone, a swipe on a desktop); `use` names the\n * component that answers there, when one does.\n */\nexport type Absence =\n | { readonly status: \"gap\"; readonly issue: string; readonly reason: string; readonly use?: undefined }\n | { readonly status: \"n/a\"; readonly reason: string; readonly use?: ComponentName; readonly issue?: undefined };\n\n/**\n * Desktop is the Orazaka Mac app (Tauri 2: the system WebView renders the web components — ADR-002). `web`: the web\n * component runs there as it is; `desktop`: it also has a desktop form (a window's title bar, a denser layout…), said in\n * its documentation; otherwise the absence and why.\n */\nexport type DesktopSupport = \"web\" | \"desktop\" | Absence;\n\n/**\n * The three platforms of Krizaka UI — web · native (React Native, Expo) · desktop — for one component. The side a\n * component has is `platforms`; the side it lacks says why here: `native` is required for (and only for) a web-only\n * component, `web` for a native-only one; `desktop` always. `scripts/registry.test.mjs` fails on a missing decision.\n */\nexport interface Parity {\n readonly web?: Absence;\n readonly native?: Absence;\n readonly desktop: DesktopSupport;\n}\n\n/**\n * `experimental`: created for a filed need (ADR-008 §4), it may change or go in any minor until its first consumer imports it; `adoption`\n * names that consumer's issue. `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"experimental\" | \"stable\" | \"beta\" | \"deprecated\";\n\n/**\n * What a component is for (ADR-008 §3): the twelve domains the documentation, the size budgets and the guards are\n * organised by. The domain is metadata: the entries stay flat (`@krizaka/ui/<name>`). `cahier` is the sites' register\n * (ADR-004): a product never imports it.\n */\nexport type Domain =\n | \"foundations\"\n | \"forms\"\n | \"data-display\"\n | \"navigation-shell\"\n | \"feedback\"\n | \"maps\"\n | \"media\"\n | \"commerce\"\n | \"identity\"\n | \"conversation\"\n | \"page-blocks\"\n | \"cahier\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n /** The version that deprecated it (`3.6.0`). */\n readonly since: string;\n /** The major that removes it (`4.0.0`). */\n readonly removedIn: string;\n /** What replaces it, when a component does. */\n readonly use?: ComponentName;\n /** Why it goes: no product uses it, no planned work needs it. */\n readonly reason: string;\n}\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\ninterface ExampleBase {\n /** The file name, kebab-case (`primary`, `icon-button`). */\n readonly name: string;\n /** A short title (`Primary`, `Icon button`). */\n readonly title: string;\n /** One or two sentences: when this variant is the right one. */\n readonly description: string;\n}\n\n/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n | (ExampleBase & {\n /**\n * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n */\n readonly template: true;\n /** The intent that groups it: why you need this block. */\n readonly purpose: TemplatePurpose;\n /** Why this layout: the user goal it serves, in one sentence. */\n readonly why: string;\n });\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n readonly imports: readonly string[];\n /** The examples, in reading order; the first one is the component's preview. */\n readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n /**\n * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n */\n readonly entry?: string;\n /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n readonly differences: readonly string[];\n /** The React Native entry alone is deprecated while the web one stays (ADR-006 §7); a deprecated component says it once, above. */\n readonly deprecated?: Deprecation;\n}\n\nexport interface KeyboardInteraction {\n /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n readonly keys: string;\n /** What they do. */\n readonly action: string;\n}\n\nexport interface ComponentMeta {\n /** The display name: `Button`, `Dropdown menu`. */\n readonly title: string;\n /** One sentence: what it is. */\n readonly summary: string;\n readonly status: Status;\n /** Required for, and only for, a `deprecated` component. */\n readonly deprecated?: Deprecation;\n readonly category: Category;\n /** What it is for: one of the twelve domains (ADR-008 §3). */\n readonly domain: Domain;\n /** The `<repo>#<n>` issue of its first consumer: required for, and only for, an `experimental` component. */\n readonly adoption?: string;\n /** Must match the sides below: `both` ⇔ `web` and `native`. */\n readonly platforms: Platform;\n /** The platforms it is not on, and why; and its desktop form (see `Parity`). */\n readonly parity: Parity;\n /** When to reach for it: concrete situations, one per item. */\n readonly whenToUse: readonly string[];\n /** When not to — and what to use instead (`use`), when another component is the answer. */\n readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n /** How to use it well: wording, placement, composition. */\n readonly bestPractices: readonly string[];\n readonly accessibility: {\n /** The keyboard, when it does more than Tab and Enter. */\n readonly keyboard: readonly KeyboardInteraction[];\n /** Roles, names and announcements: what the component does, what the app must provide. */\n readonly notes: readonly string[];\n };\n /** The components a reader of this page should know about. */\n readonly related: readonly ComponentName[];\n readonly web?: PlatformDocs;\n readonly native?: NativeDocs;\n}\n"
|
|
833
835
|
}
|
|
834
836
|
],
|
|
835
837
|
"dependencies": [
|
|
@@ -7,6 +7,8 @@
|
|
|
7
7
|
"status": "beta",
|
|
8
8
|
"deprecated": null,
|
|
9
9
|
"category": "forms",
|
|
10
|
+
"domain": "forms",
|
|
11
|
+
"adoption": null,
|
|
10
12
|
"platforms": "both",
|
|
11
13
|
"parity": {
|
|
12
14
|
"web": {
|
|
@@ -1476,7 +1478,7 @@
|
|
|
1476
1478
|
},
|
|
1477
1479
|
{
|
|
1478
1480
|
"path": "date-picker/meta.ts",
|
|
1479
|
-
"content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n title: \"Date picker\",\n summary:\n \"Dates and times chosen the way the task asks — a calendar, a period with presets, a strip of days, wheels, time slots, a month, a date of birth — as ISO values (`2026-10-11`, `2026-10`, `18:30`) the form, the address and the API share, in the locale's own words.\",\n status: \"beta\",\n category: \"forms\",\n platforms: \"both\",\n parity: { desktop: \"web\" },\n whenToUse: [\n \"`DatePicker`: a day near today in a form — a publication, an auction's end, a reminder.\",\n \"`DateRangePicker`: a period — an earnings report, an audit log — with presets and two months side by side.\",\n \"`Calendar` inline (`variant=\\\"card\\\"`): when the month itself is the interface (availability, a booking).\",\n \"`DayStrip`: the next days in a row (a delivery day, a session, an agenda) — one thumb away on a phone.\",\n \"`TimePicker`: wheels to set a time (a reminder); `variant=\\\"slots\\\"` to book one among the free times.\",\n \"`MonthPicker`: a month of a year (a billing month, a card's expiry, a report).\",\n \"`DateField` (typed) or `DateWheel` (wheels): a memorable date far away — a date of birth with an age gate.\",\n ],\n whenNotToUse: [\n { when: \"For a date of birth or any date years away: a calendar makes it slow — use `DateField` or `DateWheel`.\", use: \"field\" },\n { when: \"For a relative choice (“last 7 days”, “this month”) without a calendar: chips.\", use: \"chip\" },\n ],\n bestPractices: [\n \"Always pass the person's `locale`: names, the first day of the week, the order of day · month · year and 12/24 hours follow it.\",\n \"Keep values as ISO strings in state and in the address (`YYYY-MM-DD`, `YYYY-MM`, `HH:mm`); format them only for display.\",\n \"Bound the choice with `min` / `max`, `isDateDisabled` or `isTimeDisabled` rather than refusing after the fact — an age gate is `max={latestBirthDate(18)}`.\",\n \"Offer presets on a period picker: most people want “Last 30 days”, not two clicks.\",\n \"Mark the days that have something (`isDateMarked`) on a strip: the dot is read in the day's name too.\",\n ],\n accessibility: {\n keyboard: [\n { keys: \"Arrow keys\", action: \"Calendar: move by a day or a week. Month picker: by a month or a row. Day strip and slots: move and pick.\" },\n { keys: \"Home / End\", action: \"First or last day of the week (calendar), first or last item (strip, slots, wheel).\" },\n { keys: \"Page Up / Page Down\", action: \"Calendar: previous or next month (with Shift: year). Month picker: year. Wheel: by five values.\" },\n { keys: \"Up / Down\", action: \"Wheel: the previous or next value.\" },\n { keys: \"Enter / Space\", action: \"Pick the focused day or month.\" },\n { keys: \"Esc\", action: \"Close the calendar and return to the field.\" },\n ],\n notes: [\n \"The APG date picker: the month is a `grid` labelled by its month, one day in the tab order, each day named by its full date; today carries `aria-current=\\\"date\\\"`, chosen days `aria-selected`, unavailable days are disabled.\",\n \"The month's title is a button that opens the months of the year (`aria-expanded`); a change of month is announced by a polite live region.\",\n \"A wheel is a `spinbutton` (`aria-valuetext` reads the value as words); on React Native an adjustable control — swipe up or down with VoiceOver or TalkBack.\",\n \"The day strip and the time slots are radio groups: one tab stop, the arrows move and pick, taken or closed items are disabled and skipped.\",\n \"`DateField` is a fieldset named by its legend, each box named by its part; the error is read with the field (`aria-describedby`).\",\n \"Nothing moves under reduced motion: the month's slide stops; the wheel's curve is tied to the scroll, not to time.\",\n ],\n },\n related: [\"field\", \"popover\", \"filter-bar\", \"form\"],\n web: {\n imports: [\"DatePicker\", \"DateRangePicker\", \"Calendar\", \"MonthPicker\", \"DayStrip\", \"WheelPicker\", \"Wheel\", \"TimePicker\", \"DateField\", \"DateWheel\", \"latestBirthDate\", \"timeSlots\"],\n examples: [\n { name: \"schedule\", title: \"Schedule\", description: \"A publication date, from today on, written the way the locale writes it.\" },\n { name: \"open\", title: \"Calendar open\", description: \"The popover open on the month: today's node, the chosen day lit.\" },\n { name: \"range\", title: \"Period with presets\", description: \"`DateRangePicker` for an earnings report: presets beside two months, the period as one band.\" },\n { name: \"french\", title: \"In French\", description: \"`locale=\\\"fr-CA\\\"`: the names, the order and the first day of the week follow.\" },\n { name: \"calendar\", title: \"Inline calendar\", description: \"`Calendar variant=\\\"card\\\"`: the month is the interface, weekends unavailable; its title opens the months.\" },\n { name: \"month-year\", title: \"Month and year\", description: \"`MonthPicker`: a billing month, nothing later than this one.\" },\n { name: \"day-strip\", title: \"Day strip\", description: \"`DayStrip`: the next two weeks in a row, closed days dashed, the days with a session marked.\" },\n { name: \"wheel\", title: \"Wheel\", description: \"`WheelPicker` + `Wheel`: any short list turned by the thumb or the arrows — a party size.\" },\n { name: \"time-wheel\", title: \"Time, wheels\", description: \"`TimePicker`: hours, minutes by 5 and the period of a 12-hour locale; the value is `HH:mm`.\" },\n { name: \"time-slots\", title: \"Time, slots\", description: \"`TimePicker variant=\\\"slots\\\"`: the free times of an agenda by part of the day, taken ones struck through.\" },\n { name: \"birth-date\", title: \"Date of birth, typed\", description: \"`DateField`: day · month · year in the locale's order, autofilled, an under-18 date refused.\" },\n { name: \"birth-date-wheel\", title: \"Date of birth, wheels\", description: \"`DateWheel` with `max` at the 18th birthday: an under-18 date cannot be chosen.\" },\n ],\n },\n native: {\n imports: [\"Calendar\", \"MonthPicker\", \"DayStrip\", \"TimePicker\", \"DateWheel\", \"WheelPicker\", \"Wheel\", \"DateField\", \"latestBirthDate\", \"timeSlots\"],\n differences: [\n \"No popover field (`DatePicker`, `DateRangePicker`): on a phone, the `Calendar`, the `DayStrip` or the wheels sit in the screen or in a `Sheet`.\",\n \"`DateField` is typed (day · month · year, numeric keypads); `DateWheel` is the same date as three wheels — the native form's `DateField` uses the wheels.\",\n \"Each value a wheel passes, each day or slot pressed plays a `selection` haptic — when the app passes `haptics` to the `ThemeProvider` (expo-haptics): the platform has no native module.\",\n \"A wheel is an adjustable control for VoiceOver and TalkBack (swipe up or down), named by its `label`, its value read as words.\",\n ],\n examples: [\n { name: \"birth-date\", title: \"Date of birth, typed\", description: \"Day, month and year with `autoComplete=\\\"bday\\\"`, and the error of an under-18 date.\" },\n { name: \"birth-date-wheel\", title: \"Date of birth, wheels\", description: \"`DateWheel` ending at the 18th birthday: an under-18 date cannot be chosen.\" },\n { name: \"calendar\", title: \"Calendar\", description: \"A month to book a day: 44-pt days, today's node, the past unavailable.\" },\n { name: \"day-strip\", title: \"Day strip\", description: \"The days ahead swiped sideways, closed days dashed, marked days with a dot.\" },\n { name: \"time-wheel\", title: \"Time, wheels\", description: \"Hours, minutes by 5 and the period; the value is `HH:mm`.\" },\n { name: \"time-slots\", title: \"Time, slots\", description: \"The free times of an agenda as buttons, taken ones dashed.\" },\n { name: \"month-year\", title: \"Month and year\", description: \"`MonthPicker`: the twelve months, nothing later than this one.\" },\n ],\n },\n} satisfies ComponentMeta;\n"
|
|
1481
|
+
"content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n title: \"Date picker\",\n summary:\n \"Dates and times chosen the way the task asks — a calendar, a period with presets, a strip of days, wheels, time slots, a month, a date of birth — as ISO values (`2026-10-11`, `2026-10`, `18:30`) the form, the address and the API share, in the locale's own words.\",\n status: \"beta\",\n category: \"forms\",\n domain: \"forms\",\n platforms: \"both\",\n parity: { desktop: \"web\" },\n whenToUse: [\n \"`DatePicker`: a day near today in a form — a publication, an auction's end, a reminder.\",\n \"`DateRangePicker`: a period — an earnings report, an audit log — with presets and two months side by side.\",\n \"`Calendar` inline (`variant=\\\"card\\\"`): when the month itself is the interface (availability, a booking).\",\n \"`DayStrip`: the next days in a row (a delivery day, a session, an agenda) — one thumb away on a phone.\",\n \"`TimePicker`: wheels to set a time (a reminder); `variant=\\\"slots\\\"` to book one among the free times.\",\n \"`MonthPicker`: a month of a year (a billing month, a card's expiry, a report).\",\n \"`DateField` (typed) or `DateWheel` (wheels): a memorable date far away — a date of birth with an age gate.\",\n ],\n whenNotToUse: [\n { when: \"For a date of birth or any date years away: a calendar makes it slow — use `DateField` or `DateWheel`.\", use: \"field\" },\n { when: \"For a relative choice (“last 7 days”, “this month”) without a calendar: chips.\", use: \"chip\" },\n ],\n bestPractices: [\n \"Always pass the person's `locale`: names, the first day of the week, the order of day · month · year and 12/24 hours follow it.\",\n \"Keep values as ISO strings in state and in the address (`YYYY-MM-DD`, `YYYY-MM`, `HH:mm`); format them only for display.\",\n \"Bound the choice with `min` / `max`, `isDateDisabled` or `isTimeDisabled` rather than refusing after the fact — an age gate is `max={latestBirthDate(18)}`.\",\n \"Offer presets on a period picker: most people want “Last 30 days”, not two clicks.\",\n \"Mark the days that have something (`isDateMarked`) on a strip: the dot is read in the day's name too.\",\n ],\n accessibility: {\n keyboard: [\n { keys: \"Arrow keys\", action: \"Calendar: move by a day or a week. Month picker: by a month or a row. Day strip and slots: move and pick.\" },\n { keys: \"Home / End\", action: \"First or last day of the week (calendar), first or last item (strip, slots, wheel).\" },\n { keys: \"Page Up / Page Down\", action: \"Calendar: previous or next month (with Shift: year). Month picker: year. Wheel: by five values.\" },\n { keys: \"Up / Down\", action: \"Wheel: the previous or next value.\" },\n { keys: \"Enter / Space\", action: \"Pick the focused day or month.\" },\n { keys: \"Esc\", action: \"Close the calendar and return to the field.\" },\n ],\n notes: [\n \"The APG date picker: the month is a `grid` labelled by its month, one day in the tab order, each day named by its full date; today carries `aria-current=\\\"date\\\"`, chosen days `aria-selected`, unavailable days are disabled.\",\n \"The month's title is a button that opens the months of the year (`aria-expanded`); a change of month is announced by a polite live region.\",\n \"A wheel is a `spinbutton` (`aria-valuetext` reads the value as words); on React Native an adjustable control — swipe up or down with VoiceOver or TalkBack.\",\n \"The day strip and the time slots are radio groups: one tab stop, the arrows move and pick, taken or closed items are disabled and skipped.\",\n \"`DateField` is a fieldset named by its legend, each box named by its part; the error is read with the field (`aria-describedby`).\",\n \"Nothing moves under reduced motion: the month's slide stops; the wheel's curve is tied to the scroll, not to time.\",\n ],\n },\n related: [\"field\", \"popover\", \"filter-bar\", \"form\"],\n web: {\n imports: [\"DatePicker\", \"DateRangePicker\", \"Calendar\", \"MonthPicker\", \"DayStrip\", \"WheelPicker\", \"Wheel\", \"TimePicker\", \"DateField\", \"DateWheel\", \"latestBirthDate\", \"timeSlots\"],\n examples: [\n { name: \"schedule\", title: \"Schedule\", description: \"A publication date, from today on, written the way the locale writes it.\" },\n { name: \"open\", title: \"Calendar open\", description: \"The popover open on the month: today's node, the chosen day lit.\" },\n { name: \"range\", title: \"Period with presets\", description: \"`DateRangePicker` for an earnings report: presets beside two months, the period as one band.\" },\n { name: \"french\", title: \"In French\", description: \"`locale=\\\"fr-CA\\\"`: the names, the order and the first day of the week follow.\" },\n { name: \"calendar\", title: \"Inline calendar\", description: \"`Calendar variant=\\\"card\\\"`: the month is the interface, weekends unavailable; its title opens the months.\" },\n { name: \"month-year\", title: \"Month and year\", description: \"`MonthPicker`: a billing month, nothing later than this one.\" },\n { name: \"day-strip\", title: \"Day strip\", description: \"`DayStrip`: the next two weeks in a row, closed days dashed, the days with a session marked.\" },\n { name: \"wheel\", title: \"Wheel\", description: \"`WheelPicker` + `Wheel`: any short list turned by the thumb or the arrows — a party size.\" },\n { name: \"time-wheel\", title: \"Time, wheels\", description: \"`TimePicker`: hours, minutes by 5 and the period of a 12-hour locale; the value is `HH:mm`.\" },\n { name: \"time-slots\", title: \"Time, slots\", description: \"`TimePicker variant=\\\"slots\\\"`: the free times of an agenda by part of the day, taken ones struck through.\" },\n { name: \"birth-date\", title: \"Date of birth, typed\", description: \"`DateField`: day · month · year in the locale's order, autofilled, an under-18 date refused.\" },\n { name: \"birth-date-wheel\", title: \"Date of birth, wheels\", description: \"`DateWheel` with `max` at the 18th birthday: an under-18 date cannot be chosen.\" },\n ],\n },\n native: {\n imports: [\"Calendar\", \"MonthPicker\", \"DayStrip\", \"TimePicker\", \"DateWheel\", \"WheelPicker\", \"Wheel\", \"DateField\", \"latestBirthDate\", \"timeSlots\"],\n differences: [\n \"No popover field (`DatePicker`, `DateRangePicker`): on a phone, the `Calendar`, the `DayStrip` or the wheels sit in the screen or in a `Sheet`.\",\n \"`DateField` is typed (day · month · year, numeric keypads); `DateWheel` is the same date as three wheels — the native form's `DateField` uses the wheels.\",\n \"Each value a wheel passes, each day or slot pressed plays a `selection` haptic — when the app passes `haptics` to the `ThemeProvider` (expo-haptics): the platform has no native module.\",\n \"A wheel is an adjustable control for VoiceOver and TalkBack (swipe up or down), named by its `label`, its value read as words.\",\n ],\n examples: [\n { name: \"birth-date\", title: \"Date of birth, typed\", description: \"Day, month and year with `autoComplete=\\\"bday\\\"`, and the error of an under-18 date.\" },\n { name: \"birth-date-wheel\", title: \"Date of birth, wheels\", description: \"`DateWheel` ending at the 18th birthday: an under-18 date cannot be chosen.\" },\n { name: \"calendar\", title: \"Calendar\", description: \"A month to book a day: 44-pt days, today's node, the past unavailable.\" },\n { name: \"day-strip\", title: \"Day strip\", description: \"The days ahead swiped sideways, closed days dashed, marked days with a dot.\" },\n { name: \"time-wheel\", title: \"Time, wheels\", description: \"Hours, minutes by 5 and the period; the value is `HH:mm`.\" },\n { name: \"time-slots\", title: \"Time, slots\", description: \"The free times of an agenda as buttons, taken ones dashed.\" },\n { name: \"month-year\", title: \"Month and year\", description: \"`MonthPicker`: the twelve months, nothing later than this one.\" },\n ],\n },\n} satisfies ComponentMeta;\n"
|
|
1480
1482
|
},
|
|
1481
1483
|
{
|
|
1482
1484
|
"path": "date-picker/month-picker.tsx",
|
|
@@ -1504,7 +1506,7 @@
|
|
|
1504
1506
|
},
|
|
1505
1507
|
{
|
|
1506
1508
|
"path": "meta.ts",
|
|
1507
|
-
"content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n | \"notification-preferences\"\n | \"quota-meter\"\n | \"environment-notice\"\n | \"embed-facade\"\n | \"reviews\"\n | \"margin-layout\"\n | \"analysis-report\"\n | \"status-chip\"\n | \"kind-config-editor\"\n | \"agenda\"\n | \"account-settings\"\n | \"drop-overlay\"\n | \"upload-queue\"\n | \"achievement\"\n | \"anatomy-plate\"\n | \"bird-plate\"\n | \"taped-photo\"\n | \"stuck\"\n | \"doodle\"\n | \"signature\"\n | \"grade-stamp\"\n | \"versus-card\"\n | \"speed-lines\"\n | \"site-cahier\"\n | \"text-style\"\n | \"flock\"\n | \"elephant\"\n | \"footnote\"\n | \"page-index\"\n | \"chapter\"\n | \"specimen-tag\"\n | \"action-bar\"\n | \"action-sheet\"\n | \"activity-feed\"\n | \"alert\"\n | \"app-frame\"\n | \"desktop-window\"\n | \"form-flow\"\n | \"grid\"\n | \"list-detail\"\n | \"state-screen\"\n | \"app-header\"\n | \"app-shell\"\n | \"argument-card\"\n | \"audio-player\"\n | \"auth-layout\"\n | \"avatar\"\n | \"badge\"\n | \"button\"\n | \"captcha\"\n | \"card\"\n | \"card-grid\"\n | \"catalogue-page\"\n | \"changelog-page\"\n | \"chat\"\n | \"checkbox\"\n | \"chip\"\n | \"chip-link\"\n | \"chip-row\"\n | \"choice-grid\"\n | \"cn\"\n | \"code-block\"\n | \"combobox\"\n | \"comparison-table\"\n | \"command\"\n | \"component-page\"\n | \"confirm-button\"\n | \"copy-button\"\n | \"money-input\"\n | \"price-catalogue-editor\"\n | \"promo-code-field\"\n | \"contact-page\"\n | \"continue-prompt\"\n | \"countdown\"\n | \"cover-hero\"\n | \"cta-panel\"\n | \"dashboard-layout\"\n | \"data-table\"\n | \"date-picker\"\n | \"decision-list\"\n | \"description-list\"\n | \"detail-layout\"\n | \"dialog\"\n | \"docs-article-page\"\n | \"docs-hub-page\"\n | \"docs-layout\"\n | \"docs-nav\"\n | \"document-viewer\"\n | \"dropdown-menu\"\n | \"empty-state\"\n | \"engine-flow\"\n | \"error-page\"\n | \"fab\"\n | \"field\"\n | \"file-upload\"\n | \"filter-bar\"\n | \"force-update-screen\"\n | \"form\"\n | \"gallery-page\"\n | \"genui\"\n | \"glossary\"\n | \"glossary-term\"\n | \"glow-card\"\n | \"goal-gauge\"\n | \"header\"\n | \"how-it-works-page\"\n | \"image-cropper\"\n | \"image-viewer\"\n | \"iso\"\n | \"kanban\"\n | \"kbd\"\n | \"kpi-explained\"\n | \"landing-page\"\n | \"landscape\"\n | \"legal-page\"\n | \"link-card\"\n | \"list\"\n | \"loader\"\n | \"longform-page\"\n | \"maintenance-screen\"\n | \"map\"\n | \"markdown\"\n | \"meta-row\"\n | \"waveform\"\n | \"proposal\"\n | \"qr-code\"\n | \"entity-header\"\n | \"collection-switcher\"\n | \"marketing-layout\"\n | \"marquee\"\n | \"mascot-quote\"\n | \"mascot-state\"\n | \"mascots\"\n | \"match-dialog\"\n | \"media-capture\"\n | \"media-grid\"\n | \"language-switch\"\n | \"media-gallery\"\n | \"media-picker\"\n | \"meter\"\n | \"nav-bar\"\n | \"number-ticker\"\n | \"onboarding\"\n | \"opening-hours\"\n | \"otp-input\"\n | \"page\"\n | \"page-header\"\n | \"page-hero\"\n | \"pagination\"\n | \"permission-prompt\"\n | \"photo-grid\"\n | \"pointer-light\"\n | \"popover\"\n | \"pricing-page\"\n | \"product-page\"\n | \"profile-card\"\n | \"progress\"\n | \"promise-card\"\n | \"pull-to-refresh\"\n | \"retro-tv\"\n | \"shop-gallery\"\n | \"radio-group\"\n | \"router\"\n | \"rail-nav\"\n | \"recipes\"\n | \"screen\"\n | \"scroll-stage\"\n | \"search-field\"\n | \"section-backdrop\"\n | \"segmented\"\n | \"separator\"\n | \"service-card\"\n | \"shop\"\n | \"shop-composer\"\n | \"schema-form\"\n | \"settings-layout\"\n | \"account-menu\"\n | \"showcase\"\n | \"step-showcase\"\n | \"site-footer\"\n | \"sites\"\n | \"skeleton\"\n | \"skip-link\"\n | \"slider\"\n | \"slot-picker\"\n | \"slot\"\n | \"spinner\"\n | \"sticky-action\"\n | \"splash-handoff\"\n | \"split-view\"\n | \"stage-banner\"\n | \"stat\"\n | \"usage\"\n | \"status-page\"\n | \"step-progress\"\n | \"stepper\"\n | \"swipe-deck\"\n | \"swipeable-row\"\n | \"switch\"\n | \"tab-bar\"\n | \"tabs\"\n | \"tag-input\"\n | \"tag-selector\"\n | \"terminal-replay\"\n | \"theme\"\n | \"toast\"\n | \"toc\"\n | \"tooltip\"\n | \"tree-view\"\n | \"txt\"\n | \"update-prompt\"\n | \"verified-badge\"\n | \"vertical-video\"\n | \"video-player\"\n | \"video-trimmer\"\n | \"virtual\"\n | \"wall\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/**\n * Why a component is not on a platform — a decision, never a silence (the parity matrix of ui.krizaka.com/platforms):\n * - `gap` (✗): it belongs there and is not built yet; `issue` is the issue that tracks it (`krizaka/krizaka-ui#275`);\n * - `n/a`: it is not meant for that platform (a site's page block on a phone, a swipe on a desktop); `use` names the\n * component that answers there, when one does.\n */\nexport type Absence =\n | { readonly status: \"gap\"; readonly issue: string; readonly reason: string; readonly use?: undefined }\n | { readonly status: \"n/a\"; readonly reason: string; readonly use?: ComponentName; readonly issue?: undefined };\n\n/**\n * Desktop is the Orazaka Mac app (Tauri 2: the system WebView renders the web components — ADR-002). `web`: the web\n * component runs there as it is; `desktop`: it also has a desktop form (a window's title bar, a denser layout…), said in\n * its documentation; otherwise the absence and why.\n */\nexport type DesktopSupport = \"web\" | \"desktop\" | Absence;\n\n/**\n * The three platforms of Krizaka UI — web · native (React Native, Expo) · desktop — for one component. The side a\n * component has is `platforms`; the side it lacks says why here: `native` is required for (and only for) a web-only\n * component, `web` for a native-only one; `desktop` always. `scripts/registry.test.mjs` fails on a missing decision.\n */\nexport interface Parity {\n readonly web?: Absence;\n readonly native?: Absence;\n readonly desktop: DesktopSupport;\n}\n\n/**\n * `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"stable\" | \"beta\" | \"deprecated\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n /** The version that deprecated it (`3.6.0`). */\n readonly since: string;\n /** The major that removes it (`4.0.0`). */\n readonly removedIn: string;\n /** What replaces it, when a component does. */\n readonly use?: ComponentName;\n /** Why it goes: no product uses it, no planned work needs it. */\n readonly reason: string;\n}\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\ninterface ExampleBase {\n /** The file name, kebab-case (`primary`, `icon-button`). */\n readonly name: string;\n /** A short title (`Primary`, `Icon button`). */\n readonly title: string;\n /** One or two sentences: when this variant is the right one. */\n readonly description: string;\n}\n\n/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n | (ExampleBase & {\n /**\n * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n */\n readonly template: true;\n /** The intent that groups it: why you need this block. */\n readonly purpose: TemplatePurpose;\n /** Why this layout: the user goal it serves, in one sentence. */\n readonly why: string;\n });\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n readonly imports: readonly string[];\n /** The examples, in reading order; the first one is the component's preview. */\n readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n /**\n * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n */\n readonly entry?: string;\n /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n readonly differences: readonly string[];\n /** The React Native entry alone is deprecated while the web one stays (ADR-006 §7); a deprecated component says it once, above. */\n readonly deprecated?: Deprecation;\n}\n\nexport interface KeyboardInteraction {\n /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n readonly keys: string;\n /** What they do. */\n readonly action: string;\n}\n\nexport interface ComponentMeta {\n /** The display name: `Button`, `Dropdown menu`. */\n readonly title: string;\n /** One sentence: what it is. */\n readonly summary: string;\n readonly status: Status;\n /** Required for, and only for, a `deprecated` component. */\n readonly deprecated?: Deprecation;\n readonly category: Category;\n /** Must match the sides below: `both` ⇔ `web` and `native`. */\n readonly platforms: Platform;\n /** The platforms it is not on, and why; and its desktop form (see `Parity`). */\n readonly parity: Parity;\n /** When to reach for it: concrete situations, one per item. */\n readonly whenToUse: readonly string[];\n /** When not to — and what to use instead (`use`), when another component is the answer. */\n readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n /** How to use it well: wording, placement, composition. */\n readonly bestPractices: readonly string[];\n readonly accessibility: {\n /** The keyboard, when it does more than Tab and Enter. */\n readonly keyboard: readonly KeyboardInteraction[];\n /** Roles, names and announcements: what the component does, what the app must provide. */\n readonly notes: readonly string[];\n };\n /** The components a reader of this page should know about. */\n readonly related: readonly ComponentName[];\n readonly web?: PlatformDocs;\n readonly native?: NativeDocs;\n}\n"
|
|
1509
|
+
"content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n | \"notification-preferences\"\n | \"quota-meter\"\n | \"environment-notice\"\n | \"embed-facade\"\n | \"reviews\"\n | \"margin-layout\"\n | \"analysis-report\"\n | \"status-chip\"\n | \"kind-config-editor\"\n | \"agenda\"\n | \"account-settings\"\n | \"drop-overlay\"\n | \"upload-queue\"\n | \"achievement\"\n | \"anatomy-plate\"\n | \"bird-plate\"\n | \"taped-photo\"\n | \"stuck\"\n | \"doodle\"\n | \"signature\"\n | \"grade-stamp\"\n | \"versus-card\"\n | \"speed-lines\"\n | \"site-cahier\"\n | \"text-style\"\n | \"flock\"\n | \"elephant\"\n | \"footnote\"\n | \"page-index\"\n | \"chapter\"\n | \"specimen-tag\"\n | \"action-bar\"\n | \"action-sheet\"\n | \"activity-feed\"\n | \"alert\"\n | \"app-frame\"\n | \"desktop-window\"\n | \"form-flow\"\n | \"grid\"\n | \"list-detail\"\n | \"state-screen\"\n | \"app-header\"\n | \"app-shell\"\n | \"argument-card\"\n | \"audio-player\"\n | \"auth-layout\"\n | \"avatar\"\n | \"badge\"\n | \"button\"\n | \"captcha\"\n | \"card\"\n | \"card-grid\"\n | \"catalogue-page\"\n | \"changelog-page\"\n | \"chat\"\n | \"checkbox\"\n | \"chip\"\n | \"chip-link\"\n | \"chip-row\"\n | \"choice-grid\"\n | \"cn\"\n | \"code-block\"\n | \"combobox\"\n | \"comparison-table\"\n | \"command\"\n | \"component-page\"\n | \"confirm-button\"\n | \"copy-button\"\n | \"money-input\"\n | \"price-catalogue-editor\"\n | \"promo-code-field\"\n | \"contact-page\"\n | \"continue-prompt\"\n | \"countdown\"\n | \"cover-hero\"\n | \"cta-panel\"\n | \"dashboard-layout\"\n | \"data-table\"\n | \"date-picker\"\n | \"decision-list\"\n | \"description-list\"\n | \"detail-layout\"\n | \"dialog\"\n | \"docs-article-page\"\n | \"docs-hub-page\"\n | \"docs-layout\"\n | \"docs-nav\"\n | \"document-viewer\"\n | \"dropdown-menu\"\n | \"empty-state\"\n | \"engine-flow\"\n | \"error-page\"\n | \"fab\"\n | \"field\"\n | \"file-upload\"\n | \"filter-bar\"\n | \"force-update-screen\"\n | \"form\"\n | \"gallery-page\"\n | \"genui\"\n | \"glossary\"\n | \"glossary-term\"\n | \"glow-card\"\n | \"goal-gauge\"\n | \"header\"\n | \"how-it-works-page\"\n | \"image-cropper\"\n | \"image-viewer\"\n | \"kanban\"\n | \"kbd\"\n | \"kpi-explained\"\n | \"landing-page\"\n | \"landscape\"\n | \"legal-page\"\n | \"link-card\"\n | \"list\"\n | \"loader\"\n | \"longform-page\"\n | \"maintenance-screen\"\n | \"map\"\n | \"markdown\"\n | \"waveform\"\n | \"proposal\"\n | \"qr-code\"\n | \"entity-header\"\n | \"collection-switcher\"\n | \"marketing-layout\"\n | \"marquee\"\n | \"mascot-quote\"\n | \"mascot-state\"\n | \"mascots\"\n | \"match-dialog\"\n | \"media-capture\"\n | \"media-grid\"\n | \"language-switch\"\n | \"media-gallery\"\n | \"media-picker\"\n | \"meter\"\n | \"nav-bar\"\n | \"number-ticker\"\n | \"onboarding\"\n | \"opening-hours\"\n | \"otp-input\"\n | \"page\"\n | \"page-header\"\n | \"page-hero\"\n | \"pagination\"\n | \"permission-prompt\"\n | \"photo-grid\"\n | \"pointer-light\"\n | \"popover\"\n | \"pricing-page\"\n | \"product-page\"\n | \"profile-card\"\n | \"progress\"\n | \"promise-card\"\n | \"pull-to-refresh\"\n | \"retro-tv\"\n | \"shop-gallery\"\n | \"radio-group\"\n | \"router\"\n | \"rail-nav\"\n | \"recipes\"\n | \"screen\"\n | \"scroll-stage\"\n | \"search-field\"\n | \"section-backdrop\"\n | \"segmented\"\n | \"separator\"\n | \"service-card\"\n | \"shop\"\n | \"shop-composer\"\n | \"schema-form\"\n | \"settings-layout\"\n | \"account-menu\"\n | \"showcase\"\n | \"step-showcase\"\n | \"site-footer\"\n | \"sites\"\n | \"skeleton\"\n | \"skip-link\"\n | \"slider\"\n | \"slot-picker\"\n | \"slot\"\n | \"spinner\"\n | \"sticky-action\"\n | \"splash-handoff\"\n | \"split-view\"\n | \"stage-banner\"\n | \"stat\"\n | \"usage\"\n | \"status-page\"\n | \"step-progress\"\n | \"stepper\"\n | \"swipe-deck\"\n | \"swipeable-row\"\n | \"switch\"\n | \"tab-bar\"\n | \"tabs\"\n | \"tag-input\"\n | \"tag-selector\"\n | \"terminal-replay\"\n | \"theme\"\n | \"toast\"\n | \"toc\"\n | \"tooltip\"\n | \"tree-view\"\n | \"txt\"\n | \"update-prompt\"\n | \"verified-badge\"\n | \"vertical-video\"\n | \"video-player\"\n | \"video-trimmer\"\n | \"virtual\"\n | \"wall\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/**\n * Why a component is not on a platform — a decision, never a silence (the parity matrix of ui.krizaka.com/platforms):\n * - `gap` (✗): it belongs there and is not built yet; `issue` is the issue that tracks it (`krizaka/krizaka-ui#275`);\n * - `n/a`: it is not meant for that platform (a site's page block on a phone, a swipe on a desktop); `use` names the\n * component that answers there, when one does.\n */\nexport type Absence =\n | { readonly status: \"gap\"; readonly issue: string; readonly reason: string; readonly use?: undefined }\n | { readonly status: \"n/a\"; readonly reason: string; readonly use?: ComponentName; readonly issue?: undefined };\n\n/**\n * Desktop is the Orazaka Mac app (Tauri 2: the system WebView renders the web components — ADR-002). `web`: the web\n * component runs there as it is; `desktop`: it also has a desktop form (a window's title bar, a denser layout…), said in\n * its documentation; otherwise the absence and why.\n */\nexport type DesktopSupport = \"web\" | \"desktop\" | Absence;\n\n/**\n * The three platforms of Krizaka UI — web · native (React Native, Expo) · desktop — for one component. The side a\n * component has is `platforms`; the side it lacks says why here: `native` is required for (and only for) a web-only\n * component, `web` for a native-only one; `desktop` always. `scripts/registry.test.mjs` fails on a missing decision.\n */\nexport interface Parity {\n readonly web?: Absence;\n readonly native?: Absence;\n readonly desktop: DesktopSupport;\n}\n\n/**\n * `experimental`: created for a filed need (ADR-008 §4), it may change or go in any minor until its first consumer imports it; `adoption`\n * names that consumer's issue. `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"experimental\" | \"stable\" | \"beta\" | \"deprecated\";\n\n/**\n * What a component is for (ADR-008 §3): the twelve domains the documentation, the size budgets and the guards are\n * organised by. The domain is metadata: the entries stay flat (`@krizaka/ui/<name>`). `cahier` is the sites' register\n * (ADR-004): a product never imports it.\n */\nexport type Domain =\n | \"foundations\"\n | \"forms\"\n | \"data-display\"\n | \"navigation-shell\"\n | \"feedback\"\n | \"maps\"\n | \"media\"\n | \"commerce\"\n | \"identity\"\n | \"conversation\"\n | \"page-blocks\"\n | \"cahier\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n /** The version that deprecated it (`3.6.0`). */\n readonly since: string;\n /** The major that removes it (`4.0.0`). */\n readonly removedIn: string;\n /** What replaces it, when a component does. */\n readonly use?: ComponentName;\n /** Why it goes: no product uses it, no planned work needs it. */\n readonly reason: string;\n}\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\ninterface ExampleBase {\n /** The file name, kebab-case (`primary`, `icon-button`). */\n readonly name: string;\n /** A short title (`Primary`, `Icon button`). */\n readonly title: string;\n /** One or two sentences: when this variant is the right one. */\n readonly description: string;\n}\n\n/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n | (ExampleBase & {\n /**\n * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n */\n readonly template: true;\n /** The intent that groups it: why you need this block. */\n readonly purpose: TemplatePurpose;\n /** Why this layout: the user goal it serves, in one sentence. */\n readonly why: string;\n });\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n readonly imports: readonly string[];\n /** The examples, in reading order; the first one is the component's preview. */\n readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n /**\n * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n */\n readonly entry?: string;\n /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n readonly differences: readonly string[];\n /** The React Native entry alone is deprecated while the web one stays (ADR-006 §7); a deprecated component says it once, above. */\n readonly deprecated?: Deprecation;\n}\n\nexport interface KeyboardInteraction {\n /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n readonly keys: string;\n /** What they do. */\n readonly action: string;\n}\n\nexport interface ComponentMeta {\n /** The display name: `Button`, `Dropdown menu`. */\n readonly title: string;\n /** One sentence: what it is. */\n readonly summary: string;\n readonly status: Status;\n /** Required for, and only for, a `deprecated` component. */\n readonly deprecated?: Deprecation;\n readonly category: Category;\n /** What it is for: one of the twelve domains (ADR-008 §3). */\n readonly domain: Domain;\n /** The `<repo>#<n>` issue of its first consumer: required for, and only for, an `experimental` component. */\n readonly adoption?: string;\n /** Must match the sides below: `both` ⇔ `web` and `native`. */\n readonly platforms: Platform;\n /** The platforms it is not on, and why; and its desktop form (see `Parity`). */\n readonly parity: Parity;\n /** When to reach for it: concrete situations, one per item. */\n readonly whenToUse: readonly string[];\n /** When not to — and what to use instead (`use`), when another component is the answer. */\n readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n /** How to use it well: wording, placement, composition. */\n readonly bestPractices: readonly string[];\n readonly accessibility: {\n /** The keyboard, when it does more than Tab and Enter. */\n readonly keyboard: readonly KeyboardInteraction[];\n /** Roles, names and announcements: what the component does, what the app must provide. */\n readonly notes: readonly string[];\n };\n /** The components a reader of this page should know about. */\n readonly related: readonly ComponentName[];\n readonly web?: PlatformDocs;\n readonly native?: NativeDocs;\n}\n"
|
|
1508
1510
|
},
|
|
1509
1511
|
{
|
|
1510
1512
|
"path": "tv.ts",
|
|
@@ -7,6 +7,8 @@
|
|
|
7
7
|
"status": "beta",
|
|
8
8
|
"deprecated": null,
|
|
9
9
|
"category": "blocks",
|
|
10
|
+
"domain": "page-blocks",
|
|
11
|
+
"adoption": null,
|
|
10
12
|
"platforms": "web",
|
|
11
13
|
"parity": {
|
|
12
14
|
"web": {
|
|
@@ -108,7 +110,7 @@
|
|
|
108
110
|
},
|
|
109
111
|
{
|
|
110
112
|
"path": "decision-list/meta.ts",
|
|
111
|
-
"content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n title: \"Decision list\",\n summary:\n \"The decisions behind a product, numbered: what was chosen, large, then side by side what was refused, why, and what it costs the reader — each with its mark and its colour.\",\n status: \"beta\",\n category: \"blocks\",\n platforms: \"web\",\n parity: { native: { status: \"n/a\", reason: \"A block of a public site's page; an app screen on a phone is built from Screen, Header and Card.\", use: \"description-list\" }, desktop: { status: \"n/a\", reason: \"A public site's page, not a window of the Mac app.\" } },\n whenToUse: [\n \"A product's or a building block's design decisions, explained to the people who will live with them.\",\n \"Any choice where the cost to the reader must be said as plainly as the benefit.\",\n ],\n whenNotToUse: [\n { when: \"For reasons that each lead to their own page.\", use: \"argument-card\" },\n { when: \"For steps the reader follows in order.\", use: \"stepper\" },\n ],\n bestPractices: [\n \"Always fill the cost: a decision without its cost is an advertisement.\",\n \"One sentence per part; the choice first, in words a newcomer understands.\",\n \"The four labels arrive as props (`We chose`, `We refused`, `Because`, `What it costs you`).\",\n ],\n accessibility: {\n keyboard: [],\n notes: [\n \"An ordered list: the number is decorative, the list says the order.\",\n \"Each part has its label in words; the marks (✓ ✕ → !) and the colours only repeat them.\",\n ],\n },\n related: [\"argument-card\", \"stepper\", \"page\"],\n web: {\n imports: [\"DecisionList\"],\n examples: [{ name: \"product\", title: \"A product's decisions\", description: \"Local inference and zero telemetry: chosen, refused, why, and what it costs.\" }],\n },\n} satisfies ComponentMeta;\n"
|
|
113
|
+
"content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n title: \"Decision list\",\n summary:\n \"The decisions behind a product, numbered: what was chosen, large, then side by side what was refused, why, and what it costs the reader — each with its mark and its colour.\",\n status: \"beta\",\n category: \"blocks\",\n domain: \"page-blocks\",\n platforms: \"web\",\n parity: { native: { status: \"n/a\", reason: \"A block of a public site's page; an app screen on a phone is built from Screen, Header and Card.\", use: \"description-list\" }, desktop: { status: \"n/a\", reason: \"A public site's page, not a window of the Mac app.\" } },\n whenToUse: [\n \"A product's or a building block's design decisions, explained to the people who will live with them.\",\n \"Any choice where the cost to the reader must be said as plainly as the benefit.\",\n ],\n whenNotToUse: [\n { when: \"For reasons that each lead to their own page.\", use: \"argument-card\" },\n { when: \"For steps the reader follows in order.\", use: \"stepper\" },\n ],\n bestPractices: [\n \"Always fill the cost: a decision without its cost is an advertisement.\",\n \"One sentence per part; the choice first, in words a newcomer understands.\",\n \"The four labels arrive as props (`We chose`, `We refused`, `Because`, `What it costs you`).\",\n ],\n accessibility: {\n keyboard: [],\n notes: [\n \"An ordered list: the number is decorative, the list says the order.\",\n \"Each part has its label in words; the marks (✓ ✕ → !) and the colours only repeat them.\",\n ],\n },\n related: [\"argument-card\", \"stepper\", \"page\"],\n web: {\n imports: [\"DecisionList\"],\n examples: [{ name: \"product\", title: \"A product's decisions\", description: \"Local inference and zero telemetry: chosen, refused, why, and what it costs.\" }],\n },\n} satisfies ComponentMeta;\n"
|
|
112
114
|
},
|
|
113
115
|
{
|
|
114
116
|
"path": "glyphs.tsx",
|
|
@@ -116,7 +118,7 @@
|
|
|
116
118
|
},
|
|
117
119
|
{
|
|
118
120
|
"path": "meta.ts",
|
|
119
|
-
"content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n | \"notification-preferences\"\n | \"quota-meter\"\n | \"environment-notice\"\n | \"embed-facade\"\n | \"reviews\"\n | \"margin-layout\"\n | \"analysis-report\"\n | \"status-chip\"\n | \"kind-config-editor\"\n | \"agenda\"\n | \"account-settings\"\n | \"drop-overlay\"\n | \"upload-queue\"\n | \"achievement\"\n | \"anatomy-plate\"\n | \"bird-plate\"\n | \"taped-photo\"\n | \"stuck\"\n | \"doodle\"\n | \"signature\"\n | \"grade-stamp\"\n | \"versus-card\"\n | \"speed-lines\"\n | \"site-cahier\"\n | \"text-style\"\n | \"flock\"\n | \"elephant\"\n | \"footnote\"\n | \"page-index\"\n | \"chapter\"\n | \"specimen-tag\"\n | \"action-bar\"\n | \"action-sheet\"\n | \"activity-feed\"\n | \"alert\"\n | \"app-frame\"\n | \"desktop-window\"\n | \"form-flow\"\n | \"grid\"\n | \"list-detail\"\n | \"state-screen\"\n | \"app-header\"\n | \"app-shell\"\n | \"argument-card\"\n | \"audio-player\"\n | \"auth-layout\"\n | \"avatar\"\n | \"badge\"\n | \"button\"\n | \"captcha\"\n | \"card\"\n | \"card-grid\"\n | \"catalogue-page\"\n | \"changelog-page\"\n | \"chat\"\n | \"checkbox\"\n | \"chip\"\n | \"chip-link\"\n | \"chip-row\"\n | \"choice-grid\"\n | \"cn\"\n | \"code-block\"\n | \"combobox\"\n | \"comparison-table\"\n | \"command\"\n | \"component-page\"\n | \"confirm-button\"\n | \"copy-button\"\n | \"money-input\"\n | \"price-catalogue-editor\"\n | \"promo-code-field\"\n | \"contact-page\"\n | \"continue-prompt\"\n | \"countdown\"\n | \"cover-hero\"\n | \"cta-panel\"\n | \"dashboard-layout\"\n | \"data-table\"\n | \"date-picker\"\n | \"decision-list\"\n | \"description-list\"\n | \"detail-layout\"\n | \"dialog\"\n | \"docs-article-page\"\n | \"docs-hub-page\"\n | \"docs-layout\"\n | \"docs-nav\"\n | \"document-viewer\"\n | \"dropdown-menu\"\n | \"empty-state\"\n | \"engine-flow\"\n | \"error-page\"\n | \"fab\"\n | \"field\"\n | \"file-upload\"\n | \"filter-bar\"\n | \"force-update-screen\"\n | \"form\"\n | \"gallery-page\"\n | \"genui\"\n | \"glossary\"\n | \"glossary-term\"\n | \"glow-card\"\n | \"goal-gauge\"\n | \"header\"\n | \"how-it-works-page\"\n | \"image-cropper\"\n | \"image-viewer\"\n | \"iso\"\n | \"kanban\"\n | \"kbd\"\n | \"kpi-explained\"\n | \"landing-page\"\n | \"landscape\"\n | \"legal-page\"\n | \"link-card\"\n | \"list\"\n | \"loader\"\n | \"longform-page\"\n | \"maintenance-screen\"\n | \"map\"\n | \"markdown\"\n | \"meta-row\"\n | \"waveform\"\n | \"proposal\"\n | \"qr-code\"\n | \"entity-header\"\n | \"collection-switcher\"\n | \"marketing-layout\"\n | \"marquee\"\n | \"mascot-quote\"\n | \"mascot-state\"\n | \"mascots\"\n | \"match-dialog\"\n | \"media-capture\"\n | \"media-grid\"\n | \"language-switch\"\n | \"media-gallery\"\n | \"media-picker\"\n | \"meter\"\n | \"nav-bar\"\n | \"number-ticker\"\n | \"onboarding\"\n | \"opening-hours\"\n | \"otp-input\"\n | \"page\"\n | \"page-header\"\n | \"page-hero\"\n | \"pagination\"\n | \"permission-prompt\"\n | \"photo-grid\"\n | \"pointer-light\"\n | \"popover\"\n | \"pricing-page\"\n | \"product-page\"\n | \"profile-card\"\n | \"progress\"\n | \"promise-card\"\n | \"pull-to-refresh\"\n | \"retro-tv\"\n | \"shop-gallery\"\n | \"radio-group\"\n | \"router\"\n | \"rail-nav\"\n | \"recipes\"\n | \"screen\"\n | \"scroll-stage\"\n | \"search-field\"\n | \"section-backdrop\"\n | \"segmented\"\n | \"separator\"\n | \"service-card\"\n | \"shop\"\n | \"shop-composer\"\n | \"schema-form\"\n | \"settings-layout\"\n | \"account-menu\"\n | \"showcase\"\n | \"step-showcase\"\n | \"site-footer\"\n | \"sites\"\n | \"skeleton\"\n | \"skip-link\"\n | \"slider\"\n | \"slot-picker\"\n | \"slot\"\n | \"spinner\"\n | \"sticky-action\"\n | \"splash-handoff\"\n | \"split-view\"\n | \"stage-banner\"\n | \"stat\"\n | \"usage\"\n | \"status-page\"\n | \"step-progress\"\n | \"stepper\"\n | \"swipe-deck\"\n | \"swipeable-row\"\n | \"switch\"\n | \"tab-bar\"\n | \"tabs\"\n | \"tag-input\"\n | \"tag-selector\"\n | \"terminal-replay\"\n | \"theme\"\n | \"toast\"\n | \"toc\"\n | \"tooltip\"\n | \"tree-view\"\n | \"txt\"\n | \"update-prompt\"\n | \"verified-badge\"\n | \"vertical-video\"\n | \"video-player\"\n | \"video-trimmer\"\n | \"virtual\"\n | \"wall\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/**\n * Why a component is not on a platform — a decision, never a silence (the parity matrix of ui.krizaka.com/platforms):\n * - `gap` (✗): it belongs there and is not built yet; `issue` is the issue that tracks it (`krizaka/krizaka-ui#275`);\n * - `n/a`: it is not meant for that platform (a site's page block on a phone, a swipe on a desktop); `use` names the\n * component that answers there, when one does.\n */\nexport type Absence =\n | { readonly status: \"gap\"; readonly issue: string; readonly reason: string; readonly use?: undefined }\n | { readonly status: \"n/a\"; readonly reason: string; readonly use?: ComponentName; readonly issue?: undefined };\n\n/**\n * Desktop is the Orazaka Mac app (Tauri 2: the system WebView renders the web components — ADR-002). `web`: the web\n * component runs there as it is; `desktop`: it also has a desktop form (a window's title bar, a denser layout…), said in\n * its documentation; otherwise the absence and why.\n */\nexport type DesktopSupport = \"web\" | \"desktop\" | Absence;\n\n/**\n * The three platforms of Krizaka UI — web · native (React Native, Expo) · desktop — for one component. The side a\n * component has is `platforms`; the side it lacks says why here: `native` is required for (and only for) a web-only\n * component, `web` for a native-only one; `desktop` always. `scripts/registry.test.mjs` fails on a missing decision.\n */\nexport interface Parity {\n readonly web?: Absence;\n readonly native?: Absence;\n readonly desktop: DesktopSupport;\n}\n\n/**\n * `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"stable\" | \"beta\" | \"deprecated\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n /** The version that deprecated it (`3.6.0`). */\n readonly since: string;\n /** The major that removes it (`4.0.0`). */\n readonly removedIn: string;\n /** What replaces it, when a component does. */\n readonly use?: ComponentName;\n /** Why it goes: no product uses it, no planned work needs it. */\n readonly reason: string;\n}\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\ninterface ExampleBase {\n /** The file name, kebab-case (`primary`, `icon-button`). */\n readonly name: string;\n /** A short title (`Primary`, `Icon button`). */\n readonly title: string;\n /** One or two sentences: when this variant is the right one. */\n readonly description: string;\n}\n\n/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n | (ExampleBase & {\n /**\n * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n */\n readonly template: true;\n /** The intent that groups it: why you need this block. */\n readonly purpose: TemplatePurpose;\n /** Why this layout: the user goal it serves, in one sentence. */\n readonly why: string;\n });\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n readonly imports: readonly string[];\n /** The examples, in reading order; the first one is the component's preview. */\n readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n /**\n * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n */\n readonly entry?: string;\n /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n readonly differences: readonly string[];\n /** The React Native entry alone is deprecated while the web one stays (ADR-006 §7); a deprecated component says it once, above. */\n readonly deprecated?: Deprecation;\n}\n\nexport interface KeyboardInteraction {\n /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n readonly keys: string;\n /** What they do. */\n readonly action: string;\n}\n\nexport interface ComponentMeta {\n /** The display name: `Button`, `Dropdown menu`. */\n readonly title: string;\n /** One sentence: what it is. */\n readonly summary: string;\n readonly status: Status;\n /** Required for, and only for, a `deprecated` component. */\n readonly deprecated?: Deprecation;\n readonly category: Category;\n /** Must match the sides below: `both` ⇔ `web` and `native`. */\n readonly platforms: Platform;\n /** The platforms it is not on, and why; and its desktop form (see `Parity`). */\n readonly parity: Parity;\n /** When to reach for it: concrete situations, one per item. */\n readonly whenToUse: readonly string[];\n /** When not to — and what to use instead (`use`), when another component is the answer. */\n readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n /** How to use it well: wording, placement, composition. */\n readonly bestPractices: readonly string[];\n readonly accessibility: {\n /** The keyboard, when it does more than Tab and Enter. */\n readonly keyboard: readonly KeyboardInteraction[];\n /** Roles, names and announcements: what the component does, what the app must provide. */\n readonly notes: readonly string[];\n };\n /** The components a reader of this page should know about. */\n readonly related: readonly ComponentName[];\n readonly web?: PlatformDocs;\n readonly native?: NativeDocs;\n}\n"
|
|
121
|
+
"content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n | \"notification-preferences\"\n | \"quota-meter\"\n | \"environment-notice\"\n | \"embed-facade\"\n | \"reviews\"\n | \"margin-layout\"\n | \"analysis-report\"\n | \"status-chip\"\n | \"kind-config-editor\"\n | \"agenda\"\n | \"account-settings\"\n | \"drop-overlay\"\n | \"upload-queue\"\n | \"achievement\"\n | \"anatomy-plate\"\n | \"bird-plate\"\n | \"taped-photo\"\n | \"stuck\"\n | \"doodle\"\n | \"signature\"\n | \"grade-stamp\"\n | \"versus-card\"\n | \"speed-lines\"\n | \"site-cahier\"\n | \"text-style\"\n | \"flock\"\n | \"elephant\"\n | \"footnote\"\n | \"page-index\"\n | \"chapter\"\n | \"specimen-tag\"\n | \"action-bar\"\n | \"action-sheet\"\n | \"activity-feed\"\n | \"alert\"\n | \"app-frame\"\n | \"desktop-window\"\n | \"form-flow\"\n | \"grid\"\n | \"list-detail\"\n | \"state-screen\"\n | \"app-header\"\n | \"app-shell\"\n | \"argument-card\"\n | \"audio-player\"\n | \"auth-layout\"\n | \"avatar\"\n | \"badge\"\n | \"button\"\n | \"captcha\"\n | \"card\"\n | \"card-grid\"\n | \"catalogue-page\"\n | \"changelog-page\"\n | \"chat\"\n | \"checkbox\"\n | \"chip\"\n | \"chip-link\"\n | \"chip-row\"\n | \"choice-grid\"\n | \"cn\"\n | \"code-block\"\n | \"combobox\"\n | \"comparison-table\"\n | \"command\"\n | \"component-page\"\n | \"confirm-button\"\n | \"copy-button\"\n | \"money-input\"\n | \"price-catalogue-editor\"\n | \"promo-code-field\"\n | \"contact-page\"\n | \"continue-prompt\"\n | \"countdown\"\n | \"cover-hero\"\n | \"cta-panel\"\n | \"dashboard-layout\"\n | \"data-table\"\n | \"date-picker\"\n | \"decision-list\"\n | \"description-list\"\n | \"detail-layout\"\n | \"dialog\"\n | \"docs-article-page\"\n | \"docs-hub-page\"\n | \"docs-layout\"\n | \"docs-nav\"\n | \"document-viewer\"\n | \"dropdown-menu\"\n | \"empty-state\"\n | \"engine-flow\"\n | \"error-page\"\n | \"fab\"\n | \"field\"\n | \"file-upload\"\n | \"filter-bar\"\n | \"force-update-screen\"\n | \"form\"\n | \"gallery-page\"\n | \"genui\"\n | \"glossary\"\n | \"glossary-term\"\n | \"glow-card\"\n | \"goal-gauge\"\n | \"header\"\n | \"how-it-works-page\"\n | \"image-cropper\"\n | \"image-viewer\"\n | \"kanban\"\n | \"kbd\"\n | \"kpi-explained\"\n | \"landing-page\"\n | \"landscape\"\n | \"legal-page\"\n | \"link-card\"\n | \"list\"\n | \"loader\"\n | \"longform-page\"\n | \"maintenance-screen\"\n | \"map\"\n | \"markdown\"\n | \"waveform\"\n | \"proposal\"\n | \"qr-code\"\n | \"entity-header\"\n | \"collection-switcher\"\n | \"marketing-layout\"\n | \"marquee\"\n | \"mascot-quote\"\n | \"mascot-state\"\n | \"mascots\"\n | \"match-dialog\"\n | \"media-capture\"\n | \"media-grid\"\n | \"language-switch\"\n | \"media-gallery\"\n | \"media-picker\"\n | \"meter\"\n | \"nav-bar\"\n | \"number-ticker\"\n | \"onboarding\"\n | \"opening-hours\"\n | \"otp-input\"\n | \"page\"\n | \"page-header\"\n | \"page-hero\"\n | \"pagination\"\n | \"permission-prompt\"\n | \"photo-grid\"\n | \"pointer-light\"\n | \"popover\"\n | \"pricing-page\"\n | \"product-page\"\n | \"profile-card\"\n | \"progress\"\n | \"promise-card\"\n | \"pull-to-refresh\"\n | \"retro-tv\"\n | \"shop-gallery\"\n | \"radio-group\"\n | \"router\"\n | \"rail-nav\"\n | \"recipes\"\n | \"screen\"\n | \"scroll-stage\"\n | \"search-field\"\n | \"section-backdrop\"\n | \"segmented\"\n | \"separator\"\n | \"service-card\"\n | \"shop\"\n | \"shop-composer\"\n | \"schema-form\"\n | \"settings-layout\"\n | \"account-menu\"\n | \"showcase\"\n | \"step-showcase\"\n | \"site-footer\"\n | \"sites\"\n | \"skeleton\"\n | \"skip-link\"\n | \"slider\"\n | \"slot-picker\"\n | \"slot\"\n | \"spinner\"\n | \"sticky-action\"\n | \"splash-handoff\"\n | \"split-view\"\n | \"stage-banner\"\n | \"stat\"\n | \"usage\"\n | \"status-page\"\n | \"step-progress\"\n | \"stepper\"\n | \"swipe-deck\"\n | \"swipeable-row\"\n | \"switch\"\n | \"tab-bar\"\n | \"tabs\"\n | \"tag-input\"\n | \"tag-selector\"\n | \"terminal-replay\"\n | \"theme\"\n | \"toast\"\n | \"toc\"\n | \"tooltip\"\n | \"tree-view\"\n | \"txt\"\n | \"update-prompt\"\n | \"verified-badge\"\n | \"vertical-video\"\n | \"video-player\"\n | \"video-trimmer\"\n | \"virtual\"\n | \"wall\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/**\n * Why a component is not on a platform — a decision, never a silence (the parity matrix of ui.krizaka.com/platforms):\n * - `gap` (✗): it belongs there and is not built yet; `issue` is the issue that tracks it (`krizaka/krizaka-ui#275`);\n * - `n/a`: it is not meant for that platform (a site's page block on a phone, a swipe on a desktop); `use` names the\n * component that answers there, when one does.\n */\nexport type Absence =\n | { readonly status: \"gap\"; readonly issue: string; readonly reason: string; readonly use?: undefined }\n | { readonly status: \"n/a\"; readonly reason: string; readonly use?: ComponentName; readonly issue?: undefined };\n\n/**\n * Desktop is the Orazaka Mac app (Tauri 2: the system WebView renders the web components — ADR-002). `web`: the web\n * component runs there as it is; `desktop`: it also has a desktop form (a window's title bar, a denser layout…), said in\n * its documentation; otherwise the absence and why.\n */\nexport type DesktopSupport = \"web\" | \"desktop\" | Absence;\n\n/**\n * The three platforms of Krizaka UI — web · native (React Native, Expo) · desktop — for one component. The side a\n * component has is `platforms`; the side it lacks says why here: `native` is required for (and only for) a web-only\n * component, `web` for a native-only one; `desktop` always. `scripts/registry.test.mjs` fails on a missing decision.\n */\nexport interface Parity {\n readonly web?: Absence;\n readonly native?: Absence;\n readonly desktop: DesktopSupport;\n}\n\n/**\n * `experimental`: created for a filed need (ADR-008 §4), it may change or go in any minor until its first consumer imports it; `adoption`\n * names that consumer's issue. `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"experimental\" | \"stable\" | \"beta\" | \"deprecated\";\n\n/**\n * What a component is for (ADR-008 §3): the twelve domains the documentation, the size budgets and the guards are\n * organised by. The domain is metadata: the entries stay flat (`@krizaka/ui/<name>`). `cahier` is the sites' register\n * (ADR-004): a product never imports it.\n */\nexport type Domain =\n | \"foundations\"\n | \"forms\"\n | \"data-display\"\n | \"navigation-shell\"\n | \"feedback\"\n | \"maps\"\n | \"media\"\n | \"commerce\"\n | \"identity\"\n | \"conversation\"\n | \"page-blocks\"\n | \"cahier\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n /** The version that deprecated it (`3.6.0`). */\n readonly since: string;\n /** The major that removes it (`4.0.0`). */\n readonly removedIn: string;\n /** What replaces it, when a component does. */\n readonly use?: ComponentName;\n /** Why it goes: no product uses it, no planned work needs it. */\n readonly reason: string;\n}\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\ninterface ExampleBase {\n /** The file name, kebab-case (`primary`, `icon-button`). */\n readonly name: string;\n /** A short title (`Primary`, `Icon button`). */\n readonly title: string;\n /** One or two sentences: when this variant is the right one. */\n readonly description: string;\n}\n\n/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n | (ExampleBase & {\n /**\n * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n */\n readonly template: true;\n /** The intent that groups it: why you need this block. */\n readonly purpose: TemplatePurpose;\n /** Why this layout: the user goal it serves, in one sentence. */\n readonly why: string;\n });\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n readonly imports: readonly string[];\n /** The examples, in reading order; the first one is the component's preview. */\n readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n /**\n * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n */\n readonly entry?: string;\n /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n readonly differences: readonly string[];\n /** The React Native entry alone is deprecated while the web one stays (ADR-006 §7); a deprecated component says it once, above. */\n readonly deprecated?: Deprecation;\n}\n\nexport interface KeyboardInteraction {\n /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n readonly keys: string;\n /** What they do. */\n readonly action: string;\n}\n\nexport interface ComponentMeta {\n /** The display name: `Button`, `Dropdown menu`. */\n readonly title: string;\n /** One sentence: what it is. */\n readonly summary: string;\n readonly status: Status;\n /** Required for, and only for, a `deprecated` component. */\n readonly deprecated?: Deprecation;\n readonly category: Category;\n /** What it is for: one of the twelve domains (ADR-008 §3). */\n readonly domain: Domain;\n /** The `<repo>#<n>` issue of its first consumer: required for, and only for, an `experimental` component. */\n readonly adoption?: string;\n /** Must match the sides below: `both` ⇔ `web` and `native`. */\n readonly platforms: Platform;\n /** The platforms it is not on, and why; and its desktop form (see `Parity`). */\n readonly parity: Parity;\n /** When to reach for it: concrete situations, one per item. */\n readonly whenToUse: readonly string[];\n /** When not to — and what to use instead (`use`), when another component is the answer. */\n readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n /** How to use it well: wording, placement, composition. */\n readonly bestPractices: readonly string[];\n readonly accessibility: {\n /** The keyboard, when it does more than Tab and Enter. */\n readonly keyboard: readonly KeyboardInteraction[];\n /** Roles, names and announcements: what the component does, what the app must provide. */\n readonly notes: readonly string[];\n };\n /** The components a reader of this page should know about. */\n readonly related: readonly ComponentName[];\n readonly web?: PlatformDocs;\n readonly native?: NativeDocs;\n}\n"
|
|
120
122
|
}
|
|
121
123
|
],
|
|
122
124
|
"dependencies": [],
|
|
@@ -7,6 +7,8 @@
|
|
|
7
7
|
"status": "beta",
|
|
8
8
|
"deprecated": null,
|
|
9
9
|
"category": "data-display",
|
|
10
|
+
"domain": "data-display",
|
|
11
|
+
"adoption": null,
|
|
10
12
|
"platforms": "both",
|
|
11
13
|
"parity": {
|
|
12
14
|
"web": {
|
|
@@ -185,11 +187,11 @@
|
|
|
185
187
|
},
|
|
186
188
|
{
|
|
187
189
|
"path": "description-list/meta.ts",
|
|
188
|
-
"content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n title: \"Description list\",\n summary: \"Facts about one thing as term and value: stacked, inline like a receipt, or a grid of key figures (`KeyValueGrid`).\",\n status: \"beta\",\n category: \"data-display\",\n platforms: \"both\",\n parity: { desktop: \"web\" },\n whenToUse: [\"A job's details in a side panel.\", \"A payout's or a tip's breakdown.\", \"An account's limits as a grid of figures.\"],\n whenNotToUse: [\n { when: \"For many records.\", use: \"list\" },\n { when: \"For one key figure with its trend.\", use: \"stat\" },\n ],\n bestPractices: [\"Keep the terms short and the values formatted (`@krizaka/intl`).\", \"Inline for amounts that add up; grid for figures to scan.\"],\n accessibility: {\n keyboard: [],\n notes: [\"A `dl`: each term (`dt`) names its value (`dd`).\", \"On React Native each pair is one element, read as “term, value”.\"],\n },\n related: [\"stat\", \"list\", \"card\"],\n web: {\n imports: [\"DescriptionList\", \"KeyValueGrid\"],\n examples: [\n { name: \"job-details\", title: \"Details\", description: \"A job's status, studio, start and credits.\" },\n { name: \"receipt\", title: \"Receipt\", description: \"`layout=\\\"inline\\\"`: where a tip goes.\" },\n { name: \"key-value-grid\", title: \"Key figures\", description: \"`KeyValueGrid`: an account's limits as cards that wrap.\" },\n ],\n },\n native: {\n imports: [\"DescriptionList\"],\n differences: [\"`term` is a string; `layout=\\\"grid\\\"` draws two cards per row.\", \"No `KeyValueGrid`: use `layout=\\\"grid\\\"`.\"],\n examples: [{ name: \"job-details\", title: \"Details\", description: \"Stacked details, then an inline summary.\" }],\n },\n} satisfies ComponentMeta;\n"
|
|
190
|
+
"content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n title: \"Description list\",\n summary: \"Facts about one thing as term and value: stacked, inline like a receipt, or a grid of key figures (`KeyValueGrid`).\",\n status: \"beta\",\n category: \"data-display\",\n domain: \"data-display\",\n platforms: \"both\",\n parity: { desktop: \"web\" },\n whenToUse: [\"A job's details in a side panel.\", \"A payout's or a tip's breakdown.\", \"An account's limits as a grid of figures.\"],\n whenNotToUse: [\n { when: \"For many records.\", use: \"list\" },\n { when: \"For one key figure with its trend.\", use: \"stat\" },\n ],\n bestPractices: [\"Keep the terms short and the values formatted (`@krizaka/intl`).\", \"Inline for amounts that add up; grid for figures to scan.\"],\n accessibility: {\n keyboard: [],\n notes: [\"A `dl`: each term (`dt`) names its value (`dd`).\", \"On React Native each pair is one element, read as “term, value”.\"],\n },\n related: [\"stat\", \"list\", \"card\"],\n web: {\n imports: [\"DescriptionList\", \"KeyValueGrid\"],\n examples: [\n { name: \"job-details\", title: \"Details\", description: \"A job's status, studio, start and credits.\" },\n { name: \"receipt\", title: \"Receipt\", description: \"`layout=\\\"inline\\\"`: where a tip goes.\" },\n { name: \"key-value-grid\", title: \"Key figures\", description: \"`KeyValueGrid`: an account's limits as cards that wrap.\" },\n ],\n },\n native: {\n imports: [\"DescriptionList\"],\n differences: [\"`term` is a string; `layout=\\\"grid\\\"` draws two cards per row.\", \"No `KeyValueGrid`: use `layout=\\\"grid\\\"`.\"],\n examples: [{ name: \"job-details\", title: \"Details\", description: \"Stacked details, then an inline summary.\" }],\n },\n} satisfies ComponentMeta;\n"
|
|
189
191
|
},
|
|
190
192
|
{
|
|
191
193
|
"path": "meta.ts",
|
|
192
|
-
"content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n | \"notification-preferences\"\n | \"quota-meter\"\n | \"environment-notice\"\n | \"embed-facade\"\n | \"reviews\"\n | \"margin-layout\"\n | \"analysis-report\"\n | \"status-chip\"\n | \"kind-config-editor\"\n | \"agenda\"\n | \"account-settings\"\n | \"drop-overlay\"\n | \"upload-queue\"\n | \"achievement\"\n | \"anatomy-plate\"\n | \"bird-plate\"\n | \"taped-photo\"\n | \"stuck\"\n | \"doodle\"\n | \"signature\"\n | \"grade-stamp\"\n | \"versus-card\"\n | \"speed-lines\"\n | \"site-cahier\"\n | \"text-style\"\n | \"flock\"\n | \"elephant\"\n | \"footnote\"\n | \"page-index\"\n | \"chapter\"\n | \"specimen-tag\"\n | \"action-bar\"\n | \"action-sheet\"\n | \"activity-feed\"\n | \"alert\"\n | \"app-frame\"\n | \"desktop-window\"\n | \"form-flow\"\n | \"grid\"\n | \"list-detail\"\n | \"state-screen\"\n | \"app-header\"\n | \"app-shell\"\n | \"argument-card\"\n | \"audio-player\"\n | \"auth-layout\"\n | \"avatar\"\n | \"badge\"\n | \"button\"\n | \"captcha\"\n | \"card\"\n | \"card-grid\"\n | \"catalogue-page\"\n | \"changelog-page\"\n | \"chat\"\n | \"checkbox\"\n | \"chip\"\n | \"chip-link\"\n | \"chip-row\"\n | \"choice-grid\"\n | \"cn\"\n | \"code-block\"\n | \"combobox\"\n | \"comparison-table\"\n | \"command\"\n | \"component-page\"\n | \"confirm-button\"\n | \"copy-button\"\n | \"money-input\"\n | \"price-catalogue-editor\"\n | \"promo-code-field\"\n | \"contact-page\"\n | \"continue-prompt\"\n | \"countdown\"\n | \"cover-hero\"\n | \"cta-panel\"\n | \"dashboard-layout\"\n | \"data-table\"\n | \"date-picker\"\n | \"decision-list\"\n | \"description-list\"\n | \"detail-layout\"\n | \"dialog\"\n | \"docs-article-page\"\n | \"docs-hub-page\"\n | \"docs-layout\"\n | \"docs-nav\"\n | \"document-viewer\"\n | \"dropdown-menu\"\n | \"empty-state\"\n | \"engine-flow\"\n | \"error-page\"\n | \"fab\"\n | \"field\"\n | \"file-upload\"\n | \"filter-bar\"\n | \"force-update-screen\"\n | \"form\"\n | \"gallery-page\"\n | \"genui\"\n | \"glossary\"\n | \"glossary-term\"\n | \"glow-card\"\n | \"goal-gauge\"\n | \"header\"\n | \"how-it-works-page\"\n | \"image-cropper\"\n | \"image-viewer\"\n | \"iso\"\n | \"kanban\"\n | \"kbd\"\n | \"kpi-explained\"\n | \"landing-page\"\n | \"landscape\"\n | \"legal-page\"\n | \"link-card\"\n | \"list\"\n | \"loader\"\n | \"longform-page\"\n | \"maintenance-screen\"\n | \"map\"\n | \"markdown\"\n | \"meta-row\"\n | \"waveform\"\n | \"proposal\"\n | \"qr-code\"\n | \"entity-header\"\n | \"collection-switcher\"\n | \"marketing-layout\"\n | \"marquee\"\n | \"mascot-quote\"\n | \"mascot-state\"\n | \"mascots\"\n | \"match-dialog\"\n | \"media-capture\"\n | \"media-grid\"\n | \"language-switch\"\n | \"media-gallery\"\n | \"media-picker\"\n | \"meter\"\n | \"nav-bar\"\n | \"number-ticker\"\n | \"onboarding\"\n | \"opening-hours\"\n | \"otp-input\"\n | \"page\"\n | \"page-header\"\n | \"page-hero\"\n | \"pagination\"\n | \"permission-prompt\"\n | \"photo-grid\"\n | \"pointer-light\"\n | \"popover\"\n | \"pricing-page\"\n | \"product-page\"\n | \"profile-card\"\n | \"progress\"\n | \"promise-card\"\n | \"pull-to-refresh\"\n | \"retro-tv\"\n | \"shop-gallery\"\n | \"radio-group\"\n | \"router\"\n | \"rail-nav\"\n | \"recipes\"\n | \"screen\"\n | \"scroll-stage\"\n | \"search-field\"\n | \"section-backdrop\"\n | \"segmented\"\n | \"separator\"\n | \"service-card\"\n | \"shop\"\n | \"shop-composer\"\n | \"schema-form\"\n | \"settings-layout\"\n | \"account-menu\"\n | \"showcase\"\n | \"step-showcase\"\n | \"site-footer\"\n | \"sites\"\n | \"skeleton\"\n | \"skip-link\"\n | \"slider\"\n | \"slot-picker\"\n | \"slot\"\n | \"spinner\"\n | \"sticky-action\"\n | \"splash-handoff\"\n | \"split-view\"\n | \"stage-banner\"\n | \"stat\"\n | \"usage\"\n | \"status-page\"\n | \"step-progress\"\n | \"stepper\"\n | \"swipe-deck\"\n | \"swipeable-row\"\n | \"switch\"\n | \"tab-bar\"\n | \"tabs\"\n | \"tag-input\"\n | \"tag-selector\"\n | \"terminal-replay\"\n | \"theme\"\n | \"toast\"\n | \"toc\"\n | \"tooltip\"\n | \"tree-view\"\n | \"txt\"\n | \"update-prompt\"\n | \"verified-badge\"\n | \"vertical-video\"\n | \"video-player\"\n | \"video-trimmer\"\n | \"virtual\"\n | \"wall\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/**\n * Why a component is not on a platform — a decision, never a silence (the parity matrix of ui.krizaka.com/platforms):\n * - `gap` (✗): it belongs there and is not built yet; `issue` is the issue that tracks it (`krizaka/krizaka-ui#275`);\n * - `n/a`: it is not meant for that platform (a site's page block on a phone, a swipe on a desktop); `use` names the\n * component that answers there, when one does.\n */\nexport type Absence =\n | { readonly status: \"gap\"; readonly issue: string; readonly reason: string; readonly use?: undefined }\n | { readonly status: \"n/a\"; readonly reason: string; readonly use?: ComponentName; readonly issue?: undefined };\n\n/**\n * Desktop is the Orazaka Mac app (Tauri 2: the system WebView renders the web components — ADR-002). `web`: the web\n * component runs there as it is; `desktop`: it also has a desktop form (a window's title bar, a denser layout…), said in\n * its documentation; otherwise the absence and why.\n */\nexport type DesktopSupport = \"web\" | \"desktop\" | Absence;\n\n/**\n * The three platforms of Krizaka UI — web · native (React Native, Expo) · desktop — for one component. The side a\n * component has is `platforms`; the side it lacks says why here: `native` is required for (and only for) a web-only\n * component, `web` for a native-only one; `desktop` always. `scripts/registry.test.mjs` fails on a missing decision.\n */\nexport interface Parity {\n readonly web?: Absence;\n readonly native?: Absence;\n readonly desktop: DesktopSupport;\n}\n\n/**\n * `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"stable\" | \"beta\" | \"deprecated\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n /** The version that deprecated it (`3.6.0`). */\n readonly since: string;\n /** The major that removes it (`4.0.0`). */\n readonly removedIn: string;\n /** What replaces it, when a component does. */\n readonly use?: ComponentName;\n /** Why it goes: no product uses it, no planned work needs it. */\n readonly reason: string;\n}\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\ninterface ExampleBase {\n /** The file name, kebab-case (`primary`, `icon-button`). */\n readonly name: string;\n /** A short title (`Primary`, `Icon button`). */\n readonly title: string;\n /** One or two sentences: when this variant is the right one. */\n readonly description: string;\n}\n\n/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n | (ExampleBase & {\n /**\n * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n */\n readonly template: true;\n /** The intent that groups it: why you need this block. */\n readonly purpose: TemplatePurpose;\n /** Why this layout: the user goal it serves, in one sentence. */\n readonly why: string;\n });\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n readonly imports: readonly string[];\n /** The examples, in reading order; the first one is the component's preview. */\n readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n /**\n * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n */\n readonly entry?: string;\n /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n readonly differences: readonly string[];\n /** The React Native entry alone is deprecated while the web one stays (ADR-006 §7); a deprecated component says it once, above. */\n readonly deprecated?: Deprecation;\n}\n\nexport interface KeyboardInteraction {\n /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n readonly keys: string;\n /** What they do. */\n readonly action: string;\n}\n\nexport interface ComponentMeta {\n /** The display name: `Button`, `Dropdown menu`. */\n readonly title: string;\n /** One sentence: what it is. */\n readonly summary: string;\n readonly status: Status;\n /** Required for, and only for, a `deprecated` component. */\n readonly deprecated?: Deprecation;\n readonly category: Category;\n /** Must match the sides below: `both` ⇔ `web` and `native`. */\n readonly platforms: Platform;\n /** The platforms it is not on, and why; and its desktop form (see `Parity`). */\n readonly parity: Parity;\n /** When to reach for it: concrete situations, one per item. */\n readonly whenToUse: readonly string[];\n /** When not to — and what to use instead (`use`), when another component is the answer. */\n readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n /** How to use it well: wording, placement, composition. */\n readonly bestPractices: readonly string[];\n readonly accessibility: {\n /** The keyboard, when it does more than Tab and Enter. */\n readonly keyboard: readonly KeyboardInteraction[];\n /** Roles, names and announcements: what the component does, what the app must provide. */\n readonly notes: readonly string[];\n };\n /** The components a reader of this page should know about. */\n readonly related: readonly ComponentName[];\n readonly web?: PlatformDocs;\n readonly native?: NativeDocs;\n}\n"
|
|
194
|
+
"content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n | \"notification-preferences\"\n | \"quota-meter\"\n | \"environment-notice\"\n | \"embed-facade\"\n | \"reviews\"\n | \"margin-layout\"\n | \"analysis-report\"\n | \"status-chip\"\n | \"kind-config-editor\"\n | \"agenda\"\n | \"account-settings\"\n | \"drop-overlay\"\n | \"upload-queue\"\n | \"achievement\"\n | \"anatomy-plate\"\n | \"bird-plate\"\n | \"taped-photo\"\n | \"stuck\"\n | \"doodle\"\n | \"signature\"\n | \"grade-stamp\"\n | \"versus-card\"\n | \"speed-lines\"\n | \"site-cahier\"\n | \"text-style\"\n | \"flock\"\n | \"elephant\"\n | \"footnote\"\n | \"page-index\"\n | \"chapter\"\n | \"specimen-tag\"\n | \"action-bar\"\n | \"action-sheet\"\n | \"activity-feed\"\n | \"alert\"\n | \"app-frame\"\n | \"desktop-window\"\n | \"form-flow\"\n | \"grid\"\n | \"list-detail\"\n | \"state-screen\"\n | \"app-header\"\n | \"app-shell\"\n | \"argument-card\"\n | \"audio-player\"\n | \"auth-layout\"\n | \"avatar\"\n | \"badge\"\n | \"button\"\n | \"captcha\"\n | \"card\"\n | \"card-grid\"\n | \"catalogue-page\"\n | \"changelog-page\"\n | \"chat\"\n | \"checkbox\"\n | \"chip\"\n | \"chip-link\"\n | \"chip-row\"\n | \"choice-grid\"\n | \"cn\"\n | \"code-block\"\n | \"combobox\"\n | \"comparison-table\"\n | \"command\"\n | \"component-page\"\n | \"confirm-button\"\n | \"copy-button\"\n | \"money-input\"\n | \"price-catalogue-editor\"\n | \"promo-code-field\"\n | \"contact-page\"\n | \"continue-prompt\"\n | \"countdown\"\n | \"cover-hero\"\n | \"cta-panel\"\n | \"dashboard-layout\"\n | \"data-table\"\n | \"date-picker\"\n | \"decision-list\"\n | \"description-list\"\n | \"detail-layout\"\n | \"dialog\"\n | \"docs-article-page\"\n | \"docs-hub-page\"\n | \"docs-layout\"\n | \"docs-nav\"\n | \"document-viewer\"\n | \"dropdown-menu\"\n | \"empty-state\"\n | \"engine-flow\"\n | \"error-page\"\n | \"fab\"\n | \"field\"\n | \"file-upload\"\n | \"filter-bar\"\n | \"force-update-screen\"\n | \"form\"\n | \"gallery-page\"\n | \"genui\"\n | \"glossary\"\n | \"glossary-term\"\n | \"glow-card\"\n | \"goal-gauge\"\n | \"header\"\n | \"how-it-works-page\"\n | \"image-cropper\"\n | \"image-viewer\"\n | \"kanban\"\n | \"kbd\"\n | \"kpi-explained\"\n | \"landing-page\"\n | \"landscape\"\n | \"legal-page\"\n | \"link-card\"\n | \"list\"\n | \"loader\"\n | \"longform-page\"\n | \"maintenance-screen\"\n | \"map\"\n | \"markdown\"\n | \"waveform\"\n | \"proposal\"\n | \"qr-code\"\n | \"entity-header\"\n | \"collection-switcher\"\n | \"marketing-layout\"\n | \"marquee\"\n | \"mascot-quote\"\n | \"mascot-state\"\n | \"mascots\"\n | \"match-dialog\"\n | \"media-capture\"\n | \"media-grid\"\n | \"language-switch\"\n | \"media-gallery\"\n | \"media-picker\"\n | \"meter\"\n | \"nav-bar\"\n | \"number-ticker\"\n | \"onboarding\"\n | \"opening-hours\"\n | \"otp-input\"\n | \"page\"\n | \"page-header\"\n | \"page-hero\"\n | \"pagination\"\n | \"permission-prompt\"\n | \"photo-grid\"\n | \"pointer-light\"\n | \"popover\"\n | \"pricing-page\"\n | \"product-page\"\n | \"profile-card\"\n | \"progress\"\n | \"promise-card\"\n | \"pull-to-refresh\"\n | \"retro-tv\"\n | \"shop-gallery\"\n | \"radio-group\"\n | \"router\"\n | \"rail-nav\"\n | \"recipes\"\n | \"screen\"\n | \"scroll-stage\"\n | \"search-field\"\n | \"section-backdrop\"\n | \"segmented\"\n | \"separator\"\n | \"service-card\"\n | \"shop\"\n | \"shop-composer\"\n | \"schema-form\"\n | \"settings-layout\"\n | \"account-menu\"\n | \"showcase\"\n | \"step-showcase\"\n | \"site-footer\"\n | \"sites\"\n | \"skeleton\"\n | \"skip-link\"\n | \"slider\"\n | \"slot-picker\"\n | \"slot\"\n | \"spinner\"\n | \"sticky-action\"\n | \"splash-handoff\"\n | \"split-view\"\n | \"stage-banner\"\n | \"stat\"\n | \"usage\"\n | \"status-page\"\n | \"step-progress\"\n | \"stepper\"\n | \"swipe-deck\"\n | \"swipeable-row\"\n | \"switch\"\n | \"tab-bar\"\n | \"tabs\"\n | \"tag-input\"\n | \"tag-selector\"\n | \"terminal-replay\"\n | \"theme\"\n | \"toast\"\n | \"toc\"\n | \"tooltip\"\n | \"tree-view\"\n | \"txt\"\n | \"update-prompt\"\n | \"verified-badge\"\n | \"vertical-video\"\n | \"video-player\"\n | \"video-trimmer\"\n | \"virtual\"\n | \"wall\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/**\n * Why a component is not on a platform — a decision, never a silence (the parity matrix of ui.krizaka.com/platforms):\n * - `gap` (✗): it belongs there and is not built yet; `issue` is the issue that tracks it (`krizaka/krizaka-ui#275`);\n * - `n/a`: it is not meant for that platform (a site's page block on a phone, a swipe on a desktop); `use` names the\n * component that answers there, when one does.\n */\nexport type Absence =\n | { readonly status: \"gap\"; readonly issue: string; readonly reason: string; readonly use?: undefined }\n | { readonly status: \"n/a\"; readonly reason: string; readonly use?: ComponentName; readonly issue?: undefined };\n\n/**\n * Desktop is the Orazaka Mac app (Tauri 2: the system WebView renders the web components — ADR-002). `web`: the web\n * component runs there as it is; `desktop`: it also has a desktop form (a window's title bar, a denser layout…), said in\n * its documentation; otherwise the absence and why.\n */\nexport type DesktopSupport = \"web\" | \"desktop\" | Absence;\n\n/**\n * The three platforms of Krizaka UI — web · native (React Native, Expo) · desktop — for one component. The side a\n * component has is `platforms`; the side it lacks says why here: `native` is required for (and only for) a web-only\n * component, `web` for a native-only one; `desktop` always. `scripts/registry.test.mjs` fails on a missing decision.\n */\nexport interface Parity {\n readonly web?: Absence;\n readonly native?: Absence;\n readonly desktop: DesktopSupport;\n}\n\n/**\n * `experimental`: created for a filed need (ADR-008 §4), it may change or go in any minor until its first consumer imports it; `adoption`\n * names that consumer's issue. `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"experimental\" | \"stable\" | \"beta\" | \"deprecated\";\n\n/**\n * What a component is for (ADR-008 §3): the twelve domains the documentation, the size budgets and the guards are\n * organised by. The domain is metadata: the entries stay flat (`@krizaka/ui/<name>`). `cahier` is the sites' register\n * (ADR-004): a product never imports it.\n */\nexport type Domain =\n | \"foundations\"\n | \"forms\"\n | \"data-display\"\n | \"navigation-shell\"\n | \"feedback\"\n | \"maps\"\n | \"media\"\n | \"commerce\"\n | \"identity\"\n | \"conversation\"\n | \"page-blocks\"\n | \"cahier\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n /** The version that deprecated it (`3.6.0`). */\n readonly since: string;\n /** The major that removes it (`4.0.0`). */\n readonly removedIn: string;\n /** What replaces it, when a component does. */\n readonly use?: ComponentName;\n /** Why it goes: no product uses it, no planned work needs it. */\n readonly reason: string;\n}\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\ninterface ExampleBase {\n /** The file name, kebab-case (`primary`, `icon-button`). */\n readonly name: string;\n /** A short title (`Primary`, `Icon button`). */\n readonly title: string;\n /** One or two sentences: when this variant is the right one. */\n readonly description: string;\n}\n\n/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n | (ExampleBase & {\n /**\n * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n */\n readonly template: true;\n /** The intent that groups it: why you need this block. */\n readonly purpose: TemplatePurpose;\n /** Why this layout: the user goal it serves, in one sentence. */\n readonly why: string;\n });\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n readonly imports: readonly string[];\n /** The examples, in reading order; the first one is the component's preview. */\n readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n /**\n * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n */\n readonly entry?: string;\n /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n readonly differences: readonly string[];\n /** The React Native entry alone is deprecated while the web one stays (ADR-006 §7); a deprecated component says it once, above. */\n readonly deprecated?: Deprecation;\n}\n\nexport interface KeyboardInteraction {\n /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n readonly keys: string;\n /** What they do. */\n readonly action: string;\n}\n\nexport interface ComponentMeta {\n /** The display name: `Button`, `Dropdown menu`. */\n readonly title: string;\n /** One sentence: what it is. */\n readonly summary: string;\n readonly status: Status;\n /** Required for, and only for, a `deprecated` component. */\n readonly deprecated?: Deprecation;\n readonly category: Category;\n /** What it is for: one of the twelve domains (ADR-008 §3). */\n readonly domain: Domain;\n /** The `<repo>#<n>` issue of its first consumer: required for, and only for, an `experimental` component. */\n readonly adoption?: string;\n /** Must match the sides below: `both` ⇔ `web` and `native`. */\n readonly platforms: Platform;\n /** The platforms it is not on, and why; and its desktop form (see `Parity`). */\n readonly parity: Parity;\n /** When to reach for it: concrete situations, one per item. */\n readonly whenToUse: readonly string[];\n /** When not to — and what to use instead (`use`), when another component is the answer. */\n readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n /** How to use it well: wording, placement, composition. */\n readonly bestPractices: readonly string[];\n readonly accessibility: {\n /** The keyboard, when it does more than Tab and Enter. */\n readonly keyboard: readonly KeyboardInteraction[];\n /** Roles, names and announcements: what the component does, what the app must provide. */\n readonly notes: readonly string[];\n };\n /** The components a reader of this page should know about. */\n readonly related: readonly ComponentName[];\n readonly web?: PlatformDocs;\n readonly native?: NativeDocs;\n}\n"
|
|
193
195
|
}
|
|
194
196
|
],
|
|
195
197
|
"dependencies": [
|