@fragments-sdk/ui 0.2.3 → 0.4.0

package/src/components/EmptyState/index.tsx

@@ -1,80 +1,115 @@
 import * as React from 'react';
-import { Button } from '../Button';
 import styles from './EmptyState.module.scss';
 // Import globals to ensure CSS variables are defined
 import '../../styles/globals.scss';
 
-export interface EmptyStateAction {
-  /** Button label */
-  label: string;
-  /** Click handler */
-  onClick: () => void;
-  /** Button variant */
-  variant?: 'primary' | 'secondary';
-}
+// ============================================
+// Types
+// ============================================
 
-export interface EmptyStateProps {
-  /** Main heading */
-  title: string;
-  /** Supporting description */
-  description?: string;
-  /** Optional icon element */
-  icon?: React.ReactNode;
-  /** Primary action */
-  action?: EmptyStateAction;
-  /** Secondary action */
-  secondaryAction?: EmptyStateAction;
-  /** Size variant */
+export interface EmptyStateProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
   size?: 'sm' | 'md' | 'lg';
-  /** Additional class name */
+}
+
+export interface EmptyStateIconProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+export interface EmptyStateTitleProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+export interface EmptyStateDescriptionProps {
+  children: React.ReactNode;
   className?: string;
 }
 
-export const EmptyState = React.forwardRef<HTMLDivElement, EmptyStateProps>(
-  function EmptyState(
-    {
-      title,
-      description,
-      icon,
-      action,
-      secondaryAction,
-      size = 'md',
-      className,
-    },
-    ref
-  ) {
-    const classes = [styles.emptyState, styles[size], className]
-      .filter(Boolean)
-      .join(' ');
-
-    return (
-      <div ref={ref} className={classes}>
-        {icon && <div className={styles.icon}>{icon}</div>}
-        <h3 className={styles.title}>{title}</h3>
-        {description && <p className={styles.description}>{description}</p>}
-        {(action || secondaryAction) && (
-          <div className={styles.actions}>
-            {action && (
-              <Button
-                variant={action.variant ?? 'primary'}
-                onClick={action.onClick}
-                size={size === 'sm' ? 'sm' : 'md'}
-              >
-                {action.label}
-              </Button>
-            )}
-            {secondaryAction && (
-              <Button
-                variant={secondaryAction.variant ?? 'secondary'}
-                onClick={secondaryAction.onClick}
-                size={size === 'sm' ? 'sm' : 'md'}
-              >
-                {secondaryAction.label}
-              </Button>
-            )}
-          </div>
-        )}
-      </div>
-    );
+export interface EmptyStateActionsProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+// ============================================
+// Context
+// ============================================
+
+interface EmptyStateContextValue {
+  size: 'sm' | 'md' | 'lg';
+}
+
+const EmptyStateContext = React.createContext<EmptyStateContextValue | null>(null);
+
+function useEmptyStateContext() {
+  const context = React.useContext(EmptyStateContext);
+  if (!context) {
+    throw new Error('EmptyState compound components must be used within an EmptyState');
   }
-);
+  return context;
+}
+
+// ============================================
+// Components
+// ============================================
+
+function EmptyStateRoot({
+  children,
+  size = 'md',
+  className,
+  ...htmlProps
+}: EmptyStateProps) {
+  const classes = [styles.emptyState, styles[size], className]
+    .filter(Boolean)
+    .join(' ');
+
+  const contextValue: EmptyStateContextValue = { size };
+
+  return (
+    <EmptyStateContext.Provider value={contextValue}>
+      <div {...htmlProps} className={classes}>{children}</div>
+    </EmptyStateContext.Provider>
+  );
+}
+
+function EmptyStateIcon({ children, className }: EmptyStateIconProps) {
+  const classes = [styles.icon, className].filter(Boolean).join(' ');
+  return <div className={classes}>{children}</div>;
+}
+
+function EmptyStateTitle({ children, className }: EmptyStateTitleProps) {
+  const classes = [styles.title, className].filter(Boolean).join(' ');
+  return <h3 className={classes}>{children}</h3>;
+}
+
+function EmptyStateDescription({ children, className }: EmptyStateDescriptionProps) {
+  const classes = [styles.description, className].filter(Boolean).join(' ');
+  return <p className={classes}>{children}</p>;
+}
+
+function EmptyStateActions({ children, className }: EmptyStateActionsProps) {
+  const classes = [styles.actions, className].filter(Boolean).join(' ');
+  return <div className={classes}>{children}</div>;
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const EmptyState = Object.assign(EmptyStateRoot, {
+  Icon: EmptyStateIcon,
+  Title: EmptyStateTitle,
+  Description: EmptyStateDescription,
+  Actions: EmptyStateActions,
+});
+
+// Re-export individual components for tree-shaking
+export {
+  EmptyStateRoot,
+  EmptyStateIcon,
+  EmptyStateTitle,
+  EmptyStateDescription,
+  EmptyStateActions,
+  useEmptyStateContext,
+};

package/src/components/Field/Field.fragment.tsx

@@ -0,0 +1,165 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Field } from './index.js';
+import { Input } from '../Input/index.js';
+import { Grid } from '../Grid/index.js';
+
+export default defineSegment({
+  component: Field,
+
+  meta: {
+    name: 'Field',
+    description: 'Compositional form field wrapper providing validation, labels, descriptions, and error messages. Use for advanced form needs beyond baked-in Input/Textarea props.',
+    category: 'forms',
+    status: 'stable',
+    tags: ['form', 'field', 'validation', 'label', 'error', 'input', 'accessible'],
+    since: '0.4.0',
+  },
+
+  usage: {
+    when: [
+      'You need granular validation with match-based error messages',
+      'Custom form controls need accessible labels and descriptions',
+      'Server-side errors need to be distributed to specific fields',
+      'You need dirty/touched tracking or custom validation logic',
+    ],
+    whenNot: [
+      'Simple inputs with basic label and helper text (use Input with label prop)',
+      'Standalone selects or textareas with built-in error display',
+    ],
+    guidelines: [
+      'Always provide a Field.Label for accessibility',
+      'Wrap any form control in Field.Control to connect it to the field context',
+      'Use match prop on Field.Error for granular native validation messages',
+      'Wrap in Form to enable server-side error distribution by field name',
+    ],
+    accessibility: [
+      'Label automatically linked to control via aria-labelledby',
+      'Description linked via aria-describedby',
+      'Error messages announced to screen readers',
+      'Supports data-disabled and data-invalid attributes for styling',
+    ],
+  },
+
+  props: {
+    name: {
+      type: 'string',
+      description: 'Field name, used for error distribution from Form',
+    },
+    disabled: {
+      type: 'boolean',
+      description: 'Disables the field and its control',
+    },
+    invalid: {
+      type: 'boolean',
+      description: 'Marks the field as invalid',
+    },
+    validate: {
+      type: 'function',
+      description: 'Custom validation function returning error string(s) or null',
+    },
+    validationMode: {
+      type: 'enum',
+      description: 'When to trigger validation',
+      values: ['onSubmit', 'onBlur', 'onChange'],
+    },
+    validationDebounceTime: {
+      type: 'number',
+      description: 'Debounce time in ms for onChange validation',
+    },
+    className: {
+      type: 'string',
+      description: 'Additional CSS class',
+    },
+  },
+
+  relations: [
+    { component: 'Input', relationship: 'alternative', note: 'Use Input for simple fields with built-in label/error' },
+    { component: 'Form', relationship: 'parent', note: 'Wrap in Form for server-side error distribution' },
+    { component: 'Fieldset', relationship: 'sibling', note: 'Use Fieldset to group related fields' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'name: string - field name for error distribution',
+      'validate: (value) => string | null - custom validation',
+      'validationMode: onSubmit|onBlur|onChange - validation trigger',
+      'Field.Control: wraps any form component (Input, Textarea, etc.)',
+      'Field.Error match: valueMissing|typeMismatch|customError|... - granular errors',
+    ],
+    scenarioTags: [
+      'form.field',
+      'form.validation',
+      'form.accessible',
+    ],
+    a11yRules: ['A11Y_FIELD_LABEL', 'A11Y_FIELD_ERROR', 'A11Y_FIELD_DESCRIPTION'],
+  },
+
+  variants: [
+    {
+      name: 'Single field',
+      description: 'A single field with label, control, and description',
+      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>
+      ),
+    },
+    {
+      name: 'Two-column layout',
+      description: 'Fields arranged in a two-column grid',
+      render: () => (
+        <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.Error match="typeMismatch">Enter a valid email address</Field.Error>
+            </Field>
+          </Grid.Item>
+        </Grid>
+      ),
+    },
+    {
+      name: 'Custom validation',
+      description: 'Field with custom validate function',
+      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>
+      ),
+    },
+  ],
+});

