@neynar/ui 0.2.1 → 0.3.1

package/src/components/ui/field.tsx

@@ -0,0 +1,494 @@
+import { useMemo } from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+import { Label } from "@/components/ui/label"
+import { Separator } from "@/components/ui/separator"
+
+/**
+ * Props for FieldSet component (Documentation only - NOT used in component implementation)
+ *
+ * Container that renders a semantic fieldset element with spacing presets. Groups related
+ * form controls for improved keyboard navigation and assistive technology compatibility.
+ */
+type FieldSetDocsProps = {
+  /** Additional CSS classes to apply to the fieldset element */
+  className?: string
+  /** Child elements to render within the fieldset, typically FieldLegend and FieldGroup */
+  children?: React.ReactNode
+} & React.ComponentProps<"fieldset">
+
+/**
+ * FieldSet - Semantic form control grouping container
+ *
+ * A container that renders a native HTML `<fieldset>` element with optimized spacing
+ * and layout presets. It provides semantic grouping for related form controls, which
+ * improves accessibility by allowing assistive technologies to understand the
+ * relationship between form fields.
+ *
+ * The component automatically adjusts gap spacing when containing checkbox or radio
+ * groups, providing tighter spacing for these control types.
+ *
+ * @example
+ * Basic fieldset with legend and fields
+ * ```tsx
+ * <FieldSet>
+ *   <FieldLegend>Delivery Information</FieldLegend>
+ *   <FieldGroup>
+ *     <Field>
+ *       <FieldLabel htmlFor="address">Address</FieldLabel>
+ *       <Input id="address" />
+ *     </Field>
+ *   </FieldGroup>
+ * </FieldSet>
+ * ```
+ *
+ * @example
+ * Fieldset with radio group
+ * ```tsx
+ * <FieldSet>
+ *   <FieldLegend>Shipping Method</FieldLegend>
+ *   <FieldGroup data-slot="radio-group">
+ *     <Field orientation="horizontal">
+ *       <Radio id="standard" />
+ *       <FieldLabel htmlFor="standard">Standard</FieldLabel>
+ *     </Field>
+ *     <Field orientation="horizontal">
+ *       <Radio id="express" />
+ *       <FieldLabel htmlFor="express">Express</FieldLabel>
+ *     </Field>
+ *   </FieldGroup>
+ * </FieldSet>
+ * ```
+ *
+ * @example
+ * Nested fieldsets for complex forms
+ * ```tsx
+ * <FieldSet>
+ *   <FieldLegend>Account Settings</FieldLegend>
+ *   <FieldGroup>
+ *     <FieldSet>
+ *       <FieldLegend variant="label">Profile</FieldLegend>
+ *       <FieldGroup>
+ *         <Field>
+ *           <FieldLabel htmlFor="username">Username</FieldLabel>
+ *           <Input id="username" />
+ *         </Field>
+ *       </FieldGroup>
+ *     </FieldSet>
+ *   </FieldGroup>
+ * </FieldSet>
+ * ```
+ *
+ * @accessibility
+ * - Uses semantic `<fieldset>` element for proper form grouping
+ * - Automatically associates grouped controls for screen readers
+ * - Enables keyboard navigation across related form controls
+ * - Works with `<legend>` element (FieldLegend) for accessible group labeling
+ * - Supports disabled state propagation to all child controls
+ *
+ * @see {@link FieldLegend} for fieldset labeling
+ * @see {@link FieldGroup} for organizing multiple fields
+ * @see {@link Field} for individual form fields
+ * @since 1.0.0
+ */
+function FieldSet({ className, ...props }: React.ComponentProps<"fieldset">) {
+  return (
+    <fieldset
+      data-slot="field-set"
+      className={cn(
+        "flex flex-col gap-6",
+        "has-[>[data-slot=checkbox-group]]:gap-3 has-[>[data-slot=radio-group]]:gap-3",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+/**
+ * Props for FieldLegend component (Documentation only - NOT used in component implementation)
+ *
+ * A legend element for a FieldSet that provides a caption describing the group of fields.
+ */
+type FieldLegendDocsProps = {
+  /** Additional CSS classes to apply to the legend element */
+  className?: string
+  /** Visual style variant - "legend" for standard size, "label" for smaller label-style text @default "legend" */
+  variant?: "legend" | "label"
+  /** Text content or elements to render as the legend */
+  children?: React.ReactNode
+} & React.ComponentProps<"legend">
+
+/**
+ * FieldLegend - Fieldset caption with size variants
+ *
+ * A caption element that provides a title or description for a group of related form
+ * fields within a FieldSet. Renders as a native HTML `<legend>` element with size
+ * variants to match different design contexts.
+ *
+ * The "legend" variant (default) uses standard text sizing for top-level fieldsets,
+ * while the "label" variant provides smaller text suitable for nested fieldsets or
+ * when you need the legend to visually match form labels.
+ *
+ * @example
+ * Standard legend for top-level fieldset
+ * ```tsx
+ * <FieldSet>
+ *   <FieldLegend>Personal Information</FieldLegend>
+ *   <FieldGroup>
+ *     <Field>
+ *       <FieldLabel htmlFor="name">Full Name</FieldLabel>
+ *       <Input id="name" />
+ *     </Field>
+ *   </FieldGroup>
+ * </FieldSet>
+ * ```
+ *
+ * @example
+ * Label-sized legend for nested fieldset
+ * ```tsx
+ * <FieldSet>
+ *   <FieldLegend variant="label">Notification Preferences</FieldLegend>
+ *   <FieldGroup>
+ *     <Field orientation="horizontal">
+ *       <Switch id="email" />
+ *       <FieldLabel htmlFor="email">Email notifications</FieldLabel>
+ *     </Field>
+ *   </FieldGroup>
+ * </FieldSet>
+ * ```
+ *
+ * @example
+ * Legend with description
+ * ```tsx
+ * <FieldSet>
+ *   <FieldLegend>Billing Address</FieldLegend>
+ *   <FieldDescription>
+ *     This address will appear on your invoices and receipts.
+ *   </FieldDescription>
+ *   <FieldGroup>
+ *     // fields go here
+ *   </FieldGroup>
+ * </FieldSet>
+ * ```
+ *
+ * @accessibility
+ * - Uses semantic `<legend>` element for proper fieldset labeling
+ * - Automatically announced by screen readers as the fieldset title
+ * - Provides context for all fields within the parent fieldset
+ * - First element read when entering a fieldset with assistive technology
+ *
+ * @see {@link FieldSet} for grouping related form controls
+ * @see {@link FieldDescription} for additional context text
+ * @since 1.0.0
+ */
+function FieldLegend({
+  className,
+  variant = "legend",
+  ...props
+}: React.ComponentProps<"legend"> & { variant?: "legend" | "label" }) {
+  return (
+    <legend
+      data-slot="field-legend"
+      data-variant={variant}
+      className={cn(
+        "mb-3 font-medium",
+        "data-[variant=legend]:text-base",
+        "data-[variant=label]:text-sm",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+/**
+ * Props for FieldGroup component (Documentation only - NOT used in component implementation)
+ *
+ * Layout wrapper that stacks Field components and enables container queries for responsive orientations.
+ */
+type FieldGroupDocsProps = {
+  /** Additional CSS classes to apply to the group container */
+  className?: string
+  /** Field components to group together */
+  children?: React.ReactNode
+} & React.ComponentProps<"div">
+
+/**
+ * FieldGroup - Container for organizing multiple form fields
+ *
+ * A layout wrapper that vertically stacks Field components with optimized spacing.
+ * It provides container query support for responsive field orientations and automatically
+ * adjusts spacing for different control types (standard fields vs. checkbox/radio groups).
+ *
+ * The component uses CSS container queries (@container) which allows child Field
+ * components with `orientation="responsive"` to adapt their layout based on the
+ * FieldGroup's width rather than the viewport width.
+ *
+ * @example
+ * Basic field grouping
+ * ```tsx
+ * <FieldSet>
+ *   <FieldLegend>Contact Information</FieldLegend>
+ *   <FieldGroup>
+ *     <Field>
+ *       <FieldLabel htmlFor="email">Email</FieldLabel>
+ *       <Input id="email" type="email" />
+ *     </Field>
+ *     <Field>
+ *       <FieldLabel htmlFor="phone">Phone</FieldLabel>
+ *       <Input id="phone" type="tel" />
+ *     </Field>
+ *   </FieldGroup>
+ * </FieldSet>
+ * ```
+ *
+ * @example
+ * Responsive field orientations with container queries
+ * ```tsx
+ * <FieldGroup>
+ *   <Field orientation="responsive">
+ *     <FieldLabel htmlFor="name">Full Name</FieldLabel>
+ *     <Input id="name" />
+ *     <FieldDescription>As it appears on your ID</FieldDescription>
+ *   </Field>
+ *   <Field orientation="responsive">
+ *     <FieldLabel htmlFor="company">Company</FieldLabel>
+ *     <Input id="company" />
+ *   </Field>
+ * </FieldGroup>
+ * ```
+ *
+ * @example
+ * Nested field groups for complex layouts
+ * ```tsx
+ * <FieldGroup>
+ *   <Field>
+ *     <FieldLabel htmlFor="street">Street Address</FieldLabel>
+ *     <Input id="street" />
+ *   </Field>
+ *   <FieldGroup>
+ *     <Field>
+ *       <FieldLabel htmlFor="city">City</FieldLabel>
+ *       <Input id="city" />
+ *     </Field>
+ *     <Field>
+ *       <FieldLabel htmlFor="zip">Zip Code</FieldLabel>
+ *       <Input id="zip" />
+ *     </Field>
+ *   </FieldGroup>
+ * </FieldGroup>
+ * ```
+ *
+ * @accessibility
+ * - Provides logical grouping of related form fields
+ * - Supports keyboard navigation between grouped fields
+ * - Works with FieldSet for semantic form sections
+ * - Maintains focus order for tab navigation
+ *
+ * @see {@link Field} for individual form fields
+ * @see {@link FieldSet} for semantic field grouping
+ * @since 1.0.0
+ */
+function FieldGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="field-group"
+      className={cn(
+        "group/field-group @container/field-group flex w-full flex-col gap-7 data-[slot=checkbox-group]:gap-3 [&>[data-slot=field-group]]:gap-4",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+const fieldVariants = cva(
+  "group/field flex w-full gap-3 data-[invalid=true]:text-destructive",
+  {
+    variants: {
+      orientation: {
+        vertical: ["flex-col [&>*]:w-full [&>.sr-only]:w-auto"],
+        horizontal: [
+          "flex-row items-center",
+          "[&>[data-slot=field-label]]:flex-auto",
+          "has-[>[data-slot=field-content]]:items-start has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
+        ],
+        responsive: [
+          "flex-col [&>*]:w-full [&>.sr-only]:w-auto @md/field-group:flex-row @md/field-group:items-center @md/field-group:[&>*]:w-auto",
+          "@md/field-group:[&>[data-slot=field-label]]:flex-auto",
+          "@md/field-group:has-[>[data-slot=field-content]]:items-start @md/field-group:has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
+        ],
+      },
+    },
+    defaultVariants: {
+      orientation: "vertical",
+    },
+  }
+)
+
+function Field({
+  className,
+  orientation = "vertical",
+  ...props
+}: React.ComponentProps<"div"> & VariantProps<typeof fieldVariants>) {
+  return (
+    <div
+      role="group"
+      data-slot="field"
+      data-orientation={orientation}
+      className={cn(fieldVariants({ orientation }), className)}
+      {...props}
+    />
+  )
+}
+
+function FieldContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="field-content"
+      className={cn(
+        "group/field-content flex flex-1 flex-col gap-1.5 leading-snug",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function FieldLabel({
+  className,
+  ...props
+}: React.ComponentProps<typeof Label>) {
+  return (
+    <Label
+      data-slot="field-label"
+      className={cn(
+        "group/field-label peer/field-label flex w-fit gap-2 leading-snug group-data-[disabled=true]/field:opacity-50",
+        "has-[>[data-slot=field]]:w-full has-[>[data-slot=field]]:flex-col has-[>[data-slot=field]]:rounded-md has-[>[data-slot=field]]:border [&>*]:data-[slot=field]:p-4",
+        "has-data-[state=checked]:bg-primary/5 has-data-[state=checked]:border-primary dark:has-data-[state=checked]:bg-primary/10",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function FieldTitle({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="field-label"
+      className={cn(
+        "flex w-fit items-center gap-2 text-sm leading-snug font-medium group-data-[disabled=true]/field:opacity-50",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function FieldDescription({ className, ...props }: React.ComponentProps<"p">) {
+  return (
+    <p
+      data-slot="field-description"
+      className={cn(
+        "text-muted-foreground text-sm leading-normal font-normal group-has-[[data-orientation=horizontal]]/field:text-balance",
+        "last:mt-0 nth-last-2:-mt-1 [[data-variant=legend]+&]:-mt-1.5",
+        "[&>a:hover]:text-primary [&>a]:underline [&>a]:underline-offset-4",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function FieldSeparator({
+  children,
+  className,
+  ...props
+}: React.ComponentProps<"div"> & {
+  children?: React.ReactNode
+}) {
+  return (
+    <div
+      data-slot="field-separator"
+      data-content={!!children}
+      className={cn(
+        "relative -my-2 h-5 text-sm group-data-[variant=outline]/field-group:-mb-2",
+        className
+      )}
+      {...props}
+    >
+      <Separator className="absolute inset-0 top-1/2" />
+      {children && (
+        <span
+          className="bg-background text-muted-foreground relative mx-auto block w-fit px-2"
+          data-slot="field-separator-content"
+        >
+          {children}
+        </span>
+      )}
+    </div>
+  )
+}
+
+function FieldError({
+  className,
+  children,
+  errors,
+  ...props
+}: React.ComponentProps<"div"> & {
+  errors?: Array<{ message?: string } | undefined>
+}) {
+  const content = useMemo(() => {
+    if (children) {
+      return children
+    }
+
+    if (!errors) {
+      return null
+    }
+
+    if (errors?.length === 1 && errors[0]?.message) {
+      return errors[0].message
+    }
+
+    return (
+      <ul className="ml-4 flex list-disc flex-col gap-1">
+        {errors.map(
+          (error, index) =>
+            error?.message && <li key={index}>{error.message}</li>
+        )}
+      </ul>
+    )
+  }, [children, errors])
+
+  if (!content) {
+    return null
+  }
+
+  return (
+    <div
+      role="alert"
+      data-slot="field-error"
+      className={cn("text-destructive text-sm font-normal", className)}
+      {...props}
+    >
+      {content}
+    </div>
+  )
+}
+
+export {
+  Field,
+  FieldLabel,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldLegend,
+  FieldSeparator,
+  FieldSet,
+  FieldContent,
+  FieldTitle,
+}