{
  "schemaVersion": 1,
  "target": "react",
  "name": "field",
  "version": "0.1.0",
  "category": "forms",
  "title": "Field",
  "description": "A field wrapper that wires a label, control, description, and validation error together with Base UI Field, plus a fieldset group.",
  "tags": [
    "form",
    "field",
    "validation",
    "fieldset",
    "base-ui"
  ],
  "requires": {
    "projectTypes": [
      "next",
      "vite-react"
    ],
    "styling": "tailwind-v4"
  },
  "npmDependencies": {
    "@base-ui/react": "^1.9.0"
  },
  "registryDependencies": [
    {
      "name": "label",
      "version": "0.1.0"
    },
    {
      "name": "input",
      "version": "0.1.1"
    },
    {
      "name": "textarea",
      "version": "0.1.1"
    }
  ],
  "docsPath": "/components/field",
  "props": [
    {
      "name": "validate",
      "type": "(value, formValues) => string | string[] | null",
      "description": "Field: custom validation. Return an error message to mark the field invalid."
    },
    {
      "name": "validationMode",
      "type": "\"onSubmit\" | \"onBlur\" | \"onChange\"",
      "default": "\"onSubmit\"",
      "description": "Field: when to validate."
    },
    {
      "name": "invalid",
      "type": "boolean",
      "description": "Field: forces the invalid state, for errors from a server or a form library."
    },
    {
      "name": "disabled",
      "type": "boolean",
      "default": "false",
      "description": "Field or FieldGroup: disables the control(s) inside."
    },
    {
      "name": "required / optional",
      "type": "boolean",
      "default": "false",
      "description": "FieldLabel: adds a required asterisk or an Optional note."
    },
    {
      "name": "render",
      "type": "ReactElement",
      "description": "FieldControl: render the existing Input or Textarea, e.g. render={<Input />}. Without it, a text input styled like Input is rendered."
    },
    {
      "name": "match",
      "type": "boolean | keyof ValidityState",
      "description": "FieldError: show only for one validity check, or always with true."
    },
    {
      "name": "legend / description",
      "type": "ReactNode",
      "description": "FieldGroup: names the fieldset and describes the group."
    }
  ],
  "accessibility": [
    "FieldLabel is bound to the control automatically; no htmlFor or id is needed.",
    "FieldDescription and a visible FieldError are linked to the control with aria-describedby.",
    "A failed check sets aria-invalid on the control, which also turns a rendered Input or Textarea border red.",
    "FieldGroup renders a <fieldset> whose legend names the group; its description is linked with aria-describedby.",
    "The error message eases in with a 2px rise and only fades under reduced motion."
  ],
  "states": [
    "default",
    "focus-visible",
    "invalid",
    "disabled"
  ],
  "files": [
    {
      "path": "ui/field.tsx",
      "content": "\"use client\";\n\nimport { Field as BaseField } from \"@base-ui/react/field\";\nimport { Fieldset as BaseFieldset } from \"@base-ui/react/fieldset\";\nimport { type ReactNode, useId } from \"react\";\nimport { Label } from \"./label\";\n\ntype ClassName<State> = string | ((state: State) => string | undefined) | undefined;\n\nfunction cx(...classes: (string | false | null | undefined)[]) {\n  return classes.filter(Boolean).join(\" \");\n}\n\n/** Prepends base classes while keeping Base UI's state-function form of className working. */\nfunction withBase<State>(base: string, className: ClassName<State>) {\n  return typeof className === \"function\" ? (state: State) => cx(base, className(state)) : cx(base, className);\n}\n\n/**\n * Groups a label, a control, a description, and an error, and wires them together: the label\n * names the control, the description and error describe it, and the control gets `aria-invalid`\n * when validation fails. Pass `validate` and `validationMode` to validate on submit, blur, or change.\n */\nexport function Field({ className, ...props }: BaseField.Root.Props) {\n  return <BaseField.Root className={withBase(\"grid content-start gap-1.5\", className)} {...props} />;\n}\n\nexport interface FieldLabelProps extends BaseField.Label.Props {\n  /** Marks the field as required with a quiet asterisk. Set `required` on the control to enforce it. */\n  required?: boolean;\n  /** Adds an \"Optional\" note, for forms where most fields are required. */\n  optional?: boolean;\n}\n\n/** The field's label. Bound to the control automatically, so no `htmlFor` is needed. */\nexport function FieldLabel({ required, optional, ...props }: FieldLabelProps) {\n  return <BaseField.Label render={<Label required={required} optional={optional} />} {...props} />;\n}\n\nconst controlBase = cx(\n  \"h-9 w-full min-w-0 rounded-lg border border-zinc-300 bg-white px-3 text-sm text-zinc-900 shadow-sm placeholder:text-zinc-400\",\n  \"transition-[border-color,box-shadow] duration-150 motion-reduce:transition-none\",\n  \"focus-visible:border-sky-500 focus-visible:ring-3 focus-visible:ring-sky-500/20 focus-visible:outline-none\",\n  \"disabled:cursor-not-allowed disabled:bg-zinc-50 disabled:opacity-60\",\n  \"dark:border-zinc-700 dark:bg-zinc-950 dark:text-zinc-100 dark:placeholder:text-zinc-500 dark:disabled:bg-zinc-900\",\n);\n\n// Applied on top of a rendered Input or Textarea, whose own border only turns red through its `error` prop.\nconst invalidControl = cx(\n  \"aria-invalid:border-red-400 aria-invalid:focus-visible:border-red-500 aria-invalid:focus-visible:ring-red-500/20\",\n  \"dark:aria-invalid:border-red-500/60\",\n);\n\n/**\n * The control to label and validate. Renders a text input styled like Input. To use the existing\n * Input or Textarea, pass `render={<Input />}` or `render={<Textarea autoGrow />}`: they keep their\n * own styles and pick up the field's id, label, description, and invalid state.\n */\nexport function FieldControl({ render, className, ...props }: BaseField.Control.Props) {\n  return (\n    <BaseField.Control\n      render={render}\n      className={withBase(render ? invalidControl : cx(controlBase, invalidControl), className)}\n      {...props}\n    />\n  );\n}\n\n/** Helper text under the control, linked with `aria-describedby`. */\nexport function FieldDescription({ className, ...props }: BaseField.Description.Props) {\n  return (\n    <BaseField.Description\n      className={withBase(\"text-sm leading-5 text-zinc-500 dark:text-zinc-400\", className)}\n      {...props}\n    />\n  );\n}\n\n/**\n * The validation message. Shows when the control is invalid: by default for any failed check,\n * or only for one with `match=\"valueMissing\"` (any ValidityState key). Pass `match` as `true`\n * to show it unconditionally, for errors that come from a server or a form library.\n * It eases in with a 2px rise and leaves faster than it came.\n */\nexport function FieldError({ className, render, ...props }: BaseField.Error.Props) {\n  return (\n    <BaseField.Error\n      className={withBase(\n        cx(\n          \"flex items-start gap-1.5 text-sm leading-5 text-red-600 dark:text-red-400\",\n          \"transition-[opacity,translate] duration-200 ease-[cubic-bezier(0.22,1,0.36,1)] motion-reduce:transition-none\",\n          \"data-[starting-style]:opacity-0 motion-safe:data-[starting-style]:-translate-y-0.5\",\n          \"data-[ending-style]:opacity-0 data-[ending-style]:duration-100 data-[ending-style]:ease-out\",\n        ),\n        className,\n      )}\n      // The render function wraps whichever message is shown: yours, or the browser's validation message.\n      render={\n        render ??\n        (({ children, ...rest }) => (\n          <div {...rest}>\n            <svg aria-hidden=\"true\" viewBox=\"0 0 16 16\" fill=\"none\" className=\"mt-0.5 size-4 shrink-0\">\n              <circle cx=\"8\" cy=\"8\" r=\"6.25\" stroke=\"currentColor\" strokeWidth=\"1.5\" />\n              <path d=\"M6 6l4 4M10 6l-4 4\" stroke=\"currentColor\" strokeWidth=\"1.5\" strokeLinecap=\"round\" />\n            </svg>\n            <span className=\"min-w-0\">{children}</span>\n          </div>\n        ))\n      }\n      {...props}\n    />\n  );\n}\n\nexport interface FieldGroupProps extends Omit<BaseFieldset.Root.Props, \"children\"> {\n  /** Names the group. Rendered as the fieldset's legend. */\n  legend?: ReactNode;\n  /** A sentence under the legend about the whole group. */\n  description?: ReactNode;\n  children?: ReactNode;\n}\n\n/**\n * A fieldset that names a set of related fields, such as an address or a notification section.\n * `disabled` disables every field inside it. Fields stack with even spacing; pass a grid class\n * in `className` to lay them out side by side.\n */\nexport function FieldGroup({ legend, description, className, children, ...props }: FieldGroupProps) {\n  const descriptionId = useId();\n  return (\n    <BaseFieldset.Root\n      aria-describedby={description != null ? descriptionId : undefined}\n      className={withBase(\"m-0 grid min-w-0 gap-5 border-0 p-0\", className)}\n      {...props}\n    >\n      {legend != null || description != null ? (\n        <div className=\"col-span-full grid gap-1\">\n          {legend != null ? (\n            <BaseFieldset.Legend className=\"text-sm leading-5 font-semibold text-zinc-950 dark:text-white\">\n              {legend}\n            </BaseFieldset.Legend>\n          ) : null}\n          {description != null ? (\n            <p id={descriptionId} className=\"text-sm leading-5 text-zinc-500 dark:text-zinc-400\">\n              {description}\n            </p>\n          ) : null}\n        </div>\n      ) : null}\n      {children}\n    </BaseFieldset.Root>\n  );\n}\n\n/** A hairline between field groups inside one form. */\nexport function FieldSeparator({ className }: { className?: string }) {\n  return <hr className={cx(\"m-0 h-px border-0 bg-zinc-950/[0.07] dark:bg-white/[0.08]\", className)} />;\n}\n"
    }
  ],
  "example": {
    "content": "\"use client\";\n\nimport { Field, FieldControl, FieldDescription, FieldError, FieldGroup, FieldLabel, FieldSeparator } from \"@/components/shaken/ui/field\";\nimport { Input } from \"@/components/shaken/ui/input\";\nimport { Textarea } from \"@/components/shaken/ui/textarea\";\n\nexport default function FieldExample() {\n  return (\n    <form className=\"grid w-full max-w-md gap-6\" noValidate>\n      <FieldGroup legend=\"Agent\" description=\"How this agent appears in runs and approval requests.\">\n        <Field name=\"agentName\" validationMode=\"onBlur\">\n          <FieldLabel required>Name</FieldLabel>\n          <FieldControl render={<Input />} required placeholder=\"Release notes writer\" />\n          <FieldDescription>Shown in run logs and in the approval inbox.</FieldDescription>\n          <FieldError match=\"valueMissing\">Give the agent a name.</FieldError>\n        </Field>\n        <Field name=\"instructions\">\n          <FieldLabel optional>Instructions</FieldLabel>\n          <FieldControl\n            render={<Textarea autoGrow maxLength={400} />}\n            placeholder=\"Summarize merged pull requests for the weekly changelog.\"\n          />\n        </Field>\n      </FieldGroup>\n\n      <FieldSeparator />\n\n      <FieldGroup legend=\"Limits\" className=\"sm:grid-cols-2\">\n        <Field\n          name=\"maxSteps\"\n          validationMode=\"onChange\"\n          validate={(value) => (Number(value) > 50 ? \"Keep it at 50 steps or fewer.\" : null)}\n        >\n          <FieldLabel>Max steps</FieldLabel>\n          <FieldControl type=\"number\" inputMode=\"numeric\" defaultValue=\"24\" min={1} className=\"font-mono tabular-nums\" />\n          <FieldError />\n        </Field>\n        <Field name=\"alertEmail\" validationMode=\"onBlur\">\n          <FieldLabel>Alert email</FieldLabel>\n          <FieldControl type=\"email\" placeholder=\"oncall@northwind.dev\" />\n          <FieldError match=\"typeMismatch\">Enter a complete email address.</FieldError>\n        </Field>\n      </FieldGroup>\n    </form>\n  );\n}\n"
  }
}
