@usefragments/ui 1.0.0

package/src/components/RadioGroup/RadioGroup.contract.json

@@ -0,0 +1,236 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "RadioGroup",
+  "description": "Single selection from a list of mutually exclusive options",
+  "category": "forms",
+  "tags": [
+    "form",
+    "radio",
+    "selection",
+    "options"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/RadioGroup/index.tsx",
+  "exportName": "RadioGroup",
+  "propsSummary": [
+    "value: string",
+    "defaultValue: string",
+    "onValueChange: function",
+    "onChange: function",
+    "orientation: horizontal|vertical (default: vertical)",
+    "disabled: boolean (default: false)",
+    "name: string",
+    "label: string",
+    "helperText: string",
+    "error: union",
+    "size: sm|md|lg (default: md)",
+    "wrapperClassName: string",
+    "groupClassName: string",
+    "children: node (required)"
+  ],
+  "props": {
+    "value": {
+      "type": "string",
+      "description": "Controlled selected value",
+      "required": false
+    },
+    "defaultValue": {
+      "type": "string",
+      "description": "Default value (uncontrolled)",
+      "required": false
+    },
+    "onValueChange": {
+      "type": "function",
+      "description": "Callback when selection changes",
+      "required": false
+    },
+    "onChange": {
+      "type": "function",
+      "description": "Alias for onValueChange",
+      "required": false
+    },
+    "orientation": {
+      "type": "enum",
+      "description": "Layout orientation",
+      "default": "vertical",
+      "required": false,
+      "values": [
+        "horizontal",
+        "vertical"
+      ]
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "Disable all options",
+      "default": "false",
+      "required": false
+    },
+    "name": {
+      "type": "string",
+      "description": "Form field name",
+      "required": false
+    },
+    "label": {
+      "type": "string",
+      "description": "Group label",
+      "required": false
+    },
+    "helperText": {
+      "type": "string",
+      "description": "Helper text shown below the group",
+      "required": false
+    },
+    "error": {
+      "type": "union",
+      "description": "Show error styling. When a string is provided, it is displayed as an error message.",
+      "required": false
+    },
+    "size": {
+      "type": "enum",
+      "description": "Size variant",
+      "default": "md",
+      "required": false,
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "variant": {
+      "type": "enum",
+      "description": "Visual variant. 'default' is the inline radio, 'card' renders each item as a full-width clickable card with the radio tucked inside.",
+      "default": "default",
+      "required": false,
+      "values": [
+        "default",
+        "card"
+      ]
+    },
+    "wrapperClassName": {
+      "type": "string",
+      "description": "Class name for the outer wrapper element",
+      "required": false
+    },
+    "groupClassName": {
+      "type": "string",
+      "description": "Class name for the inner radio group element",
+      "required": false
+    },
+    "children": {
+      "type": "node",
+      "description": "RadioGroup.Item elements",
+      "required": true
+    }
+  },
+  "usage": {
+    "when": [
+      "User must select exactly one option from a small set",
+      "Options are mutually exclusive",
+      "All options should be visible at once",
+      "2-5 options available"
+    ],
+    "whenNot": [
+      "Multiple selections allowed (use Checkbox group)",
+      "Many options (use Select)",
+      "Binary on/off choice (use Switch)",
+      "Options need to be searchable (use Combobox)"
+    ],
+    "guidelines": [
+      "Always have one option pre-selected when possible",
+      "Order options logically (alphabetical, frequency, etc.)",
+      "Keep option labels concise",
+      "Use helperText on RadioGroup.Item for complex options"
+    ],
+    "accessibility": [
+      "Group must have an accessible label",
+      "Use arrow keys to navigate between options",
+      "Selected option should be clearly indicated"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic radio group with labels",
+      "code": "<RadioGroup defaultValue=\"option1\" label=\"Select an option\">\n  <RadioGroup.Item value=\"option1\" label=\"Option 1\" />\n  <RadioGroup.Item value=\"option2\" label=\"Option 2\" />\n  <RadioGroup.Item value=\"option3\" label=\"Option 3\" />\n</RadioGroup>"
+    },
+    {
+      "name": "With Helper Text",
+      "description": "Radio items with additional context",
+      "code": "<RadioGroup defaultValue=\"standard\" label=\"Shipping Method\">\n  <RadioGroup.Item\n    value=\"standard\"\n    label=\"Standard\"\n    helperText=\"5-7 business days\"\n  />\n  <RadioGroup.Item\n    value=\"express\"\n    label=\"Express\"\n    helperText=\"2-3 business days\"\n  />\n  <RadioGroup.Item\n    value=\"overnight\"\n    label=\"Overnight\"\n    helperText=\"Next business day\"\n  />\n</RadioGroup>"
+    },
+    {
+      "name": "Horizontal",
+      "description": "Side-by-side layout",
+      "code": "<RadioGroup orientation=\"horizontal\" defaultValue=\"small\" label=\"Size\">\n  <RadioGroup.Item value=\"small\" label=\"S\" />\n  <RadioGroup.Item value=\"medium\" label=\"M\" />\n  <RadioGroup.Item value=\"large\" label=\"L\" />\n  <RadioGroup.Item value=\"xlarge\" label=\"XL\" />\n</RadioGroup>"
+    },
+    {
+      "name": "With Group Helper Text",
+      "description": "Group-level helper text",
+      "code": "<RadioGroup defaultValue=\"standard\" label=\"Plan\" helperText=\"You can change your plan at any time\">\n  <RadioGroup.Item value=\"free\" label=\"Free\" />\n  <RadioGroup.Item value=\"standard\" label=\"Standard\" />\n  <RadioGroup.Item value=\"pro\" label=\"Pro\" />\n</RadioGroup>"
+    },
+    {
+      "name": "With Error",
+      "description": "Validation error state (string shows error message)",
+      "code": "<RadioGroup label=\"Required selection\" error=\"Please select an option\">\n  <RadioGroup.Item value=\"a\" label=\"Option A\" />\n  <RadioGroup.Item value=\"b\" label=\"Option B\" />\n</RadioGroup>"
+    },
+    {
+      "name": "Disabled",
+      "description": "Non-interactive state",
+      "code": "<RadioGroup disabled defaultValue=\"locked\" label=\"Locked selection\">\n  <RadioGroup.Item value=\"locked\" label=\"This is locked\" />\n  <RadioGroup.Item value=\"other\" label=\"Cannot select\" />\n</RadioGroup>"
+    },
+    {
+      "name": "Styling Targets",
+      "description": "Use explicit class names for wrapper/group/item styling hooks",
+      "code": "<RadioGroup\n  defaultValue=\"a\"\n  label=\"Display mode\"\n  wrapperClassName=\"demo-radio-wrapper\"\n  groupClassName=\"demo-radio-group\"\n>\n  <RadioGroup.Item value=\"a\" label=\"Compact\" controlClassName=\"demo-radio-control\" contentClassName=\"demo-radio-content\" />\n  <RadioGroup.Item value=\"b\" label=\"Comfortable\" />\n</RadioGroup>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Checkbox",
+      "relationship": "alternative",
+      "note": "Use Checkbox for multiple selections"
+    },
+    {
+      "component": "Select",
+      "relationship": "alternative",
+      "note": "Use Select for many options or limited space"
+    },
+    {
+      "component": "Switch",
+      "relationship": "alternative",
+      "note": "Use Switch for binary on/off choices"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "value: string - selected value",
+      "onValueChange: (value: string) => void",
+      "onChange: (value: string) => void - alias for onValueChange",
+      "orientation: horizontal|vertical (default: vertical)",
+      "size: sm|md|lg (default: md)",
+      "label: string - group label",
+      "helperText: string - helper text below the group",
+      "error: boolean | string - error styling and message",
+      "disabled: boolean - disable all options",
+      "wrapperClassName/groupClassName - explicit styling targets for wrapper and group",
+      "RadioGroup.Item supports helperText (preferred) and description (legacy alias) plus controlClassName/contentClassName for item-level styling"
+    ],
+    "a11yRules": [
+      "A11Y_RADIO_GROUP",
+      "A11Y_LABEL_REQUIRED",
+      "A11Y_TARGET_SIZE_MIN"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Item"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:02.692Z"
+  }
+}

package/src/components/RadioGroup/RadioGroup.module.scss

@@ -0,0 +1,272 @@
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+
+// Container wrapper
+.wrapper {
+  display: flex;
+  flex-direction: column;
+  gap: var(--fui-space-1, $fui-space-1);
+}
+
+.groupLabel {
+  @include label-text;
+}
+
+// Radio group
+.group {
+  display: flex;
+  gap: var(--fui-space-3, $fui-space-3);
+}
+
+.vertical {
+  flex-direction: column;
+}
+
+.horizontal {
+  flex-direction: row;
+  flex-wrap: wrap;
+}
+
+// Individual item wrapper
+.itemWrapper {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--fui-space-1, $fui-space-1);
+  cursor: pointer;
+  font-family: var(--fui-font-sans, $fui-font-sans);
+
+  &[data-has-description] {
+    align-items: flex-start;
+  }
+
+  &[data-disabled] {
+    cursor: not-allowed;
+    opacity: 0.5;
+  }
+}
+
+// The radio circle
+.radio {
+  @include interactive-base;
+
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  box-sizing: border-box;
+  width: var(--fui-icon-sm, $fui-icon-sm);
+  height: var(--fui-icon-sm, $fui-icon-sm);
+  margin-top: 0;
+  background-color: var(--fui-field-bg, $fui-bg-elevated);
+  border: 1px solid var(--fui-field-border, $fui-border-strong);
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+  cursor: inherit;
+
+  &:hover:not([data-disabled]) {
+    border-color: var(--fui-field-border-hover, $fui-text-tertiary);
+  }
+
+  &[data-checked] {
+    background-color: color-mix(
+      in srgb,
+      var(--fui-button-primary-base, #{$fui-color-accent}) 8%,
+      var(--fui-field-bg, #{$fui-bg-elevated})
+    );
+    border-color: var(--fui-button-primary-base, $fui-color-accent);
+    box-shadow: inset 0 0 0 1px
+      color-mix(in srgb, var(--fui-button-primary-base, #{$fui-color-accent}) 55%, transparent);
+  }
+
+  &[data-checked]:hover:not([data-disabled]) {
+    background-color: color-mix(
+      in srgb,
+      var(--fui-button-primary-hover, #{$fui-color-accent}) 12%,
+      var(--fui-field-bg, #{$fui-bg-elevated})
+    );
+    border-color: var(--fui-button-primary-hover, $fui-color-accent);
+  }
+
+  &[data-invalid] {
+    border-color: var(--fui-color-danger-text, $fui-color-danger-text);
+  }
+
+  &::before {
+    content: "";
+    position: absolute;
+    top: 50%;
+    left: 50%;
+    width: var(--fui-target-size-min, $fui-target-size-min);
+    height: var(--fui-target-size-min, $fui-target-size-min);
+    transform: translate(-50%, -50%);
+  }
+}
+
+// Size variants
+.radioSm {
+  width: var(--fui-icon-xs, $fui-icon-xs);
+  height: var(--fui-icon-xs, $fui-icon-xs);
+}
+
+.radioLg {
+  width: 1.25rem;
+  height: 1.25rem;
+}
+
+// The indicator dot - use absolute positioning for perfect centering
+.indicator {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 0.5rem;
+  height: 0.5rem;
+  background-color: var(--fui-button-primary-base, $fui-color-accent);
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+
+  // Animation - use translate for centering combined with scale
+  opacity: 0;
+  transform: translate(-50%, -50%) scale(0);
+  transition:
+    opacity var(--fui-transition-fast, $fui-transition-fast),
+    transform var(--fui-transition-fast, $fui-transition-fast);
+
+  [data-checked] > & {
+    opacity: 1;
+    transform: translate(-50%, -50%) scale(1);
+  }
+}
+
+.radioSm .indicator {
+  width: 0.375rem;
+  height: 0.375rem;
+}
+
+.radioLg .indicator {
+  width: 0.625rem;
+  height: 0.625rem;
+}
+
+// Label content
+.content {
+  display: flex;
+  flex-direction: column;
+  gap: var(--fui-space-0-5, $fui-space-0-5);
+}
+
+.label {
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  color: var(--fui-text-primary, $fui-text-primary);
+  line-height: var(--fui-line-height-tight, $fui-line-height-tight);
+  user-select: none;
+}
+
+.labelSm {
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+}
+
+.labelLg {
+  font-size: var(--fui-font-size-base, $fui-font-size-base);
+}
+
+.helper {
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+}
+
+// Error message
+.error {
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  color: var(--fui-color-danger-text, $fui-color-danger-text);
+}
+
+// ============================================
+// Card variant: each item is a full-width clickable surface that signals
+// selection via background + border tint while keeping the inline radio
+// circle as the canonical control. The `:has([data-checked])` selector is
+// the source of truth for selected styling — no extra attribute plumbing
+// required from JS.
+// ============================================
+// Card variant uses a transparent base so the selected accent tint reads
+// as a deliberate state change rather than a small shift between two grey
+// surfaces. Mirrors the pattern used by the Checkbox card variant.
+.itemWrapperCard {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-3, $fui-space-3);
+  width: 100%;
+  height: var(
+    --fui-input-height,
+    $fui-input-height
+  ); // matches Input size="md" so radio cards align with form fields
+  box-sizing: border-box;
+  padding: 0 var(--fui-space-3, $fui-space-3);
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+  border: 1px solid var(--fui-border-default, $fui-border-default);
+  background: transparent;
+  transition:
+    background var(--fui-transition-fast, $fui-transition-fast),
+    border-color var(--fui-transition-fast, $fui-transition-fast),
+    box-shadow var(--fui-transition-fast, $fui-transition-fast);
+
+  &:hover:not([data-disabled]) {
+    background: var(--fui-bg-hover, $fui-bg-hover);
+    border-color: var(--fui-border-strong, $fui-border-strong);
+  }
+
+  &:focus-within:not([data-disabled]) {
+    border-color: var(--fui-button-primary-base, $fui-color-accent);
+    @include focus-ring;
+  }
+
+  &:has([data-checked]) {
+    background: color-mix(
+      in srgb,
+      var(--fui-button-primary-base, #{$fui-color-accent}) 13%,
+      transparent
+    );
+    border-color: color-mix(
+      in srgb,
+      var(--fui-button-primary-base, #{$fui-color-accent}) 62%,
+      transparent
+    );
+    box-shadow: 0 0 0 1px
+      color-mix(in srgb, var(--fui-button-primary-base, #{$fui-color-accent}) 28%, transparent);
+  }
+
+  // Inline with the input field convention rather than the lifted card
+  // headline weight — the label sits at base-size, tight against the radio.
+  .label {
+    font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  }
+}
+
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .radio {
+    border-width: 2px;
+    border-color: var(--fui-text-primary, $fui-text-primary);
+
+    &[data-checked] {
+      border-color: var(--fui-button-primary-base, $fui-color-accent);
+    }
+
+    &[data-invalid] {
+      border-color: var(--fui-color-danger-text, $fui-color-danger-text);
+    }
+  }
+}
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .indicator {
+    transition: none;
+  }
+}

package/src/components/RadioGroup/RadioGroup.stories.tsx

@@ -0,0 +1,107 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { RadioGroup } from '.';
+
+/**
+ * RadioGroup lets users select one option from a set of mutually exclusive
+ * choices. It is a compound component: each option is a RadioGroup.Item with
+ * a value and label.
+ */
+const meta = {
+  title: 'Forms/RadioGroup',
+  component: RadioGroup,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: 'Single selection from a list of mutually exclusive options.',
+      },
+    },
+  },
+  argTypes: {
+    orientation: {
+      control: 'select',
+      options: ['horizontal', 'vertical'],
+      description: 'Layout orientation',
+    },
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg'],
+      description: 'Size variant',
+    },
+    variant: {
+      control: 'select',
+      options: ['default', 'card'],
+      description: 'Visual variant',
+    },
+    disabled: { control: 'boolean', description: 'Disable all options' },
+  },
+  args: {
+    label: 'Select an option',
+    defaultValue: 'option1',
+    size: 'md',
+    orientation: 'vertical',
+    children: (
+      <>
+        <RadioGroup.Item value="option1" label="Option 1" />
+        <RadioGroup.Item value="option2" label="Option 2" />
+        <RadioGroup.Item value="option3" label="Option 3" />
+      </>
+    ),
+  },
+  render: (args) => (
+    <RadioGroup {...args}>
+      <RadioGroup.Item value="option1" label="Option 1" />
+      <RadioGroup.Item value="option2" label="Option 2" />
+      <RadioGroup.Item value="option3" label="Option 3" />
+    </RadioGroup>
+  ),
+} satisfies Meta<typeof RadioGroup>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const WithHelperText: Story = {
+  args: { label: 'Shipping method', defaultValue: 'standard' },
+  render: (args) => (
+    <RadioGroup {...args}>
+      <RadioGroup.Item value="standard" label="Standard" helperText="5-7 business days" />
+      <RadioGroup.Item value="express" label="Express" helperText="2-3 business days" />
+      <RadioGroup.Item value="overnight" label="Overnight" helperText="Next business day" />
+    </RadioGroup>
+  ),
+};
+
+export const Horizontal: Story = {
+  args: { label: 'Size', defaultValue: 'medium', orientation: 'horizontal' },
+  render: (args) => (
+    <RadioGroup {...args}>
+      <RadioGroup.Item value="small" label="S" />
+      <RadioGroup.Item value="medium" label="M" />
+      <RadioGroup.Item value="large" label="L" />
+      <RadioGroup.Item value="xlarge" label="XL" />
+    </RadioGroup>
+  ),
+};
+
+export const WithError: Story = {
+  args: { label: 'Required selection', defaultValue: undefined, error: 'Please select an option' },
+  render: (args) => (
+    <RadioGroup {...args}>
+      <RadioGroup.Item value="a" label="Option A" />
+      <RadioGroup.Item value="b" label="Option B" />
+    </RadioGroup>
+  ),
+};
+
+export const Disabled: Story = {
+  args: { label: 'Locked selection', defaultValue: 'locked', disabled: true },
+  render: (args) => (
+    <RadioGroup {...args}>
+      <RadioGroup.Item value="locked" label="This is locked" />
+      <RadioGroup.Item value="other" label="Cannot select" />
+    </RadioGroup>
+  ),
+};