@krizaka/ui 2.0.0-beta.5 → 2.0.0-beta.6

package/README.md

@@ -153,7 +153,7 @@ Colours are roles of the preset (`bg-surface-2`, `text-fg-secondary`, `border-bo
 | `@krizaka/ui` | the marks, `MotionObserver`, `RotatingWord`, `cx` (unchanged) | client |
 | `@krizaka/ui/native` | React Native: `ThemeProvider`/`useTheme`, `Txt`, `Button`, `IconButton`, `Card.*`, `Badge`, `Chip` (+ `Group`), `Avatar` (+ `Group`), `Skeleton`, `EmptyState`, `Spinner`, `Countdown`, `Segmented`, `Progress`, `Toaster`/`toast`, the marks — see [React Native](#react-native) | native |
 | `@krizaka/ui/motion.css`, `@krizaka/ui/tailwind.css` | the motion signature; the `@source` of the primitives' classes | CSS |
-| `@krizaka/ui/registry/<name>`, `@krizaka/ui/registry/demos/<name>` | the registry (JSON) and the demos — see [Registry](#registry) | data · client |
+| `@krizaka/ui/registry/<name>`, `@krizaka/ui/registry/examples/<name>/<example>` | the registry (JSON) and the examples — see [Registry](#registry--the-code-drives-the-documentation) | data · client |
 
 The theme is one mechanism for every product: dark by default, `html.light` for light, `html.theme-<name>` for a named
 theme, persisted as `kz-theme` (and `kz-theme-name`).
@@ -168,34 +168,48 @@ theme, persisted as `kz-theme` (and `kz-theme-name`).
 <ThemeToggle label={(mode) => t(`theme.${mode}`)} />
 ```
 
-## Registry
-
-Every primitive is also published as data, for documentation sites (krizaka.com's `/docs/ui`: live preview, copyable
-code, props table) and, later, a `npx @krizaka/cli add <name>` that copies a primitive into a product which forks it
-knowingly. Built by `scripts/build-registry.mjs` after tsup, from `src/<name>/` (all primitives; not the marks, the
-motion or `native`):
+## Registry — the code drives the documentation
+
+Every component is also published as data: **[krizaka.com/docs/ui](https://www.krizaka.com/docs/ui)** is generated
+from it at every build of the site (one page per component: when to use it, live examples with their code for the web
+and React Native, props, accessibility), and, later, a `npx @krizaka/cli add <name>` may copy a primitive into a
+product that forks it knowingly. Built by `scripts/build-registry.mjs` after tsup, from three sources in the code:
+
+- **`meta.ts`** beside each component (`src/<name>/meta.ts`, `src/cn.meta.ts`; a React-Native-only component:
+  `src/native/meta/<name>.ts`), typed by `src/meta.ts`: title, summary, status (`stable` · `beta`), category,
+  platforms (`web` · `native` · `both`), when to use it, when not (and what to use instead), best practices,
+  accessibility (keyboard, roles), related components, and per platform the names to import, the named examples and,
+  for React Native, what differs from the web API. A typed module rather than JSDoc tags: the fields are lists and
+  links between components, which the compiler checks; the file is plain data that Node reads without a build.
+- **Named examples**: `registry/examples/<name>/<example>.tsx` (web) and `registry/examples/<name>/native/<example>.tsx`
+  (React Native) — one per significant variant, ≤ 40 lines, importing what a product imports (`@krizaka/ui/<entry>`,
+  `@krizaka/ui/native`, `react-native`). The stories render them, so Storybook's visual tests and the docs show the
+  same code. An example that opens over the page takes `defaultOpen` (the story opens it; the docs leave it closed).
+- **Props** of the web and native components, read by `react-docgen-typescript` from the JSDoc of their props types:
+  own props only (inherited DOM, Radix and `Pressable` props are left out).
+
+`scripts/registry.test.mjs` fails when a component has no `meta.ts`, an empty section, an unknown related component, a
+platform that does not match its exports, an example missing or longer than 40 lines, or a prop without a
+description; `src/registry.test.tsx` (Vitest, axe) and `src/native/examples.test.tsx` (Jest) render every example.
 
 | Path | What |
 | :-- | :-- |
-| `@krizaka/ui/registry/index` | `{ name, version, items: [{ name, type, description, dependencies, registryDependencies }] }` |
-| `@krizaka/ui/registry/<name>` | `{ name, type: "primitive", description, files: [{ path, content }], dependencies, registryDependencies, demo: { path, content }, props }` |
-| `@krizaka/ui/registry/demos/<name>` | the demo, compiled (ESM, `"use client"`, `default` export) — its source ships beside it as `registry/demos/<name>.tsx` |
+| `@krizaka/ui/registry/index` | `{ name, version, items: [{ name, type, title, summary, status, category, platforms, examples: { web, native }, dependencies, registryDependencies }] }` |
+| `@krizaka/ui/registry/<name>` | the `meta.ts` fields, `web` and `native` (`{ entry, import, props, examples: [{ name, title, description, path, module, code }] }`, `native` adds `differences` and, per example, `screenshots: { dark, light }`), and for a web primitive `files: [{ path, content }]`, `dependencies`, `registryDependencies`, `demo` (its first example) and `props` |
+| `@krizaka/ui/registry/examples/<name>/<example>` | an example, compiled (ESM, `"use client"`, `default` export); its source ships beside it (`.tsx`), and a React Native example its screenshots (`<example>.dark.png`, `<example>.light.png`: the Linux baselines of its story — React Native has no live preview on the web) |
 
 - `files` are the sources (paths from `src/`); `dependencies` are npm `name@range` (React aside); `registryDependencies`
-  are the other primitives it imports (`cn`, `button`…).
+  are the other primitives it imports (`cn`, `button`…). `type` is `primitive` (a web entry) or `native` (React Native
+  only: `segmented`, `txt`).
 - `props` is one entry per exported component — `{ component, description, props: [{ name, type, default, description,
-  required }] }` — read by `react-docgen-typescript` from the JSDoc of the props types: the component's own props,
-  its variants included; inherited DOM and Radix props are left out. A test fails on a prop without a description.
-- A demo is ≤ 40 lines, imports the primitives as a product does (`@krizaka/ui/<name>`) and is the default story of
-  the primitive: Storybook and the docs show the same code. A demo that opens over the page takes `defaultOpen` (the
-  story opens it for the screenshot; the docs leave it closed).
+  required }] }`.
 
 ```ts
