@usefragments/ui 1.0.0

package/src/components/Field/Field.stories.tsx

@@ -0,0 +1,109 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Field } from '.';
+import { Input } from '../Input';
+
+/**
+ * Field is a compositional form-field wrapper providing validation, labels,
+ * descriptions, and error messages. It is a compound component: compose
+ * Field.Label, Field.Control, Field.Description, and Field.Error inside the
+ * root. Field.Control connects any form control to the field context.
+ */
+const meta = {
+  title: 'Forms/Field',
+  component: Field,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Form field wrapper providing labels, descriptions, validation, and error messages.',
+      },
+    },
+  },
+  argTypes: {
+    disabled: {
+      control: 'boolean',
+      description: 'Disables the field and its control',
+    },
+    invalid: { control: 'boolean', description: 'Marks the field as invalid' },
+    validationMode: {
+      control: 'select',
+      options: ['onSubmit', 'onBlur', 'onChange'],
+      description: 'When to trigger validation',
+    },
+  },
+  args: {
+    name: 'email',
+    children: (
+      <>
+        <Field.Label>Email address</Field.Label>
+        <Field.Control>
+          <Input type="email" placeholder="jane@example.com" />
+        </Field.Control>
+        <Field.Description>We will never share your email.</Field.Description>
+      </>
+    ),
+  },
+} satisfies Meta<typeof Field>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <Field name="email">
+      <Field.Label>Email address</Field.Label>
+      <Field.Control>
+        <Input type="email" placeholder="jane@example.com" />
+      </Field.Control>
+      <Field.Description>We will never share your email.</Field.Description>
+    </Field>
+  ),
+};
+
+export const WithError: Story = {
+  render: () => (
+    <Field name="email" invalid>
+      <Field.Label>Email</Field.Label>
+      <Field.Control>
+        <Input type="email" defaultValue="not-an-email" />
+      </Field.Control>
+      <Field.Error match="typeMismatch">Enter a valid email address</Field.Error>
+    </Field>
+  ),
+};
+
+export const CustomValidation: Story = {
+  render: () => (
+    <Field
+      name="age"
+      validate={(value) => {
+        const num = Number(value);
+        if (isNaN(num) || num < 18) return 'Must be 18 or older';
+        return null;
+      }}
+      validationMode="onChange"
+      validationDebounceTime={500}
+    >
+      <Field.Label>Age</Field.Label>
+      <Field.Control>
+        <Input type="number" placeholder="18" />
+      </Field.Control>
+      <Field.Description>You must be at least 18 years old.</Field.Description>
+      <Field.Error match="customError" />
+    </Field>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <Field name="username" disabled>
+      <Field.Label>Username</Field.Label>
+      <Field.Control>
+        <Input defaultValue="janedoe" />
+      </Field.Control>
+      <Field.Description>This field cannot be edited.</Field.Description>
+    </Field>
+  ),
+};

package/src/components/Field/index.tsx

