@neynar/ui 0.2.1 → 0.3.0

package/dist/components/ui/field.d.ts

@@ -0,0 +1,238 @@
+import { type VariantProps } from "class-variance-authority";
+import { Label } from "@/components/ui/label";
+/**
+ * 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
+ */
+declare function FieldSet({ className, ...props }: React.ComponentProps<"fieldset">): import("react/jsx-runtime").JSX.Element;
+/**
+ * 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
+ */
+declare function FieldLegend({ className, variant, ...props }: React.ComponentProps<"legend"> & {
+    variant?: "legend" | "label";
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * 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
+ */
+declare function FieldGroup({ className, ...props }: React.ComponentProps<"div">): import("react/jsx-runtime").JSX.Element;
+declare const fieldVariants: (props?: ({
+    orientation?: "horizontal" | "vertical" | "responsive" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+declare function Field({ className, orientation, ...props }: React.ComponentProps<"div"> & VariantProps<typeof fieldVariants>): import("react/jsx-runtime").JSX.Element;
+declare function FieldContent({ className, ...props }: React.ComponentProps<"div">): import("react/jsx-runtime").JSX.Element;
+declare function FieldLabel({ className, ...props }: React.ComponentProps<typeof Label>): import("react/jsx-runtime").JSX.Element;
+declare function FieldTitle({ className, ...props }: React.ComponentProps<"div">): import("react/jsx-runtime").JSX.Element;
+declare function FieldDescription({ className, ...props }: React.ComponentProps<"p">): import("react/jsx-runtime").JSX.Element;
+declare function FieldSeparator({ children, className, ...props }: React.ComponentProps<"div"> & {
+    children?: React.ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+declare function FieldError({ className, children, errors, ...props }: React.ComponentProps<"div"> & {
+    errors?: Array<{
+        message?: string;
+    } | undefined>;
+}): import("react/jsx-runtime").JSX.Element | null;
+export { Field, FieldLabel, FieldDescription, FieldError, FieldGroup, FieldLegend, FieldSeparator, FieldSet, FieldContent, FieldTitle, };
+//# sourceMappingURL=field.d.ts.map

package/dist/components/ui/field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../../../src/components/ui/field.tsx"],"names":[],"mappings":"AACA,OAAO,EAAO,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAGjE,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAA;AAgB7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,iBAAS,QAAQ,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,UAAU,CAAC,2CAY1E;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,iBAAS,WAAW,CAAC,EACnB,SAAS,EACT,OAAkB,EAClB,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,QAAQ,CAAC,GAAG;IAAE,OAAO,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAA;CAAE,2CAcnE;AAcD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AACH,iBAAS,UAAU,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,2CAWvE;AAED,QAAA,MAAM,aAAa;;8EAsBlB,CAAA;AAED,iBAAS,KAAK,CAAC,EACb,SAAS,EACT,WAAwB,EACxB,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,GAAG,YAAY,CAAC,OAAO,aAAa,CAAC,2CAUlE;AAED,iBAAS,YAAY,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,2CAWzE;AAED,iBAAS,UAAU,CAAC,EAClB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,KAAK,CAAC,2CAapC;AAED,iBAAS,UAAU,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,2CAWvE;AAED,iBAAS,gBAAgB,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,2CAa3E;AAED,iBAAS,cAAc,CAAC,EACtB,QAAQ,EACR,SAAS,EACT,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,GAAG;IAC/B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAC3B,2CAsBA;AAED,iBAAS,UAAU,CAAC,EAClB,SAAS,EACT,QAAQ,EACR,MAAM,EACN,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,GAAG;IAC/B,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,CAAA;CACjD,kDAsCA;AAED,OAAO,EACL,KAAK,EACL,UAAU,EACV,gBAAgB,EAChB,UAAU,EACV,UAAU,EACV,WAAW,EACX,cAAc,EACd,QAAQ,EACR,YAAY,EACZ,UAAU,GACX,CAAA"}