@krizaka/ui 2.2.0 → 2.4.0

package/registry/tag-input.json

@@ -0,0 +1,363 @@
+{
+  "name": "tag-input",
+  "type": "primitive",
+  "title": "Tag input",
+  "summary": "Free words as removable chips — Enter or a comma adds one, a paste adds several, suggestions complete, `normalize` cleans and `validate` refuses with a reason.",
+  "description": "Free words as removable chips — Enter or a comma adds one, a paste adds several, suggestions complete, `normalize` cleans and `validate` refuses with a reason.",
+  "status": "beta",
+  "category": "forms",
+  "platforms": "web",
+  "whenToUse": [
+    "For keywords a person invents: the tags of a video, the topics of an article.",
+    "For a list of values typed one after the other: e-mail recipients, domains, IP addresses."
+  ],
+  "whenNotToUse": [
+    {
+      "when": "When the values come from a closed list: a combobox with `multiple`.",
+      "use": "combobox"
+    },
+    {
+      "when": "For one free value: a plain field.",
+      "use": "field"
+    }
+  ],
+  "bestPractices": [
+    "Normalise the way the product stores tags (lower case, no `#`, no spaces) so “#Sunset” and “sunset” are one tag.",
+    "Say the limit and the separator in `hint` (“Up to 10 tags, separated by commas”).",
+    "Offer the person's own history first in `suggestions`, then a curated list.",
+    "Explain a refusal in words in `validate` (“Use letters and numbers only”)."
+  ],
+  "accessibility": {
+    "keyboard": [
+      {
+        "keys": "Enter / ,",
+        "action": "Add the typed word as a tag (or the active suggestion)."
+      },
+      {
+        "keys": "Backspace",
+        "action": "In an empty input, remove the last tag."
+      },
+      {
+        "keys": "Arrow Down / Arrow Up",
+        "action": "Move through the suggestions."
+      }
+    ],
+    "notes": [
+      "Built on `Combobox` (multiple, creatable): the same combobox pattern and announcements.",
+      "A refusal from `validate` is shown under the field and read with it (`aria-describedby`, `aria-invalid`).",
+      "Each tag's remove button is named by `labels.remove` (“Remove sunset”)."
+    ]
+  },
+  "related": [
+    "combobox",
+    "chip",
+    "field"
+  ],
+  "web": {
+    "entry": "@krizaka/ui/tag-input",
+    "import": "import { TagInput } from \"@krizaka/ui/tag-input\";",
+    "props": [
+      {
+        "component": "TagInput",
+        "description": "Words as removable chips — tags, keywords, e-mail recipients — with suggestions, cleaning and validation.",
+        "props": [
+          {
+            "name": "label",
+            "type": "string",
+            "default": null,
+            "description": "The visible label, passed translated (also the accessible name).",
+            "required": true
+          },
+          {
+            "name": "className",
+            "type": "string",
+            "default": null,
+            "description": "Classes merged on the root.",
+            "required": false
+          },
+          {
+            "name": "defaultValue",
+            "type": "readonly string[]",
+            "default": "[]",
+            "description": "The tags at first, uncontrolled.",
+            "required": false
+          },
+          {
+            "name": "disabled",
+            "type": "boolean",
+            "default": null,
+            "description": "Not available.",
+            "required": false
+          },
+          {
+            "name": "error",
+            "type": "string",
+            "default": null,
+            "description": "An error from the app (a server refusal); `validate`'s own errors show here too.",
+            "required": false
+          },
+          {
+            "name": "hideLabel",
+            "type": "boolean",
+            "default": null,
+            "description": "Hides the label visually, keeping it as the accessible name.",
+            "required": false
+          },
+          {
+            "name": "hint",
+            "type": "string",
+            "default": null,
+            "description": "A help text under the field (\"Up to 10 tags, separated by commas\").",
+            "required": false
+          },
+          {
+            "name": "labels",
+            "type": "Partial<Pick<ComboboxLabels, \"results\" | \"toggle\" | \"remove\" | \"empty\" | \"create\">>",
+            "default": null,
+            "description": "The words of the field, passed translated; English by default.",
+            "required": false
+          },
+          {
+            "name": "max",
+            "type": "number",
+            "default": null,
+            "description": "Most tags; the field stops offering more past it.",
+            "required": false
+          },
+          {
+            "name": "name",
+            "type": "string",
+            "default": null,
+            "description": "The name of the hidden inputs, for a plain `<form>` post (one per tag).",
+            "required": false
+          },
+          {
+            "name": "normalize",
+            "type": "((tag: string) => string)",
+            "default": "(tag) => tag.trim()",
+            "description": "Cleans a word before it is added (`(t) => t.toLowerCase().replace(/^#/, \"\")`). An empty result is ignored.",
+            "required": false
+          },
+          {
+            "name": "onValueChange",
+            "type": "((tags: string[]) => void)",
+            "default": null,
+            "description": "Called with every tag after a change.",
+            "required": false
+          },
+          {
+            "name": "placeholder",
+            "type": "string",
+            "default": null,
+            "description": "The input's placeholder, passed translated.",
+            "required": false
+          },
+          {
+            "name": "separators",
+            "type": "readonly string[]",
+            "default": "[\",\"]",
+            "description": "Keys that add the word, besides Enter. Default `[\",\"]`.",
+            "required": false
+          },
+          {
+            "name": "suggestions",
+            "type": "readonly string[]",
+            "default": "[]",
+            "description": "Words offered as the person types (their own history, a curated list).",
+            "required": false
+          },
+          {
+            "name": "validate",
+            "type": "((tag: string, tags: readonly string[]) => string | null)",
+            "default": null,
+            "description": "Refuses a word: return the reason (passed translated), shown and read as the field's error; `null` accepts it.",
+            "required": false
+          },
+          {
+            "name": "value",
+            "type": "readonly string[]",
+            "default": null,
+            "description": "The tags (controlled).",
+            "required": false
+          }
+        ]
+      }
+    ],
+    "examples": [
+      {
+        "name": "video-tags",
+        "title": "Tags of a video",
+        "description": "Suggestions, lower case without `#`, at most 10.",
+        "path": "examples/tag-input/video-tags.tsx",
+        "module": "@krizaka/ui/registry/examples/tag-input/video-tags",
+        "code": "\"use client\";\n\nimport { TagInput } from \"@krizaka/ui/tag-input\";\nimport * as React from \"react\";\n\n// Lower case, no “#”: “#Sunset” and “sunset” are one tag.\nexport default function TagInputVideoTags() {\n  const [tags, setTags] = React.useState([\"montreal\", \"sunset\"]);\n  return (\n    <TagInput\n      label=\"Tags\"\n      placeholder=\"Add a tag\"\n      value={tags}\n      onValueChange={setTags}\n      suggestions={[\"timelapse\", \"travel\", \"skyline\", \"golden hour\", \"drone\"]}\n      normalize={(tag) => tag.trim().toLowerCase().replace(/^#/, \"\")}\n      max={10}\n      hint=\"Up to 10 tags, separated by commas.\"\n      labels={{ create: (tag) => `Add “${tag}”`, remove: (tag) => `Remove ${tag}` }}\n    />\n  );\n}\n"
+      },
+      {
+        "name": "recipients",
+        "title": "E-mail recipients",
+        "description": "`validate` refuses what is not an address; a comma or a space adds one.",
+        "path": "examples/tag-input/recipients.tsx",
+        "module": "@krizaka/ui/registry/examples/tag-input/recipients",
+        "code": "\"use client\";\n\nimport { TagInput } from \"@krizaka/ui/tag-input\";\n\nconst EMAIL = /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/;\n\n// Paste “a@x.com, b@y.org” and both are added; what is not an address is refused, with the reason.\nexport default function TagInputRecipients() {\n  return (\n    <TagInput\n      label=\"Invite by e-mail\"\n      placeholder=\"name@example.com\"\n      defaultValue={[\"ines@krizaka.com\"]}\n      separators={[\",\", \" \"]}\n      normalize={(value) => value.trim().toLowerCase()}\n      validate={(value) => (EMAIL.test(value) ? null : `“${value}” is not an e-mail address.`)}\n      labels={{ create: (value) => `Invite ${value}` }}\n    />\n  );\n}\n"
+      }
+    ]
+  },
+  "native": null,
+  "files": [
+    {
+      "path": "media.ts",
+      "content": "// Shared by the data and media primitives (client): the clock format, the reduced-motion preference, the\n// in-view observer, a debounced callback. Never an entry of its own.\nimport * as React from \"react\";\n\n/** Seconds as a clock: `75` → `1:15`, `3725` → `1:02:05`. Negative or unknown values read `0:00`. */\nexport function formatClock(seconds: number): string {\n  const s = Number.isFinite(seconds) && seconds > 0 ? Math.floor(seconds) : 0;\n  const h = Math.floor(s / 3600);\n  const m = Math.floor((s % 3600) / 60);\n  const rest = String(s % 60).padStart(2, \"0\");\n  return h > 0 ? `${h}:${String(m).padStart(2, \"0\")}:${rest}` : `${m}:${rest}`;\n}\n\n/** Clamps `value` between `min` and `max`. */\nexport const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));\n\nconst REDUCE = \"(prefers-reduced-motion: reduce)\";\nconst subscribeReduce = (notify: () => void) => {\n  if (typeof window === \"undefined\" || !window.matchMedia) return () => undefined;\n  const query = window.matchMedia(REDUCE);\n  query.addEventListener?.(\"change\", notify);\n  return () => query.removeEventListener?.(\"change\", notify);\n};\n\n/** `true` when the person asked for less motion (`prefers-reduced-motion: reduce`); follows a change of the setting. */\nexport function usePrefersReducedMotion(): boolean {\n  return React.useSyncExternalStore(\n    subscribeReduce,\n    () => (typeof window !== \"undefined\" && window.matchMedia ? window.matchMedia(REDUCE).matches : false),\n    () => false,\n  );\n}\n\n/** The latest value of a callback, for an effect or an event that must not re-subscribe when it changes. */\nexport function useLatest<T>(value: T) {\n  const ref = React.useRef(value);\n  React.useLayoutEffect(() => {\n    ref.current = value;\n  });\n  return ref;\n}\n\n/** Calls `onChange(visible)` when at least `threshold` of the element enters or leaves the viewport. */\nexport function useInView(ref: React.RefObject<Element | null>, onChange: (visible: boolean) => void, enabled = true, threshold = 0.25) {\n  const latest = useLatest(onChange);\n  React.useEffect(() => {\n    const element = ref.current;\n    if (!enabled || !element || typeof IntersectionObserver === \"undefined\") return;\n    const observer = new IntersectionObserver(([entry]) => entry && latest.current(entry.isIntersecting), { threshold });\n    observer.observe(element);\n    return () => observer.disconnect();\n  }, [ref, enabled, threshold, latest]);\n}\n\n/** A stable function that runs `callback` once `delay` ms have passed without a new call; `cancel()` drops the pending one. */\nexport function useDebouncedCallback<A extends unknown[]>(callback: (...args: A) => void, delay: number) {\n  const latest = useLatest(callback);\n  const [debounced] = React.useState(() => {\n    let timer: ReturnType<typeof setTimeout> | undefined;\n    let wait = delay;\n    const run = (...args: A) => {\n      clearTimeout(timer);\n      if (wait <= 0) latest.current(...args);\n      else timer = setTimeout(() => latest.current(...args), wait);\n    };\n    return Object.assign(run, {\n      cancel: () => clearTimeout(timer),\n      setDelay: (next: number) => {\n        wait = next;\n      },\n    });\n  });\n  React.useEffect(() => debounced.setDelay(delay), [debounced, delay]);\n  React.useEffect(() => () => debounced.cancel(), [debounced]);\n  return debounced;\n}\n\n/** A value controlled by a prop when it is given, held inside otherwise; `set` calls `onChange` either way. */\nexport function useControllable<T>(value: T | undefined, defaultValue: T, onChange?: (next: T) => void) {\n  const [inner, setInner] = React.useState(defaultValue);\n  const controlled = value !== undefined;\n  const current = controlled ? value : inner;\n  const set = React.useCallback(\n    (next: T) => {\n      if (!controlled) setInner(next);\n      onChange?.(next);\n    },\n    [controlled, onChange],\n  );\n  return [current, set] as const;\n}\n\n/** Starts a media element without an unhandled rejection (autoplay refused, the source replaced meanwhile). */\nexport function playSafely(media: HTMLMediaElement | null | undefined) {\n  try {\n    const started = media?.play() as Promise<void> | undefined;\n    started?.catch?.(() => undefined);\n  } catch {\n    // Not playable here (no media support): the controls stay as they are.\n  }\n}\n"
+    },
+    {
+      "path": "meta.ts",
+      "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 krizaka.com renders as\n// /docs/ui/<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  | \"alert\"\n  | \"audio-player\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"cn\"\n  | \"combobox\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"glow-card\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"loader\"\n  | \"marquee\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"page-header\"\n  | \"pagination\"\n  | \"popover\"\n  | \"progress\"\n  | \"radio-group\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"stat\"\n  | \"stepper\"\n  | \"switch\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"theme\"\n  | \"toast\"\n  | \"tooltip\"\n  | \"txt\"\n  | \"video-player\"\n  | \"video-trimmer\";\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/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/** The group of the catalogue. `media`: video, sound, camera, files, cropping. */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"layout\" | \"foundations\";\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 */\nexport interface Example {\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/** 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}\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  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\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"
+    },
+    {
+      "path": "tag-input/index.ts",
+      "content": "/** @krizaka/ui/tag-input — `TagInput` (free words as chips: separators, paste, suggestions, cleaning, validation). Client (\"use client\"). */\nexport { TagInput, type TagInputProps } from \"./tag-input\";\n"
+    },
+    {
+      "path": "tag-input/meta.ts",
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Tag input\",\n  summary: \"Free words as removable chips — Enter or a comma adds one, a paste adds several, suggestions complete, `normalize` cleans and `validate` refuses with a reason.\",\n  status: \"beta\",\n  category: \"forms\",\n  platforms: \"web\",\n  whenToUse: [\n    \"For keywords a person invents: the tags of a video, the topics of an article.\",\n    \"For a list of values typed one after the other: e-mail recipients, domains, IP addresses.\",\n  ],\n  whenNotToUse: [\n    { when: \"When the values come from a closed list: a combobox with `multiple`.\", use: \"combobox\" },\n    { when: \"For one free value: a plain field.\", use: \"field\" },\n  ],\n  bestPractices: [\n    \"Normalise the way the product stores tags (lower case, no `#`, no spaces) so “#Sunset” and “sunset” are one tag.\",\n    \"Say the limit and the separator in `hint` (“Up to 10 tags, separated by commas”).\",\n    \"Offer the person's own history first in `suggestions`, then a curated list.\",\n    \"Explain a refusal in words in `validate` (“Use letters and numbers only”).\",\n  ],\n  accessibility: {\n    keyboard: [\n      { keys: \"Enter / ,\", action: \"Add the typed word as a tag (or the active suggestion).\" },\n      { keys: \"Backspace\", action: \"In an empty input, remove the last tag.\" },\n      { keys: \"Arrow Down / Arrow Up\", action: \"Move through the suggestions.\" },\n    ],\n    notes: [\n      \"Built on `Combobox` (multiple, creatable): the same combobox pattern and announcements.\",\n      \"A refusal from `validate` is shown under the field and read with it (`aria-describedby`, `aria-invalid`).\",\n      \"Each tag's remove button is named by `labels.remove` (“Remove sunset”).\",\n    ],\n  },\n  related: [\"combobox\", \"chip\", \"field\"],\n  web: {\n    imports: [\"TagInput\"],\n    examples: [\n      { name: \"video-tags\", title: \"Tags of a video\", description: \"Suggestions, lower case without `#`, at most 10.\" },\n      { name: \"recipients\", title: \"E-mail recipients\", description: \"`validate` refuses what is not an address; a comma or a space adds one.\" },\n    ],\n  },\n} satisfies ComponentMeta;\n"
+    },
+    {
+      "path": "tag-input/tag-input.tsx",
+      "content": "// Client. Free words as chips — the multiple, creatable `Combobox` on strings: Enter or a separator adds the word,\n// a paste of \"a, b, c\" adds three, Backspace on an empty input removes the last, suggestions complete as you type.\n// `normalize` cleans a word (lower case, no `#`), `validate` refuses one with a reason read aloud.\nimport * as React from \"react\";\n\nimport { Combobox, type ComboboxLabels, type ComboboxOption } from \"../combobox\";\nimport { useControllable } from \"../media\";\n\nexport type TagInputProps = {\n  /** The visible label, passed translated (also the accessible name). */\n  label: string;\n  /** Hides the label visually, keeping it as the accessible name. */\n  hideLabel?: boolean;\n  /** The tags (controlled). */\n  value?: readonly string[];\n  /** The tags at first, uncontrolled. */\n  defaultValue?: readonly string[];\n  /** Called with every tag after a change. */\n  onValueChange?: (tags: string[]) => void;\n  /** Words offered as the person types (their own history, a curated list). */\n  suggestions?: readonly string[];\n  /** Cleans a word before it is added (`(t) => t.toLowerCase().replace(/^#/, \"\")`). An empty result is ignored. */\n  normalize?: (tag: string) => string;\n  /** Refuses a word: return the reason (passed translated), shown and read as the field's error; `null` accepts it. */\n  validate?: (tag: string, tags: readonly string[]) => string | null;\n  /** Most tags; the field stops offering more past it. */\n  max?: number;\n  /** Keys that add the word, besides Enter. Default `[\",\"]`. */\n  separators?: readonly string[];\n  /** The input's placeholder, passed translated. */\n  placeholder?: string;\n  /** A help text under the field (\"Up to 10 tags, separated by commas\"). */\n  hint?: string;\n  /** An error from the app (a server refusal); `validate`'s own errors show here too. */\n  error?: string;\n  /** Not available. */\n  disabled?: boolean;\n  /** The name of the hidden inputs, for a plain `<form>` post (one per tag). */\n  name?: string;\n  /** The words of the field, passed translated; English by default. */\n  labels?: Partial<Pick<ComboboxLabels, \"create\" | \"remove\" | \"empty\" | \"results\" | \"toggle\">>;\n  /** Classes merged on the root. */\n  className?: string;\n};\n\nconst toOption = (tag: string): ComboboxOption => ({ value: tag, label: tag });\n\n/** Words as removable chips — tags, keywords, e-mail recipients — with suggestions, cleaning and validation. */\nexport function TagInput({\n  value,\n  defaultValue = [],\n  onValueChange,\n  suggestions = [],\n  normalize = (tag) => tag.trim(),\n  validate,\n  max,\n  separators = [\",\"],\n  error,\n  labels,\n  ...props\n}: TagInputProps) {\n  const [tags, setTags] = useControllable<readonly string[]>(value, defaultValue, onValueChange as (next: readonly string[]) => void);\n  const [refusal, setRefusal] = React.useState<string | null>(null);\n\n  const change = (options: ComboboxOption[]) => {\n    const next: string[] = [];\n    for (const option of options) {\n      const tag = normalize(option.value);\n      if (!tag || next.includes(tag)) continue;\n      if (!tags.includes(tag)) {\n        const reason = validate?.(tag, next) ?? null;\n        if (reason) {\n          setRefusal(reason);\n          continue;\n        }\n      }\n      next.push(tag);\n    }\n    if (next.length >= options.length || options.length < tags.length) setRefusal(null);\n    setTags(next);\n  };\n\n  return (\n    <Combobox\n      {...props}\n      multiple\n      creatable\n      separators={separators}\n      maxSelected={max}\n      value={tags.map(toOption)}\n      onValueChange={change}\n      options={suggestions.map(toOption)}\n      error={refusal ?? error}\n      labels={{ empty: \"\", results: () => \"\", ...labels }}\n    />\n  );\n}\n"
+    }
+  ],
+  "dependencies": [],
+  "registryDependencies": [
+    "combobox"
+  ],
+  "demo": {
+    "path": "examples/tag-input/video-tags.tsx",
+    "content": "\"use client\";\n\nimport { TagInput } from \"@krizaka/ui/tag-input\";\nimport * as React from \"react\";\n\n// Lower case, no “#”: “#Sunset” and “sunset” are one tag.\nexport default function TagInputVideoTags() {\n  const [tags, setTags] = React.useState([\"montreal\", \"sunset\"]);\n  return (\n    <TagInput\n      label=\"Tags\"\n      placeholder=\"Add a tag\"\n      value={tags}\n      onValueChange={setTags}\n      suggestions={[\"timelapse\", \"travel\", \"skyline\", \"golden hour\", \"drone\"]}\n      normalize={(tag) => tag.trim().toLowerCase().replace(/^#/, \"\")}\n      max={10}\n      hint=\"Up to 10 tags, separated by commas.\"\n      labels={{ create: (tag) => `Add “${tag}”`, remove: (tag) => `Remove ${tag}` }}\n    />\n  );\n}\n"
+  },
+  "props": [
+    {
+      "component": "TagInput",
+      "description": "Words as removable chips — tags, keywords, e-mail recipients — with suggestions, cleaning and validation.",
+      "props": [
+        {
+          "name": "label",
+          "type": "string",
+          "default": null,
+          "description": "The visible label, passed translated (also the accessible name).",
+          "required": true
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "default": null,
+          "description": "Classes merged on the root.",
+          "required": false
+        },
+        {
+          "name": "defaultValue",
+          "type": "readonly string[]",
+          "default": "[]",
+          "description": "The tags at first, uncontrolled.",
+          "required": false
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "default": null,
+          "description": "Not available.",
+          "required": false
+        },
+        {
+          "name": "error",
+          "type": "string",
+          "default": null,
+          "description": "An error from the app (a server refusal); `validate`'s own errors show here too.",
+          "required": false
+        },
+        {
+          "name": "hideLabel",
+          "type": "boolean",
+          "default": null,
+          "description": "Hides the label visually, keeping it as the accessible name.",
+          "required": false
+        },
+        {
+          "name": "hint",
+          "type": "string",
+          "default": null,
+          "description": "A help text under the field (\"Up to 10 tags, separated by commas\").",
+          "required": false
+        },
+        {
+          "name": "labels",
+          "type": "Partial<Pick<ComboboxLabels, \"results\" | \"toggle\" | \"remove\" | \"empty\" | \"create\">>",
+          "default": null,
+          "description": "The words of the field, passed translated; English by default.",
+          "required": false
+        },
+        {
+          "name": "max",
+          "type": "number",
+          "default": null,
+          "description": "Most tags; the field stops offering more past it.",
+          "required": false
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "default": null,
+          "description": "The name of the hidden inputs, for a plain `<form>` post (one per tag).",
+          "required": false
+        },
+        {
+          "name": "normalize",
+          "type": "((tag: string) => string)",
+          "default": "(tag) => tag.trim()",
+          "description": "Cleans a word before it is added (`(t) => t.toLowerCase().replace(/^#/, \"\")`). An empty result is ignored.",
+          "required": false
+        },
+        {
+          "name": "onValueChange",
+          "type": "((tags: string[]) => void)",
+          "default": null,
+          "description": "Called with every tag after a change.",
+          "required": false
+        },
+        {
+          "name": "placeholder",
+          "type": "string",
+          "default": null,
+          "description": "The input's placeholder, passed translated.",
+          "required": false
+        },
+        {
+          "name": "separators",
+          "type": "readonly string[]",
+          "default": "[\",\"]",
+          "description": "Keys that add the word, besides Enter. Default `[\",\"]`.",
+          "required": false
+        },
+        {
+          "name": "suggestions",
+          "type": "readonly string[]",
+          "default": "[]",
+          "description": "Words offered as the person types (their own history, a curated list).",
+          "required": false
+        },
+        {
+          "name": "validate",
+          "type": "((tag: string, tags: readonly string[]) => string | null)",
+          "default": null,
+          "description": "Refuses a word: return the reason (passed translated), shown and read as the field's error; `null` accepts it.",
+          "required": false
+        },
+        {
+          "name": "value",
+          "type": "readonly string[]",
+          "default": null,
+          "description": "The tags (controlled).",
+          "required": false
+        }
+      ]
+    }
+  ]
+}

