@krizaka/ui 3.72.0 → 3.73.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/dist/filter-bar.d.ts +3 -3
- package/dist/retro-tv-playlist.d.ts +148 -0
- package/dist/retro-tv-playlist.js +234 -0
- package/dist/retro-tv-playlist.js.map +1 -0
- package/dist/retro-tv.js +4 -160
- package/dist/retro-tv.js.map +1 -1
- package/package.json +17 -6
- package/registry/account-menu.json +4 -2
- package/registry/account-settings.json +4 -2
- package/registry/achievement.json +4 -2
- package/registry/action-bar.json +4 -2
- package/registry/action-sheet.json +2 -0
- package/registry/activity-feed.json +4 -2
- package/registry/agenda.json +4 -2
- package/registry/alert.json +4 -2
- package/registry/analysis-report.json +4 -2
- package/registry/anatomy-plate.json +4 -2
- package/registry/app-frame.json +5 -3
- package/registry/app-header.json +4 -2
- package/registry/app-shell.json +4 -2
- package/registry/argument-card.json +4 -2
- package/registry/audio-player.json +4 -2
- package/registry/auth-layout.json +4 -2
- package/registry/avatar.json +4 -2
- package/registry/badge.json +4 -2
- package/registry/bird-plate.json +4 -2
- package/registry/button.json +4 -2
- package/registry/captcha.json +4 -2
- package/registry/card-grid.json +4 -2
- package/registry/card.json +4 -2
- package/registry/catalogue-page.json +4 -2
- package/registry/changelog-page.json +4 -2
- package/registry/chapter.json +4 -2
- package/registry/chat.json +4 -2
- package/registry/checkbox.json +4 -2
- package/registry/chip-link.json +4 -2
- package/registry/chip-row.json +4 -2
- package/registry/chip.json +4 -2
- package/registry/choice-grid.json +4 -2
- package/registry/cn.json +2 -0
- package/registry/code-block.json +4 -2
- package/registry/collection-switcher.json +4 -2
- package/registry/combobox.json +4 -2
- package/registry/command.json +4 -2
- package/registry/comparison-table.json +4 -2
- package/registry/component-page.json +4 -2
- package/registry/confirm-button.json +4 -2
- package/registry/contact-page.json +4 -2
- package/registry/continue-prompt.json +4 -2
- package/registry/copy-button.json +4 -2
- package/registry/countdown.json +4 -2
- package/registry/cover-hero.json +4 -2
- package/registry/cta-panel.json +4 -2
- package/registry/dashboard-layout.json +4 -2
- package/registry/data-table.json +4 -2
- package/registry/date-picker.json +4 -2
- package/registry/decision-list.json +4 -2
- package/registry/description-list.json +4 -2
- package/registry/desktop-window.json +5 -3
- package/registry/detail-layout.json +4 -2
- package/registry/dialog.json +4 -2
- package/registry/docs-article-page.json +4 -2
- package/registry/docs-hub-page.json +4 -2
- package/registry/docs-layout.json +4 -2
- package/registry/docs-nav.json +4 -2
- package/registry/document-viewer.json +4 -2
- package/registry/doodle.json +4 -2
- package/registry/drop-overlay.json +4 -2
- package/registry/dropdown-menu.json +4 -2
- package/registry/elephant.json +5 -3
- package/registry/embed-facade.json +4 -2
- package/registry/empty-state.json +4 -2
- package/registry/engine-flow.json +4 -2
- package/registry/entity-header.json +4 -2
- package/registry/environment-notice.json +4 -2
- package/registry/error-page.json +4 -2
- package/registry/fab.json +2 -0
- package/registry/field.json +4 -2
- package/registry/file-upload.json +4 -2
- package/registry/filter-bar.json +4 -2
- package/registry/flock.json +4 -2
- package/registry/footnote.json +4 -2
- package/registry/force-update-screen.json +4 -2
- package/registry/form-flow.json +3 -1
- package/registry/form.json +4 -2
- package/registry/gallery-page.json +4 -2
- package/registry/genui.json +4 -2
- package/registry/glossary-term.json +4 -2
- package/registry/glossary.json +4 -2
- package/registry/glow-card.json +4 -2
- package/registry/goal-gauge.json +4 -2
- package/registry/grade-stamp.json +4 -2
- package/registry/grid.json +2 -0
- package/registry/header.json +2 -0
- package/registry/how-it-works-page.json +4 -2
- package/registry/image-cropper.json +4 -2
- package/registry/image-viewer.json +2 -0
- package/registry/index.json +18 -18
- package/registry/iso.json +4 -2
- package/registry/kanban.json +4 -2
- package/registry/kbd.json +4 -2
- package/registry/kind-config-editor.json +4 -2
- package/registry/kpi-explained.json +4 -2
- package/registry/landing-page.json +4 -2
- package/registry/landscape.json +4 -2
- package/registry/language-switch.json +4 -2
- package/registry/legal-page.json +4 -2
- package/registry/link-card.json +4 -2
- package/registry/list-detail.json +2 -0
- package/registry/list.json +4 -2
- package/registry/loader.json +4 -2
- package/registry/longform-page.json +4 -2
- package/registry/maintenance-screen.json +4 -2
- package/registry/map.json +5 -3
- package/registry/margin-layout.json +4 -2
- package/registry/markdown.json +4 -2
- package/registry/marketing-layout.json +4 -2
- package/registry/marquee.json +4 -2
- package/registry/mascot-quote.json +4 -2
- package/registry/mascot-state.json +4 -2
- package/registry/mascots.json +4 -2
- package/registry/match-dialog.json +4 -2
- package/registry/media-capture.json +4 -2
- package/registry/media-gallery.json +4 -2
- package/registry/media-grid.json +4 -2
- package/registry/media-picker.json +2 -0
- package/registry/meta-row.json +4 -2
- package/registry/meter.json +4 -2
- package/registry/money-input.json +5 -3
- package/registry/nav-bar.json +5 -3
- package/registry/next-actions.json +4 -2
- package/registry/notification-preferences.json +4 -2
- package/registry/number-ticker.json +4 -2
- package/registry/onboarding.json +2 -0
- package/registry/opening-hours.json +4 -2
- package/registry/otp-input.json +2 -0
- package/registry/page-header.json +4 -2
- package/registry/page-hero.json +4 -2
- package/registry/page-index.json +4 -2
- package/registry/page.json +4 -2
- package/registry/pagination.json +4 -2
- package/registry/permission-prompt.json +2 -0
- package/registry/photo-grid.json +4 -2
- package/registry/pointer-light.json +4 -2
- package/registry/popover.json +4 -2
- package/registry/price-catalogue-editor.json +5 -3
- package/registry/pricing-page.json +4 -2
- package/registry/product-page.json +4 -2
- package/registry/profile-card.json +4 -2
- package/registry/progress.json +4 -2
- package/registry/promise-card.json +4 -2
- package/registry/promo-code-field.json +5 -3
- package/registry/proposal.json +5 -3
- package/registry/pull-to-refresh.json +2 -0
- package/registry/qr-code.json +4 -2
- package/registry/quota-meter.json +4 -2
- package/registry/radio-group.json +4 -2
- package/registry/rail-nav.json +5 -3
- package/registry/recipes.json +4 -2
- package/registry/retro-tv.json +9 -3
- package/registry/reviews.json +4 -2
- package/registry/router.json +4 -2
- package/registry/schema-form.json +5 -3
- package/registry/screen.json +2 -0
- package/registry/scroll-stage.json +4 -2
- package/registry/search-field.json +4 -2
- package/registry/section-backdrop.json +4 -2
- package/registry/segmented.json +2 -0
- package/registry/separator.json +4 -2
- package/registry/service-card.json +4 -2
- package/registry/settings-layout.json +4 -2
- package/registry/shop-composer.json +4 -2
- package/registry/shop-gallery.json +5 -3
- package/registry/shop.json +5 -3
- package/registry/showcase.json +4 -2
- package/registry/signature.json +4 -2
- package/registry/site-cahier.json +4 -2
- package/registry/site-footer.json +5 -3
- package/registry/sites.json +4 -2
- package/registry/skeleton.json +4 -2
- package/registry/skip-link.json +4 -2
- package/registry/slider.json +4 -2
- package/registry/slot-picker.json +4 -2
- package/registry/slot.json +4 -2
- package/registry/specimen-tag.json +4 -2
- package/registry/speed-lines.json +4 -2
- package/registry/spinner.json +4 -2
- package/registry/splash-handoff.json +2 -0
- package/registry/split-view.json +4 -2
- package/registry/stage-banner.json +4 -2
- package/registry/stat.json +4 -2
- package/registry/state-screen.json +3 -1
- package/registry/status-chip.json +4 -2
- package/registry/status-page.json +4 -2
- package/registry/step-progress.json +4 -2
- package/registry/step-showcase.json +4 -2
- package/registry/stepper.json +4 -2
- package/registry/sticky-action.json +4 -2
- package/registry/stuck.json +4 -2
- package/registry/swipe-deck.json +4 -2
- package/registry/swipeable-row.json +2 -0
- package/registry/switch.json +4 -2
- package/registry/tab-bar.json +2 -0
- package/registry/tabs.json +4 -2
- package/registry/tag-input.json +4 -2
- package/registry/tag-selector.json +4 -2
- package/registry/taped-photo.json +4 -2
- package/registry/terminal-replay.json +4 -2
- package/registry/text-style.json +4 -2
- package/registry/theme.json +4 -2
- package/registry/toast.json +4 -2
- package/registry/toc.json +4 -2
- package/registry/tooltip.json +4 -2
- package/registry/tree-view.json +4 -2
- package/registry/txt.json +2 -0
- package/registry/update-prompt.json +4 -2
- package/registry/upload-queue.json +4 -2
- package/registry/usage.json +5 -3
- package/registry/verified-badge.json +4 -2
- package/registry/versus-card.json +4 -2
- package/registry/vertical-video.json +4 -2
- package/registry/video-player.json +4 -2
- package/registry/video-trimmer.json +4 -2
- package/registry/virtual.json +4 -2
- package/registry/wall.json +4 -2
- package/registry/waveform.json +4 -2
package/registry/recipes.json
CHANGED
|
@@ -7,6 +7,8 @@
|
|
|
7
7
|
"status": "beta",
|
|
8
8
|
"deprecated": null,
|
|
9
9
|
"category": "foundations",
|
|
10
|
+
"domain": "foundations",
|
|
11
|
+
"adoption": null,
|
|
10
12
|
"platforms": "web",
|
|
11
13
|
"parity": {
|
|
12
14
|
"web": {
|
|
@@ -76,7 +78,7 @@
|
|
|
76
78
|
"files": [
|
|
77
79
|
{
|
|
78
80
|
"path": "meta.ts",
|
|
79
|
-
"content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n | \"notification-preferences\"\n | \"quota-meter\"\n | \"environment-notice\"\n | \"embed-facade\"\n | \"reviews\"\n | \"margin-layout\"\n | \"analysis-report\"\n | \"status-chip\"\n | \"kind-config-editor\"\n | \"agenda\"\n | \"account-settings\"\n | \"drop-overlay\"\n | \"upload-queue\"\n | \"achievement\"\n | \"anatomy-plate\"\n | \"bird-plate\"\n | \"taped-photo\"\n | \"stuck\"\n | \"doodle\"\n | \"signature\"\n | \"grade-stamp\"\n | \"versus-card\"\n | \"speed-lines\"\n | \"site-cahier\"\n | \"text-style\"\n | \"flock\"\n | \"elephant\"\n | \"footnote\"\n | \"page-index\"\n | \"chapter\"\n | \"specimen-tag\"\n | \"action-bar\"\n | \"action-sheet\"\n | \"activity-feed\"\n | \"alert\"\n | \"app-frame\"\n | \"desktop-window\"\n | \"form-flow\"\n | \"grid\"\n | \"list-detail\"\n | \"state-screen\"\n | \"app-header\"\n | \"app-shell\"\n | \"argument-card\"\n | \"audio-player\"\n | \"auth-layout\"\n | \"avatar\"\n | \"badge\"\n | \"button\"\n | \"captcha\"\n | \"card\"\n | \"card-grid\"\n | \"catalogue-page\"\n | \"changelog-page\"\n | \"chat\"\n | \"checkbox\"\n | \"chip\"\n | \"chip-link\"\n | \"chip-row\"\n | \"choice-grid\"\n | \"cn\"\n | \"code-block\"\n | \"combobox\"\n | \"comparison-table\"\n | \"command\"\n | \"component-page\"\n | \"confirm-button\"\n | \"copy-button\"\n | \"money-input\"\n | \"price-catalogue-editor\"\n | \"promo-code-field\"\n | \"contact-page\"\n | \"continue-prompt\"\n | \"countdown\"\n | \"cover-hero\"\n | \"cta-panel\"\n | \"dashboard-layout\"\n | \"data-table\"\n | \"date-picker\"\n | \"decision-list\"\n | \"description-list\"\n | \"detail-layout\"\n | \"dialog\"\n | \"docs-article-page\"\n | \"docs-hub-page\"\n | \"docs-layout\"\n | \"docs-nav\"\n | \"document-viewer\"\n | \"dropdown-menu\"\n | \"empty-state\"\n | \"engine-flow\"\n | \"error-page\"\n | \"fab\"\n | \"field\"\n | \"file-upload\"\n | \"filter-bar\"\n | \"force-update-screen\"\n | \"form\"\n | \"gallery-page\"\n | \"genui\"\n | \"glossary\"\n | \"glossary-term\"\n | \"glow-card\"\n | \"goal-gauge\"\n | \"header\"\n | \"how-it-works-page\"\n | \"image-cropper\"\n | \"image-viewer\"\n | \"iso\"\n | \"kanban\"\n | \"kbd\"\n | \"kpi-explained\"\n | \"landing-page\"\n | \"landscape\"\n | \"legal-page\"\n | \"link-card\"\n | \"list\"\n | \"loader\"\n | \"longform-page\"\n | \"maintenance-screen\"\n | \"map\"\n | \"markdown\"\n | \"meta-row\"\n | \"waveform\"\n | \"proposal\"\n | \"qr-code\"\n | \"entity-header\"\n | \"collection-switcher\"\n | \"marketing-layout\"\n | \"marquee\"\n | \"mascot-quote\"\n | \"mascot-state\"\n | \"mascots\"\n | \"match-dialog\"\n | \"media-capture\"\n | \"media-grid\"\n | \"language-switch\"\n | \"media-gallery\"\n | \"media-picker\"\n | \"meter\"\n | \"nav-bar\"\n | \"number-ticker\"\n | \"onboarding\"\n | \"opening-hours\"\n | \"otp-input\"\n | \"page\"\n | \"page-header\"\n | \"page-hero\"\n | \"pagination\"\n | \"permission-prompt\"\n | \"photo-grid\"\n | \"pointer-light\"\n | \"popover\"\n | \"pricing-page\"\n | \"product-page\"\n | \"profile-card\"\n | \"progress\"\n | \"promise-card\"\n | \"pull-to-refresh\"\n | \"retro-tv\"\n | \"shop-gallery\"\n | \"radio-group\"\n | \"router\"\n | \"rail-nav\"\n | \"recipes\"\n | \"screen\"\n | \"scroll-stage\"\n | \"search-field\"\n | \"section-backdrop\"\n | \"segmented\"\n | \"separator\"\n | \"service-card\"\n | \"shop\"\n | \"shop-composer\"\n | \"schema-form\"\n | \"settings-layout\"\n | \"account-menu\"\n | \"showcase\"\n | \"step-showcase\"\n | \"site-footer\"\n | \"sites\"\n | \"skeleton\"\n | \"skip-link\"\n | \"slider\"\n | \"slot-picker\"\n | \"slot\"\n | \"spinner\"\n | \"sticky-action\"\n | \"splash-handoff\"\n | \"split-view\"\n | \"stage-banner\"\n | \"stat\"\n | \"usage\"\n | \"status-page\"\n | \"step-progress\"\n | \"stepper\"\n | \"swipe-deck\"\n | \"swipeable-row\"\n | \"switch\"\n | \"tab-bar\"\n | \"tabs\"\n | \"tag-input\"\n | \"tag-selector\"\n | \"terminal-replay\"\n | \"theme\"\n | \"toast\"\n | \"toc\"\n | \"tooltip\"\n | \"tree-view\"\n | \"txt\"\n | \"update-prompt\"\n | \"verified-badge\"\n | \"vertical-video\"\n | \"video-player\"\n | \"video-trimmer\"\n | \"virtual\"\n | \"wall\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/**\n * Why a component is not on a platform — a decision, never a silence (the parity matrix of ui.krizaka.com/platforms):\n * - `gap` (✗): it belongs there and is not built yet; `issue` is the issue that tracks it (`krizaka/krizaka-ui#275`);\n * - `n/a`: it is not meant for that platform (a site's page block on a phone, a swipe on a desktop); `use` names the\n * component that answers there, when one does.\n */\nexport type Absence =\n | { readonly status: \"gap\"; readonly issue: string; readonly reason: string; readonly use?: undefined }\n | { readonly status: \"n/a\"; readonly reason: string; readonly use?: ComponentName; readonly issue?: undefined };\n\n/**\n * Desktop is the Orazaka Mac app (Tauri 2: the system WebView renders the web components — ADR-002). `web`: the web\n * component runs there as it is; `desktop`: it also has a desktop form (a window's title bar, a denser layout…), said in\n * its documentation; otherwise the absence and why.\n */\nexport type DesktopSupport = \"web\" | \"desktop\" | Absence;\n\n/**\n * The three platforms of Krizaka UI — web · native (React Native, Expo) · desktop — for one component. The side a\n * component has is `platforms`; the side it lacks says why here: `native` is required for (and only for) a web-only\n * component, `web` for a native-only one; `desktop` always. `scripts/registry.test.mjs` fails on a missing decision.\n */\nexport interface Parity {\n readonly web?: Absence;\n readonly native?: Absence;\n readonly desktop: DesktopSupport;\n}\n\n/**\n * `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"stable\" | \"beta\" | \"deprecated\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n /** The version that deprecated it (`3.6.0`). */\n readonly since: string;\n /** The major that removes it (`4.0.0`). */\n readonly removedIn: string;\n /** What replaces it, when a component does. */\n readonly use?: ComponentName;\n /** Why it goes: no product uses it, no planned work needs it. */\n readonly reason: string;\n}\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\ninterface ExampleBase {\n /** The file name, kebab-case (`primary`, `icon-button`). */\n readonly name: string;\n /** A short title (`Primary`, `Icon button`). */\n readonly title: string;\n /** One or two sentences: when this variant is the right one. */\n readonly description: string;\n}\n\n/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n | (ExampleBase & {\n /**\n * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n */\n readonly template: true;\n /** The intent that groups it: why you need this block. */\n readonly purpose: TemplatePurpose;\n /** Why this layout: the user goal it serves, in one sentence. */\n readonly why: string;\n });\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n readonly imports: readonly string[];\n /** The examples, in reading order; the first one is the component's preview. */\n readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n /**\n * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n */\n readonly entry?: string;\n /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n readonly differences: readonly string[];\n /** The React Native entry alone is deprecated while the web one stays (ADR-006 §7); a deprecated component says it once, above. */\n readonly deprecated?: Deprecation;\n}\n\nexport interface KeyboardInteraction {\n /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n readonly keys: string;\n /** What they do. */\n readonly action: string;\n}\n\nexport interface ComponentMeta {\n /** The display name: `Button`, `Dropdown menu`. */\n readonly title: string;\n /** One sentence: what it is. */\n readonly summary: string;\n readonly status: Status;\n /** Required for, and only for, a `deprecated` component. */\n readonly deprecated?: Deprecation;\n readonly category: Category;\n /** Must match the sides below: `both` ⇔ `web` and `native`. */\n readonly platforms: Platform;\n /** The platforms it is not on, and why; and its desktop form (see `Parity`). */\n readonly parity: Parity;\n /** When to reach for it: concrete situations, one per item. */\n readonly whenToUse: readonly string[];\n /** When not to — and what to use instead (`use`), when another component is the answer. */\n readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n /** How to use it well: wording, placement, composition. */\n readonly bestPractices: readonly string[];\n readonly accessibility: {\n /** The keyboard, when it does more than Tab and Enter. */\n readonly keyboard: readonly KeyboardInteraction[];\n /** Roles, names and announcements: what the component does, what the app must provide. */\n readonly notes: readonly string[];\n };\n /** The components a reader of this page should know about. */\n readonly related: readonly ComponentName[];\n readonly web?: PlatformDocs;\n readonly native?: NativeDocs;\n}\n"
|
|
81
|
+
"content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n | \"notification-preferences\"\n | \"quota-meter\"\n | \"environment-notice\"\n | \"embed-facade\"\n | \"reviews\"\n | \"margin-layout\"\n | \"analysis-report\"\n | \"status-chip\"\n | \"kind-config-editor\"\n | \"agenda\"\n | \"account-settings\"\n | \"drop-overlay\"\n | \"upload-queue\"\n | \"achievement\"\n | \"anatomy-plate\"\n | \"bird-plate\"\n | \"taped-photo\"\n | \"stuck\"\n | \"doodle\"\n | \"signature\"\n | \"grade-stamp\"\n | \"versus-card\"\n | \"speed-lines\"\n | \"site-cahier\"\n | \"text-style\"\n | \"flock\"\n | \"elephant\"\n | \"footnote\"\n | \"page-index\"\n | \"chapter\"\n | \"specimen-tag\"\n | \"action-bar\"\n | \"action-sheet\"\n | \"activity-feed\"\n | \"alert\"\n | \"app-frame\"\n | \"desktop-window\"\n | \"form-flow\"\n | \"grid\"\n | \"list-detail\"\n | \"state-screen\"\n | \"app-header\"\n | \"app-shell\"\n | \"argument-card\"\n | \"audio-player\"\n | \"auth-layout\"\n | \"avatar\"\n | \"badge\"\n | \"button\"\n | \"captcha\"\n | \"card\"\n | \"card-grid\"\n | \"catalogue-page\"\n | \"changelog-page\"\n | \"chat\"\n | \"checkbox\"\n | \"chip\"\n | \"chip-link\"\n | \"chip-row\"\n | \"choice-grid\"\n | \"cn\"\n | \"code-block\"\n | \"combobox\"\n | \"comparison-table\"\n | \"command\"\n | \"component-page\"\n | \"confirm-button\"\n | \"copy-button\"\n | \"money-input\"\n | \"price-catalogue-editor\"\n | \"promo-code-field\"\n | \"contact-page\"\n | \"continue-prompt\"\n | \"countdown\"\n | \"cover-hero\"\n | \"cta-panel\"\n | \"dashboard-layout\"\n | \"data-table\"\n | \"date-picker\"\n | \"decision-list\"\n | \"description-list\"\n | \"detail-layout\"\n | \"dialog\"\n | \"docs-article-page\"\n | \"docs-hub-page\"\n | \"docs-layout\"\n | \"docs-nav\"\n | \"document-viewer\"\n | \"dropdown-menu\"\n | \"empty-state\"\n | \"engine-flow\"\n | \"error-page\"\n | \"fab\"\n | \"field\"\n | \"file-upload\"\n | \"filter-bar\"\n | \"force-update-screen\"\n | \"form\"\n | \"gallery-page\"\n | \"genui\"\n | \"glossary\"\n | \"glossary-term\"\n | \"glow-card\"\n | \"goal-gauge\"\n | \"header\"\n | \"how-it-works-page\"\n | \"image-cropper\"\n | \"image-viewer\"\n | \"iso\"\n | \"kanban\"\n | \"kbd\"\n | \"kpi-explained\"\n | \"landing-page\"\n | \"landscape\"\n | \"legal-page\"\n | \"link-card\"\n | \"list\"\n | \"loader\"\n | \"longform-page\"\n | \"maintenance-screen\"\n | \"map\"\n | \"markdown\"\n | \"meta-row\"\n | \"waveform\"\n | \"proposal\"\n | \"qr-code\"\n | \"entity-header\"\n | \"collection-switcher\"\n | \"marketing-layout\"\n | \"marquee\"\n | \"mascot-quote\"\n | \"mascot-state\"\n | \"mascots\"\n | \"match-dialog\"\n | \"media-capture\"\n | \"media-grid\"\n | \"language-switch\"\n | \"media-gallery\"\n | \"media-picker\"\n | \"meter\"\n | \"nav-bar\"\n | \"number-ticker\"\n | \"onboarding\"\n | \"opening-hours\"\n | \"otp-input\"\n | \"page\"\n | \"page-header\"\n | \"page-hero\"\n | \"pagination\"\n | \"permission-prompt\"\n | \"photo-grid\"\n | \"pointer-light\"\n | \"popover\"\n | \"pricing-page\"\n | \"product-page\"\n | \"profile-card\"\n | \"progress\"\n | \"promise-card\"\n | \"pull-to-refresh\"\n | \"retro-tv\"\n | \"shop-gallery\"\n | \"radio-group\"\n | \"router\"\n | \"rail-nav\"\n | \"recipes\"\n | \"screen\"\n | \"scroll-stage\"\n | \"search-field\"\n | \"section-backdrop\"\n | \"segmented\"\n | \"separator\"\n | \"service-card\"\n | \"shop\"\n | \"shop-composer\"\n | \"schema-form\"\n | \"settings-layout\"\n | \"account-menu\"\n | \"showcase\"\n | \"step-showcase\"\n | \"site-footer\"\n | \"sites\"\n | \"skeleton\"\n | \"skip-link\"\n | \"slider\"\n | \"slot-picker\"\n | \"slot\"\n | \"spinner\"\n | \"sticky-action\"\n | \"splash-handoff\"\n | \"split-view\"\n | \"stage-banner\"\n | \"stat\"\n | \"usage\"\n | \"status-page\"\n | \"step-progress\"\n | \"stepper\"\n | \"swipe-deck\"\n | \"swipeable-row\"\n | \"switch\"\n | \"tab-bar\"\n | \"tabs\"\n | \"tag-input\"\n | \"tag-selector\"\n | \"terminal-replay\"\n | \"theme\"\n | \"toast\"\n | \"toc\"\n | \"tooltip\"\n | \"tree-view\"\n | \"txt\"\n | \"update-prompt\"\n | \"verified-badge\"\n | \"vertical-video\"\n | \"video-player\"\n | \"video-trimmer\"\n | \"virtual\"\n | \"wall\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/**\n * Why a component is not on a platform — a decision, never a silence (the parity matrix of ui.krizaka.com/platforms):\n * - `gap` (✗): it belongs there and is not built yet; `issue` is the issue that tracks it (`krizaka/krizaka-ui#275`);\n * - `n/a`: it is not meant for that platform (a site's page block on a phone, a swipe on a desktop); `use` names the\n * component that answers there, when one does.\n */\nexport type Absence =\n | { readonly status: \"gap\"; readonly issue: string; readonly reason: string; readonly use?: undefined }\n | { readonly status: \"n/a\"; readonly reason: string; readonly use?: ComponentName; readonly issue?: undefined };\n\n/**\n * Desktop is the Orazaka Mac app (Tauri 2: the system WebView renders the web components — ADR-002). `web`: the web\n * component runs there as it is; `desktop`: it also has a desktop form (a window's title bar, a denser layout…), said in\n * its documentation; otherwise the absence and why.\n */\nexport type DesktopSupport = \"web\" | \"desktop\" | Absence;\n\n/**\n * The three platforms of Krizaka UI — web · native (React Native, Expo) · desktop — for one component. The side a\n * component has is `platforms`; the side it lacks says why here: `native` is required for (and only for) a web-only\n * component, `web` for a native-only one; `desktop` always. `scripts/registry.test.mjs` fails on a missing decision.\n */\nexport interface Parity {\n readonly web?: Absence;\n readonly native?: Absence;\n readonly desktop: DesktopSupport;\n}\n\n/**\n * `experimental`: created for a filed need (ADR-008 §4), it may change or go in any minor until its first consumer imports it; `adoption`\n * names that consumer's issue. `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"experimental\" | \"stable\" | \"beta\" | \"deprecated\";\n\n/**\n * What a component is for (ADR-008 §3): the twelve domains the documentation, the size budgets and the guards are\n * organised by. The domain is metadata: the entries stay flat (`@krizaka/ui/<name>`). `cahier` is the sites' register\n * (ADR-004): a product never imports it.\n */\nexport type Domain =\n | \"foundations\"\n | \"forms\"\n | \"data-display\"\n | \"navigation-shell\"\n | \"feedback\"\n | \"maps\"\n | \"media\"\n | \"commerce\"\n | \"identity\"\n | \"conversation\"\n | \"page-blocks\"\n | \"cahier\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n /** The version that deprecated it (`3.6.0`). */\n readonly since: string;\n /** The major that removes it (`4.0.0`). */\n readonly removedIn: string;\n /** What replaces it, when a component does. */\n readonly use?: ComponentName;\n /** Why it goes: no product uses it, no planned work needs it. */\n readonly reason: string;\n}\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\ninterface ExampleBase {\n /** The file name, kebab-case (`primary`, `icon-button`). */\n readonly name: string;\n /** A short title (`Primary`, `Icon button`). */\n readonly title: string;\n /** One or two sentences: when this variant is the right one. */\n readonly description: string;\n}\n\n/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n | (ExampleBase & {\n /**\n * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n */\n readonly template: true;\n /** The intent that groups it: why you need this block. */\n readonly purpose: TemplatePurpose;\n /** Why this layout: the user goal it serves, in one sentence. */\n readonly why: string;\n });\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n readonly imports: readonly string[];\n /** The examples, in reading order; the first one is the component's preview. */\n readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n /**\n * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n */\n readonly entry?: string;\n /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n readonly differences: readonly string[];\n /** The React Native entry alone is deprecated while the web one stays (ADR-006 §7); a deprecated component says it once, above. */\n readonly deprecated?: Deprecation;\n}\n\nexport interface KeyboardInteraction {\n /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n readonly keys: string;\n /** What they do. */\n readonly action: string;\n}\n\nexport interface ComponentMeta {\n /** The display name: `Button`, `Dropdown menu`. */\n readonly title: string;\n /** One sentence: what it is. */\n readonly summary: string;\n readonly status: Status;\n /** Required for, and only for, a `deprecated` component. */\n readonly deprecated?: Deprecation;\n readonly category: Category;\n /** What it is for: one of the twelve domains (ADR-008 §3). */\n readonly domain: Domain;\n /** The `<repo>#<n>` issue of its first consumer: required for, and only for, an `experimental` component. */\n readonly adoption?: string;\n /** Must match the sides below: `both` ⇔ `web` and `native`. */\n readonly platforms: Platform;\n /** The platforms it is not on, and why; and its desktop form (see `Parity`). */\n readonly parity: Parity;\n /** When to reach for it: concrete situations, one per item. */\n readonly whenToUse: readonly string[];\n /** When not to — and what to use instead (`use`), when another component is the answer. */\n readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n /** How to use it well: wording, placement, composition. */\n readonly bestPractices: readonly string[];\n readonly accessibility: {\n /** The keyboard, when it does more than Tab and Enter. */\n readonly keyboard: readonly KeyboardInteraction[];\n /** Roles, names and announcements: what the component does, what the app must provide. */\n readonly notes: readonly string[];\n };\n /** The components a reader of this page should know about. */\n readonly related: readonly ComponentName[];\n readonly web?: PlatformDocs;\n readonly native?: NativeDocs;\n}\n"
|
|
80
82
|
},
|
|
81
83
|
{
|
|
82
84
|
"path": "recipes/define.ts",
|
|
@@ -88,7 +90,7 @@
|
|
|
88
90
|
},
|
|
89
91
|
{
|
|
90
92
|
"path": "recipes/meta.ts",
|
|
91
|
-
"content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n title: \"Recipes\",\n summary:\n \"The variants of a component written once, as classes of the Krizaka tokens: the web wears them with `tv(recipe)`, React Native reads the same classes into styles on the theme's roles with `nativeRecipe(recipe).resolve(props, theme)`. Button, Badge, Chip and Card are built this way, so the two platforms cannot name different tokens.\",\n status: \"beta\",\n category: \"foundations\",\n platforms: \"web\",\n parity: { native: { status: \"n/a\", reason: \"The recipes are already shared: the native Button, Badge, Chip and Card read the same definitions through nativeRecipe.\" }, desktop: \"web\" },\n whenToUse: [\n \"A component that exists on the web and on the phone, whose variants (a look, a size, a tone) must stay the same on both.\",\n \"A product composite that adds variants to a primitive and wants its React Native twin to follow.\",\n ],\n whenNotToUse: [\n { when: \"To merge class names on the web: `cn` does that.\", use: \"cn\" },\n { when: \"For a component that has a web side only: write `tv({ … })` as the primitives do.\" },\n { when: \"For the layout, the pointer and focus states, shadows and transitions: they stay on the web side of the recipe, the phone ignores them.\" },\n ],\n bestPractices: [\n \"Write colours as roles (`bg-accent`, `text-fg-secondary`, `border-border-default`, `ring-accent/40`) and sizes in Tailwind units (`h-10`, `px-4`, `text-sm`, `text-[11px]`): those are what the phone can read.\",\n \"Sizes are a variant dimension; states are prefixes: `hover:` is for the pointer (web only), `disabled:` and `data-[state=on]:` are read on both.\",\n \"Keep what the phone draws differently in its component (the radius of a shape, the pressed opacity, a shadow): the recipe holds colours, sizes and type.\",\n \"Check the pair in a test: resolve every variant on both themes and fail on a class that is neither mapped nor declared web-only (see `recipes.test.ts`).\",\n \"Pass the native theme to `resolve` (`useTheme().theme`) and wrap the result in `StyleSheet` in the component; the recipe itself imports nothing from React Native.\",\n ],\n accessibility: {\n keyboard: [],\n notes: [\n \"A recipe only carries colours and sizes: the contrast of each pair is the tokens' (text roles ≥ 4.5:1 on the surfaces they are meant for, tested in @krizaka/tokens).\",\n \"Focus rings and the pointer's states are web classes and stay on the web side; a phone has the platform's own focus and press feedback.\",\n ],\n },\n related: [\"button\", \"badge\", \"chip\", \"card\", \"cn\"],\n web: {\n imports: [\"defineRecipe\", \"nativeRecipe\", \"withAlpha\", \"ROLES\"],\n examples: [{ name: \"tone-chip\", title: \"What the phone reads\", description: \"A recipe of two tones and two sizes, and what `nativeRecipe` reads from its classes: points, colours on a theme, and the classes only the web has.\" }],\n },\n} satisfies ComponentMeta;\n"
|
|
93
|
+
"content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n title: \"Recipes\",\n summary:\n \"The variants of a component written once, as classes of the Krizaka tokens: the web wears them with `tv(recipe)`, React Native reads the same classes into styles on the theme's roles with `nativeRecipe(recipe).resolve(props, theme)`. Button, Badge, Chip and Card are built this way, so the two platforms cannot name different tokens.\",\n status: \"beta\",\n category: \"foundations\",\n domain: \"foundations\",\n platforms: \"web\",\n parity: { native: { status: \"n/a\", reason: \"The recipes are already shared: the native Button, Badge, Chip and Card read the same definitions through nativeRecipe.\" }, desktop: \"web\" },\n whenToUse: [\n \"A component that exists on the web and on the phone, whose variants (a look, a size, a tone) must stay the same on both.\",\n \"A product composite that adds variants to a primitive and wants its React Native twin to follow.\",\n ],\n whenNotToUse: [\n { when: \"To merge class names on the web: `cn` does that.\", use: \"cn\" },\n { when: \"For a component that has a web side only: write `tv({ … })` as the primitives do.\" },\n { when: \"For the layout, the pointer and focus states, shadows and transitions: they stay on the web side of the recipe, the phone ignores them.\" },\n ],\n bestPractices: [\n \"Write colours as roles (`bg-accent`, `text-fg-secondary`, `border-border-default`, `ring-accent/40`) and sizes in Tailwind units (`h-10`, `px-4`, `text-sm`, `text-[11px]`): those are what the phone can read.\",\n \"Sizes are a variant dimension; states are prefixes: `hover:` is for the pointer (web only), `disabled:` and `data-[state=on]:` are read on both.\",\n \"Keep what the phone draws differently in its component (the radius of a shape, the pressed opacity, a shadow): the recipe holds colours, sizes and type.\",\n \"Check the pair in a test: resolve every variant on both themes and fail on a class that is neither mapped nor declared web-only (see `recipes.test.ts`).\",\n \"Pass the native theme to `resolve` (`useTheme().theme`) and wrap the result in `StyleSheet` in the component; the recipe itself imports nothing from React Native.\",\n ],\n accessibility: {\n keyboard: [],\n notes: [\n \"A recipe only carries colours and sizes: the contrast of each pair is the tokens' (text roles ≥ 4.5:1 on the surfaces they are meant for, tested in @krizaka/tokens).\",\n \"Focus rings and the pointer's states are web classes and stay on the web side; a phone has the platform's own focus and press feedback.\",\n ],\n },\n related: [\"button\", \"badge\", \"chip\", \"card\", \"cn\"],\n web: {\n imports: [\"defineRecipe\", \"nativeRecipe\", \"withAlpha\", \"ROLES\"],\n examples: [{ name: \"tone-chip\", title: \"What the phone reads\", description: \"A recipe of two tones and two sizes, and what `nativeRecipe` reads from its classes: points, colours on a theme, and the classes only the web has.\" }],\n },\n} satisfies ComponentMeta;\n"
|
|
92
94
|
},
|
|
93
95
|
{
|
|
94
96
|
"path": "recipes/native.ts",
|
package/registry/retro-tv.json
CHANGED
|
@@ -7,6 +7,8 @@
|
|
|
7
7
|
"status": "beta",
|
|
8
8
|
"deprecated": null,
|
|
9
9
|
"category": "media",
|
|
10
|
+
"domain": "media",
|
|
11
|
+
"adoption": null,
|
|
10
12
|
"platforms": "web",
|
|
11
13
|
"parity": {
|
|
12
14
|
"web": {
|
|
@@ -362,7 +364,7 @@
|
|
|
362
364
|
},
|
|
363
365
|
{
|
|
364
366
|
"path": "meta.ts",
|
|
365
|
-
"content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n | \"notification-preferences\"\n | \"quota-meter\"\n | \"environment-notice\"\n | \"embed-facade\"\n | \"reviews\"\n | \"margin-layout\"\n | \"analysis-report\"\n | \"status-chip\"\n | \"kind-config-editor\"\n | \"agenda\"\n | \"account-settings\"\n | \"drop-overlay\"\n | \"upload-queue\"\n | \"achievement\"\n | \"anatomy-plate\"\n | \"bird-plate\"\n | \"taped-photo\"\n | \"stuck\"\n | \"doodle\"\n | \"signature\"\n | \"grade-stamp\"\n | \"versus-card\"\n | \"speed-lines\"\n | \"site-cahier\"\n | \"text-style\"\n | \"flock\"\n | \"elephant\"\n | \"footnote\"\n | \"page-index\"\n | \"chapter\"\n | \"specimen-tag\"\n | \"action-bar\"\n | \"action-sheet\"\n | \"activity-feed\"\n | \"alert\"\n | \"app-frame\"\n | \"desktop-window\"\n | \"form-flow\"\n | \"grid\"\n | \"list-detail\"\n | \"state-screen\"\n | \"app-header\"\n | \"app-shell\"\n | \"argument-card\"\n | \"audio-player\"\n | \"auth-layout\"\n | \"avatar\"\n | \"badge\"\n | \"button\"\n | \"captcha\"\n | \"card\"\n | \"card-grid\"\n | \"catalogue-page\"\n | \"changelog-page\"\n | \"chat\"\n | \"checkbox\"\n | \"chip\"\n | \"chip-link\"\n | \"chip-row\"\n | \"choice-grid\"\n | \"cn\"\n | \"code-block\"\n | \"combobox\"\n | \"comparison-table\"\n | \"command\"\n | \"component-page\"\n | \"confirm-button\"\n | \"copy-button\"\n | \"money-input\"\n | \"price-catalogue-editor\"\n | \"promo-code-field\"\n | \"contact-page\"\n | \"continue-prompt\"\n | \"countdown\"\n | \"cover-hero\"\n | \"cta-panel\"\n | \"dashboard-layout\"\n | \"data-table\"\n | \"date-picker\"\n | \"decision-list\"\n | \"description-list\"\n | \"detail-layout\"\n | \"dialog\"\n | \"docs-article-page\"\n | \"docs-hub-page\"\n | \"docs-layout\"\n | \"docs-nav\"\n | \"document-viewer\"\n | \"dropdown-menu\"\n | \"empty-state\"\n | \"engine-flow\"\n | \"error-page\"\n | \"fab\"\n | \"field\"\n | \"file-upload\"\n | \"filter-bar\"\n | \"force-update-screen\"\n | \"form\"\n | \"gallery-page\"\n | \"genui\"\n | \"glossary\"\n | \"glossary-term\"\n | \"glow-card\"\n | \"goal-gauge\"\n | \"header\"\n | \"how-it-works-page\"\n | \"image-cropper\"\n | \"image-viewer\"\n | \"iso\"\n | \"kanban\"\n | \"kbd\"\n | \"kpi-explained\"\n | \"landing-page\"\n | \"landscape\"\n | \"legal-page\"\n | \"link-card\"\n | \"list\"\n | \"loader\"\n | \"longform-page\"\n | \"maintenance-screen\"\n | \"map\"\n | \"markdown\"\n | \"meta-row\"\n | \"waveform\"\n | \"proposal\"\n | \"qr-code\"\n | \"entity-header\"\n | \"collection-switcher\"\n | \"marketing-layout\"\n | \"marquee\"\n | \"mascot-quote\"\n | \"mascot-state\"\n | \"mascots\"\n | \"match-dialog\"\n | \"media-capture\"\n | \"media-grid\"\n | \"language-switch\"\n | \"media-gallery\"\n | \"media-picker\"\n | \"meter\"\n | \"nav-bar\"\n | \"number-ticker\"\n | \"onboarding\"\n | \"opening-hours\"\n | \"otp-input\"\n | \"page\"\n | \"page-header\"\n | \"page-hero\"\n | \"pagination\"\n | \"permission-prompt\"\n | \"photo-grid\"\n | \"pointer-light\"\n | \"popover\"\n | \"pricing-page\"\n | \"product-page\"\n | \"profile-card\"\n | \"progress\"\n | \"promise-card\"\n | \"pull-to-refresh\"\n | \"retro-tv\"\n | \"shop-gallery\"\n | \"radio-group\"\n | \"router\"\n | \"rail-nav\"\n | \"recipes\"\n | \"screen\"\n | \"scroll-stage\"\n | \"search-field\"\n | \"section-backdrop\"\n | \"segmented\"\n | \"separator\"\n | \"service-card\"\n | \"shop\"\n | \"shop-composer\"\n | \"schema-form\"\n | \"settings-layout\"\n | \"account-menu\"\n | \"showcase\"\n | \"step-showcase\"\n | \"site-footer\"\n | \"sites\"\n | \"skeleton\"\n | \"skip-link\"\n | \"slider\"\n | \"slot-picker\"\n | \"slot\"\n | \"spinner\"\n | \"sticky-action\"\n | \"splash-handoff\"\n | \"split-view\"\n | \"stage-banner\"\n | \"stat\"\n | \"usage\"\n | \"status-page\"\n | \"step-progress\"\n | \"stepper\"\n | \"swipe-deck\"\n | \"swipeable-row\"\n | \"switch\"\n | \"tab-bar\"\n | \"tabs\"\n | \"tag-input\"\n | \"tag-selector\"\n | \"terminal-replay\"\n | \"theme\"\n | \"toast\"\n | \"toc\"\n | \"tooltip\"\n | \"tree-view\"\n | \"txt\"\n | \"update-prompt\"\n | \"verified-badge\"\n | \"vertical-video\"\n | \"video-player\"\n | \"video-trimmer\"\n | \"virtual\"\n | \"wall\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/**\n * Why a component is not on a platform — a decision, never a silence (the parity matrix of ui.krizaka.com/platforms):\n * - `gap` (✗): it belongs there and is not built yet; `issue` is the issue that tracks it (`krizaka/krizaka-ui#275`);\n * - `n/a`: it is not meant for that platform (a site's page block on a phone, a swipe on a desktop); `use` names the\n * component that answers there, when one does.\n */\nexport type Absence =\n | { readonly status: \"gap\"; readonly issue: string; readonly reason: string; readonly use?: undefined }\n | { readonly status: \"n/a\"; readonly reason: string; readonly use?: ComponentName; readonly issue?: undefined };\n\n/**\n * Desktop is the Orazaka Mac app (Tauri 2: the system WebView renders the web components — ADR-002). `web`: the web\n * component runs there as it is; `desktop`: it also has a desktop form (a window's title bar, a denser layout…), said in\n * its documentation; otherwise the absence and why.\n */\nexport type DesktopSupport = \"web\" | \"desktop\" | Absence;\n\n/**\n * The three platforms of Krizaka UI — web · native (React Native, Expo) · desktop — for one component. The side a\n * component has is `platforms`; the side it lacks says why here: `native` is required for (and only for) a web-only\n * component, `web` for a native-only one; `desktop` always. `scripts/registry.test.mjs` fails on a missing decision.\n */\nexport interface Parity {\n readonly web?: Absence;\n readonly native?: Absence;\n readonly desktop: DesktopSupport;\n}\n\n/**\n * `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"stable\" | \"beta\" | \"deprecated\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n /** The version that deprecated it (`3.6.0`). */\n readonly since: string;\n /** The major that removes it (`4.0.0`). */\n readonly removedIn: string;\n /** What replaces it, when a component does. */\n readonly use?: ComponentName;\n /** Why it goes: no product uses it, no planned work needs it. */\n readonly reason: string;\n}\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\ninterface ExampleBase {\n /** The file name, kebab-case (`primary`, `icon-button`). */\n readonly name: string;\n /** A short title (`Primary`, `Icon button`). */\n readonly title: string;\n /** One or two sentences: when this variant is the right one. */\n readonly description: string;\n}\n\n/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n | (ExampleBase & {\n /**\n * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n */\n readonly template: true;\n /** The intent that groups it: why you need this block. */\n readonly purpose: TemplatePurpose;\n /** Why this layout: the user goal it serves, in one sentence. */\n readonly why: string;\n });\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n readonly imports: readonly string[];\n /** The examples, in reading order; the first one is the component's preview. */\n readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n /**\n * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n */\n readonly entry?: string;\n /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n readonly differences: readonly string[];\n /** The React Native entry alone is deprecated while the web one stays (ADR-006 §7); a deprecated component says it once, above. */\n readonly deprecated?: Deprecation;\n}\n\nexport interface KeyboardInteraction {\n /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n readonly keys: string;\n /** What they do. */\n readonly action: string;\n}\n\nexport interface ComponentMeta {\n /** The display name: `Button`, `Dropdown menu`. */\n readonly title: string;\n /** One sentence: what it is. */\n readonly summary: string;\n readonly status: Status;\n /** Required for, and only for, a `deprecated` component. */\n readonly deprecated?: Deprecation;\n readonly category: Category;\n /** Must match the sides below: `both` ⇔ `web` and `native`. */\n readonly platforms: Platform;\n /** The platforms it is not on, and why; and its desktop form (see `Parity`). */\n readonly parity: Parity;\n /** When to reach for it: concrete situations, one per item. */\n readonly whenToUse: readonly string[];\n /** When not to — and what to use instead (`use`), when another component is the answer. */\n readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n /** How to use it well: wording, placement, composition. */\n readonly bestPractices: readonly string[];\n readonly accessibility: {\n /** The keyboard, when it does more than Tab and Enter. */\n readonly keyboard: readonly KeyboardInteraction[];\n /** Roles, names and announcements: what the component does, what the app must provide. */\n readonly notes: readonly string[];\n };\n /** The components a reader of this page should know about. */\n readonly related: readonly ComponentName[];\n readonly web?: PlatformDocs;\n readonly native?: NativeDocs;\n}\n"
|
|
367
|
+
"content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n | \"notification-preferences\"\n | \"quota-meter\"\n | \"environment-notice\"\n | \"embed-facade\"\n | \"reviews\"\n | \"margin-layout\"\n | \"analysis-report\"\n | \"status-chip\"\n | \"kind-config-editor\"\n | \"agenda\"\n | \"account-settings\"\n | \"drop-overlay\"\n | \"upload-queue\"\n | \"achievement\"\n | \"anatomy-plate\"\n | \"bird-plate\"\n | \"taped-photo\"\n | \"stuck\"\n | \"doodle\"\n | \"signature\"\n | \"grade-stamp\"\n | \"versus-card\"\n | \"speed-lines\"\n | \"site-cahier\"\n | \"text-style\"\n | \"flock\"\n | \"elephant\"\n | \"footnote\"\n | \"page-index\"\n | \"chapter\"\n | \"specimen-tag\"\n | \"action-bar\"\n | \"action-sheet\"\n | \"activity-feed\"\n | \"alert\"\n | \"app-frame\"\n | \"desktop-window\"\n | \"form-flow\"\n | \"grid\"\n | \"list-detail\"\n | \"state-screen\"\n | \"app-header\"\n | \"app-shell\"\n | \"argument-card\"\n | \"audio-player\"\n | \"auth-layout\"\n | \"avatar\"\n | \"badge\"\n | \"button\"\n | \"captcha\"\n | \"card\"\n | \"card-grid\"\n | \"catalogue-page\"\n | \"changelog-page\"\n | \"chat\"\n | \"checkbox\"\n | \"chip\"\n | \"chip-link\"\n | \"chip-row\"\n | \"choice-grid\"\n | \"cn\"\n | \"code-block\"\n | \"combobox\"\n | \"comparison-table\"\n | \"command\"\n | \"component-page\"\n | \"confirm-button\"\n | \"copy-button\"\n | \"money-input\"\n | \"price-catalogue-editor\"\n | \"promo-code-field\"\n | \"contact-page\"\n | \"continue-prompt\"\n | \"countdown\"\n | \"cover-hero\"\n | \"cta-panel\"\n | \"dashboard-layout\"\n | \"data-table\"\n | \"date-picker\"\n | \"decision-list\"\n | \"description-list\"\n | \"detail-layout\"\n | \"dialog\"\n | \"docs-article-page\"\n | \"docs-hub-page\"\n | \"docs-layout\"\n | \"docs-nav\"\n | \"document-viewer\"\n | \"dropdown-menu\"\n | \"empty-state\"\n | \"engine-flow\"\n | \"error-page\"\n | \"fab\"\n | \"field\"\n | \"file-upload\"\n | \"filter-bar\"\n | \"force-update-screen\"\n | \"form\"\n | \"gallery-page\"\n | \"genui\"\n | \"glossary\"\n | \"glossary-term\"\n | \"glow-card\"\n | \"goal-gauge\"\n | \"header\"\n | \"how-it-works-page\"\n | \"image-cropper\"\n | \"image-viewer\"\n | \"iso\"\n | \"kanban\"\n | \"kbd\"\n | \"kpi-explained\"\n | \"landing-page\"\n | \"landscape\"\n | \"legal-page\"\n | \"link-card\"\n | \"list\"\n | \"loader\"\n | \"longform-page\"\n | \"maintenance-screen\"\n | \"map\"\n | \"markdown\"\n | \"meta-row\"\n | \"waveform\"\n | \"proposal\"\n | \"qr-code\"\n | \"entity-header\"\n | \"collection-switcher\"\n | \"marketing-layout\"\n | \"marquee\"\n | \"mascot-quote\"\n | \"mascot-state\"\n | \"mascots\"\n | \"match-dialog\"\n | \"media-capture\"\n | \"media-grid\"\n | \"language-switch\"\n | \"media-gallery\"\n | \"media-picker\"\n | \"meter\"\n | \"nav-bar\"\n | \"number-ticker\"\n | \"onboarding\"\n | \"opening-hours\"\n | \"otp-input\"\n | \"page\"\n | \"page-header\"\n | \"page-hero\"\n | \"pagination\"\n | \"permission-prompt\"\n | \"photo-grid\"\n | \"pointer-light\"\n | \"popover\"\n | \"pricing-page\"\n | \"product-page\"\n | \"profile-card\"\n | \"progress\"\n | \"promise-card\"\n | \"pull-to-refresh\"\n | \"retro-tv\"\n | \"shop-gallery\"\n | \"radio-group\"\n | \"router\"\n | \"rail-nav\"\n | \"recipes\"\n | \"screen\"\n | \"scroll-stage\"\n | \"search-field\"\n | \"section-backdrop\"\n | \"segmented\"\n | \"separator\"\n | \"service-card\"\n | \"shop\"\n | \"shop-composer\"\n | \"schema-form\"\n | \"settings-layout\"\n | \"account-menu\"\n | \"showcase\"\n | \"step-showcase\"\n | \"site-footer\"\n | \"sites\"\n | \"skeleton\"\n | \"skip-link\"\n | \"slider\"\n | \"slot-picker\"\n | \"slot\"\n | \"spinner\"\n | \"sticky-action\"\n | \"splash-handoff\"\n | \"split-view\"\n | \"stage-banner\"\n | \"stat\"\n | \"usage\"\n | \"status-page\"\n | \"step-progress\"\n | \"stepper\"\n | \"swipe-deck\"\n | \"swipeable-row\"\n | \"switch\"\n | \"tab-bar\"\n | \"tabs\"\n | \"tag-input\"\n | \"tag-selector\"\n | \"terminal-replay\"\n | \"theme\"\n | \"toast\"\n | \"toc\"\n | \"tooltip\"\n | \"tree-view\"\n | \"txt\"\n | \"update-prompt\"\n | \"verified-badge\"\n | \"vertical-video\"\n | \"video-player\"\n | \"video-trimmer\"\n | \"virtual\"\n | \"wall\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/**\n * Why a component is not on a platform — a decision, never a silence (the parity matrix of ui.krizaka.com/platforms):\n * - `gap` (✗): it belongs there and is not built yet; `issue` is the issue that tracks it (`krizaka/krizaka-ui#275`);\n * - `n/a`: it is not meant for that platform (a site's page block on a phone, a swipe on a desktop); `use` names the\n * component that answers there, when one does.\n */\nexport type Absence =\n | { readonly status: \"gap\"; readonly issue: string; readonly reason: string; readonly use?: undefined }\n | { readonly status: \"n/a\"; readonly reason: string; readonly use?: ComponentName; readonly issue?: undefined };\n\n/**\n * Desktop is the Orazaka Mac app (Tauri 2: the system WebView renders the web components — ADR-002). `web`: the web\n * component runs there as it is; `desktop`: it also has a desktop form (a window's title bar, a denser layout…), said in\n * its documentation; otherwise the absence and why.\n */\nexport type DesktopSupport = \"web\" | \"desktop\" | Absence;\n\n/**\n * The three platforms of Krizaka UI — web · native (React Native, Expo) · desktop — for one component. The side a\n * component has is `platforms`; the side it lacks says why here: `native` is required for (and only for) a web-only\n * component, `web` for a native-only one; `desktop` always. `scripts/registry.test.mjs` fails on a missing decision.\n */\nexport interface Parity {\n readonly web?: Absence;\n readonly native?: Absence;\n readonly desktop: DesktopSupport;\n}\n\n/**\n * `experimental`: created for a filed need (ADR-008 §4), it may change or go in any minor until its first consumer imports it; `adoption`\n * names that consumer's issue. `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"experimental\" | \"stable\" | \"beta\" | \"deprecated\";\n\n/**\n * What a component is for (ADR-008 §3): the twelve domains the documentation, the size budgets and the guards are\n * organised by. The domain is metadata: the entries stay flat (`@krizaka/ui/<name>`). `cahier` is the sites' register\n * (ADR-004): a product never imports it.\n */\nexport type Domain =\n | \"foundations\"\n | \"forms\"\n | \"data-display\"\n | \"navigation-shell\"\n | \"feedback\"\n | \"maps\"\n | \"media\"\n | \"commerce\"\n | \"identity\"\n | \"conversation\"\n | \"page-blocks\"\n | \"cahier\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n /** The version that deprecated it (`3.6.0`). */\n readonly since: string;\n /** The major that removes it (`4.0.0`). */\n readonly removedIn: string;\n /** What replaces it, when a component does. */\n readonly use?: ComponentName;\n /** Why it goes: no product uses it, no planned work needs it. */\n readonly reason: string;\n}\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\ninterface ExampleBase {\n /** The file name, kebab-case (`primary`, `icon-button`). */\n readonly name: string;\n /** A short title (`Primary`, `Icon button`). */\n readonly title: string;\n /** One or two sentences: when this variant is the right one. */\n readonly description: string;\n}\n\n/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n | (ExampleBase & {\n /**\n * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n */\n readonly template: true;\n /** The intent that groups it: why you need this block. */\n readonly purpose: TemplatePurpose;\n /** Why this layout: the user goal it serves, in one sentence. */\n readonly why: string;\n });\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n readonly imports: readonly string[];\n /** The examples, in reading order; the first one is the component's preview. */\n readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n /**\n * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n */\n readonly entry?: string;\n /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n readonly differences: readonly string[];\n /** The React Native entry alone is deprecated while the web one stays (ADR-006 §7); a deprecated component says it once, above. */\n readonly deprecated?: Deprecation;\n}\n\nexport interface KeyboardInteraction {\n /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n readonly keys: string;\n /** What they do. */\n readonly action: string;\n}\n\nexport interface ComponentMeta {\n /** The display name: `Button`, `Dropdown menu`. */\n readonly title: string;\n /** One sentence: what it is. */\n readonly summary: string;\n readonly status: Status;\n /** Required for, and only for, a `deprecated` component. */\n readonly deprecated?: Deprecation;\n readonly category: Category;\n /** What it is for: one of the twelve domains (ADR-008 §3). */\n readonly domain: Domain;\n /** The `<repo>#<n>` issue of its first consumer: required for, and only for, an `experimental` component. */\n readonly adoption?: string;\n /** Must match the sides below: `both` ⇔ `web` and `native`. */\n readonly platforms: Platform;\n /** The platforms it is not on, and why; and its desktop form (see `Parity`). */\n readonly parity: Parity;\n /** When to reach for it: concrete situations, one per item. */\n readonly whenToUse: readonly string[];\n /** When not to — and what to use instead (`use`), when another component is the answer. */\n readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n /** How to use it well: wording, placement, composition. */\n readonly bestPractices: readonly string[];\n readonly accessibility: {\n /** The keyboard, when it does more than Tab and Enter. */\n readonly keyboard: readonly KeyboardInteraction[];\n /** Roles, names and announcements: what the component does, what the app must provide. */\n readonly notes: readonly string[];\n };\n /** The components a reader of this page should know about. */\n readonly related: readonly ComponentName[];\n readonly web?: PlatformDocs;\n readonly native?: NativeDocs;\n}\n"
|
|
366
368
|
},
|
|
367
369
|
{
|
|
368
370
|
"path": "retro-tv/index.ts",
|
|
@@ -370,11 +372,15 @@
|
|
|
370
372
|
},
|
|
371
373
|
{
|
|
372
374
|
"path": "retro-tv/meta.ts",
|
|
373
|
-
"content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n title: \"Retro TV\",\n summary: \"A vertical video presented in a detailed television cabinet, with an accessible player, channel label, scanlines and an animated off-state.\",\n status: \"beta\",\n category: \"media\",\n platforms: \"web\",\n parity: {\n native: { status: \"n/a\", reason: \"The CSS cabinet and SVG static belong to the web presentation; use the native video player for mobile playback.\", use: \"video-player\" },\n desktop: \"web\",\n },\n whenToUse: [\n \"To give a shop's latest reel or story a place on its wall, while keeping the video itself the focus.\",\n \"For a vertical clip whose presentation should feel like a television, in either cabinet or portable style.\",\n ],\n whenNotToUse: [\n { when: \"For video without a decorative television frame: use the accessible video player.\", use: \"video-player\" },\n { when: \"For a feed of creator clips with an action rail and caption: use vertical video.\", use: \"vertical-video\" },\n ],\n bestPractices: [\n \"Give the player a title, poster and translated `labels`; pass WebVTT captions as `tracks`.\",\n \"Keep autoplay muted; it starts only while the player is on screen and waits under reduced motion.\",\n \"Use `off` for the static screen; the video is not loaded or played in this state.\",\n \"`playlist` plays the programmes in order, then loops; `transition` is `channel`, `crossfade` or `slide` and is a plain cut under reduced motion. Sound starts off: remember the visitor's choice from `onMutedChange`.\",\n \"A programme without `src` is a slot: fill it with `renderEmbed` (an `EmbedFacade` behind its consent click); the library loads no third-party script.\",\n \"A platform's short video (TikTok, YouTube Shorts, Instagram) goes in as `children`, an `EmbedFacade`: the television's screen shows the facade, and nothing is requested from the platform before the visitor's click.\",\n ],\n accessibility: {\n keyboard: [\n { keys: \"Space / K\", action: \"Play or pause the focused video.\" },\n { keys: \"N / P\", action: \"Next or previous programme of a playlist.\" },\n { keys: \"M\", action: \"Turn the sound on or off.\" },\n { keys: \"Arrow left / right\", action: \"Seek 5 seconds.\" },\n { keys: \"Tab\", action: \"Move through the player's named controls.\" },\n ],\n notes: [\n \"The cabinet, scanlines and static are decorative; the embedded video player keeps its named region and keyboard-accessible controls.\",\n \"The focus ring remains visible around the screen, and the channel name is visible text.\",\n \"Under reduced motion the power-on and static effects stop, and autoplay waits for a gesture.\",\n ],\n },\n related: [\"video-player\", \"vertical-video\", \"audio-player\", \"embed-facade\"],\n web: {\n imports: [\"RetroTv\"],\n examples: [\n { name: \"cabinet\", title: \"Wood cabinet\", description: \"A vertical shop story in the cabinet television, with its channel label and player controls.\" },\n { name: \"portable\", title: \"Portable set\", description: \"The same vertical story in a compact cream television cabinet.\" },\n { name: \"playlist-channel\", title: \"Playlist, channel switch\", description: \"`playlist` with `transition=\\\"channel\\\"`: static and a roll between programmes, in order, then looping.\" },\n { name: \"playlist-crossfade\", title: \"Playlist, crossfade\", description: \"`transition=\\\"crossfade\\\"`: one programme dissolves into the next.\" },\n { name: \"playlist-slide\", title: \"Playlist, slide\", description: \"`transition=\\\"slide\\\"`: the next programme pushes the last one out.\" },\n { name: \"facade\", title: \"A platform's reel behind a facade\", description: \"`children`: an `EmbedFacade` on the screen, nothing loaded until the click.\" },\n ],\n },\n} satisfies ComponentMeta;\n"
|
|
375
|
+
"content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n title: \"Retro TV\",\n summary: \"A vertical video presented in a detailed television cabinet, with an accessible player, channel label, scanlines and an animated off-state.\",\n status: \"beta\",\n category: \"media\",\n domain: \"media\",\n platforms: \"web\",\n parity: {\n native: { status: \"n/a\", reason: \"The CSS cabinet and SVG static belong to the web presentation; use the native video player for mobile playback.\", use: \"video-player\" },\n desktop: \"web\",\n },\n whenToUse: [\n \"To give a shop's latest reel or story a place on its wall, while keeping the video itself the focus.\",\n \"For a vertical clip whose presentation should feel like a television, in either cabinet or portable style.\",\n ],\n whenNotToUse: [\n { when: \"For video without a decorative television frame: use the accessible video player.\", use: \"video-player\" },\n { when: \"For a feed of creator clips with an action rail and caption: use vertical video.\", use: \"vertical-video\" },\n ],\n bestPractices: [\n \"Give the player a title, poster and translated `labels`; pass WebVTT captions as `tracks`.\",\n \"Keep autoplay muted; it starts only while the player is on screen and waits under reduced motion.\",\n \"Use `off` for the static screen; the video is not loaded or played in this state.\",\n \"`playlist` plays the programmes in order, then loops; `transition` is `channel`, `crossfade` or `slide` and is a plain cut under reduced motion. Sound starts off: remember the visitor's choice from `onMutedChange`.\",\n \"A programme without `src` is a slot: fill it with `renderEmbed` (an `EmbedFacade` behind its consent click); the library loads no third-party script.\",\n \"A platform's short video (TikTok, YouTube Shorts, Instagram) goes in as `children`, an `EmbedFacade`: the television's screen shows the facade, and nothing is requested from the platform before the visitor's click.\",\n ],\n accessibility: {\n keyboard: [\n { keys: \"Space / K\", action: \"Play or pause the focused video.\" },\n { keys: \"N / P\", action: \"Next or previous programme of a playlist.\" },\n { keys: \"M\", action: \"Turn the sound on or off.\" },\n { keys: \"Arrow left / right\", action: \"Seek 5 seconds.\" },\n { keys: \"Tab\", action: \"Move through the player's named controls.\" },\n ],\n notes: [\n \"The cabinet, scanlines and static are decorative; the embedded video player keeps its named region and keyboard-accessible controls.\",\n \"The focus ring remains visible around the screen, and the channel name is visible text.\",\n \"Under reduced motion the power-on and static effects stop, and autoplay waits for a gesture.\",\n ],\n },\n related: [\"video-player\", \"vertical-video\", \"audio-player\", \"embed-facade\"],\n web: {\n imports: [\"RetroTv\"],\n examples: [\n { name: \"cabinet\", title: \"Wood cabinet\", description: \"A vertical shop story in the cabinet television, with its channel label and player controls.\" },\n { name: \"portable\", title: \"Portable set\", description: \"The same vertical story in a compact cream television cabinet.\" },\n { name: \"playlist-channel\", title: \"Playlist, channel switch\", description: \"`playlist` with `transition=\\\"channel\\\"`: static and a roll between programmes, in order, then looping.\" },\n { name: \"playlist-crossfade\", title: \"Playlist, crossfade\", description: \"`transition=\\\"crossfade\\\"`: one programme dissolves into the next.\" },\n { name: \"playlist-slide\", title: \"Playlist, slide\", description: \"`transition=\\\"slide\\\"`: the next programme pushes the last one out.\" },\n { name: \"facade\", title: \"A platform's reel behind a facade\", description: \"`children`: an `EmbedFacade` on the screen, nothing loaded until the click.\" },\n ],\n },\n} satisfies ComponentMeta;\n"
|
|
376
|
+
},
|
|
377
|
+
{
|
|
378
|
+
"path": "retro-tv/playlist-screen.tsx",
|
|
379
|
+
"content": "\"use client\";\n\nimport * as React from \"react\";\n\nimport { CaptionsGlyph, PauseGlyph, PlayGlyph, VolumeGlyph } from \"../glyphs\";\nimport { formatClock, playSafely, useInView } from \"../media\";\nimport type { RetroTvLabels, RetroTvSource, RetroTvTransition } from \"./retro-tv\";\n\nconst styles = `.kz-rtv-layer{position:absolute;inset:0;background:var(--kz-scrim-strong)}\n.kz-rtv-layer video,.kz-rtv-layer img,.kz-rtv-layer .kz-embed{width:100%;height:100%;object-fit:contain;aspect-ratio:auto}\n.kz-rtv-layer[data-role=out]{z-index:1}.kz-rtv-layer[data-role=in]{z-index:2}\n.kz-rtv-static{position:absolute;inset:0;z-index:4;overflow:hidden;pointer-events:none}\n.kz-rtv-static:after{position:absolute;inset:-20% 0 auto;height:18%;background:linear-gradient(transparent,color-mix(in srgb,var(--kz-text-on-media) 55%,transparent),transparent);content:\"\"}\n.kz-rtv-chip,.kz-rtv-bar button{display:inline-flex;min-width:2.25rem;min-height:2.25rem;align-items:center;justify-content:center;gap:.35rem;padding:0 .55rem;border:1px solid color-mix(in srgb,var(--kz-text-on-media) 30%,transparent);border-radius:999px;background:color-mix(in srgb,var(--kz-scrim-strong) 82%,transparent);color:var(--kz-text-on-media);font:600 .72rem/1 var(--kz-font-mono,monospace);cursor:pointer}\n.kz-rtv-chip{position:absolute;z-index:8;top:.5rem;left:.5rem}\n.kz-rtv-chip:focus-visible,.kz-rtv-bar button:focus-visible,.kz-rtv-seek:focus-visible{outline:2px solid var(--kz-ring);outline-offset:2px}\n.kz-rtv-bar{position:absolute;z-index:8;inset:auto 0 0;display:flex;flex-wrap:wrap;align-items:center;gap:.4rem;padding:1.6rem .6rem .6rem;background:linear-gradient(transparent,color-mix(in srgb,var(--kz-scrim-strong) 85%,transparent));opacity:0;transition:opacity .25s}\n.kz-rtv-screen[data-active=true] .kz-rtv-bar,.kz-rtv-screen:focus-within .kz-rtv-bar,.kz-rtv-screen:hover .kz-rtv-bar{opacity:1}\n.kz-rtv-bar svg{width:1rem;height:1rem}\n.kz-rtv-time{padding:.2rem .45rem;border-radius:4px;background:var(--kz-scrim-strong);color:var(--kz-text-on-media);font:600 .75rem/1 var(--kz-font-mono,monospace);font-variant-numeric:tabular-nums}\n.kz-rtv-seek{flex:1 1 6rem;min-width:5rem;height:1.5rem;accent-color:var(--kz-accent);cursor:pointer}\n.kz-rtv-progress{position:absolute;z-index:7;inset:auto 0 0;height:3px;background:color-mix(in srgb,var(--kz-text-on-media) 25%,transparent)}\n.kz-rtv-progress i{display:block;height:100%;background:var(--kz-accent);transform-origin:left;transform:scaleX(var(--kz-rtv-p,0))}\n@keyframes kz-rtv-in{from{opacity:0}to{opacity:1}}@keyframes kz-rtv-out{from{opacity:1}to{opacity:0}}\n@keyframes kz-rtv-sin{from{transform:translateX(100%)}to{transform:none}}@keyframes kz-rtv-sout{from{transform:none}to{transform:translateX(-100%)}}\n@keyframes kz-rtv-tune{0%{transform:translateY(-12%) scaleY(1.15);filter:contrast(2) brightness(1.6)}100%{transform:none;filter:none}}\n@keyframes kz-rtv-roll{from{transform:translateY(0)}to{transform:translateY(700%)}}\n@media (prefers-reduced-motion:no-preference){\n.kz-rtv-layer[data-role=in][data-tr=crossfade]{animation:kz-rtv-in .6s both}.kz-rtv-layer[data-role=out][data-tr=crossfade]{animation:kz-rtv-out .6s both}\n.kz-rtv-layer[data-role=in][data-tr=slide]{animation:kz-rtv-sin .5s ease-out both}.kz-rtv-layer[data-role=out][data-tr=slide]{animation:kz-rtv-sout .5s ease-out both}\n.kz-rtv-layer[data-role=in][data-tr=channel]{animation:kz-rtv-tune .55s steps(8,end) both}\n.kz-rtv-static{animation:kz-rtv-in .55s reverse both}.kz-rtv-static:after{animation:kz-rtv-roll .55s linear both}}\n`;\n\ntype PlaylistProps = { playlist: readonly RetroTvSource[]; transition: RetroTvTransition; labels: RetroTvLabels; muted: boolean; autoPlay: boolean; renderEmbed?: (source: RetroTvSource) => React.ReactNode; onMutedChange?: (muted: boolean) => void; onIndexChange?: (index: number) => void; title?: string; reduced: boolean; setMutedState: (m: boolean) => void; setIndex: (i: number) => void; index: number };\n\nexport function PlaylistScreen({ playlist, transition, labels, muted, autoPlay, renderEmbed, onMutedChange, onIndexChange, title, reduced, setMutedState, setIndex, index }: PlaylistProps) {\n const region = React.useRef<HTMLDivElement>(null);\n const video = React.useRef<HTMLVideoElement>(null);\n const [prev, setPrev] = React.useState<number | null>(null);\n const [seen, setSeen] = React.useState(false);\n const [playing, setPlaying] = React.useState(false);\n const [time, setTime] = React.useState({ t: 0, d: 0 });\n const [active, setActive] = React.useState(false);\n const [captionsOn, setCaptionsOn] = React.useState(false);\n const n = playlist.length;\n const current = playlist[index];\n const wake = React.useCallback(() => setActive(true), []);\n\n useInView(region, (v) => { if (v) setSeen(true); else video.current?.pause(); });\n React.useEffect(() => { if (!active) return; const id = setTimeout(() => setActive(false), 2500); return () => clearTimeout(id); }, [active]);\n React.useEffect(() => { if (prev === null) return; const id = setTimeout(() => setPrev(null), reduced ? 0 : 650); return () => clearTimeout(id); }, [prev, reduced]);\n React.useEffect(() => { if (seen && autoPlay && !reduced && current?.src) playSafely(video.current); }, [seen, autoPlay, reduced, index, current?.src]);\n React.useEffect(() => { const list = video.current?.textTracks; if (list) Array.from(list).forEach((track, i) => { track.mode = captionsOn && i === 0 ? \"showing\" : \"disabled\"; }); }, [captionsOn, index]);\n\n const go = (to: number) => {\n const next = ((to % n) + n) % n;\n if (next === index && n > 1) return;\n if (!reduced && n > 1) setPrev(index);\n setIndex(next);\n setTime({ t: 0, d: 0 });\n onIndexChange?.(next);\n };\n const toggle = () => { const v = video.current; if (!v) return; if (v.paused) playSafely(v); else v.pause(); };\n const setMuted = (m: boolean) => { setMutedState(m); onMutedChange?.(m); };\n const onKey = (e: React.KeyboardEvent) => {\n if (e.target !== e.currentTarget) return;\n const v = video.current;\n const act: Record<string, () => void> = { \" \": toggle, k: toggle, m: () => setMuted(!muted), n: () => go(index + 1), p: () => go(index - 1), ArrowRight: () => { if (v) v.currentTime += 5; }, ArrowLeft: () => { if (v) v.currentTime -= 5; } };\n const fn = act[e.key.length === 1 ? e.key.toLowerCase() : e.key];\n if (fn) { e.preventDefault(); fn(); wake(); }\n };\n const layer = (i: number, role: \"in\" | \"out\") => {\n const src = playlist[i];\n if (!src) return null;\n return (\n <div className=\"kz-rtv-layer\" key={src.id} data-role={role} data-tr={transition}>\n {src.src ? (\n role === \"in\" ? (\n <video ref={video} src={seen ? src.src : undefined} poster={src.poster} muted={muted} playsInline preload={seen ? \"auto\" : \"none\"} loop={n === 1} aria-label={src.title}\n onPlay={() => setPlaying(true)} onPause={() => setPlaying(false)} onEnded={() => { if (n > 1) go(index + 1); }}\n onTimeUpdate={(e) => setTime({ t: e.currentTarget.currentTime, d: e.currentTarget.duration || 0 })} onLoadedMetadata={(e) => setTime({ t: 0, d: e.currentTarget.duration || 0 })}>\n {src.tracks?.map((t) => <track key={t.src} kind=\"captions\" src={t.src} srcLang={t.srcLang} label={t.label} />)}\n </video>\n ) : src.poster ? <img src={src.poster} alt=\"\" /> : null\n ) : role === \"in\" ? renderEmbed?.(src) : null}\n </div>\n );\n };\n const p = time.d ? Math.min(1, time.t / time.d) : 0;\n const hasCaptions = !!current?.tracks?.length;\n return (\n <>\n <style>{styles}</style>\n <div ref={region} role=\"region\" aria-label={title ?? current?.title} tabIndex={0} className=\"kz-rtv-playlist\" data-active={active ? \"true\" : undefined} onKeyDown={onKey} onPointerMove={wake} onPointerDown={wake} onFocus={wake} style={{ position: \"absolute\", inset: 0, \"--kz-rtv-p\": p } as React.CSSProperties}>\n {prev !== null && layer(prev, \"out\")}\n {layer(index, \"in\")}\n {prev !== null && transition === \"channel\" && <div className=\"kz-rtv-static\" aria-hidden=\"true\"><span className=\"kz-rtv-noise\" style={{ position: \"absolute\", inset: 0, background: \"repeating-linear-gradient(0deg,var(--kz-text-on-media) 0 1px,var(--kz-scrim-strong) 1px 3px)\" }} /></div>}\n <button type=\"button\" className=\"kz-rtv-chip\" aria-pressed={!muted} aria-label={muted ? labels.soundOff : labels.soundOn} onClick={() => setMuted(!muted)}><VolumeGlyph muted={muted} /></button>\n <div className=\"kz-rtv-progress\" aria-hidden=\"true\"><i /></div>\n <div className=\"kz-rtv-bar\">\n <button type=\"button\" aria-label={labels.previous} onClick={() => go(index - 1)} disabled={n < 2}>«</button>\n <button type=\"button\" aria-label={playing ? labels.pause : labels.play} onClick={toggle} disabled={!current?.src}>{playing ? <PauseGlyph /> : <PlayGlyph />}</button>\n <button type=\"button\" aria-label={labels.next} onClick={() => go(index + 1)} disabled={n < 2}>»</button>\n <span className=\"kz-rtv-time\">{formatClock(time.t)} / {formatClock(time.d)}</span>\n <input className=\"kz-rtv-seek\" type=\"range\" aria-label={labels.seek} min={0} max={Math.max(1, Math.floor(time.d))} value={Math.floor(time.t)} disabled={!time.d} onChange={(e) => { if (video.current) video.current.currentTime = Number(e.target.value); }} />\n {hasCaptions && <button type=\"button\" aria-label={labels.captions} aria-pressed={captionsOn} onClick={() => setCaptionsOn(!captionsOn)}><CaptionsGlyph /></button>}\n </div>\n <span className=\"sr-only\" aria-live=\"polite\">{labels.nowPlaying}: {current?.title} ({index + 1}/{n})</span>\n </div>\n </>\n );\n}\n"
|
|
374
380
|
},
|
|
375
381
|
{
|
|
376
382
|
"path": "retro-tv/retro-tv.tsx",
|
|
377
|
-
"content": "\"use client\";\n\nimport * as React from \"react\";\n\nimport { CaptionsGlyph, PauseGlyph, PlayGlyph, VolumeGlyph } from \"../glyphs\";\nimport { formatClock, playSafely, useInView, usePrefersReducedMotion } from \"../media\";\nimport { VideoPlayer, type VideoPlayerProps } from \"../video-player/video-player\";\n\nconst styles = `\n.kz-rtv{container-type:inline-size;width:100%;max-width:100%;color:var(--kz-text-primary)}\n.kz-rtv-frame{position:relative;isolation:isolate;width:100%;aspect-ratio:4/5}\n@container (min-width:44rem){.kz-rtv-frame{aspect-ratio:16/10}.kz-rtv-bezel{width:72%}.kz-rtv-screen{width:66%}.kz-rtv-controls{width:18%;right:5%}.kz-rtv-speaker{width:18%;right:5%}}\n.kz-rtv-cabinet{position:absolute;inset:0;overflow:hidden}\n.kz-rtv-body{position:absolute;inset:4% 4% 16%;border:1px solid var(--kz-border-strong);border-radius:8% / 6%;background:linear-gradient(145deg,var(--kz-surface-sheen),transparent 35%),linear-gradient(145deg,color-mix(in srgb,var(--kz-warning) 18%,var(--kz-surface-3)),color-mix(in srgb,var(--kz-warning-text) 10%,var(--kz-surface-2)) 48%,var(--kz-surface-1));box-shadow:inset 0 1px 0 var(--kz-surface-sheen),inset 0 -3px 6px color-mix(in srgb,var(--kz-scrim-strong) 30%,transparent),0 1.2rem 2rem color-mix(in srgb,var(--kz-scrim-strong) 24%,transparent)}\n.kz-rtv[data-variant=portable] .kz-rtv-body{border-radius:12% / 8%;background:linear-gradient(145deg,var(--kz-surface-1),var(--kz-surface-2) 55%,var(--kz-surface-3))}\n.kz-rtv-body:after{position:absolute;inset:0;border-radius:inherit;background:repeating-linear-gradient(115deg,transparent 0 7px,color-mix(in srgb,var(--kz-border-subtle) 35%,transparent) 8px 9px);content:\"\";opacity:.4;pointer-events:none}\n.kz-rtv-bezel{position:absolute;top:0;bottom:0;left:6%;width:61%;border:1px solid var(--kz-border-strong);border-radius:14% / 7%;background:linear-gradient(145deg,var(--kz-surface-1),var(--kz-surface-3));box-shadow:inset 0 2px 5px color-mix(in srgb,var(--kz-scrim-strong) 35%,transparent),0 1px 2px color-mix(in srgb,var(--kz-surface-sheen) 60%,transparent)}\n.kz-rtv[data-variant=portable] .kz-rtv-bezel{border-radius:19% / 9%;background:linear-gradient(145deg,var(--kz-surface-0),var(--kz-surface-2))}\n.kz-rtv-controls{position:absolute;top:16%;right:7%;display:flex;width:23%;flex-direction:column;align-items:center;gap:1.1rem}\n.kz-rtv-knob{position:relative;display:block;width:2.3rem;max-width:70%;aspect-ratio:1;border:2px solid var(--kz-border-strong);border-radius:50%;background:radial-gradient(circle at 35% 28%,var(--kz-surface-sheen),transparent 30%),linear-gradient(145deg,var(--kz-surface-1),var(--kz-surface-3));box-shadow:inset 0 -2px 3px color-mix(in srgb,var(--kz-scrim-strong) 35%,transparent),0 2px 4px color-mix(in srgb,var(--kz-scrim-strong) 25%,transparent);color:var(--kz-accent)}\n.kz-rtv-knob[data-hue=accent]{background:radial-gradient(circle at 35% 28%,var(--kz-surface-sheen),transparent 30%),linear-gradient(145deg,var(--kz-accent-text),var(--kz-accent))}\n.kz-rtv-knob{transform:rotate(var(--kz-rtv-angle,0deg));transition:transform .4s cubic-bezier(.3,1.4,.5,1)}\n.kz-rtv-knob:before{position:absolute;inset:-.35rem;border-radius:50%;background:repeating-conic-gradient(from -135deg,var(--kz-border-strong) 0 2deg,transparent 2deg 27deg);content:\"\";-webkit-mask:radial-gradient(circle,transparent 62%,#000 64%);mask:radial-gradient(circle,transparent 62%,#000 64%);transform:rotate(calc(var(--kz-rtv-angle,0deg)*-1))}\n.kz-rtv-knob:after{position:absolute;top:14%;left:calc(50% - 1px);width:2px;height:27%;border-radius:2px;background:var(--kz-on-accent);content:\"\"}\n.kz-rtv[data-variant=portable] .kz-rtv-knob{width:1.9rem}\n.kz-rtv-speaker{position:absolute;right:7%;bottom:9%;display:flex;width:23%;flex-direction:column;gap:3px}\n.kz-rtv-speaker i{height:2px;border-radius:2px;background:var(--kz-border-strong);box-shadow:0 1px 0 var(--kz-surface-sheen)}\n.kz-rtv[data-variant=portable] .kz-rtv-speaker{display:none}\n.kz-rtv-stand{position:absolute;bottom:4%;left:36%;width:28%;height:12%;border-bottom:1px solid var(--kz-border-strong);border-radius:0 0 30% 30%;background:linear-gradient(180deg,var(--kz-surface-2),var(--kz-surface-3));clip-path:polygon(25% 0,75% 0,88% 78%,100% 100%,0 100%,12% 78%)}\n.kz-rtv[data-variant=portable] .kz-rtv-stand{left:40%;width:20%;height:8%;border-radius:50%;clip-path:ellipse(50% 50% at 50% 50%)}\n.kz-rtv-screen{position:absolute;top:4%;left:9.5%;width:56%;height:80%;overflow:hidden;border:2px solid color-mix(in srgb,var(--kz-border-strong) 72%,var(--kz-accent));border-radius:13% / 7%;background:var(--kz-scrim-strong);box-shadow:0 0 1.1rem color-mix(in srgb,var(--kz-accent) 30%,transparent),inset 0 0 1.2rem var(--kz-scrim-strong)}\n.kz-rtv[data-variant=portable] .kz-rtv-screen{border-radius:18% / 9%}\n.kz-rtv-screen .kz-rtv-player{height:100%;width:100%;border-radius:inherit}\n.kz-rtv-screen .kz-embed{height:100%;width:100%;aspect-ratio:auto;border-radius:inherit}\n.kz-rtv-player video,.kz-rtv-player img{object-fit:cover}\n.kz-rtv-effects{position:absolute;z-index:5;inset:0;overflow:hidden;border-radius:inherit;pointer-events:none}\n.kz-rtv-effects:before{position:absolute;inset:0;background:repeating-linear-gradient(to bottom,transparent 0 3px,color-mix(in srgb,var(--kz-scrim-strong) 25%,transparent) 4px 5px);content:\"\";opacity:.46}\n.kz-rtv-effects:after{position:absolute;inset:-1px;background:radial-gradient(ellipse at center,transparent 55%,var(--kz-scrim-strong) 100%);content:\"\";opacity:.52}\n.kz-rtv-glow{position:absolute;inset:0;background:radial-gradient(ellipse at 50% 45%,color-mix(in srgb,var(--kz-accent) 14%,transparent),transparent 68%);opacity:.7}\n.kz-rtv-noise{position:absolute;inset:0;height:100%;width:100%;opacity:.55;filter:contrast(1.3) brightness(.85)}\n.kz-rtv-glass{position:absolute;inset:0;height:100%;width:100%;opacity:.28}\n.kz-rtv-power{position:absolute;inset:0;background:var(--kz-text-on-media);opacity:0;transform:scaleY(.01);transform-origin:center;pointer-events:none}\n.kz-rtv[data-powered=true] .kz-rtv-power{animation:kz-rtv-power .65s ease-out both}\n.kz-rtv-channel{position:absolute;z-index:7;top:8%;right:5%;width:24%;overflow:hidden;padding:.25em .4em;border:1px solid var(--kz-border-strong);border-radius:3px;background:var(--kz-surface-1);box-shadow:inset 0 1px 0 var(--kz-surface-sheen);color:var(--kz-text-primary);font:700 clamp(.5rem,1.4cqw,.7rem)/1.2 var(--kz-font-mono,monospace);letter-spacing:.12em;text-transform:uppercase;text-align:center;text-overflow:ellipsis;white-space:nowrap}\n.kz-rtv[data-variant=portable] .kz-rtv-channel{top:7%}\n.kz-rtv-layer{position:absolute;inset:0;background:var(--kz-scrim-strong)}\n.kz-rtv-layer video,.kz-rtv-layer img,.kz-rtv-layer .kz-embed{width:100%;height:100%;object-fit:contain;aspect-ratio:auto}\n.kz-rtv-layer[data-role=out]{z-index:1}.kz-rtv-layer[data-role=in]{z-index:2}\n.kz-rtv-static{position:absolute;inset:0;z-index:4;overflow:hidden;pointer-events:none}\n.kz-rtv-static:after{position:absolute;inset:-20% 0 auto;height:18%;background:linear-gradient(transparent,color-mix(in srgb,var(--kz-text-on-media) 55%,transparent),transparent);content:\"\"}\n.kz-rtv-chip,.kz-rtv-bar button{display:inline-flex;min-width:2.25rem;min-height:2.25rem;align-items:center;justify-content:center;gap:.35rem;padding:0 .55rem;border:1px solid color-mix(in srgb,var(--kz-text-on-media) 30%,transparent);border-radius:999px;background:color-mix(in srgb,var(--kz-scrim-strong) 82%,transparent);color:var(--kz-text-on-media);font:600 .72rem/1 var(--kz-font-mono,monospace);cursor:pointer}\n.kz-rtv-chip{position:absolute;z-index:8;top:.5rem;left:.5rem}\n.kz-rtv-chip:focus-visible,.kz-rtv-bar button:focus-visible,.kz-rtv-seek:focus-visible{outline:2px solid var(--kz-ring);outline-offset:2px}\n.kz-rtv-bar{position:absolute;z-index:8;inset:auto 0 0;display:flex;flex-wrap:wrap;align-items:center;gap:.4rem;padding:1.6rem .6rem .6rem;background:linear-gradient(transparent,color-mix(in srgb,var(--kz-scrim-strong) 85%,transparent));opacity:0;transition:opacity .25s}\n.kz-rtv-screen[data-active=true] .kz-rtv-bar,.kz-rtv-screen:focus-within .kz-rtv-bar,.kz-rtv-screen:hover .kz-rtv-bar{opacity:1}\n.kz-rtv-bar svg{width:1rem;height:1rem}\n.kz-rtv-time{padding:.2rem .45rem;border-radius:4px;background:var(--kz-scrim-strong);color:var(--kz-text-on-media);font:600 .75rem/1 var(--kz-font-mono,monospace);font-variant-numeric:tabular-nums}\n.kz-rtv-seek{flex:1 1 6rem;min-width:5rem;height:1.5rem;accent-color:var(--kz-accent);cursor:pointer}\n.kz-rtv-progress{position:absolute;z-index:7;inset:auto 0 0;height:3px;background:color-mix(in srgb,var(--kz-text-on-media) 25%,transparent)}\n.kz-rtv-progress i{display:block;height:100%;background:var(--kz-accent);transform-origin:left;transform:scaleX(var(--kz-rtv-p,0))}\n@media (prefers-reduced-motion:no-preference){\n.kz-rtv-layer[data-role=in][data-tr=crossfade]{animation:kz-rtv-in .6s both}.kz-rtv-layer[data-role=out][data-tr=crossfade]{animation:kz-rtv-out .6s both}\n.kz-rtv-layer[data-role=in][data-tr=slide]{animation:kz-rtv-sin .5s ease-out both}.kz-rtv-layer[data-role=out][data-tr=slide]{animation:kz-rtv-sout .5s ease-out both}\n.kz-rtv-layer[data-role=in][data-tr=channel]{animation:kz-rtv-tune .55s steps(8,end) both}\n.kz-rtv-static{animation:kz-rtv-in .55s reverse both}.kz-rtv-static:after{animation:kz-rtv-roll .55s linear both}}\n@keyframes kz-rtv-in{from{opacity:0}to{opacity:1}}@keyframes kz-rtv-out{from{opacity:1}to{opacity:0}}\n@keyframes kz-rtv-sin{from{transform:translateX(100%)}to{transform:none}}@keyframes kz-rtv-sout{from{transform:none}to{transform:translateX(-100%)}}\n@keyframes kz-rtv-tune{0%{transform:translateY(-12%) scaleY(1.15);filter:contrast(2) brightness(1.6)}100%{transform:none;filter:none}}\n@keyframes kz-rtv-roll{from{transform:translateY(0)}to{transform:translateY(700%)}}\n.kz-rtv:focus-within .kz-rtv-screen{outline:2px solid var(--kz-ring);outline-offset:3px}\n@keyframes kz-rtv-power{0%{opacity:1;transform:scaleY(.01)}45%{opacity:.9;transform:scaleY(1)}100%{opacity:0;transform:scaleY(1)}}\n@keyframes kz-rtv-noise{0%,100%{opacity:.38}50%{opacity:.62}}\n@media (prefers-reduced-motion:no-preference){.kz-rtv[data-off=true] .kz-rtv-noise{animation:kz-rtv-noise .18s steps(2,end) infinite}}\n@media (prefers-reduced-motion:reduce){.kz-rtv-power{display:none!important}.kz-rtv-noise{animation:none!important}}\n`;\n\n\n/** One programme of the playlist: an uploaded video (`src`) or, without `src`, a slot the host fills with `renderEmbed`. */\nexport interface RetroTvSource {\n id: string;\n title: string;\n src?: string;\n poster?: string;\n /** WebVTT captions of this video. */\n tracks?: VideoPlayerProps[\"tracks\"];\n}\nexport type RetroTvTransition = \"channel\" | \"crossfade\" | \"slide\";\nexport interface RetroTvLabels { play: string; pause: string; next: string; previous: string; soundOff: string; soundOn: string; captions: string; seek: string; nowPlaying: string }\nexport const retroTvLabels: RetroTvLabels = { play: \"Play\", pause: \"Pause\", next: \"Next video\", previous: \"Previous video\", soundOff: \"Sound off: turn on\", soundOn: \"Sound on: turn off\", captions: \"Captions\", seek: \"Seek\", nowPlaying: \"Now playing\" };\nexport const retroTvLabelsFr: RetroTvLabels = { play: \"Lecture\", pause: \"Pause\", next: \"Vidéo suivante\", previous: \"Vidéo précédente\", soundOff: \"Son coupé : activer\", soundOn: \"Son activé : couper\", captions: \"Sous-titres\", seek: \"Position\", nowPlaying: \"En cours\" };\n\ntype PlaylistProps = { playlist: readonly RetroTvSource[]; transition: RetroTvTransition; labels: RetroTvLabels; muted: boolean; autoPlay: boolean; renderEmbed?: (source: RetroTvSource) => React.ReactNode; onMutedChange?: (muted: boolean) => void; onIndexChange?: (index: number) => void; title?: string; reduced: boolean; setMutedState: (m: boolean) => void; setIndex: (i: number) => void; index: number };\n\nfunction PlaylistScreen({ playlist, transition, labels, muted, autoPlay, renderEmbed, onMutedChange, onIndexChange, title, reduced, setMutedState, setIndex, index }: PlaylistProps) {\n const region = React.useRef<HTMLDivElement>(null);\n const video = React.useRef<HTMLVideoElement>(null);\n const [prev, setPrev] = React.useState<number | null>(null);\n const [seen, setSeen] = React.useState(false);\n const [playing, setPlaying] = React.useState(false);\n const [time, setTime] = React.useState({ t: 0, d: 0 });\n const [active, setActive] = React.useState(false);\n const [captionsOn, setCaptionsOn] = React.useState(false);\n const n = playlist.length;\n const current = playlist[index];\n const wake = React.useCallback(() => setActive(true), []);\n\n useInView(region, (v) => { if (v) setSeen(true); else video.current?.pause(); });\n React.useEffect(() => { if (!active) return; const id = setTimeout(() => setActive(false), 2500); return () => clearTimeout(id); }, [active]);\n React.useEffect(() => { if (prev === null) return; const id = setTimeout(() => setPrev(null), reduced ? 0 : 650); return () => clearTimeout(id); }, [prev, reduced]);\n React.useEffect(() => { if (seen && autoPlay && !reduced && current?.src) playSafely(video.current); }, [seen, autoPlay, reduced, index, current?.src]);\n React.useEffect(() => { const list = video.current?.textTracks; if (list) Array.from(list).forEach((track, i) => { track.mode = captionsOn && i === 0 ? \"showing\" : \"disabled\"; }); }, [captionsOn, index]);\n\n const go = (to: number) => {\n const next = ((to % n) + n) % n;\n if (next === index && n > 1) return;\n if (!reduced && n > 1) setPrev(index);\n setIndex(next);\n setTime({ t: 0, d: 0 });\n onIndexChange?.(next);\n };\n const toggle = () => { const v = video.current; if (!v) return; if (v.paused) playSafely(v); else v.pause(); };\n const setMuted = (m: boolean) => { setMutedState(m); onMutedChange?.(m); };\n const onKey = (e: React.KeyboardEvent) => {\n if (e.target !== e.currentTarget) return;\n const v = video.current;\n const act: Record<string, () => void> = { \" \": toggle, k: toggle, m: () => setMuted(!muted), n: () => go(index + 1), p: () => go(index - 1), ArrowRight: () => { if (v) v.currentTime += 5; }, ArrowLeft: () => { if (v) v.currentTime -= 5; } };\n const fn = act[e.key.length === 1 ? e.key.toLowerCase() : e.key];\n if (fn) { e.preventDefault(); fn(); wake(); }\n };\n const layer = (i: number, role: \"in\" | \"out\") => {\n const src = playlist[i];\n if (!src) return null;\n return (\n <div className=\"kz-rtv-layer\" key={src.id} data-role={role} data-tr={transition}>\n {src.src ? (\n role === \"in\" ? (\n <video ref={video} src={seen ? src.src : undefined} poster={src.poster} muted={muted} playsInline preload={seen ? \"auto\" : \"none\"} loop={n === 1} aria-label={src.title}\n onPlay={() => setPlaying(true)} onPause={() => setPlaying(false)} onEnded={() => { if (n > 1) go(index + 1); }}\n onTimeUpdate={(e) => setTime({ t: e.currentTarget.currentTime, d: e.currentTarget.duration || 0 })} onLoadedMetadata={(e) => setTime({ t: 0, d: e.currentTarget.duration || 0 })}>\n {src.tracks?.map((t) => <track key={t.src} kind=\"captions\" src={t.src} srcLang={t.srcLang} label={t.label} />)}\n </video>\n ) : src.poster ? <img src={src.poster} alt=\"\" /> : null\n ) : role === \"in\" ? renderEmbed?.(src) : null}\n </div>\n );\n };\n const p = time.d ? Math.min(1, time.t / time.d) : 0;\n const hasCaptions = !!current?.tracks?.length;\n return (\n <div ref={region} role=\"region\" aria-label={title ?? current?.title} tabIndex={0} className=\"kz-rtv-playlist\" data-active={active ? \"true\" : undefined} onKeyDown={onKey} onPointerMove={wake} onPointerDown={wake} onFocus={wake} style={{ position: \"absolute\", inset: 0, \"--kz-rtv-p\": p } as React.CSSProperties}>\n {prev !== null && layer(prev, \"out\")}\n {layer(index, \"in\")}\n {prev !== null && transition === \"channel\" && <div className=\"kz-rtv-static\" aria-hidden=\"true\"><span className=\"kz-rtv-noise\" style={{ position: \"absolute\", inset: 0, background: \"repeating-linear-gradient(0deg,var(--kz-text-on-media) 0 1px,var(--kz-scrim-strong) 1px 3px)\" }} /></div>}\n <button type=\"button\" className=\"kz-rtv-chip\" aria-pressed={!muted} aria-label={muted ? labels.soundOff : labels.soundOn} onClick={() => setMuted(!muted)}><VolumeGlyph muted={muted} /></button>\n <div className=\"kz-rtv-progress\" aria-hidden=\"true\"><i /></div>\n <div className=\"kz-rtv-bar\">\n <button type=\"button\" aria-label={labels.previous} onClick={() => go(index - 1)} disabled={n < 2}>«</button>\n <button type=\"button\" aria-label={playing ? labels.pause : labels.play} onClick={toggle} disabled={!current?.src}>{playing ? <PauseGlyph /> : <PlayGlyph />}</button>\n <button type=\"button\" aria-label={labels.next} onClick={() => go(index + 1)} disabled={n < 2}>»</button>\n <span className=\"kz-rtv-time\">{formatClock(time.t)} / {formatClock(time.d)}</span>\n <input className=\"kz-rtv-seek\" type=\"range\" aria-label={labels.seek} min={0} max={Math.max(1, Math.floor(time.d))} value={Math.floor(time.t)} disabled={!time.d} onChange={(e) => { if (video.current) video.current.currentTime = Number(e.target.value); }} />\n {hasCaptions && <button type=\"button\" aria-label={labels.captions} aria-pressed={captionsOn} onClick={() => setCaptionsOn(!captionsOn)}><CaptionsGlyph /></button>}\n </div>\n <span className=\"sr-only\" aria-live=\"polite\">{labels.nowPlaying}: {current?.title} ({index + 1}/{n})</span>\n </div>\n );\n}\n\n/** A vertical video in a CSS-and-SVG television cabinet. */\nexport interface RetroTvProps extends Omit<VideoPlayerProps, \"aspectRatio\" | \"labels\" | \"autoPlay\" | \"className\" | \"loop\" | \"muted\" | \"preload\" | \"src\"> {\n /** The video's address. Optional when the screen shows `children`. */\n src?: VideoPlayerProps[\"src\"];\n /** What the screen shows instead of the video player: an `EmbedFacade` for a platform's short video. */\n children?: React.ReactNode;\n /** The cabinet style. */\n variant?: \"cabinet\" | \"portable\";\n /** A short channel label shown on the cabinet, for example `\"CH 3 · Plateau\"`. */\n channel?: string;\n /** Shows animated static instead of loading or playing the video. */\n off?: boolean;\n /** Starts muted and plays only while on screen; reduced motion waits for a gesture. Default `true`. */\n autoPlay?: boolean;\n /** Starts the player muted. Default `true`. */\n muted?: boolean;\n /** Plays the video again from the start when it ends. Default `true`. */\n loop?: boolean;\n /** How much to fetch before playback. Default `none` for lazy loading. */\n preload?: VideoPlayerProps[\"preload\"];\n /** Additional classes on the television frame. */\n className?: string;\n /** Programmes played in order, then again from the first. Replaces `src` and `children`. */\n playlist?: readonly RetroTvSource[];\n /** How one programme gives way to the next; a cut under reduced motion. Default `channel`. */\n transition?: RetroTvTransition;\n /** The host fills the screen of a source that has no `src` (an embed behind its own consent gate); the library loads no third-party script. */\n renderEmbed?: (source: RetroTvSource) => React.ReactNode;\n /** Told when the visitor turns the sound on or off, so the host can remember the choice. */\n onMutedChange?: (muted: boolean) => void;\n /** Told when another programme starts. */\n onIndexChange?: (index: number) => void;\n /** The controls' words; `retroTvLabelsFr` for French. */\n labels?: Partial<RetroTvLabels>;\n}\n\n/**\n * A vertical video presented in an old-school television; the existing player remains fully accessible.\n */\nexport function RetroTv({\n variant = \"cabinet\",\n channel,\n off = false,\n autoPlay = true,\n muted = true,\n loop = true,\n preload = \"none\",\n className,\n children,\n src,\n playlist,\n transition = \"channel\",\n renderEmbed,\n onMutedChange,\n onIndexChange,\n labels,\n ...playerProps\n}: RetroTvProps) {\n const [index, setIndex] = React.useState(0);\n const [mutedState, setMutedState] = React.useState(muted);\n const root = React.useRef<HTMLDivElement>(null);\n const [powered, setPowered] = React.useState(false);\n const reducedMotion = usePrefersReducedMotion();\n const uid = React.useId().replace(/[^a-zA-Z0-9_-]/g, \"\");\n const noiseId = `${uid}-noise`;\n const glassId = `${uid}-glass`;\n const shineId = `${uid}-shine`;\n\n useInView(root, setPowered);\n const player = src ? <VideoPlayer {...playerProps} src={src} className=\"kz-rtv-player\" aspectRatio=\"9 / 16\" autoPlay={autoPlay} muted={muted} loop={loop} preload={preload} /> : null;\n const knob = { channel: index * 50, sound: mutedState ? -50 : 50 };\n const screen = playlist?.length ? (\n <PlaylistScreen playlist={playlist} transition={transition} labels={{ ...retroTvLabels, ...labels }} muted={mutedState} autoPlay={autoPlay} renderEmbed={renderEmbed} onMutedChange={onMutedChange} onIndexChange={onIndexChange} title={playerProps.title} reduced={reducedMotion} setMutedState={setMutedState} setIndex={setIndex} index={index} />\n ) : children ?? player;\n\n return (\n <div ref={root} className={[\"kz-rtv\", className].filter(Boolean).join(\" \")} data-variant={variant} data-powered={powered && !reducedMotion ? \"true\" : undefined} data-off={off ? \"true\" : undefined}>\n <style>{styles}</style>\n <div className=\"kz-rtv-frame\">\n <div className=\"kz-rtv-cabinet\" aria-hidden=\"true\">\n <div className=\"kz-rtv-body\">\n <div className=\"kz-rtv-bezel\" />\n <div className=\"kz-rtv-controls\">\n <span className=\"kz-rtv-knob\" data-hue=\"accent\" style={{ \"--kz-rtv-angle\": `${knob.channel}deg` } as React.CSSProperties} />\n <span className=\"kz-rtv-knob\" data-hue=\"accent\" style={{ \"--kz-rtv-angle\": `${knob.sound}deg` } as React.CSSProperties} />\n </div>\n <div className=\"kz-rtv-speaker\">{Array.from({ length: 7 }, (_, index) => <i key={index} />)}</div>\n </div>\n <div className=\"kz-rtv-stand\" />\n </div>\n {channel && <span className=\"kz-rtv-channel\">{channel}</span>}\n <div className=\"kz-rtv-screen\">\n {off ? (\n <svg className=\"kz-rtv-noise\" viewBox=\"0 0 100 100\" preserveAspectRatio=\"none\" aria-hidden=\"true\">\n <filter id={noiseId}><feTurbulence type=\"fractalNoise\" baseFrequency=\".85\" numOctaves=\"2\" stitchTiles=\"stitch\" /><feColorMatrix type=\"saturate\" values=\"0\" /></filter>\n <rect width=\"100%\" height=\"100%\" filter={`url(#${noiseId})`} />\n </svg>\n ) : (\n screen\n )}\n <div className=\"kz-rtv-effects\" aria-hidden=\"true\">\n <svg className=\"kz-rtv-glass\" viewBox=\"0 0 100 100\" preserveAspectRatio=\"none\">\n <defs>\n <radialGradient id={shineId} cx=\"50%\" cy=\"42%\" r=\"68%\">\n <stop offset=\"0\" stopColor=\"var(--kz-surface-sheen)\" stopOpacity=\".12\" />\n <stop offset=\"1\" stopColor=\"var(--kz-scrim-strong)\" stopOpacity=\".2\" />\n </radialGradient>\n <filter id={glassId}>\n <feTurbulence baseFrequency=\".01 .04\" numOctaves=\"1\" seed=\"2\" result=\"curve\" />\n <feDisplacementMap in=\"SourceGraphic\" in2=\"curve\" scale=\"1.2\" xChannelSelector=\"R\" yChannelSelector=\"G\" />\n </filter>\n </defs>\n <rect width=\"100\" height=\"100\" fill={`url(#${shineId})`} filter={`url(#${glassId})`} />\n </svg>\n <span className=\"kz-rtv-glow\" />\n <span className=\"kz-rtv-power\" />\n </div>\n </div>\n {off && <span className=\"sr-only\">{playerProps.title}</span>}\n </div>\n </div>\n );\n}\n"
|
|
383
|
+
"content": "\"use client\";\n\nimport * as React from \"react\";\n\nimport { useInView, usePrefersReducedMotion } from \"../media\";\nimport { VideoPlayer, type VideoPlayerProps } from \"../video-player/video-player\";\n\n/**\n * The playlist (transitions, bar, seek, captions, sound chip) is its own chunk, loaded only when a `playlist` is given: the\n * single clip (a shop's video, an embed) never downloads it.\n */\nconst PlaylistScreen = React.lazy(() => import(\"./playlist-screen\").then((m) => ({ default: m.PlaylistScreen })));\n\nconst styles = `\n.kz-rtv{container-type:inline-size;width:100%;max-width:100%;color:var(--kz-text-primary)}\n.kz-rtv-frame{position:relative;isolation:isolate;width:100%;aspect-ratio:4/5}\n@container (min-width:44rem){.kz-rtv-frame{aspect-ratio:16/10}.kz-rtv-bezel{width:72%}.kz-rtv-screen{width:66%}.kz-rtv-controls{width:18%;right:5%}.kz-rtv-speaker{width:18%;right:5%}}\n.kz-rtv-cabinet{position:absolute;inset:0;overflow:hidden}\n.kz-rtv-body{position:absolute;inset:4% 4% 16%;border:1px solid var(--kz-border-strong);border-radius:8% / 6%;background:linear-gradient(145deg,var(--kz-surface-sheen),transparent 35%),linear-gradient(145deg,color-mix(in srgb,var(--kz-warning) 18%,var(--kz-surface-3)),color-mix(in srgb,var(--kz-warning-text) 10%,var(--kz-surface-2)) 48%,var(--kz-surface-1));box-shadow:inset 0 1px 0 var(--kz-surface-sheen),inset 0 -3px 6px color-mix(in srgb,var(--kz-scrim-strong) 30%,transparent),0 1.2rem 2rem color-mix(in srgb,var(--kz-scrim-strong) 24%,transparent)}\n.kz-rtv[data-variant=portable] .kz-rtv-body{border-radius:12% / 8%;background:linear-gradient(145deg,var(--kz-surface-1),var(--kz-surface-2) 55%,var(--kz-surface-3))}\n.kz-rtv-body:after{position:absolute;inset:0;border-radius:inherit;background:repeating-linear-gradient(115deg,transparent 0 7px,color-mix(in srgb,var(--kz-border-subtle) 35%,transparent) 8px 9px);content:\"\";opacity:.4;pointer-events:none}\n.kz-rtv-bezel{position:absolute;top:0;bottom:0;left:6%;width:61%;border:1px solid var(--kz-border-strong);border-radius:14% / 7%;background:linear-gradient(145deg,var(--kz-surface-1),var(--kz-surface-3));box-shadow:inset 0 2px 5px color-mix(in srgb,var(--kz-scrim-strong) 35%,transparent),0 1px 2px color-mix(in srgb,var(--kz-surface-sheen) 60%,transparent)}\n.kz-rtv[data-variant=portable] .kz-rtv-bezel{border-radius:19% / 9%;background:linear-gradient(145deg,var(--kz-surface-0),var(--kz-surface-2))}\n.kz-rtv-controls{position:absolute;top:16%;right:7%;display:flex;width:23%;flex-direction:column;align-items:center;gap:1.1rem}\n.kz-rtv-knob{position:relative;display:block;width:2.3rem;max-width:70%;aspect-ratio:1;border:2px solid var(--kz-border-strong);border-radius:50%;background:radial-gradient(circle at 35% 28%,var(--kz-surface-sheen),transparent 30%),linear-gradient(145deg,var(--kz-surface-1),var(--kz-surface-3));box-shadow:inset 0 -2px 3px color-mix(in srgb,var(--kz-scrim-strong) 35%,transparent),0 2px 4px color-mix(in srgb,var(--kz-scrim-strong) 25%,transparent);color:var(--kz-accent)}\n.kz-rtv-knob[data-hue=accent]{background:radial-gradient(circle at 35% 28%,var(--kz-surface-sheen),transparent 30%),linear-gradient(145deg,var(--kz-accent-text),var(--kz-accent))}\n.kz-rtv-knob{transform:rotate(var(--kz-rtv-angle,0deg));transition:transform .4s cubic-bezier(.3,1.4,.5,1)}\n.kz-rtv-knob:before{position:absolute;inset:-.35rem;border-radius:50%;background:repeating-conic-gradient(from -135deg,var(--kz-border-strong) 0 2deg,transparent 2deg 27deg);content:\"\";-webkit-mask:radial-gradient(circle,transparent 62%,#000 64%);mask:radial-gradient(circle,transparent 62%,#000 64%);transform:rotate(calc(var(--kz-rtv-angle,0deg)*-1))}\n.kz-rtv-knob:after{position:absolute;top:14%;left:calc(50% - 1px);width:2px;height:27%;border-radius:2px;background:var(--kz-on-accent);content:\"\"}\n.kz-rtv[data-variant=portable] .kz-rtv-knob{width:1.9rem}\n.kz-rtv-speaker{position:absolute;right:7%;bottom:9%;display:flex;width:23%;flex-direction:column;gap:3px}\n.kz-rtv-speaker i{height:2px;border-radius:2px;background:var(--kz-border-strong);box-shadow:0 1px 0 var(--kz-surface-sheen)}\n.kz-rtv[data-variant=portable] .kz-rtv-speaker{display:none}\n.kz-rtv-stand{position:absolute;bottom:4%;left:36%;width:28%;height:12%;border-bottom:1px solid var(--kz-border-strong);border-radius:0 0 30% 30%;background:linear-gradient(180deg,var(--kz-surface-2),var(--kz-surface-3));clip-path:polygon(25% 0,75% 0,88% 78%,100% 100%,0 100%,12% 78%)}\n.kz-rtv[data-variant=portable] .kz-rtv-stand{left:40%;width:20%;height:8%;border-radius:50%;clip-path:ellipse(50% 50% at 50% 50%)}\n.kz-rtv-screen{position:absolute;top:4%;left:9.5%;width:56%;height:80%;overflow:hidden;border:2px solid color-mix(in srgb,var(--kz-border-strong) 72%,var(--kz-accent));border-radius:13% / 7%;background:var(--kz-scrim-strong);box-shadow:0 0 1.1rem color-mix(in srgb,var(--kz-accent) 30%,transparent),inset 0 0 1.2rem var(--kz-scrim-strong)}\n.kz-rtv[data-variant=portable] .kz-rtv-screen{border-radius:18% / 9%}\n.kz-rtv-screen .kz-rtv-player{height:100%;width:100%;border-radius:inherit}\n.kz-rtv-screen .kz-embed{height:100%;width:100%;aspect-ratio:auto;border-radius:inherit}\n.kz-rtv-player video,.kz-rtv-player img{object-fit:cover}\n.kz-rtv-effects{position:absolute;z-index:5;inset:0;overflow:hidden;border-radius:inherit;pointer-events:none}\n.kz-rtv-effects:before{position:absolute;inset:0;background:repeating-linear-gradient(to bottom,transparent 0 3px,color-mix(in srgb,var(--kz-scrim-strong) 25%,transparent) 4px 5px);content:\"\";opacity:.46}\n.kz-rtv-effects:after{position:absolute;inset:-1px;background:radial-gradient(ellipse at center,transparent 55%,var(--kz-scrim-strong) 100%);content:\"\";opacity:.52}\n.kz-rtv-glow{position:absolute;inset:0;background:radial-gradient(ellipse at 50% 45%,color-mix(in srgb,var(--kz-accent) 14%,transparent),transparent 68%);opacity:.7}\n.kz-rtv-noise{position:absolute;inset:0;height:100%;width:100%;opacity:.55;filter:contrast(1.3) brightness(.85)}\n.kz-rtv-glass{position:absolute;inset:0;height:100%;width:100%;opacity:.28}\n.kz-rtv-power{position:absolute;inset:0;background:var(--kz-text-on-media);opacity:0;transform:scaleY(.01);transform-origin:center;pointer-events:none}\n.kz-rtv[data-powered=true] .kz-rtv-power{animation:kz-rtv-power .65s ease-out both}\n.kz-rtv-channel{position:absolute;z-index:7;top:8%;right:5%;width:24%;overflow:hidden;padding:.25em .4em;border:1px solid var(--kz-border-strong);border-radius:3px;background:var(--kz-surface-1);box-shadow:inset 0 1px 0 var(--kz-surface-sheen);color:var(--kz-text-primary);font:700 clamp(.5rem,1.4cqw,.7rem)/1.2 var(--kz-font-mono,monospace);letter-spacing:.12em;text-transform:uppercase;text-align:center;text-overflow:ellipsis;white-space:nowrap}\n.kz-rtv[data-variant=portable] .kz-rtv-channel{top:7%}\n.kz-rtv:focus-within .kz-rtv-screen{outline:2px solid var(--kz-ring);outline-offset:3px}\n@keyframes kz-rtv-power{0%{opacity:1;transform:scaleY(.01)}45%{opacity:.9;transform:scaleY(1)}100%{opacity:0;transform:scaleY(1)}}\n@keyframes kz-rtv-noise{0%,100%{opacity:.38}50%{opacity:.62}}\n@media (prefers-reduced-motion:no-preference){.kz-rtv[data-off=true] .kz-rtv-noise{animation:kz-rtv-noise .18s steps(2,end) infinite}}\n@media (prefers-reduced-motion:reduce){.kz-rtv-power{display:none!important}.kz-rtv-noise{animation:none!important}}\n\n`;\n\n\n/** One programme of the playlist: an uploaded video (`src`) or, without `src`, a slot the host fills with `renderEmbed`. */\nexport interface RetroTvSource {\n id: string;\n title: string;\n src?: string;\n poster?: string;\n /** WebVTT captions of this video. */\n tracks?: VideoPlayerProps[\"tracks\"];\n}\nexport type RetroTvTransition = \"channel\" | \"crossfade\" | \"slide\";\nexport interface RetroTvLabels { play: string; pause: string; next: string; previous: string; soundOff: string; soundOn: string; captions: string; seek: string; nowPlaying: string }\nexport const retroTvLabels: RetroTvLabels = { play: \"Play\", pause: \"Pause\", next: \"Next video\", previous: \"Previous video\", soundOff: \"Sound off: turn on\", soundOn: \"Sound on: turn off\", captions: \"Captions\", seek: \"Seek\", nowPlaying: \"Now playing\" };\nexport const retroTvLabelsFr: RetroTvLabels = { play: \"Lecture\", pause: \"Pause\", next: \"Vidéo suivante\", previous: \"Vidéo précédente\", soundOff: \"Son coupé : activer\", soundOn: \"Son activé : couper\", captions: \"Sous-titres\", seek: \"Position\", nowPlaying: \"En cours\" };\n\n/** A vertical video in a CSS-and-SVG television cabinet. */\nexport interface RetroTvProps extends Omit<VideoPlayerProps, \"aspectRatio\" | \"labels\" | \"autoPlay\" | \"className\" | \"loop\" | \"muted\" | \"preload\" | \"src\"> {\n /** The video's address. Optional when the screen shows `children`. */\n src?: VideoPlayerProps[\"src\"];\n /** What the screen shows instead of the video player: an `EmbedFacade` for a platform's short video. */\n children?: React.ReactNode;\n /** The cabinet style. */\n variant?: \"cabinet\" | \"portable\";\n /** A short channel label shown on the cabinet, for example `\"CH 3 · Plateau\"`. */\n channel?: string;\n /** Shows animated static instead of loading or playing the video. */\n off?: boolean;\n /** Starts muted and plays only while on screen; reduced motion waits for a gesture. Default `true`. */\n autoPlay?: boolean;\n /** Starts the player muted. Default `true`. */\n muted?: boolean;\n /** Plays the video again from the start when it ends. Default `true`. */\n loop?: boolean;\n /** How much to fetch before playback. Default `none` for lazy loading. */\n preload?: VideoPlayerProps[\"preload\"];\n /** Additional classes on the television frame. */\n className?: string;\n /** Programmes played in order, then again from the first. Replaces `src` and `children`. */\n playlist?: readonly RetroTvSource[];\n /** How one programme gives way to the next; a cut under reduced motion. Default `channel`. */\n transition?: RetroTvTransition;\n /** The host fills the screen of a source that has no `src` (an embed behind its own consent gate); the library loads no third-party script. */\n renderEmbed?: (source: RetroTvSource) => React.ReactNode;\n /** Told when the visitor turns the sound on or off, so the host can remember the choice. */\n onMutedChange?: (muted: boolean) => void;\n /** Told when another programme starts. */\n onIndexChange?: (index: number) => void;\n /** The controls' words; `retroTvLabelsFr` for French. */\n labels?: Partial<RetroTvLabels>;\n}\n\n/**\n * A vertical video presented in an old-school television; the existing player remains fully accessible.\n */\nexport function RetroTv({\n variant = \"cabinet\",\n channel,\n off = false,\n autoPlay = true,\n muted = true,\n loop = true,\n preload = \"none\",\n className,\n children,\n src,\n playlist,\n transition = \"channel\",\n renderEmbed,\n onMutedChange,\n onIndexChange,\n labels,\n ...playerProps\n}: RetroTvProps) {\n const [index, setIndex] = React.useState(0);\n const [mutedState, setMutedState] = React.useState(muted);\n const root = React.useRef<HTMLDivElement>(null);\n const [powered, setPowered] = React.useState(false);\n const reducedMotion = usePrefersReducedMotion();\n const uid = React.useId().replace(/[^a-zA-Z0-9_-]/g, \"\");\n const noiseId = `${uid}-noise`;\n const glassId = `${uid}-glass`;\n const shineId = `${uid}-shine`;\n\n useInView(root, setPowered);\n const player = src ? <VideoPlayer {...playerProps} src={src} className=\"kz-rtv-player\" aspectRatio=\"9 / 16\" autoPlay={autoPlay} muted={muted} loop={loop} preload={preload} /> : null;\n const knob = { channel: index * 50, sound: mutedState ? -50 : 50 };\n const screen = playlist?.length ? (\n <React.Suspense fallback={null}><PlaylistScreen playlist={playlist} transition={transition} labels={{ ...retroTvLabels, ...labels }} muted={mutedState} autoPlay={autoPlay} renderEmbed={renderEmbed} onMutedChange={onMutedChange} onIndexChange={onIndexChange} title={playerProps.title} reduced={reducedMotion} setMutedState={setMutedState} setIndex={setIndex} index={index} /></React.Suspense>\n ) : children ?? player;\n\n return (\n <div ref={root} className={[\"kz-rtv\", className].filter(Boolean).join(\" \")} data-variant={variant} data-powered={powered && !reducedMotion ? \"true\" : undefined} data-off={off ? \"true\" : undefined}>\n <style>{styles}</style>\n <div className=\"kz-rtv-frame\">\n <div className=\"kz-rtv-cabinet\" aria-hidden=\"true\">\n <div className=\"kz-rtv-body\">\n <div className=\"kz-rtv-bezel\" />\n <div className=\"kz-rtv-controls\">\n <span className=\"kz-rtv-knob\" data-hue=\"accent\" style={{ \"--kz-rtv-angle\": `${knob.channel}deg` } as React.CSSProperties} />\n <span className=\"kz-rtv-knob\" data-hue=\"accent\" style={{ \"--kz-rtv-angle\": `${knob.sound}deg` } as React.CSSProperties} />\n </div>\n <div className=\"kz-rtv-speaker\">{Array.from({ length: 7 }, (_, index) => <i key={index} />)}</div>\n </div>\n <div className=\"kz-rtv-stand\" />\n </div>\n {channel && <span className=\"kz-rtv-channel\">{channel}</span>}\n <div className=\"kz-rtv-screen\">\n {off ? (\n <svg className=\"kz-rtv-noise\" viewBox=\"0 0 100 100\" preserveAspectRatio=\"none\" aria-hidden=\"true\">\n <filter id={noiseId}><feTurbulence type=\"fractalNoise\" baseFrequency=\".85\" numOctaves=\"2\" stitchTiles=\"stitch\" /><feColorMatrix type=\"saturate\" values=\"0\" /></filter>\n <rect width=\"100%\" height=\"100%\" filter={`url(#${noiseId})`} />\n </svg>\n ) : (\n screen\n )}\n <div className=\"kz-rtv-effects\" aria-hidden=\"true\">\n <svg className=\"kz-rtv-glass\" viewBox=\"0 0 100 100\" preserveAspectRatio=\"none\">\n <defs>\n <radialGradient id={shineId} cx=\"50%\" cy=\"42%\" r=\"68%\">\n <stop offset=\"0\" stopColor=\"var(--kz-surface-sheen)\" stopOpacity=\".12\" />\n <stop offset=\"1\" stopColor=\"var(--kz-scrim-strong)\" stopOpacity=\".2\" />\n </radialGradient>\n <filter id={glassId}>\n <feTurbulence baseFrequency=\".01 .04\" numOctaves=\"1\" seed=\"2\" result=\"curve\" />\n <feDisplacementMap in=\"SourceGraphic\" in2=\"curve\" scale=\"1.2\" xChannelSelector=\"R\" yChannelSelector=\"G\" />\n </filter>\n </defs>\n <rect width=\"100\" height=\"100\" fill={`url(#${shineId})`} filter={`url(#${glassId})`} />\n </svg>\n <span className=\"kz-rtv-glow\" />\n <span className=\"kz-rtv-power\" />\n </div>\n </div>\n {off && <span className=\"sr-only\">{playerProps.title}</span>}\n </div>\n </div>\n );\n}\n"
|
|
378
384
|
}
|
|
379
385
|
],
|
|
380
386
|
"dependencies": [],
|
package/registry/reviews.json
CHANGED
|
@@ -7,6 +7,8 @@
|
|
|
7
7
|
"status": "beta",
|
|
8
8
|
"deprecated": null,
|
|
9
9
|
"category": "blocks",
|
|
10
|
+
"domain": "commerce",
|
|
11
|
+
"adoption": null,
|
|
10
12
|
"platforms": "web",
|
|
11
13
|
"parity": {
|
|
12
14
|
"web": {
|
|
@@ -207,7 +209,7 @@
|
|
|
207
209
|
"files": [
|
|
208
210
|
{
|
|
209
211
|
"path": "meta.ts",
|
|
210
|
-
"content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n | \"notification-preferences\"\n | \"quota-meter\"\n | \"environment-notice\"\n | \"embed-facade\"\n | \"reviews\"\n | \"margin-layout\"\n | \"analysis-report\"\n | \"status-chip\"\n | \"kind-config-editor\"\n | \"agenda\"\n | \"account-settings\"\n | \"drop-overlay\"\n | \"upload-queue\"\n | \"achievement\"\n | \"anatomy-plate\"\n | \"bird-plate\"\n | \"taped-photo\"\n | \"stuck\"\n | \"doodle\"\n | \"signature\"\n | \"grade-stamp\"\n | \"versus-card\"\n | \"speed-lines\"\n | \"site-cahier\"\n | \"text-style\"\n | \"flock\"\n | \"elephant\"\n | \"footnote\"\n | \"page-index\"\n | \"chapter\"\n | \"specimen-tag\"\n | \"action-bar\"\n | \"action-sheet\"\n | \"activity-feed\"\n | \"alert\"\n | \"app-frame\"\n | \"desktop-window\"\n | \"form-flow\"\n | \"grid\"\n | \"list-detail\"\n | \"state-screen\"\n | \"app-header\"\n | \"app-shell\"\n | \"argument-card\"\n | \"audio-player\"\n | \"auth-layout\"\n | \"avatar\"\n | \"badge\"\n | \"button\"\n | \"captcha\"\n | \"card\"\n | \"card-grid\"\n | \"catalogue-page\"\n | \"changelog-page\"\n | \"chat\"\n | \"checkbox\"\n | \"chip\"\n | \"chip-link\"\n | \"chip-row\"\n | \"choice-grid\"\n | \"cn\"\n | \"code-block\"\n | \"combobox\"\n | \"comparison-table\"\n | \"command\"\n | \"component-page\"\n | \"confirm-button\"\n | \"copy-button\"\n | \"money-input\"\n | \"price-catalogue-editor\"\n | \"promo-code-field\"\n | \"contact-page\"\n | \"continue-prompt\"\n | \"countdown\"\n | \"cover-hero\"\n | \"cta-panel\"\n | \"dashboard-layout\"\n | \"data-table\"\n | \"date-picker\"\n | \"decision-list\"\n | \"description-list\"\n | \"detail-layout\"\n | \"dialog\"\n | \"docs-article-page\"\n | \"docs-hub-page\"\n | \"docs-layout\"\n | \"docs-nav\"\n | \"document-viewer\"\n | \"dropdown-menu\"\n | \"empty-state\"\n | \"engine-flow\"\n | \"error-page\"\n | \"fab\"\n | \"field\"\n | \"file-upload\"\n | \"filter-bar\"\n | \"force-update-screen\"\n | \"form\"\n | \"gallery-page\"\n | \"genui\"\n | \"glossary\"\n | \"glossary-term\"\n | \"glow-card\"\n | \"goal-gauge\"\n | \"header\"\n | \"how-it-works-page\"\n | \"image-cropper\"\n | \"image-viewer\"\n | \"iso\"\n | \"kanban\"\n | \"kbd\"\n | \"kpi-explained\"\n | \"landing-page\"\n | \"landscape\"\n | \"legal-page\"\n | \"link-card\"\n | \"list\"\n | \"loader\"\n | \"longform-page\"\n | \"maintenance-screen\"\n | \"map\"\n | \"markdown\"\n | \"meta-row\"\n | \"waveform\"\n | \"proposal\"\n | \"qr-code\"\n | \"entity-header\"\n | \"collection-switcher\"\n | \"marketing-layout\"\n | \"marquee\"\n | \"mascot-quote\"\n | \"mascot-state\"\n | \"mascots\"\n | \"match-dialog\"\n | \"media-capture\"\n | \"media-grid\"\n | \"language-switch\"\n | \"media-gallery\"\n | \"media-picker\"\n | \"meter\"\n | \"nav-bar\"\n | \"number-ticker\"\n | \"onboarding\"\n | \"opening-hours\"\n | \"otp-input\"\n | \"page\"\n | \"page-header\"\n | \"page-hero\"\n | \"pagination\"\n | \"permission-prompt\"\n | \"photo-grid\"\n | \"pointer-light\"\n | \"popover\"\n | \"pricing-page\"\n | \"product-page\"\n | \"profile-card\"\n | \"progress\"\n | \"promise-card\"\n | \"pull-to-refresh\"\n | \"retro-tv\"\n | \"shop-gallery\"\n | \"radio-group\"\n | \"router\"\n | \"rail-nav\"\n | \"recipes\"\n | \"screen\"\n | \"scroll-stage\"\n | \"search-field\"\n | \"section-backdrop\"\n | \"segmented\"\n | \"separator\"\n | \"service-card\"\n | \"shop\"\n | \"shop-composer\"\n | \"schema-form\"\n | \"settings-layout\"\n | \"account-menu\"\n | \"showcase\"\n | \"step-showcase\"\n | \"site-footer\"\n | \"sites\"\n | \"skeleton\"\n | \"skip-link\"\n | \"slider\"\n | \"slot-picker\"\n | \"slot\"\n | \"spinner\"\n | \"sticky-action\"\n | \"splash-handoff\"\n | \"split-view\"\n | \"stage-banner\"\n | \"stat\"\n | \"usage\"\n | \"status-page\"\n | \"step-progress\"\n | \"stepper\"\n | \"swipe-deck\"\n | \"swipeable-row\"\n | \"switch\"\n | \"tab-bar\"\n | \"tabs\"\n | \"tag-input\"\n | \"tag-selector\"\n | \"terminal-replay\"\n | \"theme\"\n | \"toast\"\n | \"toc\"\n | \"tooltip\"\n | \"tree-view\"\n | \"txt\"\n | \"update-prompt\"\n | \"verified-badge\"\n | \"vertical-video\"\n | \"video-player\"\n | \"video-trimmer\"\n | \"virtual\"\n | \"wall\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/**\n * Why a component is not on a platform — a decision, never a silence (the parity matrix of ui.krizaka.com/platforms):\n * - `gap` (✗): it belongs there and is not built yet; `issue` is the issue that tracks it (`krizaka/krizaka-ui#275`);\n * - `n/a`: it is not meant for that platform (a site's page block on a phone, a swipe on a desktop); `use` names the\n * component that answers there, when one does.\n */\nexport type Absence =\n | { readonly status: \"gap\"; readonly issue: string; readonly reason: string; readonly use?: undefined }\n | { readonly status: \"n/a\"; readonly reason: string; readonly use?: ComponentName; readonly issue?: undefined };\n\n/**\n * Desktop is the Orazaka Mac app (Tauri 2: the system WebView renders the web components — ADR-002). `web`: the web\n * component runs there as it is; `desktop`: it also has a desktop form (a window's title bar, a denser layout…), said in\n * its documentation; otherwise the absence and why.\n */\nexport type DesktopSupport = \"web\" | \"desktop\" | Absence;\n\n/**\n * The three platforms of Krizaka UI — web · native (React Native, Expo) · desktop — for one component. The side a\n * component has is `platforms`; the side it lacks says why here: `native` is required for (and only for) a web-only\n * component, `web` for a native-only one; `desktop` always. `scripts/registry.test.mjs` fails on a missing decision.\n */\nexport interface Parity {\n readonly web?: Absence;\n readonly native?: Absence;\n readonly desktop: DesktopSupport;\n}\n\n/**\n * `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"stable\" | \"beta\" | \"deprecated\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n /** The version that deprecated it (`3.6.0`). */\n readonly since: string;\n /** The major that removes it (`4.0.0`). */\n readonly removedIn: string;\n /** What replaces it, when a component does. */\n readonly use?: ComponentName;\n /** Why it goes: no product uses it, no planned work needs it. */\n readonly reason: string;\n}\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\ninterface ExampleBase {\n /** The file name, kebab-case (`primary`, `icon-button`). */\n readonly name: string;\n /** A short title (`Primary`, `Icon button`). */\n readonly title: string;\n /** One or two sentences: when this variant is the right one. */\n readonly description: string;\n}\n\n/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n | (ExampleBase & {\n /**\n * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n */\n readonly template: true;\n /** The intent that groups it: why you need this block. */\n readonly purpose: TemplatePurpose;\n /** Why this layout: the user goal it serves, in one sentence. */\n readonly why: string;\n });\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n readonly imports: readonly string[];\n /** The examples, in reading order; the first one is the component's preview. */\n readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n /**\n * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n */\n readonly entry?: string;\n /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n readonly differences: readonly string[];\n /** The React Native entry alone is deprecated while the web one stays (ADR-006 §7); a deprecated component says it once, above. */\n readonly deprecated?: Deprecation;\n}\n\nexport interface KeyboardInteraction {\n /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n readonly keys: string;\n /** What they do. */\n readonly action: string;\n}\n\nexport interface ComponentMeta {\n /** The display name: `Button`, `Dropdown menu`. */\n readonly title: string;\n /** One sentence: what it is. */\n readonly summary: string;\n readonly status: Status;\n /** Required for, and only for, a `deprecated` component. */\n readonly deprecated?: Deprecation;\n readonly category: Category;\n /** Must match the sides below: `both` ⇔ `web` and `native`. */\n readonly platforms: Platform;\n /** The platforms it is not on, and why; and its desktop form (see `Parity`). */\n readonly parity: Parity;\n /** When to reach for it: concrete situations, one per item. */\n readonly whenToUse: readonly string[];\n /** When not to — and what to use instead (`use`), when another component is the answer. */\n readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n /** How to use it well: wording, placement, composition. */\n readonly bestPractices: readonly string[];\n readonly accessibility: {\n /** The keyboard, when it does more than Tab and Enter. */\n readonly keyboard: readonly KeyboardInteraction[];\n /** Roles, names and announcements: what the component does, what the app must provide. */\n readonly notes: readonly string[];\n };\n /** The components a reader of this page should know about. */\n readonly related: readonly ComponentName[];\n readonly web?: PlatformDocs;\n readonly native?: NativeDocs;\n}\n"
|
|
212
|
+
"content": "// The documentation of a component, carried by its code: each primitive has a `meta.ts` beside its source\n// (`src/<name>/meta.ts`; a component that exists only in React Native: `src/native/meta/<name>.ts`). Never built into\n// the package: `scripts/build-registry.mjs` reads them into `registry/<name>.json`, which ui.krizaka.com (apps/site) renders as\n// ui.krizaka.com/components/<name>, and `scripts/registry.test.mjs` fails when one is missing or incomplete.\n//\n// Why a typed module and not JSDoc tags: the fields are lists and links (`related`, `whenNotToUse[].use`, examples),\n// which a type checks and a comment does not; the file is plain data (erasable TypeScript), so Node reads it without a\n// compiler, and an editor completes it.\n\n/** Every documented component: the web primitives (one entry of the package each) and the native-only ones. */\nexport type ComponentName =\n | \"notification-preferences\"\n | \"quota-meter\"\n | \"environment-notice\"\n | \"embed-facade\"\n | \"reviews\"\n | \"margin-layout\"\n | \"analysis-report\"\n | \"status-chip\"\n | \"kind-config-editor\"\n | \"agenda\"\n | \"account-settings\"\n | \"drop-overlay\"\n | \"upload-queue\"\n | \"achievement\"\n | \"anatomy-plate\"\n | \"bird-plate\"\n | \"taped-photo\"\n | \"stuck\"\n | \"doodle\"\n | \"signature\"\n | \"grade-stamp\"\n | \"versus-card\"\n | \"speed-lines\"\n | \"site-cahier\"\n | \"text-style\"\n | \"flock\"\n | \"elephant\"\n | \"footnote\"\n | \"page-index\"\n | \"chapter\"\n | \"specimen-tag\"\n | \"action-bar\"\n | \"action-sheet\"\n | \"activity-feed\"\n | \"alert\"\n | \"app-frame\"\n | \"desktop-window\"\n | \"form-flow\"\n | \"grid\"\n | \"list-detail\"\n | \"state-screen\"\n | \"app-header\"\n | \"app-shell\"\n | \"argument-card\"\n | \"audio-player\"\n | \"auth-layout\"\n | \"avatar\"\n | \"badge\"\n | \"button\"\n | \"captcha\"\n | \"card\"\n | \"card-grid\"\n | \"catalogue-page\"\n | \"changelog-page\"\n | \"chat\"\n | \"checkbox\"\n | \"chip\"\n | \"chip-link\"\n | \"chip-row\"\n | \"choice-grid\"\n | \"cn\"\n | \"code-block\"\n | \"combobox\"\n | \"comparison-table\"\n | \"command\"\n | \"component-page\"\n | \"confirm-button\"\n | \"copy-button\"\n | \"money-input\"\n | \"price-catalogue-editor\"\n | \"promo-code-field\"\n | \"contact-page\"\n | \"continue-prompt\"\n | \"countdown\"\n | \"cover-hero\"\n | \"cta-panel\"\n | \"dashboard-layout\"\n | \"data-table\"\n | \"date-picker\"\n | \"decision-list\"\n | \"description-list\"\n | \"detail-layout\"\n | \"dialog\"\n | \"docs-article-page\"\n | \"docs-hub-page\"\n | \"docs-layout\"\n | \"docs-nav\"\n | \"document-viewer\"\n | \"dropdown-menu\"\n | \"empty-state\"\n | \"engine-flow\"\n | \"error-page\"\n | \"fab\"\n | \"field\"\n | \"file-upload\"\n | \"filter-bar\"\n | \"force-update-screen\"\n | \"form\"\n | \"gallery-page\"\n | \"genui\"\n | \"glossary\"\n | \"glossary-term\"\n | \"glow-card\"\n | \"goal-gauge\"\n | \"header\"\n | \"how-it-works-page\"\n | \"image-cropper\"\n | \"image-viewer\"\n | \"iso\"\n | \"kanban\"\n | \"kbd\"\n | \"kpi-explained\"\n | \"landing-page\"\n | \"landscape\"\n | \"legal-page\"\n | \"link-card\"\n | \"list\"\n | \"loader\"\n | \"longform-page\"\n | \"maintenance-screen\"\n | \"map\"\n | \"markdown\"\n | \"meta-row\"\n | \"waveform\"\n | \"proposal\"\n | \"qr-code\"\n | \"entity-header\"\n | \"collection-switcher\"\n | \"marketing-layout\"\n | \"marquee\"\n | \"mascot-quote\"\n | \"mascot-state\"\n | \"mascots\"\n | \"match-dialog\"\n | \"media-capture\"\n | \"media-grid\"\n | \"language-switch\"\n | \"media-gallery\"\n | \"media-picker\"\n | \"meter\"\n | \"nav-bar\"\n | \"number-ticker\"\n | \"onboarding\"\n | \"opening-hours\"\n | \"otp-input\"\n | \"page\"\n | \"page-header\"\n | \"page-hero\"\n | \"pagination\"\n | \"permission-prompt\"\n | \"photo-grid\"\n | \"pointer-light\"\n | \"popover\"\n | \"pricing-page\"\n | \"product-page\"\n | \"profile-card\"\n | \"progress\"\n | \"promise-card\"\n | \"pull-to-refresh\"\n | \"retro-tv\"\n | \"shop-gallery\"\n | \"radio-group\"\n | \"router\"\n | \"rail-nav\"\n | \"recipes\"\n | \"screen\"\n | \"scroll-stage\"\n | \"search-field\"\n | \"section-backdrop\"\n | \"segmented\"\n | \"separator\"\n | \"service-card\"\n | \"shop\"\n | \"shop-composer\"\n | \"schema-form\"\n | \"settings-layout\"\n | \"account-menu\"\n | \"showcase\"\n | \"step-showcase\"\n | \"site-footer\"\n | \"sites\"\n | \"skeleton\"\n | \"skip-link\"\n | \"slider\"\n | \"slot-picker\"\n | \"slot\"\n | \"spinner\"\n | \"sticky-action\"\n | \"splash-handoff\"\n | \"split-view\"\n | \"stage-banner\"\n | \"stat\"\n | \"usage\"\n | \"status-page\"\n | \"step-progress\"\n | \"stepper\"\n | \"swipe-deck\"\n | \"swipeable-row\"\n | \"switch\"\n | \"tab-bar\"\n | \"tabs\"\n | \"tag-input\"\n | \"tag-selector\"\n | \"terminal-replay\"\n | \"theme\"\n | \"toast\"\n | \"toc\"\n | \"tooltip\"\n | \"tree-view\"\n | \"txt\"\n | \"update-prompt\"\n | \"verified-badge\"\n | \"vertical-video\"\n | \"video-player\"\n | \"video-trimmer\"\n | \"virtual\"\n | \"wall\";\n\n/** Where a component exists: `@krizaka/ui/<name>` (web), `@krizaka/ui/native` (React Native), or both. */\nexport type Platform = \"web\" | \"native\" | \"both\";\n\n/**\n * Why a component is not on a platform — a decision, never a silence (the parity matrix of ui.krizaka.com/platforms):\n * - `gap` (✗): it belongs there and is not built yet; `issue` is the issue that tracks it (`krizaka/krizaka-ui#275`);\n * - `n/a`: it is not meant for that platform (a site's page block on a phone, a swipe on a desktop); `use` names the\n * component that answers there, when one does.\n */\nexport type Absence =\n | { readonly status: \"gap\"; readonly issue: string; readonly reason: string; readonly use?: undefined }\n | { readonly status: \"n/a\"; readonly reason: string; readonly use?: ComponentName; readonly issue?: undefined };\n\n/**\n * Desktop is the Orazaka Mac app (Tauri 2: the system WebView renders the web components — ADR-002). `web`: the web\n * component runs there as it is; `desktop`: it also has a desktop form (a window's title bar, a denser layout…), said in\n * its documentation; otherwise the absence and why.\n */\nexport type DesktopSupport = \"web\" | \"desktop\" | Absence;\n\n/**\n * The three platforms of Krizaka UI — web · native (React Native, Expo) · desktop — for one component. The side a\n * component has is `platforms`; the side it lacks says why here: `native` is required for (and only for) a web-only\n * component, `web` for a native-only one; `desktop` always. `scripts/registry.test.mjs` fails on a missing decision.\n */\nexport interface Parity {\n readonly web?: Absence;\n readonly native?: Absence;\n readonly desktop: DesktopSupport;\n}\n\n/**\n * `experimental`: created for a filed need (ADR-008 §4), it may change or go in any minor until its first consumer imports it; `adoption`\n * names that consumer's issue. `stable`: its API only changes in a major. `beta`: it may still change in a minor. `deprecated`: no product uses it and\n * no work plans to — it still works, says what replaces it, and goes in the major named by `deprecated.removedIn`.\n */\nexport type Status = \"experimental\" | \"stable\" | \"beta\" | \"deprecated\";\n\n/**\n * What a component is for (ADR-008 §3): the twelve domains the documentation, the size budgets and the guards are\n * organised by. The domain is metadata: the entries stay flat (`@krizaka/ui/<name>`). `cahier` is the sites' register\n * (ADR-004): a product never imports it.\n */\nexport type Domain =\n | \"foundations\"\n | \"forms\"\n | \"data-display\"\n | \"navigation-shell\"\n | \"feedback\"\n | \"maps\"\n | \"media\"\n | \"commerce\"\n | \"identity\"\n | \"conversation\"\n | \"page-blocks\"\n | \"cahier\";\n\n/** What a deprecated component says (required when `status` is `deprecated`, absent otherwise). */\nexport interface Deprecation {\n /** The version that deprecated it (`3.6.0`). */\n readonly since: string;\n /** The major that removes it (`4.0.0`). */\n readonly removedIn: string;\n /** What replaces it, when a component does. */\n readonly use?: ComponentName;\n /** Why it goes: no product uses it, no planned work needs it. */\n readonly reason: string;\n}\n\n/**\n * The group of the catalogue. `media`: video, sound, camera, files, cropping. `blocks`: the page blocks — the frame,\n * the hero, sections, cards that lead or argue, decisions, code, calls to act — that every page of a site is made of.\n * `layouts`: the shells of whole screens — an application, a dashboard, settings, sign-in, an object, a list and its\n * item, a site's page, a documentation page — each with its screens. `templates`: the page templates — whole pages of a\n * site (a landing, a product, a docs hub, a long read, a changelog, pricing, status, an error…), each a distinct\n * composition of the blocks, words and content as props.\n */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"blocks\" | \"layouts\" | \"templates\" | \"layout\" | \"foundations\";\n\n/** Why a reader needs a template: the seven intents the templates are grouped by (sidebar sub-headings, catalogue filter). */\nexport type TemplatePurpose = \"convince\" | \"explain\" | \"show\" | \"act\" | \"operate\" | \"converse\" | \"recover\";\n\n/** The groups of templates, in reading order: the title, and the one line that says when to come to that group. */\nexport const templatePurposes = {\n convince: { title: \"Convince\", useWhen: \"You come here when a visitor must decide: a landing, a product, a price, a comparison, a proof.\" },\n explain: { title: \"Explain\", useWhen: \"You come here when a reader must understand: how it works, a documentation hub or article, a changelog, a FAQ, a policy.\" },\n show: { title: \"Show\", useWhen: \"You come here when the work itself is the argument: a gallery, a story, a case study, an object and its details.\" },\n act: { title: \"Act\", useWhen: \"You come here when a person must do something once: reach the team, sign in or up, set up, pay.\" },\n operate: { title: \"Operate\", useWhen: \"You come here when a person works every day: a dashboard, a console with a table, settings, an app shell.\" },\n converse: { title: \"Converse\", useWhen: \"You come here when people talk: an inbox, a chat, comments, a notifications centre.\" },\n recover: { title: \"Recover\", useWhen: \"You come here when the way is blocked: an empty list, an error, a missing page, maintenance, a product still being built.\" },\n} as const satisfies Record<TemplatePurpose, { readonly title: string; readonly useWhen: string }>;\n\n/**\n * A named example: the file `registry/examples/<component>/<name>.tsx` (web) or\n * `registry/examples/<component>/native/<name>.tsx` (React Native) — at most 40 lines, imported by the stories and\n * shown (live, with its code) by the documentation.\n */\ninterface ExampleBase {\n /** The file name, kebab-case (`primary`, `icon-button`). */\n readonly name: string;\n /** A short title (`Primary`, `Icon button`). */\n readonly title: string;\n /** One or two sentences: when this variant is the right one. */\n readonly description: string;\n}\n\n/** A plain example, or a template: a whole screen with its intent (`purpose`) and the user goal its layout serves (`why`). */\nexport type Example =\n | (ExampleBase & { readonly template?: false; readonly purpose?: undefined; readonly why?: undefined })\n | (ExampleBase & {\n /**\n * A template: a whole screen of a product composed from the platform (a layout and its blocks, real words, its\n * phone version thought out), copied as a starting point — at most 160 lines, listed on ui.krizaka.com/templates.\n */\n readonly template: true;\n /** The intent that groups it: why you need this block. */\n readonly purpose: TemplatePurpose;\n /** Why this layout: the user goal it serves, in one sentence. */\n readonly why: string;\n });\n\n/** One platform's side of a component. */\nexport interface PlatformDocs {\n /** The names to import (`[\"Button\", \"IconButton\"]`): from `@krizaka/ui/<name>` on the web, `@krizaka/ui/native` in React Native. */\n readonly imports: readonly string[];\n /** The examples, in reading order; the first one is the component's preview. */\n readonly examples: readonly Example[];\n}\n\n/** The React Native side: the same concept, and what differs from the web API. */\nexport interface NativeDocs extends PlatformDocs {\n /**\n * The entry to import from when it is not `@krizaka/ui/native`: a component that needs an Expo module (an optional\n * peer) has its own, `@krizaka/ui/native/<name>`, so an app that does not use it never installs the module.\n */\n readonly entry?: string;\n /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n readonly differences: readonly string[];\n /** The React Native entry alone is deprecated while the web one stays (ADR-006 §7); a deprecated component says it once, above. */\n readonly deprecated?: Deprecation;\n}\n\nexport interface KeyboardInteraction {\n /** The keys, as written on a keyboard: `Space`, `Enter`, `Arrow keys`, `Esc`, `Tab`. */\n readonly keys: string;\n /** What they do. */\n readonly action: string;\n}\n\nexport interface ComponentMeta {\n /** The display name: `Button`, `Dropdown menu`. */\n readonly title: string;\n /** One sentence: what it is. */\n readonly summary: string;\n readonly status: Status;\n /** Required for, and only for, a `deprecated` component. */\n readonly deprecated?: Deprecation;\n readonly category: Category;\n /** What it is for: one of the twelve domains (ADR-008 §3). */\n readonly domain: Domain;\n /** The `<repo>#<n>` issue of its first consumer: required for, and only for, an `experimental` component. */\n readonly adoption?: string;\n /** Must match the sides below: `both` ⇔ `web` and `native`. */\n readonly platforms: Platform;\n /** The platforms it is not on, and why; and its desktop form (see `Parity`). */\n readonly parity: Parity;\n /** When to reach for it: concrete situations, one per item. */\n readonly whenToUse: readonly string[];\n /** When not to — and what to use instead (`use`), when another component is the answer. */\n readonly whenNotToUse: readonly { readonly when: string; readonly use?: ComponentName }[];\n /** How to use it well: wording, placement, composition. */\n readonly bestPractices: readonly string[];\n readonly accessibility: {\n /** The keyboard, when it does more than Tab and Enter. */\n readonly keyboard: readonly KeyboardInteraction[];\n /** Roles, names and announcements: what the component does, what the app must provide. */\n readonly notes: readonly string[];\n };\n /** The components a reader of this page should know about. */\n readonly related: readonly ComponentName[];\n readonly web?: PlatformDocs;\n readonly native?: NativeDocs;\n}\n"
|
|
211
213
|
},
|
|
212
214
|
{
|
|
213
215
|
"path": "reviews/index.ts",
|
|
@@ -215,7 +217,7 @@
|
|
|
215
217
|
},
|
|
216
218
|
{
|
|
217
219
|
"path": "reviews/meta.ts",
|
|
218
|
-
"content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n title: \"Reviews\",\n summary: \"A score you can trust: `ReviewSummary` shows the shop's score as a stamp with the verified count, five meters for the distribution and its text equivalent — nothing under the host's minimum — and `ReviewCard` one review with the owner's reply indented.\",\n status: \"beta\",\n category: \"blocks\",\n platforms: \"web\",\n parity: { native: { status: \"n/a\", reason: \"A public storefront's block; the native apps read reviews in their own lists.\", use: \"card\" }, desktop: \"web\" },\n whenToUse: [\n \"A shop's page: the clients' word as verified reviews (only a completed appointment may review), with a fair score.\",\n \"Any place that rates a place, a person or a service with a 1 to 5 scale and wants the distribution visible.\",\n ],\n whenNotToUse: [\n { when: \"A school-style mark out of 20 (a teacher's red): that is the tool sites' register.\", use: \"grade-stamp\" },\n { when: \"A measure within a range that is not a rating (a quota, a balance).\", use: \"meter\" },\n ],\n bestPractices: [\n \"The host computes the score (a Bayesian average of the verified reviews) and formats every word: `scoreText`, `countText`, `summaryText`, `starText`, the dates.\",\n \"Set `minCount` (the shop's minimum): `ReviewSummary` renders nothing under it, so a new shop shows no score rather than a lonely « 5,0 ».\",\n \"Show only verified reviews and say so (« 27 avis vérifiés »); the owner's reply is a `reply`, never an edit of the review.\",\n \"Three cards and a link to all of them, not a wall of text.\",\n ],\n accessibility: {\n keyboard: [],\n notes: [\n \"`ReviewSummary` is a group named by its text equivalent (« 4,8 sur 5, 27 avis vérifiés »); the stamp and the count are hidden from assistive technology so nothing is read twice.\",\n \"The distribution is five real `meter`s, each named (« 5 étoiles : 20 avis »); the rating of a card is read in words and its stars are decorative.\",\n \"A review's date is a `time` with its machine-readable value.\",\n ],\n },\n related: [\"meter\", \"specimen-tag\", \"grade-stamp\", \"description-list\"],\n web: {\n imports: [\"ReviewSummary\", \"ReviewCard\"],\n examples: [\n { name: \"summary\", title: \"The score\", description: \"A stamp, the verified count, five meters and the text equivalent.\" },\n { name: \"card\", title: \"A review\", description: \"First name and initial, the month, the service, the words and the owner's indented reply.\" },\n ],\n },\n} satisfies ComponentMeta;\n"
|
|
220
|
+
"content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n title: \"Reviews\",\n summary: \"A score you can trust: `ReviewSummary` shows the shop's score as a stamp with the verified count, five meters for the distribution and its text equivalent — nothing under the host's minimum — and `ReviewCard` one review with the owner's reply indented.\",\n status: \"beta\",\n category: \"blocks\",\n domain: \"commerce\",\n platforms: \"web\",\n parity: { native: { status: \"n/a\", reason: \"A public storefront's block; the native apps read reviews in their own lists.\", use: \"card\" }, desktop: \"web\" },\n whenToUse: [\n \"A shop's page: the clients' word as verified reviews (only a completed appointment may review), with a fair score.\",\n \"Any place that rates a place, a person or a service with a 1 to 5 scale and wants the distribution visible.\",\n ],\n whenNotToUse: [\n { when: \"A school-style mark out of 20 (a teacher's red): that is the tool sites' register.\", use: \"grade-stamp\" },\n { when: \"A measure within a range that is not a rating (a quota, a balance).\", use: \"meter\" },\n ],\n bestPractices: [\n \"The host computes the score (a Bayesian average of the verified reviews) and formats every word: `scoreText`, `countText`, `summaryText`, `starText`, the dates.\",\n \"Set `minCount` (the shop's minimum): `ReviewSummary` renders nothing under it, so a new shop shows no score rather than a lonely « 5,0 ».\",\n \"Show only verified reviews and say so (« 27 avis vérifiés »); the owner's reply is a `reply`, never an edit of the review.\",\n \"Three cards and a link to all of them, not a wall of text.\",\n ],\n accessibility: {\n keyboard: [],\n notes: [\n \"`ReviewSummary` is a group named by its text equivalent (« 4,8 sur 5, 27 avis vérifiés »); the stamp and the count are hidden from assistive technology so nothing is read twice.\",\n \"The distribution is five real `meter`s, each named (« 5 étoiles : 20 avis »); the rating of a card is read in words and its stars are decorative.\",\n \"A review's date is a `time` with its machine-readable value.\",\n ],\n },\n related: [\"meter\", \"specimen-tag\", \"grade-stamp\", \"description-list\"],\n web: {\n imports: [\"ReviewSummary\", \"ReviewCard\"],\n examples: [\n { name: \"summary\", title: \"The score\", description: \"A stamp, the verified count, five meters and the text equivalent.\" },\n { name: \"card\", title: \"A review\", description: \"First name and initial, the month, the service, the words and the owner's indented reply.\" },\n ],\n },\n} satisfies ComponentMeta;\n"
|
|
219
221
|
},
|
|
220
222
|
{
|
|
221
223
|
"path": "reviews/reviews.tsx",
|