@@ -0,0 +1,144 @@
+'use client';
+
+import * as React from 'react';
+import { Field as BaseField, type FieldValidityState } from '@base-ui/react/field';
+import styles from './Field.module.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export interface FieldProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  name?: string;
+  disabled?: boolean;
+  invalid?: boolean;
+  validate?: (value: unknown) => string | string[] | null | Promise<string | string[] | null>;
+  validationMode?: 'onSubmit' | 'onBlur' | 'onChange';
+  validationDebounceTime?: number;
+}
+
+export interface FieldLabelProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+export interface FieldControlProps {
+  children: React.ReactElement;
+  className?: string;
+}
+
+export interface FieldDescriptionProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+export interface FieldErrorProps {
+  children?: React.ReactNode;
+  match?: 'valueMissing' | 'typeMismatch' | 'tooShort' | 'tooLong' | 'patternMismatch' | 'customError' | boolean;
+  className?: string;
+}
+
+export interface FieldValidityProps {
+  children: (state: FieldValidityState) => React.ReactNode;
+}
+
+export type { FieldValidityState };
+
+// ============================================
+// Components
+// ============================================
+
+function FieldRoot({
+  children,
+  name,
+  disabled,
+  invalid,
+  validate,
+  validationMode,
+  validationDebounceTime,
+  className,
+  ...htmlProps
+}: FieldProps) {
+  const classes = [styles.root, className].filter(Boolean).join(' ');
+
+  return (
+    <BaseField.Root
+      {...htmlProps}
+      name={name}
+      disabled={disabled}
+      invalid={invalid}
+      validate={validate}
+      validationMode={validationMode}
+      validationDebounceTime={validationDebounceTime}
+      className={classes}
+    >
+      {children}
+    </BaseField.Root>
+  );
+}
+
+function FieldLabel({ children, className }: FieldLabelProps) {
+  const classes = [styles.label, className].filter(Boolean).join(' ');
+  return <BaseField.Label className={classes}>{children}</BaseField.Label>;
+}
+
+/**
+ * Connects any child component to the Field context.
+ * Wraps the child with Base UI's Field.Control via the `render` prop,
+ * which merges aria attributes and field state onto the child element.
+ *
+ * Works with Input, Textarea, Checkbox, Switch, Select, or any element.
+ */
+function FieldControl({ children, className }: FieldControlProps) {
+  const classes = [styles.control, className].filter(Boolean).join(' ');
+  return (
+    <BaseField.Control
+      className={classes}
+      render={children}
+    />
+  );
+}
+
+function FieldDescription({ children, className }: FieldDescriptionProps) {
+  const classes = [styles.description, className].filter(Boolean).join(' ');
+  return (
+    <BaseField.Description className={classes}>
+      {children}
+    </BaseField.Description>
+  );
+}
+
+function FieldError({ children, match, className }: FieldErrorProps) {
+  const classes = [styles.error, className].filter(Boolean).join(' ');
+  return (
+    <BaseField.Error match={match} className={classes}>
+      {children}
+    </BaseField.Error>
+  );
+}
+
+function FieldValidity({ children }: FieldValidityProps) {
+  return <BaseField.Validity>{children}</BaseField.Validity>;
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const Field = Object.assign(FieldRoot, {
+  Label: FieldLabel,
+  Control: FieldControl,
+  Description: FieldDescription,
+  Error: FieldError,
+  Validity: FieldValidity,
+});
+
+export {
+  FieldRoot,
+  FieldLabel,
+  FieldControl,
+  FieldDescription,
+  FieldError,
+  FieldValidity,
+};

package/src/components/Fieldset/Fieldset.contract.json

@@ -0,0 +1,117 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Fieldset",
+  "description": "Groups related form fields with an accessible legend. Use to organize forms into logical sections.",
+  "category": "forms",
+  "tags": [
+    "form",
+    "fieldset",
+    "group",
+    "legend",
+    "accessible"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Fieldset/index.tsx",
+  "exportName": "Fieldset",
+  "propsSummary": [
+    "children: node (required)",
+    "disabled: boolean"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Fieldset content including Fieldset.Legend and form fields",
+      "required": true
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "Disables all fields within the fieldset",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Grouping related fields in a form (e.g., address, personal info)",
+      "Disabling a group of fields together",
+      "Providing an accessible group label for screen readers"
+    ],
+    "whenNot": [
+      "Generic visual grouping (use Card)",
+      "Single field wrapping (use Field)"
+    ],
+    "guidelines": [
+      "Always include a Fieldset.Legend for accessibility",
+      "Use disabled prop to disable all fields within the group",
+      "Use Grid inside Fieldset for multi-column layouts",
+      "Fieldset.Legend forwards DOM props for ids, aria attributes, and custom data hooks"
+    ],
+    "accessibility": [
+      "Renders semantic fieldset element",
+      "Legend provides accessible group label",
+      "Disabled state propagates to all child fields"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Two-column layout",
+      "description": "Fieldset with Grid for side-by-side fields",
+      "code": "<Fieldset>\n  <Fieldset.Legend>Personal Information</Fieldset.Legend>\n  <Grid columns={2} gap=\"md\">\n    <Field name=\"firstName\">\n      <Field.Label>First Name</Field.Label>\n      <Field.Control>\n        <Input placeholder=\"Jane\" />\n      </Field.Control>\n    </Field>\n    <Field name=\"lastName\">\n      <Field.Label>Last Name</Field.Label>\n      <Field.Control>\n        <Input placeholder=\"Doe\" />\n      </Field.Control>\n    </Field>\n    <Grid.Item colSpan=\"full\">\n      <Field name=\"email\">\n        <Field.Label>Email</Field.Label>\n        <Field.Control>\n          <Input type=\"email\" placeholder=\"jane@example.com\" />\n        </Field.Control>\n      </Field>\n    </Grid.Item>\n  </Grid>\n</Fieldset>"
+    },
+    {
+      "name": "Mixed controls",
+      "description": "Fieldset with textarea, select, and checkbox",
+      "code": "<Fieldset>\n  <Fieldset.Legend>Preferences</Fieldset.Legend>\n  <Field name=\"bio\">\n    <Field.Label>Bio</Field.Label>\n    <Field.Control>\n      <Textarea placeholder=\"Tell us about yourself\" rows={3} />\n    </Field.Control>\n    <Field.Description>Brief description for your profile.</Field.Description>\n  </Field>\n  <Field name=\"role\">\n    <Field.Label>Role</Field.Label>\n    <Field.Control>\n      <Select placeholder=\"Select a role\">\n        <Select.Trigger />\n        <Select.Content>\n          <Select.Item value=\"admin\">Admin</Select.Item>\n          <Select.Item value=\"editor\">Editor</Select.Item>\n          <Select.Item value=\"viewer\">Viewer</Select.Item>\n        </Select.Content>\n      </Select>\n    </Field.Control>\n  </Field>\n  <Field name=\"newsletter\">\n    <Field.Control>\n      <Checkbox label=\"Subscribe to newsletter\" />\n    </Field.Control>\n  </Field>\n</Fieldset>"
+    },
+    {
+      "name": "With Description",
+      "description": "Fieldset with descriptive helper text below the legend",
+      "code": "<Fieldset>\n  <Fieldset.Legend>Notification Settings</Fieldset.Legend>\n  <Fieldset.Description>Choose how you want to be notified about updates.</Fieldset.Description>\n  <Field name=\"emailNotif\">\n    <Field.Control>\n      <Checkbox label=\"Email notifications\" />\n    </Field.Control>\n  </Field>\n  <Field name=\"smsNotif\">\n    <Field.Control>\n      <Checkbox label=\"SMS notifications\" />\n    </Field.Control>\n  </Field>\n</Fieldset>"
+    },
+    {
+      "name": "Disabled",
+      "description": "Disabled fieldset prevents interaction with all children",
+      "code": "<Fieldset disabled>\n  <Fieldset.Legend>Locked Section</Fieldset.Legend>\n  <Grid columns={2} gap=\"md\">\n    <Field name=\"lockedFirst\">\n      <Field.Label>First Name</Field.Label>\n      <Field.Control>\n        <Input defaultValue=\"Jane\" />\n      </Field.Control>\n    </Field>\n    <Field name=\"lockedLast\">\n      <Field.Label>Last Name</Field.Label>\n      <Field.Control>\n        <Input defaultValue=\"Doe\" />\n      </Field.Control>\n    </Field>\n  </Grid>\n  <Field name=\"lockedCheck\">\n    <Field.Control>\n      <Checkbox label=\"Cannot toggle\" defaultChecked />\n    </Field.Control>\n  </Field>\n</Fieldset>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Field",
+      "relationship": "sibling",
+      "note": "Contains Field components"
+    },
+    {
+      "component": "Form",
+      "relationship": "parent",
+      "note": "Used within a Form"
+    },
+    {
+      "component": "Card",
+      "relationship": "alternative",
+      "note": "Use Card for non-form visual grouping"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "disabled: boolean - disables all child fields",
+      "Fieldset.Legend: accessible group label",
+      "Fieldset.Legend forwards DOM props",
+      "Fieldset.Description: helper text below the legend"
+    ],
+    "a11yRules": [
+      "A11Y_FIELDSET_LEGEND"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Legend",
+      "Description"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:57.275Z"
+  }
+}

package/src/components/Fieldset/Fieldset.module.scss

@@ -0,0 +1,28 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+.root {
+  @include form-group-surface;
+
+  display: flex;
+  flex-direction: column;
+  gap: var(--fui-space-3, $fui-space-3);
+  padding: var(--fui-space-4, $fui-space-4);
+  margin: 0;
+
+  &[data-disabled] {
+    opacity: 0.5;
+  }
+}
+
+.legend {
+  @include label-text;
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  padding: 0;
+}
+
+.description {
+  @include helper-text;
+  margin: calc(-1 * var(--fui-space-2, $fui-space-2)) 0 0 0;
+}

package/src/components/Fieldset/Fieldset.stories.tsx

@@ -0,0 +1,116 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Fieldset } from '.';
+import { Field } from '../Field';
+import { Input } from '../Input';
+import { Grid } from '../Grid';
+
+/**
+ * Fieldset groups related form fields with an accessible legend. It is a
+ * compound component: compose Fieldset.Legend and Fieldset.Description inside
+ * the root, alongside the grouped Field components.
+ */
+const meta = {
+  title: 'Forms/Fieldset',
+  component: Fieldset,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Groups related form fields with an accessible legend.',
+      },
+    },
+  },
+  argTypes: {
+    disabled: {
+      control: 'boolean',
+      description: 'Disables all fields within the fieldset',
+    },
+  },
+  args: {
+    children: (
+      <>
+        <Fieldset.Legend>Personal Information</Fieldset.Legend>
+        <Field name="firstName">
+          <Field.Label>First Name</Field.Label>
+          <Field.Control>
+            <Input placeholder="Jane" />
+          </Field.Control>
+        </Field>
+      </>
+    ),
+  },
+} satisfies Meta<typeof Fieldset>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const TwoColumnLayout: Story = {
+  render: () => (
+    <Fieldset>
+      <Fieldset.Legend>Personal Information</Fieldset.Legend>
+      <Grid columns={2} gap="md">
+        <Field name="firstName">
+          <Field.Label>First Name</Field.Label>
+          <Field.Control>
+            <Input placeholder="Jane" />
+          </Field.Control>
+        </Field>
+        <Field name="lastName">
+          <Field.Label>Last Name</Field.Label>
+          <Field.Control>
+            <Input placeholder="Doe" />
+          </Field.Control>
+        </Field>
+        <Grid.Item colSpan="full">
+          <Field name="email">
+            <Field.Label>Email</Field.Label>
+            <Field.Control>
+              <Input type="email" placeholder="jane@example.com" />
+            </Field.Control>
+          </Field>
+        </Grid.Item>
+      </Grid>
+    </Fieldset>
+  ),
+};
+
+export const WithDescription: Story = {
+  render: () => (
+    <Fieldset>
+      <Fieldset.Legend>Account Details</Fieldset.Legend>
+      <Fieldset.Description>
+        Choose how others will see you on the platform.
+      </Fieldset.Description>
+      <Field name="displayName">
+        <Field.Label>Display Name</Field.Label>
+        <Field.Control>
+          <Input placeholder="How others see you" />
+        </Field.Control>
+      </Field>
+    </Fieldset>
+  ),
+};
+
+export const Disabled: Story = {
+  render: () => (
+    <Fieldset disabled>
+      <Fieldset.Legend>Locked Section</Fieldset.Legend>
+      <Grid columns={2} gap="md">
+        <Field name="lockedFirst">
+          <Field.Label>First Name</Field.Label>
+          <Field.Control>
+            <Input defaultValue="Jane" />
+          </Field.Control>
+        </Field>
+        <Field name="lockedLast">
+          <Field.Label>Last Name</Field.Label>
+          <Field.Control>
+            <Input defaultValue="Doe" />
+          </Field.Control>
+        </Field>
+      </Grid>
+    </Fieldset>
+  ),
+};

