{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "certainty-legend",
  "type": "registry:ui",
  "title": "Certainty Legend",
  "description": "A small key of three or four named classes (how sure something is, or any other kind), each with its own pattern as well as its own colour, where each class can be switched off and on.",
  "categories": [
    "ui"
  ],
  "dependencies": [
    "lucide-react"
  ],
  "registryDependencies": [
    "@rivier-ui/theme",
    "@rivier-ui/cn",
    "@rivier-ui/use-controllable-state"
  ],
  "files": [
    {
      "path": "registry/ui/certainty-legend.tsx",
      "type": "registry:ui",
      "target": "components/ui/certainty-legend.tsx",
      "content": "\"use client\";\n/**\n * @name certainty-legend\n * @category ui\n * @description A small key of three or four named classes (how sure something is, or any other kind), each with its own pattern as well as its own colour, where each class can be switched off and on.\n * @when A scene, a map, a drawing or a chart marks its parts by class and the reader needs the key and a way to hide a class: what is recorded, what is worked out, what is a guess. The project supplies the names; the legend reports which classes are shown (`onValueChange`) and the project applies that to its own scene. Use CertaintySwatch to draw the same pattern in the scene's own key or in a caption. The pattern is what tells classes apart for someone who cannot tell the colours apart, so use it in the scene too. For filters with no key use chip; for the series of a chart, the chart's own legend.\n * @example\n * const classes = [\n *   { id: \"recorded\", label: \"Recorded\", description: \"Measured on site\" },\n *   { id: \"inferred\", label: \"Inferred\", description: \"Worked out from what remains\" },\n *   { id: \"imagined\", label: \"Imagined\", description: \"A guess, drawn to complete the picture\" },\n * ];\n * <CertaintyLegend aria-label=\"How sure each part is\" classes={classes} defaultValue={[\"recorded\", \"inferred\", \"imagined\"]} onValueChange={(shown) => scene.show(shown)} />\n *\n * // The same pattern elsewhere\n * <CertaintySwatch pattern=\"hatch\" tone={2} />\n */\nimport { Eye, EyeOff } from \"lucide-react\";\nimport { createContext, use, useId, type ComponentProps, type ReactNode } from \"react\";\nimport { cn } from \"@/lib/cn\";\nimport { useControllableState } from \"@/lib/use-controllable-state\";\n\n/** The patterns, in the order classes take them: the first class is solid, the second hatched, and so on. */\nexport const CERTAINTY_PATTERNS = [\"solid\", \"hatch\", \"dots\", \"cross\"] as const;\nexport type CertaintyPattern = (typeof CERTAINTY_PATTERNS)[number];\n/** One of the theme's first four chart colours. */\nexport type CertaintyTone = 1 | 2 | 3 | 4;\n\nexport type CertaintyClass = {\n  id: string;\n  /** Its name. */\n  label: string;\n  /** A line under the name saying what the class means. */\n  description?: string;\n  /** Its pattern. Left out: by its place in the list. */\n  pattern?: CertaintyPattern;\n  /** Its colour. Left out: by its place in the list. */\n  tone?: CertaintyTone;\n};\n\nconst TONE: Record<CertaintyTone, string> = { 1: \"text-chart-1\", 2: \"text-chart-2\", 3: \"text-chart-3\", 4: \"text-chart-4\" };\n\n/** The pattern and colour a class takes from its place in the list (0 is the first). */\nexport function certaintyStyle(index: number): { pattern: CertaintyPattern; tone: CertaintyTone } {\n  const at = ((index % 4) + 4) % 4;\n  return { pattern: CERTAINTY_PATTERNS[at] ?? \"solid\", tone: (at + 1) as CertaintyTone };\n}\n\nexport type CertaintySwatchProps = Omit<ComponentProps<\"svg\">, \"children\"> & {\n  pattern?: CertaintyPattern;\n  tone?: CertaintyTone;\n};\n\n/**\n * A square filled with one pattern in one of the theme's chart colours. Decoration: it is hidden from\n * assistive technology, and the name beside it says what it stands for. Size it with `className` (`size-6`).\n */\nexport function CertaintySwatch({ className, pattern = \"solid\", tone = 1, ...props }: CertaintySwatchProps) {\n  const id = useId();\n  return (\n    <svg data-slot=\"certainty-swatch\" data-pattern={pattern} viewBox=\"0 0 16 16\" aria-hidden=\"true\" className={cn(\"size-4 shrink-0\", TONE[tone], className)} {...props}>\n      {pattern === \"solid\" ? null : (\n        <defs>\n          <pattern id={id} width={pattern === \"dots\" ? 16 / 3 : 4} height={pattern === \"dots\" ? 16 / 3 : 4} patternUnits=\"userSpaceOnUse\">\n            {pattern === \"hatch\" ? <path d=\"M-1 1 L1 -1 M0 4 L4 0 M3 5 L5 3\" stroke=\"currentColor\" strokeWidth=\"1.25\" /> : null}\n            {pattern === \"dots\" ? <circle cx={8 / 3} cy={8 / 3} r=\"1.3\" fill=\"currentColor\" /> : null}\n            {pattern === \"cross\" ? <path d=\"M0 2 H4 M2 0 V4\" stroke=\"currentColor\" strokeWidth=\"1\" /> : null}\n          </pattern>\n        </defs>\n      )}\n      <rect x=\"0.75\" y=\"0.75\" width=\"14.5\" height=\"14.5\" fill={pattern === \"solid\" ? \"currentColor\" : `url(#${id})`} stroke=\"currentColor\" strokeWidth=\"1.5\" />\n    </svg>\n  );\n}\n\ntype CertaintyLegendContextValue = { shown: readonly string[]; toggle: (id: string) => void; disabled: boolean };\n\nconst CertaintyLegendContext = createContext<CertaintyLegendContextValue | null>(null);\n\nexport type CertaintyLegendProps = Omit<ComponentProps<\"div\">, \"defaultValue\" | \"onChange\"> & {\n  /** The classes, in order. Left out, compose CertaintyLegendItem children yourself. */\n  classes?: readonly CertaintyClass[];\n  /** The ids of the classes that are shown: controlled. */\n  value?: readonly string[];\n  /** The classes shown at the start when uncontrolled. Default: every class in `classes`. */\n  defaultValue?: readonly string[];\n  /** Called with the ids now shown, in the order of `classes`, when one is switched. */\n  onValueChange?: (shown: string[], changed: { id: string; shown: boolean }) => void;\n  /** The classes cannot be switched: a key only. */\n  disabled?: boolean;\n  /** The items, when composed by hand. */\n  children?: ReactNode;\n};\n\n/**\n * A named group of toggle buttons: name it with `aria-label` or `aria-labelledby` (\"How sure each part\n * is\"). Each button carries `aria-pressed` (pressed means shown), read when focus reaches it and when it\n * changes, so the legend announces nothing more. It applies nothing itself: the project hides and shows\n * the class in its own scene from `onValueChange`.\n */\nexport function CertaintyLegend({ className, classes, value, defaultValue, onValueChange, disabled = false, children, ...props }: CertaintyLegendProps) {\n  const order = classes?.map((item) => item.id) ?? [];\n  const [shown, setShown] = useControllableState<readonly string[]>({ value, defaultValue: defaultValue ?? order });\n\n  const toggle = (id: string): void => {\n    const on = !shown.includes(id);\n    const next = on ? [...shown, id] : shown.filter((other) => other !== id);\n    // In the order of the classes, so the value does not depend on the order of the presses.\n    const sorted = [...next].sort((a, b) => (order.indexOf(a) === -1 ? order.length : order.indexOf(a)) - (order.indexOf(b) === -1 ? order.length : order.indexOf(b)));\n    setShown(sorted);\n    onValueChange?.(sorted, { id, shown: on });\n  };\n\n  return (\n    <CertaintyLegendContext value={{ shown, toggle, disabled }}>\n      <div data-slot=\"certainty-legend\" role=\"group\" className={cn(\"flex min-w-0 flex-wrap gap-2\", className)} {...props}>\n        {children ??\n          classes?.map((item, index) => {\n            const style = certaintyStyle(index);\n            return (\n              <CertaintyLegendItem key={item.id} value={item.id} pattern={item.pattern ?? style.pattern} tone={item.tone ?? style.tone} description={item.description}>\n                {item.label}\n              </CertaintyLegendItem>\n            );\n          })}\n      </div>\n    </CertaintyLegendContext>\n  );\n}\n\nexport type CertaintyLegendItemProps = Omit<ComponentProps<\"button\">, \"value\" | \"type\"> & {\n  /** The id of the class. */\n  value: string;\n  pattern?: CertaintyPattern;\n  tone?: CertaintyTone;\n  /** A line under the name. */\n  description?: ReactNode;\n};\n\n/**\n * One class: its swatch, its name, and whether it is shown. Switched off, it keeps its pattern and colour\n * (it is still the key) and is told apart by a crossed eye, a line through its name and `aria-pressed`,\n * never by fading alone.\n */\nexport function CertaintyLegendItem({ className, value, pattern = \"solid\", tone = 1, description, disabled, children, onClick, ...props }: CertaintyLegendItemProps) {\n  const context = use(CertaintyLegendContext);\n  if (!context) throw new Error(\"<CertaintyLegendItem> must be used inside <CertaintyLegend>.\");\n  const on = context.shown.includes(value);\n  const locked = disabled ?? context.disabled;\n  const Mark = on ? Eye : EyeOff;\n  return (\n    <button\n      type=\"button\"\n      data-slot=\"certainty-legend-item\"\n      data-state={on ? \"on\" : \"off\"}\n      data-class={value}\n      aria-pressed={on}\n      disabled={locked}\n      onClick={(event) => {\n        onClick?.(event);\n        if (!event.defaultPrevented) context.toggle(value);\n      }}\n      className={cn(\n        \"group/certainty inline-flex min-h-(--control-h) max-w-full min-w-0 items-center gap-2.5 rounded-control border border-input bg-background px-3 py-1.5 text-start text-sm text-foreground transition-colors duration-instant ease-out hover:bg-accent disabled:pointer-events-none aria-pressed:border-border-strong motion-reduce:transition-none\",\n        className,\n      )}\n      {...props}\n    >\n      <CertaintySwatch pattern={pattern} tone={tone} className=\"size-5\" />\n      <span className=\"flex min-w-0 flex-col\">\n        <span data-slot=\"certainty-legend-label\" dir=\"auto\" className=\"truncate font-medium group-data-[state=off]/certainty:line-through\">\n          {children}\n        </span>\n        {description ? (\n          <span data-slot=\"certainty-legend-description\" dir=\"auto\" className=\"text-xs text-muted-foreground\">\n            {description}\n          </span>\n        ) : null}\n      </span>\n      {locked ? null : <Mark aria-hidden=\"true\" strokeWidth={1.5} className=\"size-4 shrink-0 text-muted-foreground\" />}\n    </button>\n  );\n}\n"
    }
  ],
  "meta": {
    "category": "ui",
    "when": "A scene, a map, a drawing or a chart marks its parts by class and the reader needs the key and a way to hide a class: what is recorded, what is worked out, what is a guess. The project supplies the names; the legend reports which classes are shown (`onValueChange`) and the project applies that to its own scene. Use CertaintySwatch to draw the same pattern in the scene's own key or in a caption. The pattern is what tells classes apart for someone who cannot tell the colours apart, so use it in the scene too. For filters with no key use chip; for the series of a chart, the chart's own legend.",
    "example": "const classes = [\n  { id: \"recorded\", label: \"Recorded\", description: \"Measured on site\" },\n  { id: \"inferred\", label: \"Inferred\", description: \"Worked out from what remains\" },\n  { id: \"imagined\", label: \"Imagined\", description: \"A guess, drawn to complete the picture\" },\n];\n<CertaintyLegend aria-label=\"How sure each part is\" classes={classes} defaultValue={[\"recorded\", \"inferred\", \"imagined\"]} onValueChange={(shown) => scene.show(shown)} />\n\n// The same pattern elsewhere\n<CertaintySwatch pattern=\"hatch\" tone={2} />",
    "client": true
  }
}