-import card from "@krizaka/ui/registry/card" with { type: "json" };
-import CardDemo from "@krizaka/ui/registry/demos/card";
+import button from "@krizaka/ui/registry/button" with { type: "json" };
+import Primary from "@krizaka/ui/registry/examples/button/primary";
 ```
 
-A site that renders the demos adds them to Tailwind's sources: `@source "../node_modules/@krizaka/ui/registry/demos";`.
+A site that renders the examples adds them to Tailwind's sources: `@source "../node_modules/@krizaka/ui/registry/examples";`.
 
 ## React Native
 
@@ -267,7 +281,8 @@ import { Button, Card, Countdown, OrochiaMark } from "@krizaka/ui/native";
 <OrochiaMark size={72} title="Orochia" neutral={theme.borderDefault} />
 ```
 
-The native stories (`Native/*` in the catalogue) render through react-native-web in the web Storybook: audited by axe
+The native stories (`Native/*`, rendering the `registry/examples/<name>/native` examples) render through
+react-native-web in the internal Storybook: audited by axe
 and screenshot-compared in dark and light like the web ones. Tests run on Jest with React Native's preset and
 Testing Library (`src/native/*.test.tsx`); `scripts/native-dist.mjs` checks that `dist/native.js` carries no
 `"use client"`, no DOM and no import beyond React, `react-native` and `react-native-svg`.
