@usefragments/ui 1.0.0

package/src/components/RadioGroup/index.tsx

@@ -0,0 +1,298 @@
+"use client";
+
+import * as React from "react";
+import { RadioGroup as BaseRadioGroup } from "@base-ui/react/radio-group";
+import { Radio as BaseRadio } from "@base-ui/react/radio";
+import { mergeAriaIds, useFormFieldIds } from "../../utils/aria";
+import { useResolvedControlSize, type ControlSize } from "../ComponentDefaults";
+import styles from "./RadioGroup.module.scss";
+
+// ============================================
+// Types
+// ============================================
+
+/**
+ * Radio group for selecting one option from a set.
+ * @see https://usefragments.com/components/radiogroup
+ */
+export interface RadioGroupProps extends Omit<
+  React.HTMLAttributes<HTMLDivElement>,
+  "onChange" | "defaultValue"
+> {
+  /** Current value (controlled) */
+  value?: string;
+  /** Default value (uncontrolled) */
+  defaultValue?: string;
+  /** Callback when value changes */
+  onValueChange?: (value: string) => void;
+  /** Alias for onValueChange */
+  onChange?: (value: string) => void;
+  /** Orientation of the radio group */
+  orientation?: "horizontal" | "vertical";
+  /** Whether the group is disabled */
+  disabled?: boolean;
+  /** Whether the selected value cannot be changed by the user */
+  readOnly?: boolean;
+  /** Whether the user must choose a value before submitting a form */
+  required?: boolean;
+  /** Form field name */
+  name?: string;
+  /** ID of the form that owns the radio inputs */
+  form?: string;
+  /** Ref to the hidden input element */
+  inputRef?: React.Ref<HTMLInputElement>;
+  /** Label for the group */
+  label?: string;
+  /** Helper text shown below the group */
+  helperText?: string;
+  /** Show error styling. When a string is provided, it is displayed as an error message. */
+  error?: boolean | string;
+  /** Size variant */
+  size?: "sm" | "md" | "lg";
+  /**
+   * Visual variant.
+   * - `default`: inline radio circle next to a label (form-control style).
+   * - `card`: each item is a full-width clickable card with the radio circle
+   *   tucked inside. Useful for high-stakes choices, surveys, plan pickers.
+   * @default "default"
+   */
+  variant?: "default" | "card";
+  /** Class applied to the outer wrapper (label + group + error) */
+  wrapperClassName?: string;
+  /** Class applied to the inner radio group container */
+  groupClassName?: string;
+  /** Children (Radio.Item components) */
+  children: React.ReactNode;
+}
+
+export interface RadioItemProps {
+  /** The value for this radio item */
+  value: string;
+  /** Label text */
+  label?: string;
+  /** Helper text shown below the label */
+  helperText?: string;
+  /** @deprecated Use helperText instead. Description text below the label. */
+  description?: string;
+  /** Whether this item is disabled */
+  disabled?: boolean;
+  /** Accessible name for icon-only mode */
+  "aria-label"?: string;
+  /** Accessible labelled-by relationship */
+  "aria-labelledby"?: string;
+  /** Accessible described-by relationship */
+  "aria-describedby"?: string;
+  /** Additional class name */
+  className?: string;
+  /** Class applied directly to the radio control */
+  controlClassName?: string;
+  /** Class applied to the item text content wrapper */
+  contentClassName?: string;
+}
+
+// ============================================
+// Context for size + variant
+// ============================================
+
+const RadioSizeContext = React.createContext<ControlSize>("md");
+const RadioVariantContext = React.createContext<"default" | "card">("default");
+
+// ============================================
+// Radio Item Component
+// ============================================
+
+function RadioItem({
+  value,
+  label,
+  helperText,
+  description,
+  disabled = false,
+  "aria-label": ariaLabel,
+  "aria-labelledby": ariaLabelledBy,
+  "aria-describedby": ariaDescribedBy,
+  className,
+  controlClassName,
+  contentClassName,
+}: RadioItemProps) {
+  const resolvedHelperText = helperText ?? description;
+  const size = React.useContext(RadioSizeContext);
+  const variant = React.useContext(RadioVariantContext);
+  const id = React.useId();
+  const labelId = label ? `radio-label-${id}` : undefined;
+  const descriptionId = resolvedHelperText ? `radio-desc-${id}` : undefined;
+
+  const radioClasses = [
+    styles.radio,
+    size === "sm" && styles.radioSm,
+    size === "lg" && styles.radioLg,
+    controlClassName,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  const labelClasses = [
+    styles.label,
+    size === "sm" && styles.labelSm,
+    size === "lg" && styles.labelLg,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  const wrapperClasses = [
+    styles.itemWrapper,
+    variant === "card" && styles.itemWrapperCard,
+    className,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  // If no label/description, render just the radio
+  if (!label && !resolvedHelperText) {
+    return (
+      <BaseRadio.Root
+        value={value}
+        disabled={disabled}
+        aria-label={ariaLabel}
+        aria-labelledby={ariaLabelledBy}
+        aria-describedby={ariaDescribedBy}
+        className={[radioClasses, className].filter(Boolean).join(" ")}
+      >
+        <BaseRadio.Indicator className={styles.indicator} />
+      </BaseRadio.Root>
+    );
+  }
+
+  return (
+    <label
+      className={wrapperClasses}
+      data-disabled={disabled || undefined}
+      data-has-description={resolvedHelperText ? true : undefined}
+    >
+      <BaseRadio.Root
+        value={value}
+        disabled={disabled}
+        aria-label={ariaLabel}
+        aria-labelledby={mergeAriaIds(ariaLabelledBy, labelId)}
+        aria-describedby={mergeAriaIds(ariaDescribedBy, descriptionId)}
+        className={radioClasses}
+      >
+        <BaseRadio.Indicator className={styles.indicator} />
+      </BaseRadio.Root>
+      <div className={[styles.content, contentClassName].filter(Boolean).join(" ")}>
+        <span id={labelId} className={labelClasses}>
+          {label}
+        </span>
+        {resolvedHelperText && (
+          <span id={descriptionId} className={styles.helper}>
+            {resolvedHelperText}
+          </span>
+        )}
+      </div>
+    </label>
+  );
+}
+
+// ============================================
+// Radio Group Component
+// ============================================
+
+const RadioGroupRoot = React.forwardRef<HTMLDivElement, RadioGroupProps>(function RadioGroupRoot(
+  {
+    value,
+    defaultValue,
+    onValueChange,
+    onChange,
+    orientation = "vertical",
+    disabled = false,
+    readOnly = false,
+    required = false,
+    name,
+    form,
+    inputRef,
+    label,
+    helperText,
+    error,
+    size: sizeProp,
+    variant = "default",
+    wrapperClassName,
+    groupClassName,
+    children,
+    className,
+    "aria-label": ariaLabel,
+    "aria-labelledby": ariaLabelledBy,
+    "aria-describedby": ariaDescribedBy,
+    ...htmlProps
+  }: RadioGroupProps,
+  ref
+) {
+  const size = useResolvedControlSize(sizeProp);
+  const { labelId, helperId, errorId, hasError, errorMessage } = useFormFieldIds("radio-group", {
+    label,
+    helperText,
+    error,
+  });
+
+  const groupClasses = [styles.group, styles[orientation], className, groupClassName]
+    .filter(Boolean)
+    .join(" ");
+
+  const handleValueChange = onChange ?? onValueChange;
+
+  return (
+    <RadioSizeContext.Provider value={size}>
+      <RadioVariantContext.Provider value={variant}>
+        <div
+          ref={ref}
+          {...htmlProps}
+          className={[styles.wrapper, wrapperClassName].filter(Boolean).join(" ")}
+        >
+          {label && (
+            <span id={labelId} className={styles.groupLabel}>
+              {label}
+            </span>
+          )}
+          <BaseRadioGroup
+            value={value}
+            defaultValue={defaultValue}
+            onValueChange={handleValueChange}
+            disabled={disabled}
+            readOnly={readOnly}
+            required={required}
+            name={name}
+            form={form}
+            inputRef={inputRef}
+            aria-label={ariaLabel}
+            aria-labelledby={mergeAriaIds(ariaLabelledBy, labelId)}
+            aria-describedby={mergeAriaIds(ariaDescribedBy, errorId, helperId)}
+            className={groupClasses}
+          >
+            {children}
+          </BaseRadioGroup>
+          {helperText && (
+            <span
+              id={helperId}
+              className={hasError ? [styles.helper, styles.error].join(" ") : styles.helper}
+            >
+              {helperText}
+            </span>
+          )}
+          {errorMessage && (
+            <span id={errorId} className={styles.error}>
+              {errorMessage}
+            </span>
+          )}
+        </div>
+      </RadioVariantContext.Provider>
+    </RadioSizeContext.Provider>
+  );
+});
+
+// ============================================
+// Compound Component Export
+// ============================================
+
+export const RadioGroup = Object.assign(RadioGroupRoot, {
+  Item: RadioItem,
+});
+
+export type { RadioGroupProps as RadioGroupRootProps };

package/src/components/ScrollArea/ScrollArea.contract.json

@@ -0,0 +1,131 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "ScrollArea",
+  "description": "A styled scrollable container with thin scrollbars and optional fade indicators.",
+  "category": "layout",
+  "tags": [
+    "scroll",
+    "overflow",
+    "scrollbar",
+    "container",
+    "layout"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/ScrollArea/index.tsx",
+  "exportName": "ScrollArea",
+  "propsSummary": [
+    "children: node (required)",
+    "orientation: horizontal|vertical|both (default: vertical)",
+    "scrollbarVisibility: auto|always|hover (default: auto)",
+    "showFades: boolean (default: false)",
+    "className: string"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Scrollable content",
+      "required": true
+    },
+    "orientation": {
+      "type": "enum",
+      "description": "Scroll direction",
+      "default": "vertical",
+      "required": false,
+      "values": [
+        "horizontal",
+        "vertical",
+        "both"
+      ]
+    },
+    "scrollbarVisibility": {
+      "type": "enum",
+      "description": "When to show the scrollbar",
+      "default": "auto",
+      "required": false,
+      "values": [
+        "auto",
+        "always",
+        "hover"
+      ]
+    },
+    "showFades": {
+      "type": "boolean",
+      "description": "Show gradient fade indicators at scroll edges",
+      "default": "false",
+      "required": false
+    },
+    "className": {
+      "type": "string",
+      "description": "Additional class name",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Content overflows its container and needs scrolling",
+      "Horizontal tab bars or chip lists that may overflow",
+      "Scrollable panels, sidebars, or dropdown content",
+      "Any area where native scrollbars look too heavy"
+    ],
+    "whenNot": [
+      "Page-level scrolling (use native body scroll)",
+      "Very short content that never overflows"
+    ],
+    "guidelines": [
+      "Use `orientation` to constrain scroll direction",
+      "Use `showFades` to hint at hidden content beyond the viewport",
+      "The `hover` scrollbar visibility keeps the UI clean until the user interacts",
+      "Combine with `orientation=\"horizontal\"` for tab bars and chip rows"
+    ],
+    "accessibility": [
+      "Preserves native scroll behavior and keyboard support",
+      "Scrollbar is visible on focus for keyboard users",
+      "Respects prefers-reduced-motion for fade transitions"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Vertical",
+      "description": "Vertical scrollable area with thin scrollbar.",
+      "code": "<ScrollArea style={{ height: '200px' }}>\n  {/* Long content */}\n</ScrollArea>"
+    },
+    {
+      "name": "Horizontal",
+      "description": "Horizontal scrollable area for overflowing inline content like tabs or chips.",
+      "code": "<ScrollArea orientation=\"horizontal\">\n  <div style={{ display: 'flex', gap: '8px' }}>\n    {tags.map(tag => <Chip key={tag}>{tag}</Chip>)}\n  </div>\n</ScrollArea>"
+    },
+    {
+      "name": "With Fades",
+      "description": "Fade indicators show when content is scrollable in either direction.",
+      "code": "<ScrollArea orientation=\"horizontal\" showFades>\n  {/* Overflowing content */}\n</ScrollArea>"
+    },
+    {
+      "name": "Hover Scrollbar",
+      "description": "Scrollbar is hidden until the user hovers over the scroll area.",
+      "code": "<ScrollArea scrollbarVisibility=\"hover\" style={{ height: '200px' }}>\n  {/* Content */}\n</ScrollArea>"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "orientation: horizontal|vertical|both - scroll direction",
+      "scrollbarVisibility: auto|always|hover - scrollbar display mode",
+      "showFades: boolean - gradient edge indicators"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root"
+    ],
+    "commonPatterns": [
+      "<ScrollArea orientation=\"horizontal\"><div style={{ display: \"flex\", gap: 8 }}>{items}</div></ScrollArea>",
+      "<ScrollArea style={{ height: 300 }}>{longContent}</ScrollArea>"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:02.867Z"
+  }
+}

package/src/components/ScrollArea/ScrollArea.module.scss

@@ -0,0 +1,149 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+// ============================================
+// ScrollArea Root
+// ============================================
+
+.root {
+  position: relative;
+  overflow: hidden;
+}
+
+// ============================================
+// Fade masks — applied to the viewport via CSS mask-image.
+// This fades out the actual content at the edges, which is
+// far more visible than overlaying a gradient pseudo-element.
+// ============================================
+
+.fadeMaskEnd {
+  &.horizontal {
+    mask-image: linear-gradient(to right, black calc(100% - 48px), transparent 100%);
+  }
+
+  &.vertical {
+    mask-image: linear-gradient(to bottom, black calc(100% - 32px), transparent 100%);
+  }
+
+  &.both {
+    mask-image: linear-gradient(to right, black calc(100% - 48px), transparent 100%);
+  }
+}
+
+.fadeMaskStart {
+  &.horizontal {
+    mask-image: linear-gradient(to left, black calc(100% - 48px), transparent 100%);
+  }
+
+  &.vertical {
+    mask-image: linear-gradient(to top, black calc(100% - 32px), transparent 100%);
+  }
+
+  &.both {
+    mask-image: linear-gradient(to left, black calc(100% - 48px), transparent 100%);
+  }
+}
+
+.fadeMaskBoth {
+  &.horizontal {
+    mask-image: linear-gradient(to right, transparent, black 48px, black calc(100% - 48px), transparent 100%);
+  }
+
+  &.vertical {
+    mask-image: linear-gradient(to bottom, transparent, black 32px, black calc(100% - 32px), transparent 100%);
+  }
+
+  &.both {
+    mask-image: linear-gradient(to right, transparent, black 48px, black calc(100% - 48px), transparent 100%);
+  }
+}
+
+// ============================================
+// Viewport (scrollable area)
+// ============================================
+
+.viewport {
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+  // Reserve gutter space so the thumb revealing on hover doesn't shift
+  // content; transparent at rest gives the overlay-scrollbar look.
+  scrollbar-width: thin;
+  scrollbar-color: transparent transparent;
+
+  // Webkit custom scrollbar
+  &::-webkit-scrollbar {
+    width: 6px;
+    height: 6px;
+  }
+
+  &::-webkit-scrollbar-track {
+    background: transparent;
+  }
+
+  &::-webkit-scrollbar-thumb {
+    background-color: transparent;
+    border-radius: var(--fui-radius-full, $fui-radius-full);
+    transition: background-color var(--fui-transition-fast, $fui-transition-fast);
+  }
+
+  // Reveal thumb while the viewport is hovered
+  &:hover {
+    scrollbar-color: var(--fui-border-strong, $fui-border-strong) transparent;
+  }
+
+  &:hover::-webkit-scrollbar-thumb {
+    background-color: var(--fui-border-strong, $fui-border-strong);
+  }
+
+  // Darker when hovering the thumb itself
+  &::-webkit-scrollbar-thumb:hover {
+    background-color: var(--fui-text-tertiary, $fui-text-tertiary);
+  }
+}
+
+// Orientation variants
+.horizontal {
+  overflow-x: auto;
+  overflow-y: hidden;
+}
+
+.vertical {
+  overflow-x: hidden;
+  overflow-y: auto;
+}
+
+.both {
+  overflow: auto;
+}
+
+// ============================================
+// Scrollbar visibility modes
+// ============================================
+
+// Always show scrollbar
+.scrollbarAlways {
+  &::-webkit-scrollbar-thumb {
+    background-color: var(--fui-border-strong, $fui-border-strong);
+  }
+}
+
+// Only show scrollbar on hover
+.scrollbarHover {
+  scrollbar-width: none;
+
+  &::-webkit-scrollbar {
+    width: 0;
+    height: 0;
+  }
+
+  &:hover {
+    scrollbar-width: thin;
+
+    &::-webkit-scrollbar {
+      width: 6px;
+      height: 6px;
+    }
+  }
+}
+

package/src/components/ScrollArea/ScrollArea.stories.tsx

@@ -0,0 +1,97 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { ScrollArea } from '.';
+
+/**
+ * ScrollArea is a styled scrollable container with thin scrollbars and
+ * optional fade indicators. Use orientation to constrain scroll direction
+ * and showFades to hint at content beyond the viewport.
+ */
+const meta = {
+  title: 'Layout/ScrollArea',
+  component: ScrollArea,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Styled scrollable container with thin scrollbars and optional fade indicators.',
+      },
+    },
+  },
+  argTypes: {
+    orientation: {
+      control: 'select',
+      options: ['horizontal', 'vertical', 'both'],
+      description: 'Scroll direction',
+    },
+    scrollbarVisibility: {
+      control: 'select',
+      options: ['auto', 'always', 'hover'],
+      description: 'When to show the scrollbar',
+    },
+    showFades: {
+      control: 'boolean',
+      description: 'Show gradient fade indicators at scroll edges',
+    },
+  },
+  args: {
+    orientation: 'vertical',
+    scrollbarVisibility: 'auto',
+    showFades: false,
+    children: (
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 8, padding: 8 }}>
+        {Array.from({ length: 20 }, (_, i) => (
+          <div key={i}>Row {i + 1}</div>
+        ))}
+      </div>
+    ),
+  },
+  render: (args) => (
+    <ScrollArea {...args} style={{ height: 160, width: 280 }}>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 8, padding: 8 }}>
+        {Array.from({ length: 20 }, (_, i) => (
+          <div key={i}>Row {i + 1}</div>
+        ))}
+      </div>
+    </ScrollArea>
+  ),
+} satisfies Meta<typeof ScrollArea>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Vertical: Story = {};
+
+export const Horizontal: Story = {
+  args: { orientation: 'horizontal' },
+  render: (args) => (
+    <ScrollArea {...args} style={{ width: 280 }}>
+      <div style={{ display: 'flex', gap: 8, padding: 8 }}>
+        {Array.from({ length: 20 }, (_, i) => (
+          <div key={i} style={{ flex: '0 0 auto' }}>
+            Chip {i + 1}
+          </div>
+        ))}
+      </div>
+    </ScrollArea>
+  ),
+};
+
+export const WithFades: Story = {
+  args: { orientation: 'horizontal', showFades: true },
+  render: (args) => (
+    <ScrollArea {...args} style={{ width: 280 }}>
+      <div style={{ display: 'flex', gap: 8, padding: 8 }}>
+        {Array.from({ length: 20 }, (_, i) => (
+          <div key={i} style={{ flex: '0 0 auto' }}>
+            Item {i + 1}
+          </div>
+        ))}
+      </div>
+    </ScrollArea>
+  ),
+};
+
+export const HoverScrollbar: Story = {
+  args: { scrollbarVisibility: 'hover' },
+};