package/src/components/Field/Field.module.scss

@@ -0,0 +1,31 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+.root {
+  display: flex;
+  flex-direction: column;
+}
+
+.label {
+  @include label-text;
+  margin-bottom: var(--fui-space-1, $fui-space-1);
+
+  &[data-disabled] {
+    color: var(--fui-text-tertiary, $fui-text-tertiary);
+  }
+}
+
+.control {
+  // Minimal styles — users bring styled controls via render prop
+}
+
+.description {
+  @include helper-text;
+  margin-top: var(--fui-space-1, $fui-space-1);
+}
+
+.error {
+  @include helper-text;
+  margin-top: var(--fui-space-1, $fui-space-1);
+  color: var(--fui-color-danger, $fui-color-danger);
+}

package/src/components/Field/index.tsx

@@ -0,0 +1,143 @@
+import * as React from 'react';
+import { Field as BaseField, type FieldValidityState } from '@base-ui/react/field';
+import styles from './Field.module.scss';
+import '../../styles/globals.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, Toggle, 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.fragment.tsx

@@ -0,0 +1,166 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Fieldset } from './index.js';
+import { Field } from '../Field/index.js';
+import { Input } from '../Input/index.js';
+import { Textarea } from '../Textarea/index.js';
+import { Select } from '../Select/index.js';
+import { Checkbox } from '../Checkbox/index.js';
+import { Grid } from '../Grid/index.js';
+
+export default defineSegment({
+  component: Fieldset,
+
+  meta: {
+    name: 'Fieldset',
+    description: 'Groups related form fields with an accessible legend. Use to organize forms into logical sections.',
+    category: 'forms',
+    status: 'stable',
+    tags: ['form', 'fieldset', 'group', 'legend', 'accessible'],
+    since: '0.4.0',
+  },
+
+  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',
+    ],
+    accessibility: [
+      'Renders semantic fieldset element',
+      'Legend provides accessible group label',
+      'Disabled state propagates to all child fields',
+    ],
+  },
+
+  props: {
+    disabled: {
+      type: 'boolean',
+      description: 'Disables all fields within the fieldset',
+    },
+    className: {
+      type: 'string',
+      description: 'Additional CSS class',
+    },
+  },
+
+  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',
+    ],
+    scenarioTags: ['form.group', 'form.fieldset'],
+    a11yRules: ['A11Y_FIELDSET_LEGEND'],
+  },
+
+  variants: [
+    {
+      name: 'Two-column layout',
+      description: 'Fieldset with Grid for side-by-side fields',
+      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>
+      ),
+    },
+    {
+      name: 'Mixed controls',
+      description: 'Fieldset with textarea, select, and checkbox',
+      render: () => (
+        <Fieldset>
+          <Fieldset.Legend>Preferences</Fieldset.Legend>
+          <Field name="bio">
+            <Field.Label>Bio</Field.Label>
+            <Field.Control>
+              <Textarea placeholder="Tell us about yourself" rows={3} />
+            </Field.Control>
+            <Field.Description>Brief description for your profile.</Field.Description>
+          </Field>
+          <Field name="role">
+            <Field.Label>Role</Field.Label>
+            <Field.Control>
+              <Select placeholder="Select a role">
+                <Select.Trigger />
+                <Select.Content>
+                  <Select.Item value="admin">Admin</Select.Item>
+                  <Select.Item value="editor">Editor</Select.Item>
+                  <Select.Item value="viewer">Viewer</Select.Item>
+                </Select.Content>
+              </Select>
+            </Field.Control>
+          </Field>
+          <Field name="newsletter">
+            <Field.Control>
+              <Checkbox label="Subscribe to newsletter" />
+            </Field.Control>
+          </Field>
+        </Fieldset>
+      ),
+    },
+    {
+      name: 'Disabled',
+      description: 'Disabled fieldset prevents interaction with all children',
+      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>
+          <Field name="lockedCheck">
+            <Field.Control>
+              <Checkbox label="Cannot toggle" defaultChecked />
+            </Field.Control>
+          </Field>
+        </Fieldset>
+      ),
+    },
+  ],
+});