package/src/components/Fieldset/index.tsx

@@ -0,0 +1,57 @@
+'use client';
+
+import * as React from 'react';
+import { Fieldset as BaseFieldset } from '@base-ui/react/fieldset';
+import styles from './Fieldset.module.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export interface FieldsetProps extends React.HTMLAttributes<HTMLFieldSetElement> {
+  children: React.ReactNode;
+  disabled?: boolean;
+}
+
+export interface FieldsetLegendProps extends React.HTMLAttributes<HTMLElement> {
+  children: React.ReactNode;
+}
+
+export interface FieldsetDescriptionProps extends React.HTMLAttributes<HTMLParagraphElement> {
+  children: React.ReactNode;
+}
+
+// ============================================
+// Components
+// ============================================
+
+function FieldsetRoot({ children, disabled, className, ...htmlProps }: FieldsetProps) {
+  const classes = [styles.root, className].filter(Boolean).join(' ');
+
+  return (
+    <BaseFieldset.Root {...htmlProps} disabled={disabled} className={classes}>
+      {children}
+    </BaseFieldset.Root>
+  );
+}
+
+function FieldsetLegend({ children, className, ...htmlProps }: FieldsetLegendProps) {
+  const classes = [styles.legend, className].filter(Boolean).join(' ');
+  return <BaseFieldset.Legend {...htmlProps} className={classes}>{children}</BaseFieldset.Legend>;
+}
+
+function FieldsetDescription({ children, className, ...htmlProps }: FieldsetDescriptionProps) {
+  const classes = [styles.description, className].filter(Boolean).join(' ');
+  return <p {...htmlProps} className={classes}>{children}</p>;
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const Fieldset = Object.assign(FieldsetRoot, {
+  Legend: FieldsetLegend,
+  Description: FieldsetDescription,
+});
+
+export { FieldsetRoot, FieldsetLegend, FieldsetDescription };