package/registry/theme.json

@@ -92,7 +92,7 @@
           },
           {
             "name": "shape",
-            "type": "\"rounded\" | \"pill\"",
+            "type": "\"rounded\" | \"pill\" | \"cut\"",
             "default": "rounded",
             "description": "rounded · pill.",
             "required": false
@@ -191,7 +191,7 @@
   "files": [
     {
       "path": "meta.ts",
-      "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 krizaka.com renders as\n// /docs/ui/<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  | \"alert\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"cn\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"kbd\"\n  | \"mascots\"\n  | \"page-header\"\n  | \"popover\"\n  | \"progress\"\n  | \"radio-group\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"stat\"\n  | \"switch\"\n  | \"tabs\"\n  | \"theme\"\n  | \"toast\"\n  | \"tooltip\"\n  | \"txt\";\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/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/** The group of the catalogue. */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"layout\" | \"foundations\";\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 */\nexport interface Example {\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/** 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  /** What differs from the web API (`label` instead of children…); empty for a native-only component. */\n  readonly differences: readonly string[];\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  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\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"
+      "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 krizaka.com renders as\n// /docs/ui/<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  | \"alert\"\n  | \"audio-player\"\n  | \"avatar\"\n  | \"badge\"\n  | \"button\"\n  | \"card\"\n  | \"checkbox\"\n  | \"chip\"\n  | \"chip-link\"\n  | \"cn\"\n  | \"combobox\"\n  | \"command\"\n  | \"confirm-button\"\n  | \"countdown\"\n  | \"data-table\"\n  | \"date-picker\"\n  | \"dialog\"\n  | \"dropdown-menu\"\n  | \"empty-state\"\n  | \"field\"\n  | \"file-upload\"\n  | \"filter-bar\"\n  | \"glow-card\"\n  | \"image-cropper\"\n  | \"iso\"\n  | \"kbd\"\n  | \"loader\"\n  | \"marquee\"\n  | \"mascots\"\n  | \"media-capture\"\n  | \"meter\"\n  | \"nav-bar\"\n  | \"number-ticker\"\n  | \"page-header\"\n  | \"pagination\"\n  | \"popover\"\n  | \"progress\"\n  | \"radio-group\"\n  | \"search-field\"\n  | \"section-backdrop\"\n  | \"segmented\"\n  | \"separator\"\n  | \"skeleton\"\n  | \"slider\"\n  | \"slot\"\n  | \"spinner\"\n  | \"stat\"\n  | \"stepper\"\n  | \"switch\"\n  | \"tabs\"\n  | \"tag-input\"\n  | \"theme\"\n  | \"toast\"\n  | \"tooltip\"\n  | \"txt\"\n  | \"video-player\"\n  | \"video-trimmer\";\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/** `stable`: its API only changes in a major. `beta`: it may still change in a minor. */\nexport type Status = \"stable\" | \"beta\";\n\n/** The group of the catalogue. `media`: video, sound, camera, files, cropping. */\nexport type Category = \"actions\" | \"forms\" | \"navigation\" | \"overlays\" | \"feedback\" | \"data-display\" | \"media\" | \"layout\" | \"foundations\";\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 */\nexport interface Example {\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/** 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}\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  readonly category: Category;\n  /** Must match the sides below: `both` ⇔ `web` and `native`. */\n  readonly platforms: Platform;\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"
     },
     {
       "path": "theme/index.ts",
@@ -261,7 +261,7 @@
         },
         {
           "name": "shape",
-          "type": "\"rounded\" | \"pill\"",
+          "type": "\"rounded\" | \"pill\" | \"cut\"",
           "default": "rounded",
           "description": "rounded · pill.",
           "required": false