{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "checkbox-group",
  "title": "CheckboxGroup",
  "description": "A group of checkboxes under one legend, on the Field contract, for picking any number of choices: pass `legend`, and `options` (or `Checkbox` children).",
  "dependencies": [
    "@base-ui/react@^1.8.0"
  ],
  "registryDependencies": [
    "@ouro/checkbox",
    "@ouro/field",
    "@ouro/lib-dev",
    "@ouro/lib-env",
    "@ouro/lib-refs",
    "@ouro/lib-use-dev-messages",
    "@ouro/lib-use-field"
  ],
  "files": [
    {
      "path": "registry/ouro/components/ouro/checkbox/checkbox-group.tsx",
      "content": "\"use client\";\n\nimport { CheckboxGroup as BaseCheckboxGroup } from \"@base-ui/react/checkbox-group\";\nimport { useEffect, useMemo, useRef, useState, type JSX, type ReactNode, type Ref } from \"react\";\nimport { Checkbox } from \"@/registry/ouro/components/ouro/checkbox/checkbox\";\nimport { Field } from \"@/registry/ouro/components/ouro/field/field\";\nimport { choicesClass, contractWarnings } from \"@/registry/ouro/components/ouro/field/field-styles\";\nimport { devThrow } from \"@/registry/ouro/lib/ouro/dev\";\nimport { useMergedRef } from \"@/registry/ouro/lib/ouro/refs\";\nimport { FieldOwnerContext, useField, type ReadonlyErrorMessages } from \"@/registry/ouro/lib/ouro/use-field\";\nimport { useDevWarnings } from \"@/registry/ouro/lib/ouro/use-dev-messages\";\n\n/** One choice in a {@link CheckboxGroup}'s `options`. */\nexport interface CheckboxGroupOption {\n  /** What the box submits, and its entry in the group's `value`. */\n  value: string;\n  /** The choice's name, shown to the right of its box. */\n  label: string;\n  /** Supporting text under the label, read after it. */\n  description?: ReactNode | undefined;\n  /** Disables this one box. */\n  disabled?: boolean | undefined;\n}\n\n/** The props CheckboxGroup takes whichever way its choices are given. */\nexport interface CheckboxGroupOwnProps {\n  /**\n   * What the group is, shown above the choices and read as the group's name. Required: a\n   * group of controls needs a name. To hide it visually, keep it and add `hideLegend`.\n   */\n  legend: string;\n  /** Hides the legend visually; screen readers still read it as the group's name. */\n  hideLegend?: boolean | undefined;\n  /** Supporting text under the legend, read after it through `aria-describedby`. */\n  description?: ReactNode | undefined;\n  /**\n   * What is wrong, from your server action or client check, shown under the choices; every\n   * box gets `aria-invalid`. A message is text or a React node (one with a link); an empty string or array means valid.\n   * @claim \"What is wrong, from your server\" registry/ouro/components/ouro/checkbox/checkbox-group.test.tsx verify:testExists(registry/ouro/components/ouro/checkbox/checkbox-group.test.tsx::CheckboxGroup > marks the boxes invalid with error)\n   */\n  error?: ReadonlyErrorMessages | undefined;\n  /**\n   * At least one box must be checked to submit the form: the legend gets a marker (and\n   * `requiredLabel` for screen readers), and the browser shows `requiredMessage` until one is\n   * checked. HTML has no native \"at least one\" rule for checkboxes, so this check runs only\n   * once the page has hydrated: your server action must still check it.\n   * @claim \"rule for checkboxes, so this check runs only\" registry/ouro/components/ouro/checkbox/checkbox-group.test.tsx verify:testExists(registry/ouro/components/ouro/checkbox/checkbox-group.test.tsx::CheckboxGroup > required marks the legend and blocks submit until a box is checked)\n   * @claim \"rule for checkboxes, so this check runs only\" https://html.spec.whatwg.org/multipage/input.html#checkbox-state-(type=checkbox) verify:urlOk(https://html.spec.whatwg.org/multipage/input.html#checkbox-state-(type=checkbox))\n   */\n  required?: boolean | undefined;\n  /** What the browser says when `required` and nothing is checked. Translate it here. @default \"Choose at least one.\" */\n  requiredMessage?: string | undefined;\n  /**\n   * What screen readers hear after the legend when `required`, since no box can carry\n   * `aria-required`; the asterisk is what shows. Translate it here. @default \"(required)\"\n   * @claim \"What screen readers hear after the\" registry/ouro/components/ouro/checkbox/checkbox-group.test.tsx verify:testExists(registry/ouro/components/ouro/checkbox/checkbox-group.test.tsx::CheckboxGroup > announces required in the group's name, since no box carries aria-required)\n   */\n  requiredLabel?: string | undefined;\n  /**\n   * Disables every box and fades the group.\n   *\n   * @claim \"Disables every box and fades the\" registry/ouro/components/ouro/checkbox/checkbox-group.test.tsx verify:testExists(registry/ouro/components/ouro/checkbox/checkbox-group.test.tsx::CheckboxGroup > disables every box with disabled)\n   */\n  disabled?: boolean | undefined;\n  /**\n   * The form field name every checked box submits under, once per checked value.\n   *\n   * @claim \"The form field name every checked\" registry/ouro/components/ouro/checkbox/checkbox-group.test.tsx verify:testExists(registry/ouro/components/ouro/checkbox/checkbox-group.test.tsx::CheckboxGroup > submits name=value for each checked box)\n   */\n  name?: string | undefined;\n  /** The checked values, for a controlled group; pair it with `onValueChange`. */\n  value?: string[] | undefined;\n  /** The values checked at first, for an uncontrolled group. */\n  defaultValue?: string[] | undefined;\n  /**\n   * Called with every checked value, in the order they were checked, when one is checked or unchecked.\n   *\n   * @claim \"Called with every checked value, in\" registry/ouro/components/ouro/checkbox/checkbox-group.test.tsx verify:testExists(registry/ouro/components/ouro/checkbox/checkbox-group.test.tsx::CheckboxGroup > keeps the group's value: defaultValue, toggling with Space and clicks, and onValueChange)\n   */\n  onValueChange?: ((value: string[]) => void) | undefined;\n  /**\n   * Layout only: margins, width, grid placement (`mt-4`, `col-span-2`). Appearance classes\n   * warn in development; style checkboxes in your theme.\n   */\n  className?: string | undefined;\n  /** The group element, a `<div role=\"group\">`. */\n  ref?: Ref<HTMLDivElement> | undefined;\n\n  /** Not a prop. A group is named by its `legend`: `<CheckboxGroup legend=\"Herbs\">`. */\n  label?: { 'Use <CheckboxGroup legend=\"Herbs\">': never };\n  /** Not a prop. Ouro UI uses `onValueChange`, which gets the checked values: `onValueChange={setValues}`. */\n  onChange?: { 'Use onValueChange={setValues}': never };\n  /** Not a prop. Ouro UI uses `options`: `options={[{ value: \"basil\", label: \"Basil\" }]}`. */\n  items?: { 'Use options={[{ value: \"basil\", label: \"Basil\" }]}': never };\n  /** Not a prop. Ouro UI uses `error`: `<CheckboxGroup error=\"Required.\">`. */\n  errorMessage?: { 'Use <CheckboxGroup error=\"Required.\">': never };\n  /** Not a prop. Ouro UI uses `description`: `<CheckboxGroup description=\"...\">`. */\n  helperText?: { 'Use <CheckboxGroup description=\"...\">': never };\n  /** Not a prop. `error` marks the group invalid: `<CheckboxGroup error=\"What is wrong\">`. */\n  isInvalid?: { 'Use <CheckboxGroup error=\"What is wrong\">': never };\n  /** Not a prop. `error` marks the group invalid: `<CheckboxGroup error=\"What is wrong\">`. */\n  invalid?: { 'Use <CheckboxGroup error=\"What is wrong\">': never };\n  /** Not a prop. Ouro UI uses `required`: `<CheckboxGroup required>`. */\n  isRequired?: { 'Use <CheckboxGroup required>': never };\n  /** Not a prop. Ouro UI uses `disabled`: `<CheckboxGroup disabled>`. */\n  isDisabled?: { 'Use <CheckboxGroup disabled>': never };\n}\n\n/**\n * Props for {@link CheckboxGroup}: the choices as `options`, or as `Checkbox` children, not\n * both.\n */\nexport type CheckboxGroupProps = CheckboxGroupOwnProps &\n  (\n    | {\n        /**\n         * The choices, one box each, in order.\n         *\n         * @claim \"The choices, one box each, in\" registry/ouro/components/ouro/checkbox/checkbox-group.test.tsx verify:testExists(registry/ouro/components/ouro/checkbox/checkbox-group.test.tsx::CheckboxGroup > submits name=value for each checked box)\n         */\n        options: CheckboxGroupOption[];\n        /** Not with `options`: pass the choices one way. */\n        children?: never;\n      }\n    | {\n        /**\n         * The choices as `Checkbox` elements, each with a `value`, for a layout `options` cannot express.\n         *\n         * @claim \"The choices as `Checkbox` elements, each\" registry/ouro/components/ouro/checkbox/checkbox-group.test.tsx verify:testExists(registry/ouro/components/ouro/checkbox/checkbox-group.test.tsx::CheckboxGroup > lays out the choices in a column, 20px apart on touch-sized screens)\n         */\n        children: ReactNode;\n        /** Not with children: pass the choices one way. */\n        options?: never;\n      }\n  );\n\n/** Field's messages and root name CheckboxGroup, and use the label as the group's legend. */\nconst owner = { name: \"CheckboxGroup\", data: \"checkbox-group\", layout: \"group\" } as const;\n\n/** The group, inside the Field: it takes its name and description ids from the field. */\nfunction Choices(props: {\n  value: string[] | undefined;\n  defaultValue: string[] | undefined;\n  onValueChange: ((value: string[]) => void) | undefined;\n  requiredMessage: string;\n  ref: Ref<HTMLDivElement> | undefined;\n  children: ReactNode;\n}): JSX.Element {\n  const { value, defaultValue, onValueChange, requiredMessage, ref, children } = props;\n  const field = useField()!;\n  const [uncontrolled, setUncontrolled] = useState(defaultValue ?? []);\n  const checked = value ?? uncontrolled;\n  const groupRef = useRef<HTMLDivElement>(null);\n  const setRef = useMergedRef(ref, groupRef);\n\n  // A checkbox group has no native `required`, so the first enabled box carries the message\n  // while nothing is checked: the form does not submit, and the browser points at the group.\n  const missing = field.required && checked.length === 0;\n  useEffect(() => {\n    const inputs = [...groupRef.current!.querySelectorAll<HTMLInputElement>('input[type=\"checkbox\"]')];\n    const first = inputs.find((input) => !input.disabled);\n    for (const input of inputs) input.setCustomValidity(missing && input === first ? requiredMessage : \"\");\n  });\n\n  return (\n    <BaseCheckboxGroup\n      ref={setRef}\n      value={value}\n      defaultValue={defaultValue}\n      onValueChange={(next) => {\n        setUncontrolled(next);\n        onValueChange?.(next);\n      }}\n      // Set here, not left to Base UI's effects, so the server HTML names and describes the group.\n      aria-labelledby={field.labelId}\n      aria-describedby={field.describedBy}\n      className={choicesClass.vertical}\n    >\n      {children}\n    </BaseCheckboxGroup>\n  );\n}\n\n/**\n * A group of checkboxes under one legend, on the Field contract, for picking any number of\n * choices: pass `legend`, and `options` (or `Checkbox` children). `value` is the list of\n * checked values; with `name`, each checked box submits `name=value` with its form.\n * `error` and `required` apply to the whole group.\n *\n * Use `RadioGroup` instead when exactly one choice may be picked, `Checkbox` for a single\n * yes-or-no choice, and `Fieldset` to group different fields.\n *\n * @group Forms\n * @see https://ui.ouroboros.bot/docs/checkbox-group\n *\n * @example\n * <CheckboxGroup\n *   legend=\"Herbs\"\n *   name=\"herbs\"\n *   defaultValue={[\"basil\"]}\n *   options={[\n *     { value: \"basil\", label: \"Basil\", description: \"Sweet and peppery.\" },\n *     { value: \"mint\", label: \"Mint\" },\n *   ]}\n * />\n * @claim \"`value` is the list of checked\" registry/ouro/components/ouro/checkbox/checkbox-group.test.tsx verify:testExists(registry/ouro/components/ouro/checkbox/checkbox-group.test.tsx::CheckboxGroup > submits name=value for each checked box)\n */\nexport function CheckboxGroup(props: CheckboxGroupProps): JSX.Element {\n  const {\n    legend,\n    hideLegend,\n    description,\n    error,\n    required,\n    requiredMessage = \"Choose at least one.\",\n    requiredLabel = \"(required)\",\n    disabled,\n    name,\n    value,\n    defaultValue,\n    onValueChange,\n    options,\n    children,\n    className,\n    ref,\n    // Guard props (hint types), dropped here so they never reach the DOM.\n    label,\n    onChange,\n    items,\n    errorMessage,\n    helperText,\n    isInvalid,\n    invalid,\n    isRequired,\n    isDisabled,\n  } = props;\n  if (options !== undefined && children !== undefined) {\n    devThrow(\n      \"CheckboxGroup\",\n      \"takes options or Checkbox children, not both\",\n      process.env.NODE_ENV !== \"production\"\n        ? `<CheckboxGroup legend=\"${legend}\" options={options} />, or <CheckboxGroup legend=\"${legend}\"><Checkbox value=\"basil\" label=\"Basil\" /></CheckboxGroup>`\n        : /* istanbul ignore next @preserve -- production only */ \"\",\n    );\n  }\n\n  const groupOwner = useMemo(() => ({ ...owner, requiredLabel }), [requiredLabel]);\n\n  useDevWarnings(\n    \"CheckboxGroup\",\n    process.env.NODE_ENV !== \"production\"\n      ? () => [\n          ...contractWarnings(\"CheckboxGroup\", { errorMessage, helperText, isInvalid, invalid, isRequired, isDisabled }),\n          label !== undefined && [\"label is not a prop; a group is named by its legend\", `<CheckboxGroup legend=\"${String(label)}\">`],\n          onChange !== undefined && [\"onChange is not a prop; onValueChange gets the checked values\", \"<CheckboxGroup onValueChange={(values) => setValues(values)}>\"],\n          items !== undefined && [\"items is not a prop\", '<CheckboxGroup options={[{ value: \"basil\", label: \"Basil\" }]}>'],\n          value !== undefined && !onValueChange && [\"value without onValueChange never changes\", \"<CheckboxGroup value={values} onValueChange={setValues}>, or defaultValue\"],\n        ]\n      : /* istanbul ignore next @preserve -- production only */ undefined,\n  );\n\n  return (\n    <FieldOwnerContext.Provider value={groupOwner}>\n      <Field\n        label={legend}\n        hideLabel={hideLegend}\n        description={description}\n        error={error}\n        required={required}\n        disabled={disabled}\n        name={name}\n        className={className}\n      >\n        <Choices value={value} defaultValue={defaultValue} onValueChange={onValueChange} requiredMessage={requiredMessage} ref={ref}>\n          {options\n            ? options.map((option) => (\n                <Checkbox key={option.value} value={option.value} label={option.label} description={option.description} disabled={option.disabled} />\n              ))\n            : children}\n        </Choices>\n      </Field>\n    </FieldOwnerContext.Provider>\n  );\n}\n",
      "type": "registry:ui",
      "target": "@components/ouro/checkbox/checkbox-group.tsx"
    }
  ],
  "docs": "A group of checkboxes under one legend, on the Field contract, for picking any number of choices: pass `legend`, and `options` (or `Checkbox` children). Import: import { CheckboxGroup } from \"@/components/ouro/checkbox/checkbox-group\", with @/components replaced by your components alias (aliases.components in components.json, such as ~/components). Also installed: checkbox, field, the helpers they import in lib/ouro. Needs ouro-base in your stylesheet: add that item once per app, from the same place as this one, if you have not. Docs: https://ui.ouroboros.bot/docs/checkbox-group.md Ouro UI v1.3.257.",
  "type": "registry:ui"
}