@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/nav-bar.json
CHANGED
|
@@ -647,7 +647,7 @@
|
|
|
647
647
|
},
|
|
648
648
|
{
|
|
649
649
|
"path": "marks/InkMark.tsx",
|
|
650
|
-
"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"
|
|
650
|
+
"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"
|
|
651
651
|
},
|
|
652
652
|
{
|
|
653
653
|
"path": "marks/krizaka-geometry.ts",
|
|
@@ -683,7 +683,7 @@
|
|
|
683
683
|
},
|
|
684
684
|
{
|
|
685
685
|
"path": "meta.ts",
|
|
686
|
-
"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"
|
|
686
|
+
"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"
|
|
687
687
|
},
|
|
688
688
|
{
|
|
689
689
|
"path": "nav-bar/index.ts",
|
|
@@ -707,11 +707,11 @@
|
|
|
707
707
|
},
|
|
708
708
|
{
|
|
709
709
|
"path": "nav-bar/product-actions.tsx",
|
|
710
|
-
"content": "// Client (the Button). The right side of a product's bar, decided once for every product (« the objective is to use the app,\n// not to talk to us »): the primary action is using the app — « Sign in » while sign-up is closed, « Try » once it opens —\n// never a duplicate « Sign in » beside it, never « Contact » (that is a plain link in the footer).\nimport type * as React from \"react\";\n\nimport { Button } from \"../button/button\";\n\n/** The two ways into a product. */\nexport const ProductBarAction = { SignIn: \"sign-in\", Try: \"try\" } as const;\nexport type ProductBarAction = (typeof ProductBarAction)[keyof typeof ProductBarAction];\n\nexport interface ProductBarState {\n /** Whether the product accepts new accounts (its `signupOpen` setting). */\n signupOpen: boolean;\n /** Whether the product has a « try it » action (a free first audit, a founder offer). */\n hasTry: boolean;\n}\n\n/** What the bar shows: one primary, and « Sign in » beside it only when it is not the primary. */\nexport function productBarActions({ signupOpen, hasTry }: ProductBarState): { primary: ProductBarAction; secondary: ProductBarAction | null } {\n return signupOpen && hasTry ? { primary: ProductBarAction.Try, secondary: ProductBarAction.SignIn } : { primary: ProductBarAction.SignIn, secondary: null };\n}\n\nexport interface ProductBarLink {\n href: string;\n /** Passed translated. */\n label: string;\n}\n\nexport type ProductBarActionsProps = {\n /** Where « Sign in » leads, and its words. */\n signIn: ProductBarLink;\n /** « Try for free » (the first audit is free), the founder offer: absent when the product has none. */\n tryIt?: ProductBarLink;\n /** Whether the product accepts new accounts (its `signupOpen` setting): « Try » is the primary action only then. */\n signupOpen: boolean;\n /** The app's link component (Next's `Link`); an `<a>` otherwise. */\n linkAs?: React.ElementType;\n /**\n * `bar` (from `md`, the buttons of the bar) or `panel` (the mobile panel: full-width, the primary last).\n * @default \"bar\"\n */\n placement?: \"bar\" | \"panel\";\n};\n\n/** The product bar's actions: use the app. Put it in `NavBar.Actions` (`placement=\"bar\"`) or in `NavBar.Mobile` (`placement=\"panel\"`). */\nexport function ProductBarActions({ signIn, tryIt, signupOpen, linkAs: Link = \"a\", placement = \"bar\" }: ProductBarActionsProps) {\n const { primary, secondary } = productBarActions({ signupOpen, hasTry: Boolean(tryIt) });\n const link = (kind: ProductBarAction) => (kind === ProductBarAction.Try && tryIt ? tryIt : signIn);\n const panel = placement === \"panel\";\n const button = (kind: ProductBarAction, variant: \"primary\" | \"ghost\") => (\n <Button key={kind} asChild data-signed-out-only=\"\" variant={variant} size={panel ? \"md\" : \"sm\"} className={panel ? (variant === \"primary\" ? \"mt-2 w-full font-bold\" : \"w-full\") : variant === \"primary\" ? \"ml-1 hidden font-bold md:inline-flex\" : \"hidden md:inline-flex\"}>\n <Link href={link(kind).href}>{link(kind).label}</Link>\n </Button>\n );\n return (\n <>\n {secondary ? button(secondary, \"ghost\") : null}\n {button(primary, \"primary\")}\n </>\n );\n}\n"
|
|
710
|
+
"content": "// Client (the Button). The right side of a product's bar, decided once for every product (« the objective is to use the app,\n// not to talk to us »): the primary action is using the app — « Sign in » while sign-up is closed, « Try » once it opens —\n// never a duplicate « Sign in » beside it, never « Contact » (that is a plain link in the footer).\nimport type * as React from \"react\";\n\nimport { Button } from \"../button/button\";\n\n/** The two ways into a product. */\nexport const ProductBarAction = { SignIn: \"sign-in\", Try: \"try\" } as const;\nexport type ProductBarAction = (typeof ProductBarAction)[keyof typeof ProductBarAction];\n\nexport interface ProductBarState {\n /** Whether the product accepts new accounts (its `signupOpen` setting). */\n signupOpen: boolean;\n /** Whether the product has a « try it » action (a free first audit, a founder offer). */\n hasTry: boolean;\n}\n\n/** What the bar shows: one primary, and « Sign in » beside it only when it is not the primary. */\nexport function productBarActions({ signupOpen, hasTry }: ProductBarState): { primary: ProductBarAction; secondary: ProductBarAction | null } {\n return signupOpen && hasTry ? { primary: ProductBarAction.Try, secondary: ProductBarAction.SignIn } : { primary: ProductBarAction.SignIn, secondary: null };\n}\n\nexport interface ProductBarLink {\n href: string;\n /** Passed translated. */\n label: string;\n}\n\nexport type ProductBarActionsProps = {\n /** Where « Sign in » leads, and its words. */\n signIn: ProductBarLink;\n /** « Try for free » (the first audit is free), the founder offer: absent when the product has none. */\n tryIt?: ProductBarLink;\n /** Whether the product accepts new accounts (its `signupOpen` setting): « Try » is the primary action only then. */\n signupOpen: boolean;\n /** The app's link component (Next's `Link`); an `<a>` otherwise. */\n linkAs?: React.ElementType;\n /**\n * `bar` (from `md`, the buttons of the bar) or `panel` (the mobile panel: full-width, the primary last).\n * @default \"bar\"\n */\n placement?: \"bar\" | \"panel\";\n};\n\n/** The product bar's actions: use the app. Put it in `NavBar.Actions` (`placement=\"bar\"`) or in `NavBar.Mobile` (`placement=\"panel\"`). */\nexport function ProductBarActions({ signIn, tryIt, signupOpen, linkAs: Link = \"a\", placement = \"bar\" }: Readonly<ProductBarActionsProps>) {\n const { primary, secondary } = productBarActions({ signupOpen, hasTry: Boolean(tryIt) });\n const link = (kind: ProductBarAction) => (kind === ProductBarAction.Try && tryIt ? tryIt : signIn);\n const panel = placement === \"panel\";\n const button = (kind: ProductBarAction, variant: \"primary\" | \"ghost\") => (\n <Button key={kind} asChild data-signed-out-only=\"\" variant={variant} size={panel ? \"md\" : \"sm\"} className={panel ? (variant === \"primary\" ? \"mt-2 w-full font-bold\" : \"w-full\") : variant === \"primary\" ? \"ml-1 hidden font-bold md:inline-flex\" : \"hidden md:inline-flex\"}>\n <Link href={link(kind).href}>{link(kind).label}</Link>\n </Button>\n );\n return (\n <>\n {secondary ? button(secondary, \"ghost\") : null}\n {button(primary, \"primary\")}\n </>\n );\n}\n"
|
|
711
711
|
},
|
|
712
712
|
{
|
|
713
713
|
"path": "nav-bar/session.tsx",
|
|
714
|
-
"content": "// Client. The bar's « who is here » island, the same for every product: it asks `GET /api/me` (the contract of ./me)\n// through @krizaka/query and shows the product's account menu or its sign-in actions. It needs a QueryClient above it.\nimport { krizakaFetch, useQuery } from \"@krizaka/query\";\nimport * as React from \"react\";\n\nimport { type MeResponse, meSchema } from \"./me\";\n\nexport type NavBarSessionProps<TAccount = unknown> = {\n /**\n * Where the contract is served.\n * @default \"/api/me\"\n */\n endpoint?: string;\n /**\n * The session the server already knows (a dynamic page reading its cookie): the first paint then IS the answer, with no\n * placeholder and no swap. Leave it out on a static page; the bar reserves its place until the answer comes.\n */\n initial?: MeResponse<TAccount>;\n /** Signed out: the product's `ProductBarActions`, told whether sign-up is open. */\n signedOut: (state: { signupOpen: boolean }) => React.ReactNode;\n /** Signed in: the product's `AccountMenu`, given the account. */\n signedIn: (account: TAccount, state: { signupOpen: boolean }) => React.ReactNode;\n /**\n * The server's hint that a session cookie exists (krizaka-ui#827): while the answer is on its way the bar then reserves\n * a signed-in placeholder (account-sized, `data-state=\"signed-in-pending\"`) instead of an empty place, and never the\n * « Sign in » action. A hint, never the proof: `/api/me` still decides. Left out, it is read from the family's readable\n * flag cookie (`kz-session=1`, kept by `sessionHint` of `@krizaka/auth` in the proxy), so a static page needs no prop.\n */\n sessionHint?: boolean;\n /** The hint's words while the answer is on its way (“Checking your session…”) — passed translated. */\n hint: string;\n /** Classes of the loading placeholder. */\n className?: string;\n};\n\n/** The readable flag the proxy keeps next to the HttpOnly session cookie (`@krizaka/auth` `SESSION_HINT_COOKIE`; a test pins the two). */\nexport const SESSION_HINT_COOKIE = \"kz-session\";\n\nconst noop = () => () => {};\nconst readFlag = () => typeof document !== \"undefined\" && document.cookie.split(\";\").some((part) => part.trim() === `${SESSION_HINT_COOKIE}=1`);\n\n/** Whether the readable flag cookie says a session exists. False on the server and on the first hydration pass (no mismatch). */\nexport function useSessionHint(): boolean {\n return React.useSyncExternalStore(noop, readFlag, () => false);\n}\n\nexport const sessionKey = (endpoint: string) => [\"krizaka\", \"session\", endpoint] as const;\n\n/** What the bar knows of the visitor: `pending` is NOT « signed out » — nothing is drawn as either until the answer comes. */\nexport type NavSession<TAccount = unknown> = { status: \"pending\" } | { status: \"in\"; account: TAccount; signupOpen: boolean } | { status: \"out\"; signupOpen: boolean };\n\n/**\n * The one « who is here » reading of the family (the bar, a hero's action, a closing call all read this and so never\n * disagree). Three rules, krizaka-ui#800: (1) `pending` is its own state, never drawn as signed out; (2) only an answer\n * (`GET /api/me` 200) changes the state — a failed or throttled refetch keeps the last known state instead of flipping a\n * signed-in person to « Sign in »; (3) with no answer at all (the first request failed) the visitor can still sign in.\n */\nexport function useNavSession<TAccount = unknown>(endpoint = \"/api/me\", initial?: MeResponse<TAccount>): NavSession<TAccount> {\n const { data, isPending, isError } = useQuery({\n queryKey: sessionKey(endpoint),\n queryFn: ({ signal }) => krizakaFetch(endpoint, { schema: meSchema, signal, cache: \"no-store\" }),\n staleTime: 30_000,\n retry: false,\n throwOnError: false,\n ...(initial ? { initialData: initial as MeResponse } : {}),\n });\n if (data) {\n const me = data as MeResponse<TAccount>;\n return me.signedIn && me.account !== undefined ? { status: \"in\", account: me.account, signupOpen: me.signupOpen } : { status: \"out\", signupOpen: me.signupOpen };\n }\n if (isPending && !isError) return { status: \"pending\" };\n return { status: \"out\", signupOpen: false };\n}\n\n/**\n * The bar's session island: put it in `NavBar.Actions`. While the answer is on its way it reserves the place and says\n * `hint` politely (or, given `initial`, draws the server's answer at once); if the first request fails it shows the\n * signed-out actions (the visitor can still sign in).\n */\nexport function NavBarSession<TAccount = unknown>({ endpoint = \"/api/me\", initial, sessionHint, signedOut, signedIn, hint, className }: NavBarSessionProps<TAccount
|
|
714
|
+
"content": "// Client. The bar's « who is here » island, the same for every product: it asks `GET /api/me` (the contract of ./me)\n// through @krizaka/query and shows the product's account menu or its sign-in actions. It needs a QueryClient above it.\nimport { krizakaFetch, useQuery } from \"@krizaka/query\";\nimport * as React from \"react\";\n\nimport { type MeResponse, meSchema } from \"./me\";\n\nexport type NavBarSessionProps<TAccount = unknown> = {\n /**\n * Where the contract is served.\n * @default \"/api/me\"\n */\n endpoint?: string;\n /**\n * The session the server already knows (a dynamic page reading its cookie): the first paint then IS the answer, with no\n * placeholder and no swap. Leave it out on a static page; the bar reserves its place until the answer comes.\n */\n initial?: MeResponse<TAccount>;\n /** Signed out: the product's `ProductBarActions`, told whether sign-up is open. */\n signedOut: (state: { signupOpen: boolean }) => React.ReactNode;\n /** Signed in: the product's `AccountMenu`, given the account. */\n signedIn: (account: TAccount, state: { signupOpen: boolean }) => React.ReactNode;\n /**\n * The server's hint that a session cookie exists (krizaka-ui#827): while the answer is on its way the bar then reserves\n * a signed-in placeholder (account-sized, `data-state=\"signed-in-pending\"`) instead of an empty place, and never the\n * « Sign in » action. A hint, never the proof: `/api/me` still decides. Left out, it is read from the family's readable\n * flag cookie (`kz-session=1`, kept by `sessionHint` of `@krizaka/auth` in the proxy), so a static page needs no prop.\n */\n sessionHint?: boolean;\n /** The hint's words while the answer is on its way (“Checking your session…”) — passed translated. */\n hint: string;\n /** Classes of the loading placeholder. */\n className?: string;\n};\n\n/** The readable flag the proxy keeps next to the HttpOnly session cookie (`@krizaka/auth` `SESSION_HINT_COOKIE`; a test pins the two). */\nexport const SESSION_HINT_COOKIE = \"kz-session\";\n\nconst noop = () => () => {};\nconst readFlag = () => typeof document !== \"undefined\" && document.cookie.split(\";\").some((part) => part.trim() === `${SESSION_HINT_COOKIE}=1`);\n\n/** Whether the readable flag cookie says a session exists. False on the server and on the first hydration pass (no mismatch). */\nexport function useSessionHint(): boolean {\n return React.useSyncExternalStore(noop, readFlag, () => false);\n}\n\nexport const sessionKey = (endpoint: string) => [\"krizaka\", \"session\", endpoint] as const;\n\n/** What the bar knows of the visitor: `pending` is NOT « signed out » — nothing is drawn as either until the answer comes. */\nexport type NavSession<TAccount = unknown> = { status: \"pending\" } | { status: \"in\"; account: TAccount; signupOpen: boolean } | { status: \"out\"; signupOpen: boolean };\n\n/**\n * The one « who is here » reading of the family (the bar, a hero's action, a closing call all read this and so never\n * disagree). Three rules, krizaka-ui#800: (1) `pending` is its own state, never drawn as signed out; (2) only an answer\n * (`GET /api/me` 200) changes the state — a failed or throttled refetch keeps the last known state instead of flipping a\n * signed-in person to « Sign in »; (3) with no answer at all (the first request failed) the visitor can still sign in.\n */\nexport function useNavSession<TAccount = unknown>(endpoint = \"/api/me\", initial?: MeResponse<TAccount>): NavSession<TAccount> {\n const { data, isPending, isError } = useQuery({\n queryKey: sessionKey(endpoint),\n queryFn: ({ signal }) => krizakaFetch(endpoint, { schema: meSchema, signal, cache: \"no-store\" }),\n staleTime: 30_000,\n retry: false,\n throwOnError: false,\n ...(initial ? { initialData: initial as MeResponse } : {}),\n });\n if (data) {\n const me = data as MeResponse<TAccount>;\n return me.signedIn && me.account !== undefined ? { status: \"in\", account: me.account, signupOpen: me.signupOpen } : { status: \"out\", signupOpen: me.signupOpen };\n }\n if (isPending && !isError) return { status: \"pending\" };\n return { status: \"out\", signupOpen: false };\n}\n\n/**\n * The bar's session island: put it in `NavBar.Actions`. While the answer is on its way it reserves the place and says\n * `hint` politely (or, given `initial`, draws the server's answer at once); if the first request fails it shows the\n * signed-out actions (the visitor can still sign in).\n */\nexport function NavBarSession<TAccount = unknown>({ endpoint = \"/api/me\", initial, sessionHint, signedOut, signedIn, hint, className }: Readonly<NavBarSessionProps<TAccount>>) {\n const session = useNavSession<TAccount>(endpoint, initial);\n const flagged = useSessionHint();\n if (session.status === \"pending\") {\n if (sessionHint ?? flagged) {\n return (\n <span role=\"status\" aria-live=\"polite\" data-state=\"signed-in-pending\" className={className}>\n <span aria-hidden=\"true\" className=\"inline-block size-9 rounded-full bg-surface-2\" />\n <span className=\"sr-only\">{hint}</span>\n </span>\n );\n }\n return (\n <span role=\"status\" aria-live=\"polite\" data-state=\"loading\" className={className}>\n <span className=\"sr-only\">{hint}</span>\n </span>\n );\n }\n const state = { signupOpen: session.signupOpen };\n return <>{session.status === \"in\" ? signedIn(session.account, state) : signedOut(state)}</>;\n}\n"
|
|
715
715
|
},
|
|
716
716
|
{
|
|
717
717
|
"path": "sliding-indicator.ts",
|
|
@@ -719,7 +719,7 @@
|
|
|
719
719
|
}
|
|
720
720
|
],
|
|
721
721
|
"dependencies": [
|
|
722
|
-
"@krizaka/tokens@^4.
|
|
722
|
+
"@krizaka/tokens@^4.5.0",
|
|
723
723
|
"radix-ui@^1.8.1",
|
|
724
724
|
"tailwind-variants@^3.3.1"
|
|
725
725
|
],
|
|
@@ -98,7 +98,7 @@
|
|
|
98
98
|
"files": [
|
|
99
99
|
{
|
|
100
100
|
"path": "meta.ts",
|
|
101
|
-
"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"
|
|
101
|
+
"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"
|
|
102
102
|
},
|
|
103
103
|
{
|
|
104
104
|
"path": "next-actions/index.ts",
|
|
@@ -110,7 +110,7 @@
|
|
|
110
110
|
},
|
|
111
111
|
{
|
|
112
112
|
"path": "next-actions/next-actions.tsx",
|
|
113
|
-
"content": "// Server-safe. A ranked list from the host: this block never creates an action of its own.\nimport type * as React from \"react\";\n\nexport type ActionUrgency = \"low\" | \"medium\" | \"high\";\n\nexport interface NextAction {\n /** A stable key supplied by the host. */\n id: string;\n /** The action's short name. */\n title: React.ReactNode;\n /** Why it matters, in one line. */\n why: string;\n /** How soon it matters. */\n urgency: ActionUrgency;\n /** The host's translated urgency word. */\n urgencyLabel: React.ReactNode;\n /** A host-rendered link, button or command for a developer tool. */\n action: React.ReactNode;\n}\n\nexport interface NextActionsProps extends Omit<React.ComponentProps<\"section\">, \"children\" | \"title\"> {\n /** A heading such as “Que faire maintenant”. */\n title: React.ReactNode;\n /** Two or three actions, already ordered by the host from most to least important. */\n actions: readonly [NextAction, NextAction] | readonly [NextAction, NextAction, NextAction];\n}\n\n/** “What to do now”: two or three ranked actions, with their reason and urgency. */\nexport function NextActions({ title, actions, className, ...props }: NextActionsProps) {\n return (\n <section className={[\"kz-next-actions\", className].filter(Boolean).join(\" \")} {...props}>\n <h2 className=\"kz-next-actions-title\">{title}</h2>\n <ol className=\"kz-next-actions-list\">\n {actions.map((action, index) => (\n <li className=\"kz-next-action\" data-urgency={action.urgency} key={action.id}>\n <span className=\"kz-next-action-rank\" aria-hidden=\"true\">{index + 1}.</span>\n <div className=\"kz-next-action-content\">\n <div className=\"kz-next-action-copy\">\n <div className=\"kz-next-action-heading\">\n <h3>{action.title}</h3>\n <span className=\"kz-next-action-urgency\" data-urgency={action.urgency}>{action.urgencyLabel}</span>\n </div>\n <p>{action.why}</p>\n </div>\n <div className=\"kz-next-action-control\">{action.action}</div>\n </div>\n </li>\n ))}\n </ol>\n </section>\n );\n}\n"
|
|
113
|
+
"content": "// Server-safe. A ranked list from the host: this block never creates an action of its own.\nimport type * as React from \"react\";\n\nexport type ActionUrgency = \"low\" | \"medium\" | \"high\";\n\nexport interface NextAction {\n /** A stable key supplied by the host. */\n id: string;\n /** The action's short name. */\n title: React.ReactNode;\n /** Why it matters, in one line. */\n why: string;\n /** How soon it matters. */\n urgency: ActionUrgency;\n /** The host's translated urgency word. */\n urgencyLabel: React.ReactNode;\n /** A host-rendered link, button or command for a developer tool. */\n action: React.ReactNode;\n}\n\nexport interface NextActionsProps extends Omit<React.ComponentProps<\"section\">, \"children\" | \"title\"> {\n /** A heading such as “Que faire maintenant”. */\n title: React.ReactNode;\n /** Two or three actions, already ordered by the host from most to least important. */\n actions: readonly [NextAction, NextAction] | readonly [NextAction, NextAction, NextAction];\n}\n\n/** “What to do now”: two or three ranked actions, with their reason and urgency. */\nexport function NextActions({ title, actions, className, ...props }: Readonly<NextActionsProps>) {\n return (\n <section className={[\"kz-next-actions\", className].filter(Boolean).join(\" \")} {...props}>\n <h2 className=\"kz-next-actions-title\">{title}</h2>\n <ol className=\"kz-next-actions-list\">\n {actions.map((action, index) => (\n <li className=\"kz-next-action\" data-urgency={action.urgency} key={action.id}>\n <span className=\"kz-next-action-rank\" aria-hidden=\"true\">{index + 1}.</span>\n <div className=\"kz-next-action-content\">\n <div className=\"kz-next-action-copy\">\n <div className=\"kz-next-action-heading\">\n <h3>{action.title}</h3>\n <span className=\"kz-next-action-urgency\" data-urgency={action.urgency}>{action.urgencyLabel}</span>\n </div>\n <p>{action.why}</p>\n </div>\n <div className=\"kz-next-action-control\">{action.action}</div>\n </div>\n </li>\n ))}\n </ol>\n </section>\n );\n}\n"
|
|
114
114
|
}
|
|
115
115
|
],
|
|
116
116
|
"dependencies": [],
|
|
@@ -152,7 +152,7 @@
|
|
|
152
152
|
"files": [
|
|
153
153
|
{
|
|
154
154
|
"path": "meta.ts",
|
|
155
|
-
"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"
|
|
155
|
+
"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"
|
|
156
156
|
},
|
|
157
157
|
{
|
|
158
158
|
"path": "notification-preferences/index.ts",
|
|
@@ -164,7 +164,7 @@
|
|
|
164
164
|
},
|
|
165
165
|
{
|
|
166
166
|
"path": "notification-preferences/notification-preferences.tsx",
|
|
167
|
-
"content": "\"use client\";\n// Client (switches and chips). What reaches a person: categories down, channels across, a switch at each crossing, and\n// presets that set the whole matrix at once. The value is controlled and plain data; the words are props.\nimport * as React from \"react\";\nimport { tv } from \"tailwind-variants\";\n\nimport { Chip } from \"../chip\";\nimport { Switch } from \"../switch\";\n\nexport const notificationPreferences = tv({\n slots: {\n root: \"flex flex-col gap-3\",\n hint: \"text-xs text-fg-secondary\",\n table: \"w-full overflow-hidden rounded-2xl border border-border-default text-left\",\n head: \"bg-surface-2 text-xs font-semibold text-fg-secondary\",\n channelCell: \"w-16 px-2 py-2.5 text-center sm:w-24\",\n cornerCell: \"px-4 py-2.5\",\n row: \"border-t border-border-subtle\",\n category: \"px-4 py-3 text-left font-normal\",\n name: \"block text-sm font-semibold text-fg\",\n note: \"block text-xs text-fg-secondary\",\n cell: \"px-2 py-3 text-center\",\n },\n});\n\n/** Category id → channel id → on. A missing entry is off; a crossing a category does not use (see `channels`) is never written. */\nexport type NotificationMatrix = Record<string, Record<string, boolean>>;\n\nexport type NotificationChannel = {\n /** Its key in the matrix (`app`, `email`). */\n id: string;\n /** The column's name (`In the app`, `By e-mail`). */\n label: string;\n /** The whole column is inert (e-mail is off for the account). */\n disabled?: boolean;\n};\n\nexport type NotificationCategory = {\n /** Its key in the matrix (`social`, `security`). */\n id: string;\n /** The row's name. */\n label: string;\n /** What these notifications are, one line. */\n description?: string;\n /** The channels this category can use (ids); left out, every channel. Other crossings show no switch. */\n channels?: readonly string[];\n /** Always on, and shown so (security): the switches are inert and `lockedNote` replaces the description. */\n locked?: boolean;\n lockedNote?: string;\n};\n\nexport type NotificationPreset = {\n /** Its key (`everything`, `essentials`). */\n id: string;\n /** The chip's words. */\n label: string;\n /** What the preset does, one sentence, shown while it is the one in force. */\n hint: string;\n /** The matrix it sets (locked categories stay on and inert channels keep their value, whatever it says). */\n value: NotificationMatrix;\n};\n\nexport type NotificationPreferencesProps = {\n /** The group's accessible name (`Notification settings`). */\n label: string;\n /** The columns: where a notification can go. */\n channels: readonly NotificationChannel[];\n /** The rows: what can be sent. */\n categories: readonly NotificationCategory[];\n /** What is on, by category then channel (controlled). */\n value: NotificationMatrix;\n /** Called with the whole matrix after a switch or a preset — normalised: locked rows on, inert channels unchanged, unused crossings absent. */\n onValueChange: (next: NotificationMatrix) => void;\n /** Quick settings above the matrix (`Everything`, `Essentials`, `Nothing`). */\n presets?: readonly NotificationPreset[];\n /** The presets' own accessible name (`Presets`). Required with `presets`. */\n presetsLabel?: string;\n /** Said under the presets when the matrix matches none (`Custom`). */\n customHint?: string;\n /** Classes merged on the root. */\n className?: string;\n};\n\nconst uses = (c: NotificationCategory, channel: string) => !c.channels || c.channels.includes(channel);\n\n// Only what a preset can change counts: not the locked rows, the inert channels, or the crossings a category does not use.\nconst same = (a: NotificationMatrix, b: NotificationMatrix, categories: readonly NotificationCategory[], channels: readonly NotificationChannel[]) =>\n categories.every((c) => c.locked || channels.every((ch) => ch.disabled || !uses(c, ch.id) || Boolean(a[c.id]?.[ch.id]) === Boolean(b[c.id]?.[ch.id])));\n\n/** The preset in force, or null for a custom matrix. */\nexport function presetInForce(value: NotificationMatrix, presets: readonly NotificationPreset[], categories: readonly NotificationCategory[], channels: readonly NotificationChannel[]): string | null {\n return presets.find((p) => same(value, p.value, categories, channels))?.id ?? null;\n}\n\n/**\n * The matrix the controls can show: every crossing a category uses, locked rows on, an inert channel keeping its\n * `current` value whatever `next` says, and nothing for the crossings a category does not use.\n */\nexport function normalizeMatrix(next: NotificationMatrix, current: NotificationMatrix, categories: readonly NotificationCategory[], channels: readonly NotificationChannel[]): NotificationMatrix {\n return Object.fromEntries(\n categories.map((c) => [\n c.id,\n Object.fromEntries(\n channels.filter((ch) => uses(c, ch.id)).map((ch) => [ch.id, c.locked ? true : Boolean(
|
|
167
|
+
"content": "\"use client\";\n// Client (switches and chips). What reaches a person: categories down, channels across, a switch at each crossing, and\n// presets that set the whole matrix at once. The value is controlled and plain data; the words are props.\nimport * as React from \"react\";\nimport { tv } from \"tailwind-variants\";\n\nimport { Chip } from \"../chip\";\nimport { Switch } from \"../switch\";\n\nexport const notificationPreferences = tv({\n slots: {\n root: \"flex flex-col gap-3\",\n hint: \"text-xs text-fg-secondary\",\n table: \"w-full overflow-hidden rounded-2xl border border-border-default text-left\",\n head: \"bg-surface-2 text-xs font-semibold text-fg-secondary\",\n channelCell: \"w-16 px-2 py-2.5 text-center sm:w-24\",\n cornerCell: \"px-4 py-2.5\",\n row: \"border-t border-border-subtle\",\n category: \"px-4 py-3 text-left font-normal\",\n name: \"block text-sm font-semibold text-fg\",\n note: \"block text-xs text-fg-secondary\",\n cell: \"px-2 py-3 text-center\",\n },\n});\n\n/** Category id → channel id → on. A missing entry is off; a crossing a category does not use (see `channels`) is never written. */\nexport type NotificationMatrix = Record<string, Record<string, boolean>>;\n\nexport type NotificationChannel = {\n /** Its key in the matrix (`app`, `email`). */\n id: string;\n /** The column's name (`In the app`, `By e-mail`). */\n label: string;\n /** The whole column is inert (e-mail is off for the account). */\n disabled?: boolean;\n};\n\nexport type NotificationCategory = {\n /** Its key in the matrix (`social`, `security`). */\n id: string;\n /** The row's name. */\n label: string;\n /** What these notifications are, one line. */\n description?: string;\n /** The channels this category can use (ids); left out, every channel. Other crossings show no switch. */\n channels?: readonly string[];\n /** Always on, and shown so (security): the switches are inert and `lockedNote` replaces the description. */\n locked?: boolean;\n lockedNote?: string;\n};\n\nexport type NotificationPreset = {\n /** Its key (`everything`, `essentials`). */\n id: string;\n /** The chip's words. */\n label: string;\n /** What the preset does, one sentence, shown while it is the one in force. */\n hint: string;\n /** The matrix it sets (locked categories stay on and inert channels keep their value, whatever it says). */\n value: NotificationMatrix;\n};\n\nexport type NotificationPreferencesProps = {\n /** The group's accessible name (`Notification settings`). */\n label: string;\n /** The columns: where a notification can go. */\n channels: readonly NotificationChannel[];\n /** The rows: what can be sent. */\n categories: readonly NotificationCategory[];\n /** What is on, by category then channel (controlled). */\n value: NotificationMatrix;\n /** Called with the whole matrix after a switch or a preset — normalised: locked rows on, inert channels unchanged, unused crossings absent. */\n onValueChange: (next: NotificationMatrix) => void;\n /** Quick settings above the matrix (`Everything`, `Essentials`, `Nothing`). */\n presets?: readonly NotificationPreset[];\n /** The presets' own accessible name (`Presets`). Required with `presets`. */\n presetsLabel?: string;\n /** Said under the presets when the matrix matches none (`Custom`). */\n customHint?: string;\n /** Classes merged on the root. */\n className?: string;\n};\n\nconst uses = (c: NotificationCategory, channel: string) => !c.channels || c.channels.includes(channel);\n\n// Only what a preset can change counts: not the locked rows, the inert channels, or the crossings a category does not use.\nconst same = (a: NotificationMatrix, b: NotificationMatrix, categories: readonly NotificationCategory[], channels: readonly NotificationChannel[]) =>\n categories.every((c) => c.locked || channels.every((ch) => ch.disabled || !uses(c, ch.id) || Boolean(a[c.id]?.[ch.id]) === Boolean(b[c.id]?.[ch.id])));\n\n/** The preset in force, or null for a custom matrix. */\nexport function presetInForce(value: NotificationMatrix, presets: readonly NotificationPreset[], categories: readonly NotificationCategory[], channels: readonly NotificationChannel[]): string | null {\n return presets.find((p) => same(value, p.value, categories, channels))?.id ?? null;\n}\n\n/**\n * The matrix the controls can show: every crossing a category uses, locked rows on, an inert channel keeping its\n * `current` value whatever `next` says, and nothing for the crossings a category does not use.\n */\nexport function normalizeMatrix(next: NotificationMatrix, current: NotificationMatrix, categories: readonly NotificationCategory[], channels: readonly NotificationChannel[]): NotificationMatrix {\n return Object.fromEntries(\n categories.map((c) => [\n c.id,\n Object.fromEntries(\n channels.filter((ch) => uses(c, ch.id)).map((ch) => {\n const source = ch.disabled ? current : next;\n return [ch.id, c.locked ? true : Boolean(source[c.id]?.[ch.id])];\n }),\n ),\n ]),\n );\n}\n\nexport function NotificationPreferences({ label, channels, categories, value, onValueChange, presets, presetsLabel, customHint, className }: Readonly<NotificationPreferencesProps>) {\n const s = notificationPreferences();\n const inForce = presets ? presetInForce(value, presets, categories, channels) : null;\n const emit = (next: NotificationMatrix) => onValueChange(normalizeMatrix(next, value, categories, channels));\n const set = (category: string, channel: string, on: boolean) => emit({ ...value, [category]: { ...value[category], [channel]: on } });\n return (\n <div className={s.root({ className })} role=\"group\" aria-label={label}>\n {presets && presets.length > 0 && (\n <div>\n <Chip.Group type=\"single\" required label={presetsLabel ?? label} value={inForce ?? \"\"} onValueChange={(id) => { const p = presets.find((x) => x.id === id); if (p) emit(p.value); }}>\n {presets.map((p) => (\n <Chip key={p.id} value={p.id}>\n {p.label}\n </Chip>\n ))}\n </Chip.Group>\n <p className={s.hint({ className: \"mt-2\" })}>{inForce ? presets.find((p) => p.id === inForce)?.hint : customHint}</p>\n </div>\n )}\n <table className={s.table()}>\n <thead className={s.head()}>\n <tr>\n <td className={s.cornerCell()} />\n {channels.map((ch) => (\n <th key={ch.id} scope=\"col\" className={s.channelCell()}>\n {ch.label}\n </th>\n ))}\n </tr>\n </thead>\n <tbody>\n {categories.map((c) => (\n <tr key={c.id} className={s.row()}>\n <th scope=\"row\" className={s.category()}>\n <span className={s.name()}>{c.label}</span>\n {(c.locked ? c.lockedNote : c.description) && <span className={s.note()}>{c.locked ? c.lockedNote : c.description}</span>}\n </th>\n {channels.map((ch) => (\n <td key={ch.id} className={s.cell()}>\n {uses(c, ch.id) ? (\n <Switch label={`${c.label} — ${ch.label}`} checked={c.locked || Boolean(value[c.id]?.[ch.id])} disabled={c.locked || ch.disabled} onCheckedChange={(on) => set(c.id, ch.id, on)} />\n ) : (\n <span aria-hidden className={s.note()}>\n –\n </span>\n )}\n </td>\n ))}\n </tr>\n ))}\n </tbody>\n </table>\n </div>\n );\n}\n"
|
|
168
168
|
}
|
|
169
169
|
],
|
|
170
170
|
"dependencies": [
|
|
@@ -252,7 +252,7 @@
|
|
|
252
252
|
},
|
|
253
253
|
{
|
|
254
254
|
"path": "meta.ts",
|
|
255
|
-
"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"
|
|
255
|
+
"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"
|
|
256
256
|
},
|
|
257
257
|
{
|
|
258
258
|
"path": "number-ticker/index.ts",
|