@@ -334,8 +349,8 @@ classes the components use are generated in your stylesheet.
 @import "@krizaka/ui/tailwind.css";
 ```
 
-Every component, in dark and light and under each product identity:
-[krizaka.github.io/krizaka-ui/latest](https://krizaka.github.io/krizaka-ui/latest/).
+Every component, with when to use it, live examples and their code (web and React Native) and its props:
+[krizaka.com/docs/ui](https://www.krizaka.com/docs/ui).
 
 ## Develop
 

package/dist/native.d.ts

@@ -23,6 +23,7 @@ type BrandId = "krizaka" | "orazaka" | "orochia";
 
 type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl";
 type AvatarProps = Omit<ViewProps, "children"> & {
+    /** The image URI; absent, `null` or failing: the fallback. */
     src?: string | null;
     /** The person's name: the image's accessible name and the source of the default initial. */
     alt?: string;
@@ -48,7 +49,9 @@ declare const Avatar: typeof AvatarRoot & {
 
 type BadgeTone = "neutral" | "accent" | "success" | "warning" | "danger" | "scrim";
 type BadgeProps = ViewProps & {
+    /** neutral (default) · accent · success · warning · danger · scrim (on a media). */
     tone?: BadgeTone;
+    /** sm (default) · md. */
     size?: "sm" | "md";
     /** A small dot before the text, in the tone's colour. */
     dot?: boolean;
@@ -62,12 +65,15 @@ declare function Badge({ tone, size, dot, pulse, style, children, ...props }: Ba
 type ButtonVariant = "primary" | "secondary" | "outline" | "ghost" | "danger";
 type ButtonSize = "sm" | "md" | "lg";
 type BaseProps = Omit<PressableProps, "children" | "style"> & {
+    /** The look: `primary`, `secondary` (default), `outline`, `ghost`, `danger` — as on the web. */
     variant?: ButtonVariant;
+    /** sm · md (default) · lg: 32, 40 or 48 points high. */
     size?: ButtonSize;
     /** `rounded` (default) or `pill`. */
     shape?: "rounded" | "pill";
     /** Disables, shows a spinner in place of the icon and says busy. */
     loading?: boolean;
+    /** Styles merged last, over the button's frame. */
     style?: StyleProp<ViewStyle>;
 };
 type ButtonProps = BaseProps & {
@@ -81,6 +87,7 @@ declare function Button({ label, icon, variant, size, shape, loading, disabled,
 type IconButtonProps = BaseProps & {
     /** The accessible name — required, passed translated. */
     label: string;
+    /** The icon (from the app's icon set); the button shows nothing else. */
     icon: React.ReactNode;
 };
 /** A square button holding only an icon: `label` is required, it is its accessible name. */
@@ -132,6 +139,7 @@ declare const textStyles: {
 type CardRootProps = ViewProps & {
     /** `default` (the raised surface) or `elevated` (one step higher, with a shadow). */
     tone?: "default" | "elevated";
+    /** The corner radius, from the theme: md · lg · xl (default). */
     radius?: "md" | "lg" | "xl";
     /**
      * Makes the whole card pressable: a button for screen readers, named by its content (an `aria-label`, if any, must
@@ -147,11 +155,13 @@ declare const ASPECT: {
     readonly portrait: number;
 };
 type CardMediaProps = ViewProps & {
+    /** video (default, 16:9) · square · portrait, or `auto` (the image's own). */
     aspect?: keyof typeof ASPECT | "auto";
 };
 /** The media area at the top of a card: a fixed ratio, the `media` role behind (what shows while an image loads). */
 declare function CardMedia({ aspect, style, ...props }: CardMediaProps): React.JSX.Element;
 type CardImageProps = Omit<ImageProps, "source" | "src"> & {
+    /** The image URI; absent or `null`: the `fallback` on the media colour. */
     src?: string | null;
     /** Shown when there is no image: an icon, an illustration (decorative). */
     fallback?: React.ReactNode;
@@ -160,6 +170,7 @@ type CardImageProps = Omit<ImageProps, "source" | "src"> & {
 declare function CardImage({ src, fallback, alt, style, ...props }: CardImageProps): React.JSX.Element;
 declare const CORNER: Record<"top-left" | "top-right" | "bottom-left" | "bottom-right", ViewStyle>;
 type CardOverlayProps = ViewProps & {
+    /** The corner of the media it sits in: top-left (default) · top-right · bottom-left · bottom-right. */
     corner?: keyof typeof CORNER;
 };
 /** What sits on the media (badges, a caption), in a corner. */
@@ -171,6 +182,7 @@ declare const PADDING: {
     readonly lg: 24;
 };
 type CardBodyProps = ViewProps & {
+    /** none · sm · md (default) · lg. */
     padding?: keyof typeof PADDING;
 };
 declare function CardBody({ padding, style, ...props }: CardBodyProps): React.JSX.Element;
@@ -192,7 +204,9 @@ declare const Card: {
 
 type ChipSize = "sm" | "md";
 type CommonProps = Omit<PressableProps, "children" | "style" | "onPress"> & {
+    /** sm · md (default); in a group, the group's size. */
     size?: ChipSize;
+    /** Styles merged last. */
     style?: StyleProp<ViewStyle>;
     /** The text (passed translated) or a node (an icon and a text). */
     children: React.ReactNode;
@@ -202,7 +216,9 @@ type ToggleChipProps = CommonProps & {
     value?: string;
     /** Alone: pressed or not (`defaultSelected` uncontrolled), `onSelectedChange` on every press. */
     selected?: boolean;
+    /** Uncontrolled: selected at first (alone, outside a group). */
     defaultSelected?: boolean;
+    /** Alone: called with the new state when it is pressed. */
     onSelectedChange?: (selected: boolean) => void;
     removable?: false;
 };
@@ -211,18 +227,21 @@ type RemovableChipProps = CommonProps & {
     removable: true;
     /** The accessible name of the remove button — passed translated, e.g. "Remove #night". */
     removeLabel: string;
+    /** Called when its remove button is pressed. */
     onRemove: () => void;
 };
 type ChipProps = ToggleChipProps | RemovableChipProps;
 /** A selectable pill (`selected` / `onSelectedChange`), an item of `Chip.Group` (`value`), or `removable`. */
 declare function ChipBase(props: ChipProps): React.JSX.Element;
 type GroupBase = {
+    /** sm · md (default); in a group, the group's size. */
     size?: ChipSize;
     disabled?: boolean;
     /** One horizontal scrolling row (a filter bar) instead of wrapping lines. */
     scrollable?: boolean;
     /** The accessible name of the group — passed translated. */
     "aria-label"?: string;
+    /** Styles merged last. */
     style?: StyleProp<ViewStyle>;
     children: React.ReactNode;
 };
@@ -245,6 +264,7 @@ declare const Chip: typeof ChipBase & {
 };
 
 type CountdownProps = {
+    /** The moment it counts down to: a Date, an ISO string or epoch milliseconds. */
     target: Date | string | number;
     /** Server clock − this clock, in milliseconds. */
     skewMs?: number;
@@ -252,9 +272,11 @@ type CountdownProps = {
     units: CountdownUnits;
     /** Below this many milliseconds it turns urgent (the danger role, the last segment breathes). Default 60 s. */
     urgentBelowMs?: number;
+    /** sm · md (default) · lg. */
     size?: "sm" | "md" | "lg";
     /** Accessible name, e.g. "Ends in". */
     label: string;
+    /** Styles merged last. */
     style?: StyleProp<ViewStyle>;
 };
 /**
@@ -267,7 +289,9 @@ declare function Countdown({ target, skewMs, units, urgentBelowMs, size, label,
 type EmptyStateProps = Omit<ViewProps, "children"> & {
     /** A decorative icon (hidden from screen readers). */
     icon?: React.ReactNode;
+    /** What is empty, in a few words ("No notifications yet"). */
     title: string;
+    /** Why, or what will fill it. */
     description?: string;
     /** What to do next: a Button. */
     action?: React.ReactNode;
@@ -314,9 +338,11 @@ declare function ProductMark({ id, ...props }: NativeMarkProps & {
 type ProgressProps = {
     /** `bar` (default) or `ring`. */
     variant?: "bar" | "ring";
+    /** sm · md (default) · lg: the bar's thickness or the ring's diameter. */
     size?: "sm" | "md" | "lg";
     /** How far, between 0 and `max`. `null` or absent: indeterminate (a wait of unknown length). */
     value?: number | null;
+    /** The value of a full bar. Default 100. */
     max?: number;
     /** The accessible name — passed translated ("Upload", "Raised towards the goal"). */
     label: string;
@@ -324,6 +350,7 @@ type ProgressProps = {
     valueText?: string;
     /** A ring's centre: an amount, a percentage, an icon. */
     children?: React.ReactNode;
+    /** Styles merged last. */
     style?: StyleProp<ViewStyle>;
 };
 /**
@@ -340,11 +367,15 @@ type SegmentedOption<T extends string> = {
 type SegmentedProps<T extends string> = {
     /** The views, in order; `label` passed translated. */
     options: readonly SegmentedOption<T>[];
+    /** The selected view (controlled). */
     value: T;
+    /** Called with the view pressed. */
     onValueChange: (value: T) => void;
+    /** sm · md (default). */
     size?: "sm" | "md";
     /** The accessible name of the tab list — passed translated. */
     "aria-label"?: string;
+    /** Styles merged last. */
     style?: StyleProp<ViewStyle>;
 };
 /**
@@ -356,9 +387,13 @@ declare function Segmented<T extends string>({ options, value, onValueChange, si
 type SkeletonProps = {
     /** `text` (a line), `circle` (an avatar), `rect` (a media, a card). */
     shape?: "text" | "circle" | "rect";
+    /** Points or a percentage; default: the shape's. */
     width?: DimensionValue;
+    /** Points or a percentage; default: the shape's. */
     height?: DimensionValue;
+    /** Styles merged last. */
     style?: StyleProp<ViewStyle>;
+    /** The id the tests find it by. */
     testID?: string;
 };
 /** A pulsing placeholder the size of what is loading — hidden from screen readers; still when the system reduces motion. */
@@ -367,6 +402,7 @@ declare function Skeleton({ shape, width, height, style, testID }: SkeletonProps
 type SpinnerProps = Omit<ActivityIndicatorProps, "size" | "color"> & {
     /** The accessible name of the wait, e.g. "Loading" — passed translated. */
     label: string;
+    /** sm · md (default) · lg. */
     size?: "sm" | "md" | "lg";
 };
 /** An indeterminate wait: the platform's activity indicator in the accent, named by `label`. */
@@ -451,6 +487,7 @@ type ThemeProviderProps = {
     onModeChange?: (mode: Mode) => void;
     /** The product's roles over the platform's, per theme. */
     overrides?: ThemeOverrides;
+    /** Font families the app has loaded (`expo-font`…); absent: the system font. */
     fonts?: ThemeFonts;
 };
 /** Once, at the root of the app. Without it, `useTheme()` follows the system with the platform's roles. */
@@ -499,6 +536,7 @@ declare const toast: typeof show & {
 type ToasterProps = {
     /** The accessible name of each toast's close button — passed translated. */
     closeLabel: string;
+    /** Where the toasts stack: `top` (default) or `bottom`. */
     position?: "top" | "bottom";
     /** Distance from the edge, e.g. the safe-area inset + a margin (no safe-area dependency here). */
     offset?: number;