@krizaka/ui 4.4.0 → 4.5.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 +1 -0
- package/dist/account-menu.d.ts +1 -1
- package/dist/account-menu.js +1 -1
- package/dist/account-menu.js.map +1 -1
- package/dist/account-settings.d.ts +1 -1
- package/dist/account-settings.js +13 -6
- package/dist/account-settings.js.map +1 -1
- package/dist/agenda.d.ts +1 -1
- package/dist/agenda.js +2 -1
- package/dist/agenda.js.map +1 -1
- package/dist/analysis-report.js +19 -11
- package/dist/analysis-report.js.map +1 -1
- package/dist/app-frame.d.ts +1 -1
- package/dist/app-frame.js.map +1 -1
- package/dist/app-header/search.js +2 -2
- package/dist/app-header/search.js.map +1 -1
- package/dist/avatar/defaults.js +3 -1
- package/dist/avatar/defaults.js.map +1 -1
- package/dist/avatar.js +3 -1
- package/dist/avatar.js.map +1 -1
- package/dist/bird-plate.js +8 -2
- package/dist/bird-plate.js.map +1 -1
- package/dist/chapter.js +7 -4
- package/dist/chapter.js.map +1 -1
- package/dist/chat.js +1 -1
- package/dist/chip.d.ts +1 -1
- package/dist/chip.js +1 -1
- package/dist/{chunk-SNSQLGGS.js → chunk-5VZ37TY3.js} +1 -1
- package/dist/{chunk-XWJDBQU7.js.map → chunk-5VZ37TY3.js.map} +1 -1
- package/dist/{chunk-MTVX4RRF.js → chunk-HP7BDMVK.js} +11 -3
- package/dist/chunk-HP7BDMVK.js.map +1 -0
- package/dist/{chunk-PK3L6WQT.js → chunk-LNAAWT4Y.js} +4 -2
- package/dist/{chunk-PK3L6WQT.js.map → chunk-LNAAWT4Y.js.map} +1 -1
- package/dist/{chunk-UIP3WX5O.js → chunk-MDSP7DJR.js} +2 -2
- package/dist/chunk-MDSP7DJR.js.map +1 -0
- package/dist/{chunk-IEGTRCDI.js → chunk-NQENOT6L.js} +2 -2
- package/dist/{chunk-IEGTRCDI.js.map → chunk-NQENOT6L.js.map} +1 -1
- package/dist/{chunk-FM42KOAU.js → chunk-P7AFIKWG.js} +5 -3
- package/dist/chunk-P7AFIKWG.js.map +1 -0
- package/dist/{chunk-BCD2CRFG.js → chunk-PJNR4NTS.js} +2 -2
- package/dist/chunk-PJNR4NTS.js.map +1 -0
- package/dist/{chunk-ZFR6ZNXD.js → chunk-PVQ2KKPZ.js} +1 -1
- package/dist/chunk-PVQ2KKPZ.js.map +1 -0
- package/dist/{chunk-U4XTZMB7.js → chunk-QA3WETWT.js} +1 -1
- package/dist/{chunk-U4XTZMB7.js.map → chunk-QA3WETWT.js.map} +1 -1
- package/dist/{chunk-YXETEQQJ.js → chunk-SG2RKUVJ.js} +2 -2
- package/dist/{chunk-EOWV6BNQ.js → chunk-TXFX4PMN.js} +4 -2
- package/dist/{chunk-EOWV6BNQ.js.map → chunk-TXFX4PMN.js.map} +1 -1
- package/dist/{chunk-XWJDBQU7.js → chunk-V5RO6JYI.js} +1 -1
- package/dist/{chunk-SNSQLGGS.js.map → chunk-V5RO6JYI.js.map} +1 -1
- package/dist/{chunk-VUD4IEVJ.js → chunk-VZ6ZALIJ.js} +1 -1
- package/dist/chunk-VZ6ZALIJ.js.map +1 -0
- package/dist/{chunk-2DHL7NJW.js → chunk-XVRKKYWU.js} +5 -3
- package/dist/{chunk-2DHL7NJW.js.map → chunk-XVRKKYWU.js.map} +1 -1
- package/dist/{chunk-CDNOT2KR.js → chunk-YTYNKMNS.js} +1 -1
- package/dist/chunk-YTYNKMNS.js.map +1 -0
- package/dist/code-block.js.map +1 -1
- package/dist/columns.d.ts +132 -0
- package/dist/columns.js +89 -0
- package/dist/columns.js.map +1 -0
- package/dist/combobox.js +2 -2
- package/dist/copy-button.js +2 -2
- package/dist/copy-button.js.map +1 -1
- package/dist/data-table.js +3 -3
- package/dist/desktop-window.d.ts +1 -1
- package/dist/desktop-window.js +3 -1
- package/dist/desktop-window.js.map +1 -1
- package/dist/drop-overlay.js +8 -8
- package/dist/drop-overlay.js.map +1 -1
- package/dist/elephant.d.ts +1 -1
- package/dist/elephant.js.map +1 -1
- package/dist/embed-facade.d.ts +1 -1
- package/dist/embed-facade.js +3 -1
- package/dist/embed-facade.js.map +1 -1
- package/dist/engine-flow.js +7 -2
- package/dist/engine-flow.js.map +1 -1
- package/dist/entity-header.js +9 -3
- package/dist/entity-header.js.map +1 -1
- package/dist/file-upload.d.ts +1 -1
- package/dist/file-upload.js.map +1 -1
- package/dist/filter-bar.d.ts +4 -4
- package/dist/filter-bar.js +2 -2
- package/dist/flock.js +9 -6
- package/dist/flock.js.map +1 -1
- package/dist/form.d.ts +3 -3
- package/dist/form.js.map +1 -1
- package/dist/genui.js +3 -3
- package/dist/glossary-term.d.ts +1 -1
- package/dist/glossary-term.js.map +1 -1
- package/dist/glossary.d.ts +1 -1
- package/dist/glossary.js.map +1 -1
- package/dist/identity-card.js +1 -1
- package/dist/index.js +1 -1
- package/dist/kind-config-editor.d.ts +2 -2
- package/dist/kind-config-editor.js +1 -1
- package/dist/kind-config-editor.js.map +1 -1
- package/dist/kpi-explained.d.ts +1 -1
- package/dist/kpi-explained.js +4 -4
- package/dist/kpi-explained.js.map +1 -1
- package/dist/landing-page.js +1 -1
- package/dist/{lightbox-Q45BZ3HW.js → lightbox-MRB2YZEP.js} +1 -1
- package/dist/lightbox-MRB2YZEP.js.map +1 -0
- package/dist/map/cards.js +4 -2
- package/dist/map/cards.js.map +1 -1
- package/dist/map/pin.js +2 -1
- package/dist/map/pin.js.map +1 -1
- package/dist/map.d.ts +1 -1
- package/dist/map.js.map +1 -1
- package/dist/mascot-quote.js +1 -1
- package/dist/mascot-state.js +1 -1
- package/dist/mascots.js +1 -1
- package/dist/match-dialog.js +1 -1
- package/dist/motion.d.ts +1 -1
- package/dist/motion.js.map +1 -1
- package/dist/native/form.d.ts +3 -3
- package/dist/native/form.js.map +1 -1
- package/dist/native/markdown.d.ts +1 -1
- package/dist/native/markdown.js.map +1 -1
- package/dist/native/vertical-video.js.map +1 -1
- package/dist/native.d.ts +12 -12
- package/dist/native.js +12 -7
- package/dist/native.js.map +1 -1
- package/dist/nav-bar.d.ts +2 -2
- package/dist/nav-bar.js +1 -1
- package/dist/nav-bar.js.map +1 -1
- package/dist/next-actions.d.ts +1 -1
- package/dist/next-actions.js.map +1 -1
- package/dist/notification-preferences.d.ts +1 -1
- package/dist/notification-preferences.js +5 -2
- package/dist/notification-preferences.js.map +1 -1
- package/dist/page-index.js +2 -2
- package/dist/page-index.js.map +1 -1
- package/dist/product-page.js +1 -1
- package/dist/promo-code-field.d.ts +1 -1
- package/dist/promo-code-field.js.map +1 -1
- package/dist/qr-code.d.ts +1 -1
- package/dist/qr-code.js +1 -1
- package/dist/rail-nav.js +3 -3
- package/dist/rail-nav.js.map +1 -1
- package/dist/retro-tv.d.ts +1 -1
- package/dist/retro-tv.js.map +1 -1
- package/dist/reviews.d.ts +2 -2
- package/dist/reviews.js.map +1 -1
- package/dist/router.d.ts +1 -1
- package/dist/router.js +8 -8
- package/dist/router.js.map +1 -1
- package/dist/{schema-CL7t7xqb.d.ts → schema-Dd05m48Q.d.ts} +9 -9
- package/dist/service-card.js +22 -13
- package/dist/service-card.js.map +1 -1
- package/dist/settings-layout.js +1 -1
- package/dist/shop/booking.js.map +1 -1
- package/dist/shop/gallery.js +7 -6
- package/dist/shop/gallery.js.map +1 -1
- package/dist/shop/hero.js.map +1 -1
- package/dist/shop/look.d.ts +2 -2
- package/dist/shop/look.js +1 -1
- package/dist/shop/look.js.map +1 -1
- package/dist/shop/map-gate.d.ts +1 -1
- package/dist/shop/map-gate.js +2 -2
- package/dist/shop/map-gate.js.map +1 -1
- package/dist/shop/services.js.map +1 -1
- package/dist/shop-composer.d.ts +10 -10
- package/dist/shop-composer.js +27 -14
- package/dist/shop-composer.js.map +1 -1
- package/dist/shop-gallery.js +1 -1
- package/dist/shop.d.ts +2 -2
- package/dist/shop.js +2 -2
- package/dist/shop.js.map +1 -1
- package/dist/signature.js +2 -1
- package/dist/signature.js.map +1 -1
- package/dist/site-cahier.js +7 -3
- package/dist/site-cahier.js.map +1 -1
- package/dist/site-footer.js +6 -2
- package/dist/site-footer.js.map +1 -1
- package/dist/slot-picker.js +5 -2
- package/dist/slot-picker.js.map +1 -1
- package/dist/stat.js +1 -1
- package/dist/status-chip.d.ts +1 -1
- package/dist/status-chip.js.map +1 -1
- package/dist/tabs.js.map +1 -1
- package/dist/tag-input.js +2 -2
- package/dist/tag-selector.js +1 -1
- package/dist/text-style.js +4 -3
- package/dist/text-style.js.map +1 -1
- package/dist/usage.js +8 -3
- package/dist/usage.js.map +1 -1
- package/dist/versus-card.js +1 -1
- package/dist/versus-card.js.map +1 -1
- package/dist/vertical-video.js +1 -1
- package/dist/vertical-video.js.map +1 -1
- package/dist/virtual.d.ts +3 -3
- package/dist/wall.d.ts +4 -4
- package/dist/wall.js +1 -1
- package/dist/wall.js.map +1 -1
- package/package.json +20 -6
- package/registry/account-menu.json +2 -2
- package/registry/account-settings.json +3 -3
- package/registry/achievement.json +1 -1
- package/registry/action-bar.json +1 -1
- package/registry/activity-feed.json +1 -1
- package/registry/agenda.json +2 -2
- package/registry/alert.json +1 -1
- package/registry/analysis-report.json +3 -3
- package/registry/anatomy-plate.json +1 -1
- package/registry/app-frame.json +4 -4
- package/registry/app-header.json +2 -2
- package/registry/app-shell.json +1 -1
- package/registry/argument-card.json +1 -1
- package/registry/auth-layout.json +1 -1
- package/registry/avatar.json +2 -2
- package/registry/badge.json +3 -3
- package/registry/bird-plate.json +2 -2
- package/registry/button.json +1 -1
- package/registry/captcha.json +1 -1
- package/registry/card-grid.json +1 -1
- package/registry/card.json +1 -1
- package/registry/catalogue-page.json +1 -1
- package/registry/changelog-page.json +1 -1
- package/registry/chapter.json +2 -2
- package/registry/chat.json +1 -1
- package/registry/checkbox.json +1 -1
- package/registry/chip-link.json +1 -1
- package/registry/chip-row.json +1 -1
- package/registry/chip.json +2 -2
- package/registry/choice-grid.json +1 -1
- package/registry/code-block.json +1 -1
- package/registry/collection-switcher.json +1 -1
- package/registry/columns.json +319 -0
- package/registry/combobox.json +1 -1
- package/registry/command.json +1 -1
- package/registry/comparison-table.json +1 -1
- package/registry/component-page.json +1 -1
- package/registry/confirm-button.json +1 -1
- package/registry/contact-page.json +1 -1
- package/registry/continue-prompt.json +1 -1
- package/registry/copy-button.json +2 -2
- package/registry/countdown.json +1 -1
- package/registry/cover-hero.json +1 -1
- package/registry/cta-panel.json +1 -1
- package/registry/dashboard-layout.json +1 -1
- package/registry/data-table.json +2 -2
- package/registry/date-picker.json +1 -1
- package/registry/decision-list.json +1 -1
- package/registry/description-list.json +1 -1
- package/registry/desktop-window.json +2 -2
- package/registry/detail-layout.json +1 -1
- package/registry/dialog.json +1 -1
- package/registry/docs-article-page.json +1 -1
- package/registry/docs-hub-page.json +1 -1
- package/registry/docs-layout.json +1 -1
- package/registry/docs-nav.json +1 -1
- package/registry/document-viewer.json +1 -1
- package/registry/doodle.json +1 -1
- package/registry/drop-overlay.json +2 -2
- package/registry/dropdown-menu.json +1 -1
- package/registry/elephant.json +2 -2
- package/registry/embed-facade.json +3 -3
- package/registry/empty-state.json +1 -1
- package/registry/engine-flow.json +3 -3
- package/registry/entity-header.json +2 -2
- package/registry/environment-notice.json +1 -1
- package/registry/error-page.json +1 -1
- package/registry/examples/columns/columns.d.ts +4 -0
- package/registry/examples/columns/columns.js +21 -0
- package/registry/examples/columns/columns.tsx +18 -0
- package/registry/examples/columns/photos.d.ts +4 -0
- package/registry/examples/columns/photos.js +12 -0
- package/registry/examples/columns/photos.tsx +16 -0
- package/registry/examples/columns/stats.d.ts +4 -0
- package/registry/examples/columns/stats.js +20 -0
- package/registry/examples/columns/stats.tsx +22 -0
- package/registry/field.json +1 -1
- package/registry/file-upload.json +2 -2
- package/registry/filter-bar.json +2 -2
- package/registry/flock.json +3 -3
- package/registry/footnote.json +1 -1
- package/registry/force-update-screen.json +1 -1
- package/registry/form.json +8 -8
- package/registry/gallery-page.json +1 -1
- package/registry/genui.json +1 -1
- package/registry/glossary-term.json +2 -2
- package/registry/glossary.json +2 -2
- package/registry/glow-card.json +1 -1
- package/registry/goal-gauge.json +1 -1
- package/registry/grade-stamp.json +1 -1
- package/registry/grid.json +4 -3
- package/registry/identity-card.json +1 -1
- package/registry/image-cropper.json +1 -1
- package/registry/index.json +40 -9
- package/registry/kanban.json +1 -1
- package/registry/kbd.json +1 -1
- package/registry/kind-config-editor.json +2 -2
- package/registry/kpi-explained.json +2 -2
- package/registry/landing-page.json +1 -1
- package/registry/landscape.json +1 -1
- package/registry/language-switch.json +1 -1
- package/registry/legal-page.json +1 -1
- package/registry/link-card.json +1 -1
- package/registry/list.json +1 -1
- package/registry/loader.json +1 -1
- package/registry/longform-page.json +1 -1
- package/registry/maintenance-screen.json +1 -1
- package/registry/map.json +5 -5
- package/registry/margin-layout.json +1 -1
- package/registry/markdown.json +1 -1
- package/registry/marketing-layout.json +1 -1
- package/registry/mascot-quote.json +1 -1
- package/registry/mascot-state.json +2 -2
- package/registry/mascots.json +3 -3
- package/registry/match-dialog.json +1 -1
- package/registry/media-capture.json +1 -1
- package/registry/media-gallery.json +1 -1
- package/registry/meter.json +1 -1
- package/registry/money-input.json +1 -1
- package/registry/nav-bar.json +5 -5
- package/registry/next-actions.json +2 -2
- package/registry/notification-preferences.json +2 -2
- package/registry/number-ticker.json +1 -1
- package/registry/opening-hours.json +1 -1
- package/registry/page-header.json +1 -1
- package/registry/page-hero.json +1 -1
- package/registry/page-index.json +2 -2
- package/registry/page.json +2 -2
- package/registry/pagination.json +1 -1
- package/registry/pointer-light.json +1 -1
- package/registry/popover.json +1 -1
- package/registry/price-catalogue-editor.json +1 -1
- package/registry/pricing-page.json +1 -1
- package/registry/product-page.json +1 -1
- package/registry/profile-card.json +1 -1
- package/registry/progress.json +1 -1
- package/registry/promise-card.json +1 -1
- package/registry/promo-code-field.json +2 -2
- package/registry/proposal.json +1 -1
- package/registry/qr-code.json +3 -3
- package/registry/quota-meter.json +1 -1
- package/registry/radio-group.json +1 -1
- package/registry/rail-nav.json +4 -4
- package/registry/recipes.json +1 -1
- package/registry/retro-tv.json +2 -2
- package/registry/reviews.json +2 -2
- package/registry/router.json +2 -2
- package/registry/schema-form.json +1 -1
- package/registry/scroll-stage.json +1 -1
- package/registry/search-field.json +1 -1
- package/registry/section-backdrop.json +1 -1
- package/registry/separator.json +1 -1
- package/registry/service-card.json +2 -2
- package/registry/settings-layout.json +2 -2
- package/registry/shop-composer.json +8 -8
- package/registry/shop-gallery.json +2 -2
- package/registry/shop.json +12 -12
- package/registry/showcase.json +1 -1
- package/registry/signature.json +2 -2
- package/registry/site-cahier.json +2 -2
- package/registry/site-footer.json +4 -4
- package/registry/sites.json +1 -1
- package/registry/skeleton.json +1 -1
- package/registry/skip-link.json +1 -1
- package/registry/slider.json +1 -1
- package/registry/slot-picker.json +2 -2
- package/registry/slot.json +1 -1
- package/registry/specimen-tag.json +1 -1
- package/registry/speed-lines.json +1 -1
- package/registry/spinner.json +1 -1
- package/registry/split-view.json +1 -1
- package/registry/stage-banner.json +1 -1
- package/registry/stat.json +2 -2
- package/registry/status-chip.json +2 -2
- package/registry/status-page.json +1 -1
- package/registry/step-progress.json +1 -1
- package/registry/step-showcase.json +1 -1
- package/registry/stepper.json +1 -1
- package/registry/sticky-action.json +1 -1
- package/registry/stuck.json +1 -1
- package/registry/swipe-deck.json +1 -1
- package/registry/switch.json +1 -1
- package/registry/tabs.json +2 -2
- package/registry/tag-input.json +1 -1
- package/registry/tag-selector.json +1 -1
- package/registry/taped-photo.json +1 -1
- package/registry/terminal-replay.json +1 -1
- package/registry/text-style.json +2 -2
- package/registry/theme.json +1 -1
- package/registry/toast.json +1 -1
- package/registry/toc.json +1 -1
- package/registry/tooltip.json +1 -1
- package/registry/tree-view.json +1 -1
- package/registry/update-prompt.json +1 -1
- package/registry/upload-queue.json +1 -1
- package/registry/usage.json +3 -3
- package/registry/verified-badge.json +1 -1
- package/registry/versus-card.json +2 -2
- package/registry/vertical-video.json +2 -2
- package/registry/video-player.json +1 -1
- package/registry/video-trimmer.json +1 -1
- package/registry/virtual.json +1 -1
- package/registry/wall.json +6 -6
- package/registry/waveform.json +3 -3
- package/dist/chunk-BCD2CRFG.js.map +0 -1
- package/dist/chunk-CDNOT2KR.js.map +0 -1
- package/dist/chunk-FM42KOAU.js.map +0 -1
- package/dist/chunk-MTVX4RRF.js.map +0 -1
- package/dist/chunk-UIP3WX5O.js.map +0 -1
- package/dist/chunk-VUD4IEVJ.js.map +0 -1
- package/dist/chunk-ZFR6ZNXD.js.map +0 -1
- package/dist/lightbox-Q45BZ3HW.js.map +0 -1
- /package/dist/{chunk-YXETEQQJ.js.map → chunk-SG2RKUVJ.js.map} +0 -0
package/registry/qr-code.json
CHANGED
|
@@ -238,11 +238,11 @@
|
|
|
238
238
|
},
|
|
239
239
|
{
|
|
240
240
|
"path": "meta.ts",
|
|
241
|
-
"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 | \"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 | \"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 | \"identity-card\"\n | \"entity-header\"\n | \"collection-switcher\"\n | \"marketing-layout\"\n | \"mascot-quote\"\n | \"mascot-state\"\n | \"mascots\"\n | \"match-dialog\"\n | \"media-capture\"\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 | \"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 Sovkora 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 thirteen 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 | \"abuse\"\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"
|
|
241
|
+
"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 | \"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 | \"columns\"\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 | \"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 | \"identity-card\"\n | \"entity-header\"\n | \"collection-switcher\"\n | \"marketing-layout\"\n | \"mascot-quote\"\n | \"mascot-state\"\n | \"mascots\"\n | \"match-dialog\"\n | \"media-capture\"\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 | \"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 Sovkora 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 thirteen 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 | \"abuse\"\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"
|
|
242
242
|
},
|
|
243
243
|
{
|
|
244
244
|
"path": "qr-code/encode.ts",
|
|
245
|
-
"content": "// The QR encoder: a string in, a square of dark/light modules out. Pure, offline, no dependency, shared by the web\n// and the native drawing. Byte mode (UTF-8), versions 1-40, the four error-correction levels, the eight masks chosen\n// by the standard's penalty rules (ISO/IEC 18004). `qr-code.test.tsx` decodes what it draws, version by version.\n\nexport type QrLevel = \"L\" | \"M\" | \"Q\" | \"H\";\n\n/** The square of modules, row by row: `true` is dark. */\nexport type QrMatrix = readonly (readonly boolean[])[];\n\nconst LEVEL_INDEX: Record<QrLevel, number> = { L: 0, M: 1, Q: 2, H: 3 };\nconst LEVEL_BITS: Record<QrLevel, number> = { L: 1, M: 0, Q: 3, H: 2 };\n\n// Error-correction codewords per block, and number of blocks, by level (L, M, Q, H) then version (index 0 is unused).\nconst ECC_PER_BLOCK = [\n [-1, 7, 10, 15, 20, 26, 18, 20, 24, 30, 18, 20, 24, 26, 30, 22, 24, 28, 30, 28, 28, 28, 28, 30, 30, 26, 28, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30],\n [-1, 10, 16, 26, 18, 24, 16, 18, 22, 22, 26, 30, 22, 22, 24, 24, 28, 28, 26, 26, 26, 26, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28],\n [-1, 13, 22, 18, 26, 18, 24, 18, 22, 20, 24, 28, 26, 24, 20, 30, 24, 28, 28, 26, 30, 28, 30, 30, 30, 30, 28, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30],\n [-1, 17, 28, 22, 16, 22, 28, 26, 26, 24, 28, 24, 28, 22, 24, 24, 30, 28, 28, 26, 28, 30, 24, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30],\n] as const;\nconst BLOCKS = [\n [-1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 4, 4, 4, 4, 4, 6, 6, 6, 6, 7, 8, 8, 9, 9, 10, 12, 12, 12, 13, 14, 15, 16, 17, 18, 19, 19, 20, 21, 22, 24, 25],\n [-1, 1, 1, 1, 2, 2, 4, 4, 4, 5, 5, 5, 8, 9, 9, 10, 10, 11, 13, 14, 16, 17, 17, 18, 20, 21, 23, 25, 26, 28, 29, 31, 33, 35, 37, 38, 40, 43, 45, 47, 49],\n [-1, 1, 1, 2, 2, 4, 4, 6, 6, 8, 8, 8, 10, 12, 16, 12, 17, 16, 18, 21, 20, 23, 23, 25, 27, 29, 34, 34, 35, 38, 40, 43, 45, 48, 51, 53, 56, 59, 62, 65, 68],\n [-1, 1, 1, 2, 4, 4, 4, 5, 6, 8, 8, 11, 11, 16, 16, 18, 16, 19, 21, 25, 25, 25, 34, 30, 32, 35, 37, 40, 42, 45, 48, 51, 54, 57, 60, 63, 66, 70, 74, 77, 81],\n] as const;\n\n/** Data modules of a version (everything but the finder, timing, alignment, format and version patterns). */\nfunction rawModules(version: number): number {\n let result = (16 * version + 128) * version + 64;\n if (version >= 2) {\n const align = Math.floor(version / 7) + 2;\n result -= (25 * align - 10) * align - 55;\n if (version >= 7) result -= 36;\n }\n return result;\n}\n\nfunction dataCodewords(version: number, level: QrLevel): number {\n const l = LEVEL_INDEX[level];\n return Math.floor(rawModules(version) / 8) - ECC_PER_BLOCK[l]![version]! * BLOCKS[l]![version]!;\n}\n\nexport function utf8(text: string): number[] {\n return [...new TextEncoder().encode(text)];\n}\n\n// Reed-Solomon over GF(256), polynomial 0x11D.\nfunction gfMultiply(x: number, y: number): number {\n let z = 0;\n for (let i = 7; i >= 0; i--) {\n z = (z << 1) ^ ((z >>> 7) * 0x11d);\n z ^= ((y >>> i) & 1) * x;\n }\n return z;\n}\n\nfunction divisor(degree: number): number[] {\n const result = new Array<number>(degree).fill(0);\n result[degree - 1] = 1;\n let root = 1;\n for (let i = 0; i < degree; i++) {\n for (let j = 0; j < degree; j++) {\n result[j] = gfMultiply(result[j]!, root);\n if (j + 1 < degree) result[j] = result[j]! ^ result[j + 1]!;\n }\n root = gfMultiply(root, 0x02);\n }\n return result;\n}\n\nfunction remainder(data: readonly number[], div: readonly number[]): number[] {\n const result = div.map(() => 0);\n for (const b of data) {\n const factor = b ^ result.shift()!;\n result.push(0);\n div.forEach((coef, i) => {\n result[i] = result[i]! ^ gfMultiply(coef, factor);\n });\n }\n return result;\n}\n\nfunction pushBits(bits: number[], value: number, count: number) {\n for (let i = count - 1; i >= 0; i--) bits.push((value >>> i) & 1);\n}\n\n/** The codewords of the message: mode, length, bytes, terminator, padding, then blocks interleaved with their ECC. */\nfunction codewords(bytes: readonly number[], version: number, level: QrLevel): number[] {\n const bits: number[] = [];\n pushBits(bits, 0b0100, 4);\n pushBits(bits, bytes.length, version <= 9 ? 8 : 16);\n for (const b of bytes) pushBits(bits, b, 8);\n const capacity = dataCodewords(version, level) * 8;\n pushBits(bits, 0, Math.min(4, capacity - bits.length));\n pushBits(bits, 0, (8 - (bits.length % 8)) % 8);\n let pad = 0xec;\n while (bits.length < capacity) {\n pushBits(bits, pad, 8);\n pad ^= 0xec ^ 0x11;\n }\n const data: number[] = [];\n for (let i = 0; i < bits.length; i += 8) data.push(parseInt(bits.slice(i, i + 8).join(\"\"), 2));\n\n const l = LEVEL_INDEX[level];\n const blocks = BLOCKS[l]![version]!;\n const eccLen = ECC_PER_BLOCK[l]![version]!;\n const shortBlocks = blocks - (Math.floor(rawModules(version) / 8) % blocks);\n const shortLen = Math.floor(rawModules(version) / 8 / blocks) - eccLen;\n const div = divisor(eccLen);\n const parts: { data: number[]; ecc: number[] }[] = [];\n for (let i = 0, k = 0; i < blocks; i++) {\n const chunk = data.slice(k, k + shortLen + (i < shortBlocks ? 0 : 1));\n k += chunk.length;\n parts.push({ data: chunk, ecc: remainder(chunk, div) });\n }\n const out: number[] = [];\n for (let i = 0; i <= shortLen; i++) parts.forEach((p) => i < p.data.length && out.push(p.data[i]!));\n for (let i = 0; i < eccLen; i++) parts.forEach((p) => out.push(p.ecc[i]!));\n return out;\n}\n\nfunction alignmentPositions(version: number): number[] {\n if (version === 1) return [];\n const count = Math.floor(version / 7) + 2;\n const step = version === 32 ? 26 : Math.ceil((version * 4 + 4) / (count * 2 - 2)) * 2;\n const result = [6];\n let pos = version * 4 + 10;\n while (result.length < count) {\n result.splice(1, 0, pos);\n pos -= step;\n }\n return result;\n}\n\ntype Grid = { size: number; dark: boolean[][]; fn: boolean[][] };\n\nfunction drawFunctionPatterns(version: number, level: QrLevel): Grid {\n const size = version * 4 + 17;\n const dark = Array.from({ length: size }, () => new Array<boolean>(size).fill(false));\n const fn = Array.from({ length: size }, () => new Array<boolean>(size).fill(false));\n const set = (x: number, y: number, on: boolean) => {\n dark[y]![x] = on;\n fn[y]![x] = true;\n };\n for (let i = 0; i < size; i++) {\n set(6, i, i % 2 === 0);\n set(i, 6, i % 2 === 0);\n }\n const finder = (cx: number, cy: number) => {\n for (let dy = -4; dy <= 4; dy++)\n for (let dx = -4; dx <= 4; dx++) {\n const x = cx + dx;\n const y = cy + dy;\n if (x < 0 || x >= size || y < 0 || y >= size) continue;\n const dist = Math.max(Math.abs(dx), Math.abs(dy));\n set(x, y, dist !== 2 && dist !== 4);\n }\n };\n finder(3, 3);\n finder(size - 4, 3);\n finder(3, size - 4);\n const align = alignmentPositions(version);\n align.forEach((cx, i) =>\n align.forEach((cy, j) => {\n if ((i === 0 && j === 0) || (i === 0 && j === align.length - 1) || (i === align.length - 1 && j === 0)) return;\n for (let dy = -2; dy <= 2; dy++) for (let dx = -2; dx <= 2; dx++) set(cx + dx, cy + dy, Math.max(Math.abs(dx), Math.abs(dy)) !== 1);\n }),\n );\n drawFormat(dark, fn, size, level, 0);\n if (version >= 7) {\n let rem = version;\n for (let i = 0; i < 12; i++) rem = (rem << 1) ^ ((rem >>> 11) * 0x1f25);\n const bits = (version << 12) | rem;\n for (let i = 0; i < 18; i++) {\n const on = ((bits >>> i) & 1) !== 0;\n const a = size - 11 + (i % 3);\n const b = Math.floor(i / 3);\n set(a, b, on);\n set(b, a, on);\n }\n }\n return { size, dark, fn };\n}\n\nfunction drawFormat(dark: boolean[][], fn: boolean[][], size: number, level: QrLevel, mask: number) {\n const data = (LEVEL_BITS[level] << 3) | mask;\n let rem = data;\n for (let i = 0; i < 10; i++) rem = (rem << 1) ^ ((rem >>> 9) * 0x537);\n const bits = ((data << 10) | rem) ^ 0x5412;\n const bit = (i: number) => ((bits >>> i) & 1) !== 0;\n const set = (x: number, y: number, on: boolean) => {\n dark[y]![x] = on;\n fn[y]![x] = true;\n };\n for (let i = 0; i <= 5; i++) set(8, i, bit(i));\n set(8, 7, bit(6));\n set(8, 8, bit(7));\n set(7, 8, bit(8));\n for (let i = 9; i < 15; i++) set(14 - i, 8, bit(i));\n for (let i = 0; i < 8; i++) set(size - 1 - i, 8, bit(i));\n for (let i = 8; i < 15; i++) set(8, size - 15 + i, bit(i));\n set(8, size - 8, true);\n}\n\n/** The data modules in the standard's order: two-column strips from the right, up then down, skipping the timing column. */\nfunction* dataPositions(size: number): Generator<[number, number]> {\n for (let right = size - 1; right >= 1; right -= 2) {\n if (right === 6) right = 5;\n for (let vert = 0; vert < size; vert++) {\n const y = ((right + 1) & 2) === 0 ? size - 1 - vert : vert;\n yield [right, y];\n yield [right - 1, y];\n }\n }\n}\n\nfunction placeData(grid: Grid, data: readonly number[]) {\n const { size, dark, fn } = grid;\n let i = 0;\n for (const [x, y] of dataPositions(size)) {\n if (fn[y]![x] || i >= data.length * 8) continue;\n dark[y]![x] = ((data[i >>> 3]! >>> (7 - (i & 7))) & 1) !== 0;\n i++;\n }\n}\n\nconst MASKS: ((x: number, y: number) => boolean)[] = [\n (x, y) => (x + y) % 2 === 0,\n (_x, y) => y % 2 === 0,\n (x) => x % 3 === 0,\n (x, y) => (x + y) % 3 === 0,\n (x, y) => (Math.floor(x / 3) + Math.floor(y / 2)) % 2 === 0,\n (x, y) => ((x * y) % 2) + ((x * y) % 3) === 0,\n (x, y) => (((x * y) % 2) + ((x * y) % 3)) % 2 === 0,\n (x, y) => (((x + y) % 2) + ((x * y) % 3)) % 2 === 0,\n];\n\ntype Dark = readonly (readonly boolean[])[];\n\n/** Rule 1: runs of five or more of one colour in a line (3, then 1 per module beyond). */\nfunction runPenalty(line: readonly boolean[]): number {\n let score = 0;\n let run = 1;\n for (let i = 1; i < line.length; i++) {\n run = line[i] === line[i - 1] ? run + 1 : 1;\n if (run === 5) score += 3;\n else if (run > 5) score++;\n }\n return score;\n}\n\n/** Rule 3: the finder-like pattern 1011101 with four light modules on one side, 40 each. */\nfunction finderPenalty(line: readonly boolean[]): number {\n const text = line.map((on) => (on ? \"1\" : \"0\")).join(\"\");\n let score = 0;\n for (const pattern of [\"00001011101\", \"10111010000\"]) {\n for (let at = text.indexOf(pattern); at >= 0; at = text.indexOf(pattern, at + 1)) score += 40;\n }\n return score;\n}\n\n/** Rule 2: 2x2 blocks of one colour, 3 each. */\nfunction blockPenalty(dark: Dark): number {\n let score = 0;\n for (let y = 0; y < dark.length - 1; y++)\n for (let x = 0; x < dark.length - 1; x++) {\n const c = dark[y]![x]!;\n if (c === dark[y]![x + 1] && c === dark[y + 1]![x] && c === dark[y + 1]![x + 1]) score += 3;\n }\n return score;\n}\n\n/** Rule 4: the share of dark modules away from 50 %, 10 per started 5 %. */\nfunction balancePenalty(dark: Dark): number {\n const size = dark.length;\n const total = dark.reduce((n, row) => n + row.filter(Boolean).length, 0);\n return (Math.ceil(Math.abs(total * 20 - size * size * 10) / (size * size)) - 1) * 10;\n}\n\nfunction penalty(dark: Dark): number {\n const columns = dark.map((_, x) => dark.map((row) => row[x]!));\n const lines = [...dark, ...columns];\n return lines.reduce((n, line) => n + runPenalty(line) + finderPenalty(line), 0) + blockPenalty(dark) + balancePenalty(dark);\n}\n\n/** Thrown when the text does not fit the biggest code (version 40) at the asked level. */\nexport class QrTooLongError extends Error {\n constructor(length: number, level: QrLevel) {\n super(`The text (${length} bytes) is too long for a QR code at level ${level}.`);\n this.name = \"QrTooLongError\";\n }\n}\n\n/** The smallest version whose data capacity holds the bytes (mode and length fields included). */\nfunction smallestVersion(bytes: readonly number[], level: QrLevel): number {\n for (let version = 1; version <= 40; version++) {\n if (4 + (version <= 9 ? 8 : 16) + bytes.length * 8 <= dataCodewords(version, level) * 8) return version;\n }\n throw new QrTooLongError(bytes.length, level);\n}\n\n/** The grid with one mask applied to its data modules and its format bits written. */\nfunction masked(base: Grid, mask: number, level: QrLevel): boolean[][] {\n const dark = base.dark.map((row) => [...row]);\n const fn = base.fn.map((row) => [...row]);\n for (let y = 0; y < base.size; y++) for (let x = 0; x < base.size; x++) if (!fn[y]![x] && MASKS[mask]!(x, y)) dark[y]![x] = !dark[y]![x];\n drawFormat(dark, fn, base.size, level, mask);\n return dark;\n}\n\n/** Encodes a text as a QR code: the smallest version that holds it at `level`, the best of the eight masks. */\nexport function encodeQr(text: string, level: QrLevel = \"M\"): QrMatrix {\n const bytes = utf8(text);\n const version = smallestVersion(bytes, level);\n const base = drawFunctionPatterns(version, level);\n placeData(base, codewords(bytes, version, level));\n const candidates = MASKS.map((_, mask) => masked(base, mask, level));\n const scores = candidates.map(penalty);\n return candidates[scores.indexOf(Math.min(...scores))]!;\n}\n\n/**\n * The drawing of a matrix as one SVG path: a rectangle per horizontal run of dark modules, in module units, offset by\n * the quiet zone. Shared by the web `<svg>` and the native `<Path>`.\n */\nexport function qrPath(matrix: QrMatrix, quiet: number): string {\n const parts: string[] = [];\n matrix.forEach((row, y) => {\n for (let x = 0; x < row.length; x++) {\n if (!row[x]) continue;\n let end = x;\n while (end + 1 < row.length && row[end + 1]) end++;\n parts.push(`M${x + quiet} ${y + quiet}h${end - x + 1}v1h${x - end - 1}z`);\n x = end;\n }\n });\n return parts.join(\"\");\n}\n"
|
|
245
|
+
"content": "// The QR encoder: a string in, a square of dark/light modules out. Pure, offline, no dependency, shared by the web\n// and the native drawing. Byte mode (UTF-8), versions 1-40, the four error-correction levels, the eight masks chosen\n// by the standard's penalty rules (ISO/IEC 18004). `qr-code.test.tsx` decodes what it draws, version by version.\n\nexport type QrLevel = \"L\" | \"M\" | \"Q\" | \"H\";\n\n/** The square of modules, row by row: `true` is dark. */\nexport type QrMatrix = readonly (readonly boolean[])[];\n\nconst LEVEL_INDEX: Record<QrLevel, number> = { L: 0, M: 1, Q: 2, H: 3 };\nconst LEVEL_BITS: Record<QrLevel, number> = { L: 1, M: 0, Q: 3, H: 2 };\n\n// Error-correction codewords per block, and number of blocks, by level (L, M, Q, H) then version (index 0 is unused).\nconst ECC_PER_BLOCK = [\n [-1, 7, 10, 15, 20, 26, 18, 20, 24, 30, 18, 20, 24, 26, 30, 22, 24, 28, 30, 28, 28, 28, 28, 30, 30, 26, 28, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30],\n [-1, 10, 16, 26, 18, 24, 16, 18, 22, 22, 26, 30, 22, 22, 24, 24, 28, 28, 26, 26, 26, 26, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28],\n [-1, 13, 22, 18, 26, 18, 24, 18, 22, 20, 24, 28, 26, 24, 20, 30, 24, 28, 28, 26, 30, 28, 30, 30, 30, 30, 28, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30],\n [-1, 17, 28, 22, 16, 22, 28, 26, 26, 24, 28, 24, 28, 22, 24, 24, 30, 28, 28, 26, 28, 30, 24, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30],\n] as const;\nconst BLOCKS = [\n [-1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 4, 4, 4, 4, 4, 6, 6, 6, 6, 7, 8, 8, 9, 9, 10, 12, 12, 12, 13, 14, 15, 16, 17, 18, 19, 19, 20, 21, 22, 24, 25],\n [-1, 1, 1, 1, 2, 2, 4, 4, 4, 5, 5, 5, 8, 9, 9, 10, 10, 11, 13, 14, 16, 17, 17, 18, 20, 21, 23, 25, 26, 28, 29, 31, 33, 35, 37, 38, 40, 43, 45, 47, 49],\n [-1, 1, 1, 2, 2, 4, 4, 6, 6, 8, 8, 8, 10, 12, 16, 12, 17, 16, 18, 21, 20, 23, 23, 25, 27, 29, 34, 34, 35, 38, 40, 43, 45, 48, 51, 53, 56, 59, 62, 65, 68],\n [-1, 1, 1, 2, 4, 4, 4, 5, 6, 8, 8, 11, 11, 16, 16, 18, 16, 19, 21, 25, 25, 25, 34, 30, 32, 35, 37, 40, 42, 45, 48, 51, 54, 57, 60, 63, 66, 70, 74, 77, 81],\n] as const;\n\n/** Data modules of a version (everything but the finder, timing, alignment, format and version patterns). */\nfunction rawModules(version: number): number {\n let result = (16 * version + 128) * version + 64;\n if (version >= 2) {\n const align = Math.floor(version / 7) + 2;\n result -= (25 * align - 10) * align - 55;\n if (version >= 7) result -= 36;\n }\n return result;\n}\n\nfunction dataCodewords(version: number, level: QrLevel): number {\n const l = LEVEL_INDEX[level];\n return Math.floor(rawModules(version) / 8) - ECC_PER_BLOCK[l]![version]! * BLOCKS[l]![version]!;\n}\n\nexport function utf8(text: string): number[] {\n return [...new TextEncoder().encode(text)];\n}\n\n// Reed-Solomon over GF(256), polynomial 0x11D.\nfunction gfMultiply(x: number, y: number): number {\n let z = 0;\n for (let i = 7; i >= 0; i--) {\n z = (z << 1) ^ ((z >>> 7) * 0x11d);\n z ^= ((y >>> i) & 1) * x;\n }\n return z;\n}\n\nfunction divisor(degree: number): number[] {\n const result = new Array<number>(degree).fill(0);\n result[degree - 1] = 1;\n let root = 1;\n for (let i = 0; i < degree; i++) {\n for (let j = 0; j < degree; j++) {\n result[j] = gfMultiply(result[j]!, root);\n if (j + 1 < degree) result[j] = result[j]! ^ result[j + 1]!;\n }\n root = gfMultiply(root, 0x02);\n }\n return result;\n}\n\nfunction remainder(data: readonly number[], div: readonly number[]): number[] {\n const result = div.map(() => 0);\n for (const b of data) {\n const factor = b ^ result.shift()!;\n result.push(0);\n div.forEach((coef, i) => {\n result[i] = result[i]! ^ gfMultiply(coef, factor);\n });\n }\n return result;\n}\n\nfunction pushBits(bits: number[], value: number, count: number) {\n for (let i = count - 1; i >= 0; i--) bits.push((value >>> i) & 1);\n}\n\n/** The codewords of the message: mode, length, bytes, terminator, padding, then blocks interleaved with their ECC. */\nfunction codewords(bytes: readonly number[], version: number, level: QrLevel): number[] {\n const bits: number[] = [];\n pushBits(bits, 0b0100, 4);\n pushBits(bits, bytes.length, version <= 9 ? 8 : 16);\n for (const b of bytes) pushBits(bits, b, 8);\n const capacity = dataCodewords(version, level) * 8;\n pushBits(bits, 0, Math.min(4, capacity - bits.length));\n pushBits(bits, 0, (8 - (bits.length % 8)) % 8);\n let pad = 0xec;\n while (bits.length < capacity) {\n pushBits(bits, pad, 8);\n pad ^= 0xec ^ 0x11;\n }\n const data: number[] = [];\n for (let i = 0; i < bits.length; i += 8) data.push(Number.parseInt(bits.slice(i, i + 8).join(\"\"), 2));\n\n const l = LEVEL_INDEX[level];\n const blocks = BLOCKS[l]![version]!;\n const eccLen = ECC_PER_BLOCK[l]![version]!;\n const shortBlocks = blocks - (Math.floor(rawModules(version) / 8) % blocks);\n const shortLen = Math.floor(rawModules(version) / 8 / blocks) - eccLen;\n const div = divisor(eccLen);\n const parts: { data: number[]; ecc: number[] }[] = [];\n for (let i = 0, k = 0; i < blocks; i++) {\n const chunk = data.slice(k, k + shortLen + (i < shortBlocks ? 0 : 1));\n k += chunk.length;\n parts.push({ data: chunk, ecc: remainder(chunk, div) });\n }\n const out: number[] = [];\n for (let i = 0; i <= shortLen; i++) parts.forEach((p) => i < p.data.length && out.push(p.data[i]!));\n for (let i = 0; i < eccLen; i++) parts.forEach((p) => out.push(p.ecc[i]!));\n return out;\n}\n\nfunction alignmentPositions(version: number): number[] {\n if (version === 1) return [];\n const count = Math.floor(version / 7) + 2;\n const step = version === 32 ? 26 : Math.ceil((version * 4 + 4) / (count * 2 - 2)) * 2;\n const result = [6];\n let pos = version * 4 + 10;\n while (result.length < count) {\n result.splice(1, 0, pos);\n pos -= step;\n }\n return result;\n}\n\ntype Grid = { size: number; dark: boolean[][]; fn: boolean[][] };\n\nfunction drawFunctionPatterns(version: number, level: QrLevel): Grid {\n const size = version * 4 + 17;\n const dark = Array.from({ length: size }, () => new Array<boolean>(size).fill(false));\n const fn = Array.from({ length: size }, () => new Array<boolean>(size).fill(false));\n const set = (x: number, y: number, on: boolean) => {\n dark[y]![x] = on;\n fn[y]![x] = true;\n };\n for (let i = 0; i < size; i++) {\n set(6, i, i % 2 === 0);\n set(i, 6, i % 2 === 0);\n }\n const finder = (cx: number, cy: number) => {\n for (let dy = -4; dy <= 4; dy++)\n for (let dx = -4; dx <= 4; dx++) {\n const x = cx + dx;\n const y = cy + dy;\n if (x < 0 || x >= size || y < 0 || y >= size) continue;\n const dist = Math.max(Math.abs(dx), Math.abs(dy));\n set(x, y, dist !== 2 && dist !== 4);\n }\n };\n finder(3, 3);\n finder(size - 4, 3);\n finder(3, size - 4);\n const align = alignmentPositions(version);\n align.forEach((cx, i) =>\n align.forEach((cy, j) => {\n if ((i === 0 && j === 0) || (i === 0 && j === align.length - 1) || (i === align.length - 1 && j === 0)) return;\n for (let dy = -2; dy <= 2; dy++) for (let dx = -2; dx <= 2; dx++) set(cx + dx, cy + dy, Math.max(Math.abs(dx), Math.abs(dy)) !== 1);\n }),\n );\n drawFormat(dark, fn, size, level, 0);\n if (version >= 7) {\n let rem = version;\n for (let i = 0; i < 12; i++) rem = (rem << 1) ^ ((rem >>> 11) * 0x1f25);\n const bits = (version << 12) | rem;\n for (let i = 0; i < 18; i++) {\n const on = ((bits >>> i) & 1) !== 0;\n const a = size - 11 + (i % 3);\n const b = Math.floor(i / 3);\n set(a, b, on);\n set(b, a, on);\n }\n }\n return { size, dark, fn };\n}\n\nfunction drawFormat(dark: boolean[][], fn: boolean[][], size: number, level: QrLevel, mask: number) {\n const data = (LEVEL_BITS[level] << 3) | mask;\n let rem = data;\n for (let i = 0; i < 10; i++) rem = (rem << 1) ^ ((rem >>> 9) * 0x537);\n const bits = ((data << 10) | rem) ^ 0x5412;\n const bit = (i: number) => ((bits >>> i) & 1) !== 0;\n const set = (x: number, y: number, on: boolean) => {\n dark[y]![x] = on;\n fn[y]![x] = true;\n };\n for (let i = 0; i <= 5; i++) set(8, i, bit(i));\n set(8, 7, bit(6));\n set(8, 8, bit(7));\n set(7, 8, bit(8));\n for (let i = 9; i < 15; i++) set(14 - i, 8, bit(i));\n for (let i = 0; i < 8; i++) set(size - 1 - i, 8, bit(i));\n for (let i = 8; i < 15; i++) set(8, size - 15 + i, bit(i));\n set(8, size - 8, true);\n}\n\n/** The data modules in the standard's order: two-column strips from the right, up then down, skipping the timing column. */\nfunction* dataPositions(size: number): Generator<[number, number]> {\n for (let right = size - 1; right >= 1; right -= 2) {\n if (right === 6) right = 5;\n for (let vert = 0; vert < size; vert++) {\n const y = ((right + 1) & 2) === 0 ? size - 1 - vert : vert;\n yield [right, y];\n yield [right - 1, y];\n }\n }\n}\n\nfunction placeData(grid: Grid, data: readonly number[]) {\n const { size, dark, fn } = grid;\n let i = 0;\n for (const [x, y] of dataPositions(size)) {\n if (fn[y]![x] || i >= data.length * 8) continue;\n dark[y]![x] = ((data[i >>> 3]! >>> (7 - (i & 7))) & 1) !== 0;\n i++;\n }\n}\n\nconst MASKS: ((x: number, y: number) => boolean)[] = [\n (x, y) => (x + y) % 2 === 0,\n (_x, y) => y % 2 === 0,\n (x) => x % 3 === 0,\n (x, y) => (x + y) % 3 === 0,\n (x, y) => (Math.floor(x / 3) + Math.floor(y / 2)) % 2 === 0,\n (x, y) => ((x * y) % 2) + ((x * y) % 3) === 0,\n (x, y) => (((x * y) % 2) + ((x * y) % 3)) % 2 === 0,\n (x, y) => (((x + y) % 2) + ((x * y) % 3)) % 2 === 0,\n];\n\ntype Dark = readonly (readonly boolean[])[];\n\n/** Rule 1: runs of five or more of one colour in a line (3, then 1 per module beyond). */\nfunction runPenalty(line: readonly boolean[]): number {\n let score = 0;\n let run = 1;\n for (let i = 1; i < line.length; i++) {\n run = line[i] === line[i - 1] ? run + 1 : 1;\n if (run === 5) score += 3;\n else if (run > 5) score++;\n }\n return score;\n}\n\n/** Rule 3: the finder-like pattern 1011101 with four light modules on one side, 40 each. */\nfunction finderPenalty(line: readonly boolean[]): number {\n const text = line.map((on) => (on ? \"1\" : \"0\")).join(\"\");\n let score = 0;\n for (const pattern of [\"00001011101\", \"10111010000\"]) {\n for (let at = text.indexOf(pattern); at >= 0; at = text.indexOf(pattern, at + 1)) score += 40;\n }\n return score;\n}\n\n/** Rule 2: 2x2 blocks of one colour, 3 each. */\nfunction blockPenalty(dark: Dark): number {\n let score = 0;\n for (let y = 0; y < dark.length - 1; y++)\n for (let x = 0; x < dark.length - 1; x++) {\n const c = dark[y]![x]!;\n if (c === dark[y]![x + 1] && c === dark[y + 1]![x] && c === dark[y + 1]![x + 1]) score += 3;\n }\n return score;\n}\n\n/** Rule 4: the share of dark modules away from 50 %, 10 per started 5 %. */\nfunction balancePenalty(dark: Dark): number {\n const size = dark.length;\n const total = dark.reduce((n, row) => n + row.filter(Boolean).length, 0);\n return (Math.ceil(Math.abs(total * 20 - size * size * 10) / (size * size)) - 1) * 10;\n}\n\nfunction penalty(dark: Dark): number {\n const columns = dark.map((_, x) => dark.map((row) => row[x]!));\n const lines = [...dark, ...columns];\n return lines.reduce((n, line) => n + runPenalty(line) + finderPenalty(line), 0) + blockPenalty(dark) + balancePenalty(dark);\n}\n\n/** Thrown when the text does not fit the biggest code (version 40) at the asked level. */\nexport class QrTooLongError extends Error {\n constructor(length: number, level: QrLevel) {\n super(`The text (${length} bytes) is too long for a QR code at level ${level}.`);\n this.name = \"QrTooLongError\";\n }\n}\n\n/** The smallest version whose data capacity holds the bytes (mode and length fields included). */\nfunction smallestVersion(bytes: readonly number[], level: QrLevel): number {\n for (let version = 1; version <= 40; version++) {\n if (4 + (version <= 9 ? 8 : 16) + bytes.length * 8 <= dataCodewords(version, level) * 8) return version;\n }\n throw new QrTooLongError(bytes.length, level);\n}\n\n/** The grid with one mask applied to its data modules and its format bits written. */\nfunction masked(base: Grid, mask: number, level: QrLevel): boolean[][] {\n const dark = base.dark.map((row) => [...row]);\n const fn = base.fn.map((row) => [...row]);\n for (let y = 0; y < base.size; y++) for (let x = 0; x < base.size; x++) if (!fn[y]![x] && MASKS[mask]!(x, y)) dark[y]![x] = !dark[y]![x];\n drawFormat(dark, fn, base.size, level, mask);\n return dark;\n}\n\n/** Encodes a text as a QR code: the smallest version that holds it at `level`, the best of the eight masks. */\nexport function encodeQr(text: string, level: QrLevel = \"M\"): QrMatrix {\n const bytes = utf8(text);\n const version = smallestVersion(bytes, level);\n const base = drawFunctionPatterns(version, level);\n placeData(base, codewords(bytes, version, level));\n const candidates = MASKS.map((_, mask) => masked(base, mask, level));\n const scores = candidates.map(penalty);\n return candidates[scores.indexOf(Math.min(...scores))]!;\n}\n\n/**\n * The drawing of a matrix as one SVG path: a rectangle per horizontal run of dark modules, in module units, offset by\n * the quiet zone. Shared by the web `<svg>` and the native `<Path>`.\n */\nexport function qrPath(matrix: QrMatrix, quiet: number): string {\n const parts: string[] = [];\n matrix.forEach((row, y) => {\n for (let x = 0; x < row.length; x++) {\n if (!row[x]) continue;\n let end = x;\n while (end + 1 < row.length && row[end + 1]) end++;\n parts.push(`M${x + quiet} ${y + quiet}h${end - x + 1}v1h${x - end - 1}z`);\n x = end;\n }\n });\n return parts.join(\"\");\n}\n"
|
|
246
246
|
},
|
|
247
247
|
{
|
|
248
248
|
"path": "qr-code/index.ts",
|
|
@@ -254,7 +254,7 @@
|
|
|
254
254
|
},
|
|
255
255
|
{
|
|
256
256
|
"path": "qr-code/qr-code.tsx",
|
|
257
|
-
"content": "// Client (the copy action). A QR code drawn from a text, offline: an SVG of dark modules on a light tile, whatever the\n// theme (a phone reads dark on light), with its quiet zone. No call to any service; the text never leaves the page.\nimport * as React from \"react\";\n\nimport { Button } from \"../button/button\";\nimport { cn } from \"../cn\";\nimport { CheckGlyph, CopyGlyph } from \"../glyphs\";\nimport { encodeQr, type QrLevel, qrPath } from \"./encode\";\n\n// The tile and the modules are the same in dark and light on purpose: a scanner needs dark modules on a light ground.\nexport const QR_TILE = \"#ffffff\";\nexport const QR_MODULE = \"#0b0f19\";\n\nexport type QrCodeProps = {\n /** The text to encode — an address, a feed URL. Encoded here, in the browser (or on the server); never sent anywhere. */\n value: string;\n /** What the code is, for a screen reader (“Calendar feed — scan with your phone”), passed translated. The image is named by it. */\n label: string;\n /** The side of the tile, in px, quiet zone included. Default 176. */\n size?: number;\n /** The quiet zone, in modules, around the code (the standard asks for 4). Default 4, never less than 2. */\n quietZone?: number;\n /** The error-correction level: L · M (default) · Q · H (a logo or wear on the print). */\n level?: QrLevel;\n /** The words of the copy action, passed translated. Without them there is no « copy » button. */\n copyLabel?: string;\n /** Said once the text is on the clipboard. Default: the copy label. */\n copiedLabel?: string;\n /** Called after the text is copied. */\n onCopy?: () => void;\n /** Classes merged last, on the wrapper. */\n className?: string;\n};\n\n/** A QR code from a text: dark modules on a light tile in both themes, a quiet zone, an accessible name, an optional copy action. */\nexport function QrCode({ value, label, size = 176, quietZone = 4, level = \"M\", copyLabel, copiedLabel, onCopy, className }: QrCodeProps) {\n const quiet = Math.max(2, Math.round(quietZone));\n const { matrix, path } = React.useMemo(() => {\n const m = encodeQr(value, level);\n return { matrix: m, path: qrPath(m, quiet) };\n }, [value, level, quiet]);\n const modules = matrix.length + quiet * 2;\n const [copied, setCopied] = React.useState(false);\n React.useEffect(() => {\n if (!copied) return;\n const t = setTimeout(() => setCopied(false), 1800);\n return () => clearTimeout(t);\n }, [copied]);\n const copy = () =>\n navigator.clipboard?.writeText(value).then(() => {\n setCopied(true);\n onCopy?.();\n });\n\n return (\n <div className={cn(\"inline-flex flex-col items-start gap-3\", className)} data-qr-code>\n <svg\n role=\"img\"\n aria-label={label}\n viewBox={`0 0 ${modules} ${modules}`}\n width={size}\n height={size}\n shapeRendering=\"crispEdges\"\n className=\"block max-w-full rounded-lg border border-border-default\"\n style={{ height: \"auto\", aspectRatio: \"1 / 1\" }}\n >\n <rect width={modules} height={modules} fill={QR_TILE} />\n <path d={path} fill={QR_MODULE} />\n </svg>\n {copyLabel ? (\n <Button type=\"button\" variant=\"secondary\" size=\"sm\" onClick={copy} announce={copied ? (copiedLabel ?? copyLabel) : undefined}>\n {copied ? <CheckGlyph className=\"h-3.5 w-3.5\" /> : <CopyGlyph className=\"h-3.5 w-3.5\" />}\n {copied ? (copiedLabel ?? copyLabel) : copyLabel}\n </Button>\n ) : null}\n </div>\n );\n}\n"
|
|
257
|
+
"content": "// Client (the copy action). A QR code drawn from a text, offline: an SVG of dark modules on a light tile, whatever the\n// theme (a phone reads dark on light), with its quiet zone. No call to any service; the text never leaves the page.\nimport * as React from \"react\";\n\nimport { Button } from \"../button/button\";\nimport { cn } from \"../cn\";\nimport { CheckGlyph, CopyGlyph } from \"../glyphs\";\nimport { encodeQr, type QrLevel, qrPath } from \"./encode\";\n\n// The tile and the modules are the same in dark and light on purpose: a scanner needs dark modules on a light ground.\nexport const QR_TILE = \"#ffffff\";\nexport const QR_MODULE = \"#0b0f19\";\n\nexport type QrCodeProps = {\n /** The text to encode — an address, a feed URL. Encoded here, in the browser (or on the server); never sent anywhere. */\n value: string;\n /** What the code is, for a screen reader (“Calendar feed — scan with your phone”), passed translated. The image is named by it. */\n label: string;\n /** The side of the tile, in px, quiet zone included. Default 176. */\n size?: number;\n /** The quiet zone, in modules, around the code (the standard asks for 4). Default 4, never less than 2. */\n quietZone?: number;\n /** The error-correction level: L · M (default) · Q · H (a logo or wear on the print). */\n level?: QrLevel;\n /** The words of the copy action, passed translated. Without them there is no « copy » button. */\n copyLabel?: string;\n /** Said once the text is on the clipboard. Default: the copy label. */\n copiedLabel?: string;\n /** Called after the text is copied. */\n onCopy?: () => void;\n /** Classes merged last, on the wrapper. */\n className?: string;\n};\n\n/** A QR code from a text: dark modules on a light tile in both themes, a quiet zone, an accessible name, an optional copy action. */\nexport function QrCode({ value, label, size = 176, quietZone = 4, level = \"M\", copyLabel, copiedLabel, onCopy, className }: Readonly<QrCodeProps>) {\n const quiet = Math.max(2, Math.round(quietZone));\n const { matrix, path } = React.useMemo(() => {\n const m = encodeQr(value, level);\n return { matrix: m, path: qrPath(m, quiet) };\n }, [value, level, quiet]);\n const modules = matrix.length + quiet * 2;\n const [copied, setCopied] = React.useState(false);\n React.useEffect(() => {\n if (!copied) return;\n const t = setTimeout(() => setCopied(false), 1800);\n return () => clearTimeout(t);\n }, [copied]);\n const copy = () =>\n navigator.clipboard?.writeText(value).then(() => {\n setCopied(true);\n onCopy?.();\n });\n\n return (\n <div className={cn(\"inline-flex flex-col items-start gap-3\", className)} data-qr-code>\n <svg\n role=\"img\"\n aria-label={label}\n viewBox={`0 0 ${modules} ${modules}`}\n width={size}\n height={size}\n shapeRendering=\"crispEdges\"\n className=\"block max-w-full rounded-lg border border-border-default\"\n style={{ height: \"auto\", aspectRatio: \"1 / 1\" }}\n >\n <rect width={modules} height={modules} fill={QR_TILE} />\n <path d={path} fill={QR_MODULE} />\n </svg>\n {copyLabel ? (\n <Button type=\"button\" variant=\"secondary\" size=\"sm\" onClick={copy} announce={copied ? (copiedLabel ?? copyLabel) : undefined}>\n {copied ? <CheckGlyph className=\"h-3.5 w-3.5\" /> : <CopyGlyph className=\"h-3.5 w-3.5\" />}\n {copied ? (copiedLabel ?? copyLabel) : copyLabel}\n </Button>\n ) : null}\n </div>\n );\n}\n"
|
|
258
258
|
},
|
|
259
259
|
{
|
|
260
260
|
"path": "qr-code/vcard.ts",
|
|
@@ -183,7 +183,7 @@
|
|
|
183
183
|
"files": [
|
|
184
184
|
{
|
|
185
185
|
"path": "meta.ts",
|
|
186
|
-
"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 | \"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 | \"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 | \"identity-card\"\n | \"entity-header\"\n | \"collection-switcher\"\n | \"marketing-layout\"\n | \"mascot-quote\"\n | \"mascot-state\"\n | \"mascots\"\n | \"match-dialog\"\n | \"media-capture\"\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 | \"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 Sovkora 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 thirteen 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 | \"abuse\"\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"
|
|
186
|
+
"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 | \"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 | \"columns\"\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 | \"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 | \"identity-card\"\n | \"entity-header\"\n | \"collection-switcher\"\n | \"marketing-layout\"\n | \"mascot-quote\"\n | \"mascot-state\"\n | \"mascots\"\n | \"match-dialog\"\n | \"media-capture\"\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 | \"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 Sovkora 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 thirteen 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 | \"abuse\"\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"
|
|
187
187
|
},
|
|
188
188
|
{
|
|
189
189
|
"path": "quota-meter/index.ts",
|
|
@@ -380,7 +380,7 @@
|
|
|
380
380
|
},
|
|
381
381
|
{
|
|
382
382
|
"path": "meta.ts",
|
|
383
|
-
"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 | \"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 | \"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 | \"identity-card\"\n | \"entity-header\"\n | \"collection-switcher\"\n | \"marketing-layout\"\n | \"mascot-quote\"\n | \"mascot-state\"\n | \"mascots\"\n | \"match-dialog\"\n | \"media-capture\"\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 | \"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 Sovkora 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 thirteen 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 | \"abuse\"\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"
|
|
383
|
+
"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 | \"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 | \"columns\"\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 | \"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 | \"identity-card\"\n | \"entity-header\"\n | \"collection-switcher\"\n | \"marketing-layout\"\n | \"mascot-quote\"\n | \"mascot-state\"\n | \"mascots\"\n | \"match-dialog\"\n | \"media-capture\"\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 | \"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 Sovkora 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 thirteen 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 | \"abuse\"\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"
|
|
384
384
|
},
|
|
385
385
|
{
|
|
386
386
|
"path": "radio-group/index.ts",
|
package/registry/rail-nav.json
CHANGED
|
@@ -292,7 +292,7 @@
|
|
|
292
292
|
},
|
|
293
293
|
{
|
|
294
294
|
"path": "marks/InkMark.tsx",
|
|
295
|
-
"content": "import type { ReactNode } from \"react\";\n\nimport { KRIZAKA } from \"./krizaka-geometry\";\nimport { a11y, type MarkProps, neutral, useIds } from \"./shared\";\n\n/** What an ink mark draws on the family frame: the Krizaka geometry, its node and core moved where its figure opens. */\nexport interface InkGeometry {\n readonly viewBox: string;\n readonly croppedViewBox: string;\n readonly offset: number;\n readonly ink: typeof KRIZAKA.ink;\n readonly blue: typeof KRIZAKA.blue;\n readonly glow: typeof KRIZAKA.glow;\n readonly orbit: typeof KRIZAKA.orbit;\n readonly ring: typeof KRIZAKA.ring;\n readonly highlight: string;\n readonly node: { readonly cx: number; readonly cy: number; readonly r: number; readonly inner: number };\n readonly core: { readonly cx: number; readonly cy: number; readonly r: number; readonly inner: number };\n}\n\ninterface InkMarkProps extends MarkProps {\n /** The class prefix of `css` (`<prefix>-spin` turns the orbit, `<prefix>-pulse` makes the node and core breathe). */\n readonly prefix: string;\n readonly css: string;\n readonly geometry: InkGeometry;\n /** The figure, drawn with the ink gradient `url(#ink)` it is given. */\n readonly figure: (ink: string) => ReactNode;\n}\n\n/** The ink, blue and glow gradients of the marks in Krizaka's colours, under the instance's own ids. */\nexport function InkDefs({ ids: id, geometry: G }: Readonly<{ ids: Record<\"ink\" | \"blue\" | \"glow\", string>; geometry: Pick<InkGeometry, \"ink\" | \"blue\" | \"glow\"> }>) {\n return (\n <defs>\n <linearGradient id={id.ink} gradientUnits=\"userSpaceOnUse\" x1={G.ink.x1} y1={G.ink.y1} x2={G.ink.x2} y2={G.ink.y2}>\n <stop offset=\"0%\" stopColor={neutral(\"--kz-text-secondary\", 60)} />\n <stop offset=\"100%\" stopColor={neutral(\"--kz-text-primary\", 92)} />\n </linearGradient>\n <linearGradient id={id.blue} gradientUnits=\"userSpaceOnUse\" x1={G.blue.x1} y1={G.blue.y1} x2={G.blue.x2} y2={G.blue.y2}>\n {G.blue.stops.map(([offset, color]) => (\n <stop key={offset} offset={offset} stopColor={color} />\n ))}\n </linearGradient>\n <radialGradient id={id.glow} cx=\"50%\" cy=\"50%\" r=\"50%\">\n <stop offset=\"0%\" stopColor={G.glow.color} stopOpacity={G.glow.opacity} />\n <stop offset=\"100%\" stopColor={G.glow.color} stopOpacity=\"0\" />\n </radialGradient>\n </defs>\n );\n}\n\n/**\n * The frame of the marks in Krizaka's colours (the company and its services: Krizaka, Kridoc): halo, dashed orbit, ring,\n * an ink figure, the blue node where it opens and the blue core. Below 48 px it crops to the emblem.\n */\nexport function InkMark({ size = 32, animated = true, title, className, prefix, css, geometry: G, figure }: InkMarkProps) {\n const id = useIds(prefix, [\"ink\", \"blue\", \"glow\"] as const);\n const m = (cls: string) => (animated ? `${prefix}-${cls}` : undefined);\n const dots = [G.node, G.core];\n return (\n <svg width={size} height={size} viewBox={size < 48 ? G.croppedViewBox : G.viewBox} fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\" className={className} {...a11y(title)}>\n <style>{css}</style>\n <InkDefs ids={id} geometry={G} />\n {size >= 48 ? <circle cx=\"200\" cy=\"200\" r=\"190\" fill={`url(#${id.glow})`} /> : null /* cropped: the halo would show its square */}\n <circle className={m(\"spin\")} cx=\"200\" cy=\"200\" r={G.orbit.r} stroke={neutral(\"--kz-border-strong\", 40)} strokeWidth={G.orbit.width} strokeDasharray={G.orbit.dash} opacity=\".6\" />\n <circle cx=\"200\" cy=\"200\" r={G.ring.r} stroke={neutral(\"--kz-border-default\", 30)} strokeWidth={G.ring.width} opacity=\".35\" />\n <g transform={`translate(${G.offset} ${G.offset})`}>\n {figure(`url(#${id.ink})`)}\n {dots.map((d) => (\n <g key={`${d.cx},${d.cy}`} className={m(\"pulse\")}>\n <circle cx={d.cx} cy={d.cy} r={d.r} fill={`url(#${id.blue})`} />\n <circle cx={d.cx} cy={d.cy} r={d.inner} fill={G.highlight} />\n </g>\n ))}\n </g>\n </svg>\n );\n}\n"
|
|
295
|
+
"content": "import type { ReactNode } from \"react\";\n\nimport { KRIZAKA } from \"./krizaka-geometry\";\nimport { a11y, type MarkProps, neutral, useIds } from \"./shared\";\n\n/** What an ink mark draws on the family frame: the Krizaka geometry, its node and core moved where its figure opens. */\nexport interface InkGeometry {\n readonly viewBox: string;\n readonly croppedViewBox: string;\n readonly offset: number;\n readonly ink: typeof KRIZAKA.ink;\n readonly blue: typeof KRIZAKA.blue;\n readonly glow: typeof KRIZAKA.glow;\n readonly orbit: typeof KRIZAKA.orbit;\n readonly ring: typeof KRIZAKA.ring;\n readonly highlight: string;\n readonly node: { readonly cx: number; readonly cy: number; readonly r: number; readonly inner: number };\n readonly core: { readonly cx: number; readonly cy: number; readonly r: number; readonly inner: number };\n}\n\ninterface InkMarkProps extends MarkProps {\n /** The class prefix of `css` (`<prefix>-spin` turns the orbit, `<prefix>-pulse` makes the node and core breathe). */\n readonly prefix: string;\n readonly css: string;\n readonly geometry: InkGeometry;\n /** The figure, drawn with the ink gradient `url(#ink)` it is given. */\n readonly figure: (ink: string) => ReactNode;\n}\n\n/** The ink, blue and glow gradients of the marks in Krizaka's colours, under the instance's own ids. */\nexport function InkDefs({ ids: id, geometry: G }: Readonly<{ ids: Record<\"ink\" | \"blue\" | \"glow\", string>; geometry: Pick<InkGeometry, \"ink\" | \"blue\" | \"glow\"> }>) {\n return (\n <defs>\n <linearGradient id={id.ink} gradientUnits=\"userSpaceOnUse\" x1={G.ink.x1} y1={G.ink.y1} x2={G.ink.x2} y2={G.ink.y2}>\n <stop offset=\"0%\" stopColor={neutral(\"--kz-text-secondary\", 60)} />\n <stop offset=\"100%\" stopColor={neutral(\"--kz-text-primary\", 92)} />\n </linearGradient>\n <linearGradient id={id.blue} gradientUnits=\"userSpaceOnUse\" x1={G.blue.x1} y1={G.blue.y1} x2={G.blue.x2} y2={G.blue.y2}>\n {G.blue.stops.map(([offset, color]) => (\n <stop key={offset} offset={offset} stopColor={color} />\n ))}\n </linearGradient>\n <radialGradient id={id.glow} cx=\"50%\" cy=\"50%\" r=\"50%\">\n <stop offset=\"0%\" stopColor={G.glow.color} stopOpacity={G.glow.opacity} />\n <stop offset=\"100%\" stopColor={G.glow.color} stopOpacity=\"0\" />\n </radialGradient>\n </defs>\n );\n}\n\n/**\n * The frame of the marks in Krizaka's colours (the company and its services: Krizaka, Kridoc): halo, dashed orbit, ring,\n * an ink figure, the blue node where it opens and the blue core. Below 48 px it crops to the emblem.\n */\nexport function InkMark({ size = 32, animated = true, title, className, prefix, css, geometry: G, figure }: Readonly<InkMarkProps>) {\n const id = useIds(prefix, [\"ink\", \"blue\", \"glow\"] as const);\n const m = (cls: string) => (animated ? `${prefix}-${cls}` : undefined);\n const dots = [G.node, G.core];\n return (\n <svg width={size} height={size} viewBox={size < 48 ? G.croppedViewBox : G.viewBox} fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\" className={className} {...a11y(title)}>\n <style>{css}</style>\n <InkDefs ids={id} geometry={G} />\n {size >= 48 ? <circle cx=\"200\" cy=\"200\" r=\"190\" fill={`url(#${id.glow})`} /> : null /* cropped: the halo would show its square */}\n <circle className={m(\"spin\")} cx=\"200\" cy=\"200\" r={G.orbit.r} stroke={neutral(\"--kz-border-strong\", 40)} strokeWidth={G.orbit.width} strokeDasharray={G.orbit.dash} opacity=\".6\" />\n <circle cx=\"200\" cy=\"200\" r={G.ring.r} stroke={neutral(\"--kz-border-default\", 30)} strokeWidth={G.ring.width} opacity=\".35\" />\n <g transform={`translate(${G.offset} ${G.offset})`}>\n {figure(`url(#${id.ink})`)}\n {dots.map((d) => (\n <g key={`${d.cx},${d.cy}`} className={m(\"pulse\")}>\n <circle cx={d.cx} cy={d.cy} r={d.r} fill={`url(#${id.blue})`} />\n <circle cx={d.cx} cy={d.cy} r={d.inner} fill={G.highlight} />\n </g>\n ))}\n </g>\n </svg>\n );\n}\n"
|
|
296
296
|
},
|
|
297
297
|
{
|
|
298
298
|
"path": "marks/krizaka-geometry.ts",
|
|
@@ -328,7 +328,7 @@
|
|
|
328
328
|
},
|
|
329
329
|
{
|
|
330
330
|
"path": "meta.ts",
|
|
331
|
-
"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 | \"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 | \"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 | \"identity-card\"\n | \"entity-header\"\n | \"collection-switcher\"\n | \"marketing-layout\"\n | \"mascot-quote\"\n | \"mascot-state\"\n | \"mascots\"\n | \"match-dialog\"\n | \"media-capture\"\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 | \"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 Sovkora 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 thirteen 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 | \"abuse\"\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"
|
|
331
|
+
"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 | \"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 | \"columns\"\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 | \"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 | \"identity-card\"\n | \"entity-header\"\n | \"collection-switcher\"\n | \"marketing-layout\"\n | \"mascot-quote\"\n | \"mascot-state\"\n | \"mascots\"\n | \"match-dialog\"\n | \"media-capture\"\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 | \"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 Sovkora 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 thirteen 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 | \"abuse\"\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"
|
|
332
332
|
},
|
|
333
333
|
{
|
|
334
334
|
"path": "rail-nav/index.ts",
|
|
@@ -340,11 +340,11 @@
|
|
|
340
340
|
},
|
|
341
341
|
{
|
|
342
342
|
"path": "rail-nav/rail-nav.tsx",
|
|
343
|
-
"content": "// Client (the expand state, the arrow keys, the tooltip). The compact navigation of an application, read from Sovkora's\n// web client: a vertical rail of icons on a desktop — the product's mark on top, a tooltip on each icon, the current one\n// marked by an accent bar on its left edge, a footer for settings and the account — that becomes a bottom tab bar on a\n// phone. The same nodes in both: only the layout changes, so the items, their order and their words are written once.\n// The mark lives in the rail on a desktop; on a phone, where the rail has no room for it, `AppHeader` shows it (the rule\n// « one mark visible at every width »). Brand-aware through the tokens: `accent` scopes `.brand-<id>`.\nimport { Tooltip } from \"@krizaka/ui/tooltip\";\nimport { Slot } from \"radix-ui\";\nimport * as React from \"react\";\nimport { tv } from \"tailwind-variants\";\n\nimport { cn } from \"../cn\";\nimport { ChevronGlyph } from \"../glyphs\";\nimport type { BrandId } from \"../marks/ProductLogo\";\n\nexport const railNav = tv({\n slots: {\n shell: \"flex min-h-dvh w-full bg-surface-0 text-fg\",\n root:\n // Phone: a bottom tab bar, clear of the home indicator. Desktop: a sticky column that is only as wide as its icons.\n \"fixed inset-x-0 bottom-0 z-40 flex h-[calc(3.5rem+env(safe-area-inset-bottom))] flex-row border-t border-border-subtle bg-surface-1 pb-[env(safe-area-inset-bottom)] \" +\n \"md:sticky md:overflow-x-clip md:inset-auto md:top-0 md:bottom-auto md:z-auto md:h-dvh md:w-14 md:shrink-0 md:flex-col md:border-t-0 md:border-r md:bg-surface-1 md:pb-0 \" +\n \"md:transition-[width] md:duration-300 motion-reduce:md:transition-none md:data-expanded:w-56\",\n // The mark is the rail's on a desktop; hidden on a phone (the header carries it there).\n mark: \"hidden h-14 w-full shrink-0 items-center overflow-hidden justify-center md:flex md:group-data-expanded/rail:justify-start md:group-data-expanded/rail:px-4\",\n group: \"flex min-w-0 flex-row items-stretch md:flex-col md:items-center md:gap-1 md:px-1.5 md:group-data-expanded/rail:items-stretch\",\n main: \"max-md:grow-(--rail-n) md:flex-1 md:py-2\",\n foot: \"max-md:grow-(--rail-n) md:border-t md:border-border-subtle md:py-2\",\n // The shortcuts: the product's quick ways in (a saved view, a client, « new invoice »), desktop only — a phone's tab bar\n // keeps its five destinations. Their heading shows once the rail is expanded; collapsed, it names the group.\n shortcuts: \"hidden md:flex md:border-t md:border-border-subtle md:py-2\",\n shortcutsHeading: \"sr-only md:group-data-expanded/rail:not-sr-only md:group-data-expanded/rail:px-3.5 md:group-data-expanded/rail:pb-1 md:group-data-expanded/rail:pt-1 text-[11px] font-semibold text-fg-secondary\",\n item:\n \"group/item relative flex min-w-0 flex-1 flex-col items-center justify-center gap-0.5 px-1 text-[11px] font-medium text-fg-secondary no-underline transition-colors \" +\n \"hover:bg-surface-2 hover:text-fg focus-visible:outline-hidden focus-visible:focus-ring-inset \" +\n \"aria-[current=page]:bg-accent-soft aria-[current=page]:text-fg-accent \" +\n // The accent bar: on the top edge of a tab, on the left edge of a rail item.\n \"before:absolute before:inset-x-3 before:top-0 before:h-[3px] before:rounded-b-full before:bg-accent before:opacity-0 before:transition-opacity aria-[current=page]:before:opacity-100 \" +\n \"md:h-10 md:w-full md:flex-none md:flex-row md:justify-center md:gap-3 md:rounded-none md:px-0 md:text-sm \" +\n \"md:before:inset-x-auto md:before:inset-y-2 md:before:left-0 md:before:top-2 md:before:h-auto md:before:w-[3px] md:before:rounded-r-full md:before:rounded-b-none \" +\n \"md:group-data-expanded/rail:justify-start md:group-data-expanded/rail:px-3.5 [&>svg]:h-5 [&>svg]:w-5 [&>svg]:shrink-0\",\n icon: \"relative inline-flex shrink-0 items-center justify-center [&>svg]:h-5 [&>svg]:w-5\",\n label: \"max-w-full truncate leading-none md:sr-only md:text-sm md:leading-normal md:group-data-expanded/rail:not-sr-only\",\n badge:\n \"absolute -right-2 -top-1.5 inline-flex min-w-4 items-center justify-center rounded-sm bg-accent px-1 text-[10px] font-bold leading-4 text-on-accent after:content-[attr(data-count)]\",\n toggle:\n \"hidden h-10 w-full items-center justify-center gap-3 text-xs font-medium text-fg-secondary hover:bg-surface-2 hover:text-fg focus-visible:outline-hidden focus-visible:focus-ring-inset md:flex \" +\n \"md:group-data-expanded/rail:justify-start md:group-data-expanded/rail:px-3.5\",\n body: \"flex min-w-0 flex-1 flex-col max-md:pb-[calc(3.5rem+env(safe-area-inset-bottom))]\",\n },\n});\nconst s = railNav();\n\ninterface RailState {\n expanded: boolean;\n}\nconst RailContext = React.createContext<RailState | null>(null);\nconst useRail = () => {\n const ctx = React.useContext(RailContext);\n if (!ctx) throw new Error(\"RailNav parts must be inside <RailNav.Root>\");\n return ctx;\n};\n\n/** The frame of the page: the rail, then `RailNav.Body` (the header and the content). A row on a desktop. */\nexport function RailNavShell({ className, ...props }: React.ComponentProps<\"div\">) {\n return <div className={s.shell({ className })} {...props} />;\n}\n\n/** The column beside the rail: the `AppHeader`, then the content. On a phone it keeps clear of the tab bar. */\nexport function RailNavBody({ className, ...props }: React.ComponentProps<\"div\">) {\n return <div className={s.body({ className })} {...props} />;\n}\n\nexport type RailNavRootProps = Omit<React.ComponentProps<\"nav\">, \"children\"> & {\n /** The navigation's accessible name (`Sovkora`, `Studio`). */\n label: string;\n /** The product's mark on top of the rail, as a link home (`<Link href=\"/\"><ProductLogo id=\"sovkora\" /></Link>`); named by the app (its `aria-label`). Hidden on a phone: `AppHeader` shows it there. */\n mark?: React.ReactNode;\n /** The product's brand: scopes its colours (`brand-sovkora`…) over the rail, so the accent follows. Omit it inside a page that already wears the brand. */\n accent?: BrandId;\n /** The main destinations: `RailNav.Item`, the ones you work in. Five at most so that they fit a phone's tab bar. */\n children: React.ReactNode;\n /** At the foot of the rail (settings, account), after the main items; on a phone they follow them in the same bar. `RailNav.Item`s or a control with `data-rail-item`. */\n footer?: React.ReactNode;\n /** The product's shortcuts (`RailNav.Item`s: a saved view, a client, « New invoice »), a group above the footer and the expand toggle. Desktop only: a phone's tab bar keeps its destinations. */\n shortcuts?: React.ReactNode;\n /** The shortcuts' heading (« Raccourcis », « Shortcuts ») — passed translated: the group's name, shown once the rail is expanded. */\n shortcutsLabel?: string;\n /** Adds a button that widens the rail to show the words (desktop only). Needs `expandLabels`. */\n expandable?: boolean;\n /** Controlled width (pair with `onExpandedChange` to keep the choice). */\n expanded?: boolean;\n /** The starting width when uncontrolled. Unset: expanded from 1280 px (the words fit there), narrow below — until the person toggles it. */\n defaultExpanded?: boolean;\n /** Called when the toggle widens or narrows the rail. */\n onExpandedChange?: (expanded: boolean) => void;\n /** The toggle's words, `[expand, collapse]`. */\n expandLabels?: readonly [string, string];\n};\n\nconst count = (node: React.ReactNode) => React.Children.toArray(node).length;\n\n// The width from which an expandable rail shows its words by default — 80 rem (1280 px), Tailwind's `xl`.\nconst WIDE = \"(min-width: 80rem)\";\nconst subscribeWide = (onChange: () => void) => {\n if (typeof window === \"undefined\" || !window.matchMedia) return () => undefined;\n const query = window.matchMedia(WIDE);\n query.addEventListener(\"change\", onChange);\n return () => query.removeEventListener(\"change\", onChange);\n};\nconst isWide = () => typeof window !== \"undefined\" && Boolean(window.matchMedia?.(WIDE).matches);\n/** Whether the window is 1280 px wide or more; `false` on the server (the rail then widens before the first paint). */\nfunction useWide() {\n return React.useSyncExternalStore(subscribeWide, isWide, () => false);\n}\n\n/** Moves the focus along the rail's items with the arrows (↑ ↓ on the rail, ← → on the tab bar; both always work), Home and End. */\nfunction moveFocus(event: React.KeyboardEvent<HTMLElement>) {\n const keys: Record<string, number> = { ArrowDown: 1, ArrowRight: 1, ArrowUp: -1, ArrowLeft: -1 };\n const step = keys[event.key];\n if (step === undefined && event.key !== \"Home\" && event.key !== \"End\") return;\n const items = [...event.currentTarget.querySelectorAll<HTMLElement>(\"[data-rail-item]\")];\n if (items.length === 0) return;\n const here = items.findIndex((el) => el === document.activeElement || el.contains(document.activeElement));\n let next: number;\n if (event.key === \"Home\") next = 0;\n else if (event.key === \"End\") next = items.length - 1;\n else if (here < 0) next = step > 0 ? 0 : items.length - 1;\n else next = (here + step + items.length) % items.length;\n event.preventDefault();\n items[next]?.focus();\n}\n\n/** The rail: a vertical column of icons on a desktop, a bottom tab bar on a phone. */\nexport function RailNavRoot({\n label, mark, accent, children, footer, shortcuts, shortcutsLabel, expandable, expanded: controlled, defaultExpanded, onExpandedChange, expandLabels, className, onKeyDown, ...props\n}: RailNavRootProps) {\n const [own, setOwn] = React.useState<boolean | undefined>(defaultExpanded);\n const wide = useWide();\n const headingId = React.useId();\n const expanded = expandable ? (controlled ?? own ?? wide) : false;\n const toggle = () => {\n if (controlled === undefined) setOwn(!expanded);\n onExpandedChange?.(!expanded);\n };\n const value = React.useMemo(() => ({ expanded }), [expanded]);\n return (\n <RailContext.Provider value={value}>\n <nav\n aria-label={label}\n data-expanded={expanded ? \"\" : undefined}\n className={cn(\"group/rail\", accent && \"brand-\" + accent, s.root({ className }))}\n onKeyDown={(e) => {\n onKeyDown?.(e);\n if (!e.defaultPrevented) moveFocus(e);\n }}\n {...props}\n >\n {mark && (\n <div data-brand-mark className={s.mark()}>\n {mark}\n </div>\n )}\n <div className={s.group({ className: s.main() })} style={{ [\"--rail-n\" as string]: Math.max(count(children), 1) }}>\n {children}\n </div>\n {shortcuts && (\n <div role=\"group\" aria-labelledby={shortcutsLabel ? headingId : undefined} data-rail-shortcuts=\"\" className={s.group({ className: s.shortcuts() })}>\n {shortcutsLabel && (\n <p id={headingId} className={s.shortcutsHeading()}>\n {shortcutsLabel}\n </p>\n )}\n {shortcuts}\n </div>\n )}\n {(footer || expandable) && (\n <div className={s.group({ className: s.foot() })} style={{ [\"--rail-n\" as string]: Math.max(count(footer), 1) }}>\n {footer}\n {expandable && expandLabels && (\n <button type=\"button\" data-rail-item className={s.toggle()} aria-expanded={expanded} onClick={toggle}>\n <ChevronGlyph direction={expanded ? \"left\" : \"right\"} className=\"h-4 w-4 shrink-0\" />\n <span className={expanded ? undefined : \"sr-only\"}>{expanded ? expandLabels[1] : expandLabels[0]}</span>\n </button>\n )}\n </div>\n )}\n </nav>\n </RailContext.Provider>\n );\n}\n\nexport type RailNavItemProps = Omit<React.ComponentProps<\"a\">, \"children\"> & {\n /** The item's icon (a signature icon of `@krizaka/icons`): all that shows on a desktop rail. */\n icon: React.ReactNode;\n /** Its words: the accessible name, the tooltip, the tab's caption on a phone, the row's text when the rail is expanded. */\n label: string;\n /** This is the section the user is in: `aria-current=\"page\"`, the accent bar and the accent colour. */\n current?: boolean;\n /** A count (unread, pending) on the icon. Say it in words with `badgeLabel`. */\n badge?: React.ReactNode;\n /** The count in words (« 3 unread »), appended to the accessible name. */\n badgeLabel?: string;\n /** Renders your router's link with the item's look: pass it as the only child. */\n asChild?: boolean;\n children?: React.ReactElement;\n};\n\n/** A destination of the rail. */\nexport function RailNavItem({ icon, label, current, badge, badgeLabel, asChild, children, className, ...props }: RailNavItemProps) {\n const { expanded } = useRail();\n const Comp = asChild ? Slot.Root : \"a\";\n const inner = (\n <>\n <span className={s.icon()}>\n {icon}\n {badge != null && (typeof badge === \"string\" || typeof badge === \"number\") ? (\n // Drawn by CSS, so the count is no text of the link: the visible text stays the label, which the name `Chat, 2 unread` contains.\n <span className={s.badge()} data-count={badge} aria-hidden />\n ) : (\n badge != null && <span className={s.badge()} aria-hidden>{badge}</span>\n )}\n </span>\n <span className={s.label()}>{label}</span>\n </>\n );\n const link = (\n <Comp data-rail-item aria-label={badgeLabel ? `${label}, ${badgeLabel}` : label} aria-current={current ? \"page\" : undefined} className={s.item({ className })} {...props}>\n {asChild && children ? React.cloneElement(children, undefined, inner) : inner}\n </Comp>\n );\n // Expanded, the words are on the row; collapsed, the tooltip says them (Escape dismisses it, the keyboard focus shows it).\n return expanded ? link : <Tooltip content={label} side=\"right\">{link}</Tooltip>;\n}\n\nexport const RailNav = {\n Shell: RailNavShell,\n Root: RailNavRoot,\n Item: RailNavItem,\n Body: RailNavBody,\n};\n"
|
|
343
|
+
"content": "// Client (the expand state, the arrow keys, the tooltip). The compact navigation of an application, read from Sovkora's\n// web client: a vertical rail of icons on a desktop — the product's mark on top, a tooltip on each icon, the current one\n// marked by an accent bar on its left edge, a footer for settings and the account — that becomes a bottom tab bar on a\n// phone. The same nodes in both: only the layout changes, so the items, their order and their words are written once.\n// The mark lives in the rail on a desktop; on a phone, where the rail has no room for it, `AppHeader` shows it (the rule\n// « one mark visible at every width »). Brand-aware through the tokens: `accent` scopes `.brand-<id>`.\nimport { Tooltip } from \"@krizaka/ui/tooltip\";\nimport { Slot } from \"radix-ui\";\nimport * as React from \"react\";\nimport { tv } from \"tailwind-variants\";\n\nimport { cn } from \"../cn\";\nimport { ChevronGlyph } from \"../glyphs\";\nimport type { BrandId } from \"../marks/ProductLogo\";\n\nexport const railNav = tv({\n slots: {\n shell: \"flex min-h-dvh w-full bg-surface-0 text-fg\",\n root:\n // Phone: a bottom tab bar, clear of the home indicator. Desktop: a sticky column that is only as wide as its icons.\n \"fixed inset-x-0 bottom-0 z-40 flex h-[calc(3.5rem+env(safe-area-inset-bottom))] flex-row border-t border-border-subtle bg-surface-1 pb-[env(safe-area-inset-bottom)] \" +\n \"md:sticky md:overflow-x-clip md:inset-auto md:top-0 md:bottom-auto md:z-auto md:h-dvh md:w-14 md:shrink-0 md:flex-col md:border-t-0 md:border-r md:bg-surface-1 md:pb-0 \" +\n \"md:transition-[width] md:duration-300 motion-reduce:md:transition-none md:data-expanded:w-56\",\n // The mark is the rail's on a desktop; hidden on a phone (the header carries it there).\n mark: \"hidden h-14 w-full shrink-0 items-center overflow-hidden justify-center md:flex md:group-data-expanded/rail:justify-start md:group-data-expanded/rail:px-4\",\n group: \"flex min-w-0 flex-row items-stretch md:flex-col md:items-center md:gap-1 md:px-1.5 md:group-data-expanded/rail:items-stretch\",\n main: \"max-md:grow-(--rail-n) md:flex-1 md:py-2\",\n foot: \"max-md:grow-(--rail-n) md:border-t md:border-border-subtle md:py-2\",\n // The shortcuts: the product's quick ways in (a saved view, a client, « new invoice »), desktop only — a phone's tab bar\n // keeps its five destinations. Their heading shows once the rail is expanded; collapsed, it names the group.\n shortcuts: \"hidden md:flex md:border-t md:border-border-subtle md:py-2\",\n shortcutsHeading: \"sr-only md:group-data-expanded/rail:not-sr-only md:group-data-expanded/rail:px-3.5 md:group-data-expanded/rail:pb-1 md:group-data-expanded/rail:pt-1 text-[11px] font-semibold text-fg-secondary\",\n item:\n \"group/item relative flex min-w-0 flex-1 flex-col items-center justify-center gap-0.5 px-1 text-[11px] font-medium text-fg-secondary no-underline transition-colors \" +\n \"hover:bg-surface-2 hover:text-fg focus-visible:outline-hidden focus-visible:focus-ring-inset \" +\n \"aria-[current=page]:bg-accent-soft aria-[current=page]:text-fg-accent \" +\n // The accent bar: on the top edge of a tab, on the left edge of a rail item.\n \"before:absolute before:inset-x-3 before:top-0 before:h-[3px] before:rounded-b-full before:bg-accent before:opacity-0 before:transition-opacity aria-[current=page]:before:opacity-100 \" +\n \"md:h-10 md:w-full md:flex-none md:flex-row md:justify-center md:gap-3 md:rounded-none md:px-0 md:text-sm \" +\n \"md:before:inset-x-auto md:before:inset-y-2 md:before:left-0 md:before:top-2 md:before:h-auto md:before:w-[3px] md:before:rounded-r-full md:before:rounded-b-none \" +\n \"md:group-data-expanded/rail:justify-start md:group-data-expanded/rail:px-3.5 [&>svg]:h-5 [&>svg]:w-5 [&>svg]:shrink-0\",\n icon: \"relative inline-flex shrink-0 items-center justify-center [&>svg]:h-5 [&>svg]:w-5\",\n label: \"max-w-full truncate leading-none md:sr-only md:text-sm md:leading-normal md:group-data-expanded/rail:not-sr-only\",\n badge:\n \"absolute -right-2 -top-1.5 inline-flex min-w-4 items-center justify-center rounded-sm bg-accent px-1 text-[10px] font-bold leading-4 text-on-accent after:content-[attr(data-count)]\",\n toggle:\n \"hidden h-10 w-full items-center justify-center gap-3 text-xs font-medium text-fg-secondary hover:bg-surface-2 hover:text-fg focus-visible:outline-hidden focus-visible:focus-ring-inset md:flex \" +\n \"md:group-data-expanded/rail:justify-start md:group-data-expanded/rail:px-3.5\",\n body: \"flex min-w-0 flex-1 flex-col max-md:pb-[calc(3.5rem+env(safe-area-inset-bottom))]\",\n },\n});\nconst s = railNav();\n\ninterface RailState {\n expanded: boolean;\n}\nconst RailContext = React.createContext<RailState | null>(null);\nconst useRail = () => {\n const ctx = React.useContext(RailContext);\n if (!ctx) throw new Error(\"RailNav parts must be inside <RailNav.Root>\");\n return ctx;\n};\n\n/** The frame of the page: the rail, then `RailNav.Body` (the header and the content). A row on a desktop. */\nexport function RailNavShell({ className, ...props }: React.ComponentProps<\"div\">) {\n return <div className={s.shell({ className })} {...props} />;\n}\n\n/** The column beside the rail: the `AppHeader`, then the content. On a phone it keeps clear of the tab bar. */\nexport function RailNavBody({ className, ...props }: React.ComponentProps<\"div\">) {\n return <div className={s.body({ className })} {...props} />;\n}\n\nexport type RailNavRootProps = Omit<React.ComponentProps<\"nav\">, \"children\"> & {\n /** The navigation's accessible name (`Sovkora`, `Studio`). */\n label: string;\n /** The product's mark on top of the rail, as a link home (`<Link href=\"/\"><ProductLogo id=\"sovkora\" /></Link>`); named by the app (its `aria-label`). Hidden on a phone: `AppHeader` shows it there. */\n mark?: React.ReactNode;\n /** The product's brand: scopes its colours (`brand-sovkora`…) over the rail, so the accent follows. Omit it inside a page that already wears the brand. */\n accent?: BrandId;\n /** The main destinations: `RailNav.Item`, the ones you work in. Five at most so that they fit a phone's tab bar. */\n children: React.ReactNode;\n /** At the foot of the rail (settings, account), after the main items; on a phone they follow them in the same bar. `RailNav.Item`s or a control with `data-rail-item`. */\n footer?: React.ReactNode;\n /** The product's shortcuts (`RailNav.Item`s: a saved view, a client, « New invoice »), a group above the footer and the expand toggle. Desktop only: a phone's tab bar keeps its destinations. */\n shortcuts?: React.ReactNode;\n /** The shortcuts' heading (« Raccourcis », « Shortcuts ») — passed translated: the group's name, shown once the rail is expanded. */\n shortcutsLabel?: string;\n /** Adds a button that widens the rail to show the words (desktop only). Needs `expandLabels`. */\n expandable?: boolean;\n /** Controlled width (pair with `onExpandedChange` to keep the choice). */\n expanded?: boolean;\n /** The starting width when uncontrolled. Unset: expanded from 1280 px (the words fit there), narrow below — until the person toggles it. */\n defaultExpanded?: boolean;\n /** Called when the toggle widens or narrows the rail. */\n onExpandedChange?: (expanded: boolean) => void;\n /** The toggle's words, `[expand, collapse]`. */\n expandLabels?: readonly [string, string];\n};\n\nconst count = (node: React.ReactNode) => React.Children.toArray(node).length;\n\n// The width from which an expandable rail shows its words by default — 80 rem (1280 px), Tailwind's `xl`.\nconst WIDE = \"(min-width: 80rem)\";\nconst subscribeWide = (onChange: () => void) => {\n if (globalThis.window === undefined || !globalThis.matchMedia) return () => undefined;\n const query = globalThis.matchMedia(WIDE);\n query.addEventListener(\"change\", onChange);\n return () => query.removeEventListener(\"change\", onChange);\n};\nconst isWide = () => globalThis.window !== undefined && Boolean(globalThis.matchMedia?.(WIDE).matches);\n/** Whether the window is 1280 px wide or more; `false` on the server (the rail then widens before the first paint). */\nfunction useWide() {\n return React.useSyncExternalStore(subscribeWide, isWide, () => false);\n}\n\n/** Moves the focus along the rail's items with the arrows (↑ ↓ on the rail, ← → on the tab bar; both always work), Home and End. */\nfunction moveFocus(event: React.KeyboardEvent<HTMLElement>) {\n const keys: Record<string, number> = { ArrowDown: 1, ArrowRight: 1, ArrowUp: -1, ArrowLeft: -1 };\n const step = keys[event.key];\n if (step === undefined && event.key !== \"Home\" && event.key !== \"End\") return;\n const items = [...event.currentTarget.querySelectorAll<HTMLElement>(\"[data-rail-item]\")];\n if (items.length === 0) return;\n const here = items.findIndex((el) => el === document.activeElement || el.contains(document.activeElement));\n let next: number;\n if (event.key === \"Home\") next = 0;\n else if (event.key === \"End\") next = items.length - 1;\n else if (here < 0) next = step > 0 ? 0 : items.length - 1;\n else next = (here + step + items.length) % items.length;\n event.preventDefault();\n items[next]?.focus();\n}\n\n/** The rail: a vertical column of icons on a desktop, a bottom tab bar on a phone. */\nexport function RailNavRoot({\n label, mark, accent, children, footer, shortcuts, shortcutsLabel, expandable, expanded: controlled, defaultExpanded, onExpandedChange, expandLabels, className, onKeyDown, ...props\n}: RailNavRootProps) {\n const [own, setOwn] = React.useState<boolean | undefined>(defaultExpanded);\n const wide = useWide();\n const headingId = React.useId();\n const expanded = expandable ? (controlled ?? own ?? wide) : false;\n const toggle = () => {\n if (controlled === undefined) setOwn(!expanded);\n onExpandedChange?.(!expanded);\n };\n const value = React.useMemo(() => ({ expanded }), [expanded]);\n return (\n <RailContext.Provider value={value}>\n <nav\n aria-label={label}\n data-expanded={expanded ? \"\" : undefined}\n className={cn(\"group/rail\", accent && \"brand-\" + accent, s.root({ className }))}\n onKeyDown={(e) => {\n onKeyDown?.(e);\n if (!e.defaultPrevented) moveFocus(e);\n }}\n {...props}\n >\n {mark && (\n <div data-brand-mark className={s.mark()}>\n {mark}\n </div>\n )}\n <div className={s.group({ className: s.main() })} style={{ [\"--rail-n\" as string]: Math.max(count(children), 1) }}>\n {children}\n </div>\n {shortcuts && (\n <div role=\"group\" aria-labelledby={shortcutsLabel ? headingId : undefined} data-rail-shortcuts=\"\" className={s.group({ className: s.shortcuts() })}>\n {shortcutsLabel && (\n <p id={headingId} className={s.shortcutsHeading()}>\n {shortcutsLabel}\n </p>\n )}\n {shortcuts}\n </div>\n )}\n {(footer || expandable) && (\n <div className={s.group({ className: s.foot() })} style={{ [\"--rail-n\" as string]: Math.max(count(footer), 1) }}>\n {footer}\n {expandable && expandLabels && (\n <button type=\"button\" data-rail-item className={s.toggle()} aria-expanded={expanded} onClick={toggle}>\n <ChevronGlyph direction={expanded ? \"left\" : \"right\"} className=\"h-4 w-4 shrink-0\" />\n <span className={expanded ? undefined : \"sr-only\"}>{expanded ? expandLabels[1] : expandLabels[0]}</span>\n </button>\n )}\n </div>\n )}\n </nav>\n </RailContext.Provider>\n );\n}\n\nexport type RailNavItemProps = Omit<React.ComponentProps<\"a\">, \"children\"> & {\n /** The item's icon (a signature icon of `@krizaka/icons`): all that shows on a desktop rail. */\n icon: React.ReactNode;\n /** Its words: the accessible name, the tooltip, the tab's caption on a phone, the row's text when the rail is expanded. */\n label: string;\n /** This is the section the user is in: `aria-current=\"page\"`, the accent bar and the accent colour. */\n current?: boolean;\n /** A count (unread, pending) on the icon. Say it in words with `badgeLabel`. */\n badge?: React.ReactNode;\n /** The count in words (« 3 unread »), appended to the accessible name. */\n badgeLabel?: string;\n /** Renders your router's link with the item's look: pass it as the only child. */\n asChild?: boolean;\n children?: React.ReactElement;\n};\n\n/** A destination of the rail. */\nexport function RailNavItem({ icon, label, current, badge, badgeLabel, asChild, children, className, ...props }: RailNavItemProps) {\n const { expanded } = useRail();\n const Comp = asChild ? Slot.Root : \"a\";\n const inner = (\n <>\n <span className={s.icon()}>\n {icon}\n {badge != null && (typeof badge === \"string\" || typeof badge === \"number\") ? (\n // Drawn by CSS, so the count is no text of the link: the visible text stays the label, which the name `Chat, 2 unread` contains.\n <span className={s.badge()} data-count={badge} aria-hidden />\n ) : (\n badge != null && <span className={s.badge()} aria-hidden>{badge}</span>\n )}\n </span>\n <span className={s.label()}>{label}</span>\n </>\n );\n const link = (\n <Comp data-rail-item aria-label={badgeLabel ? `${label}, ${badgeLabel}` : label} aria-current={current ? \"page\" : undefined} className={s.item({ className })} {...props}>\n {asChild && children ? React.cloneElement(children, undefined, inner) : inner}\n </Comp>\n );\n // Expanded, the words are on the row; collapsed, the tooltip says them (Escape dismisses it, the keyboard focus shows it).\n return expanded ? link : <Tooltip content={label} side=\"right\">{link}</Tooltip>;\n}\n\nexport const RailNav = {\n Shell: RailNavShell,\n Root: RailNavRoot,\n Item: RailNavItem,\n Body: RailNavBody,\n};\n"
|
|
344
344
|
}
|
|
345
345
|
],
|
|
346
346
|
"dependencies": [
|
|
347
|
-
"@krizaka/tokens@^4.
|
|
347
|
+
"@krizaka/tokens@^4.5.0",
|
|
348
348
|
"radix-ui@^1.8.1",
|
|
349
349
|
"tailwind-variants@^3.3.1"
|
|
350
350
|
],
|