@fragments-sdk/ui 0.1.0

package/src/components/Progress/index.tsx

@@ -0,0 +1,196 @@
+import * as React from 'react';
+import { Progress as BaseProgress } from '@base-ui/react/progress';
+import styles from './Progress.module.scss';
+// Import globals to ensure CSS variables are defined
+import '../../styles/globals.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export interface ProgressProps {
+  /** Current progress value (0-100). Null for indeterminate. */
+  value?: number | null;
+  /** Minimum value */
+  min?: number;
+  /** Maximum value */
+  max?: number;
+  /** Size of the progress bar */
+  size?: 'sm' | 'md' | 'lg';
+  /** Color variant */
+  variant?: 'default' | 'success' | 'warning' | 'danger';
+  /** Label text */
+  label?: string;
+  /** Show percentage value */
+  showValue?: boolean;
+  /** Custom value formatter */
+  formatValue?: (value: number) => string;
+  /** Additional class name */
+  className?: string;
+}
+
+export interface CircularProgressProps {
+  /** Current progress value (0-100). Null for indeterminate. */
+  value?: number | null;
+  /** Size of the circular progress */
+  size?: 'sm' | 'md' | 'lg';
+  /** Color variant */
+  variant?: 'default' | 'success' | 'warning' | 'danger';
+  /** Show percentage in center */
+  showValue?: boolean;
+  /** Stroke width */
+  strokeWidth?: number;
+  /** Additional class name */
+  className?: string;
+}
+
+// ============================================
+// Linear Progress
+// ============================================
+
+export function Progress({
+  value = null,
+  min = 0,
+  max = 100,
+  size = 'md',
+  variant = 'default',
+  label,
+  showValue = false,
+  formatValue,
+  className,
+}: ProgressProps) {
+  const isIndeterminate = value === null;
+  const percentage = isIndeterminate ? 0 : Math.round(((value - min) / (max - min)) * 100);
+
+  const trackClasses = [
+    styles.track,
+    size === 'sm' && styles.trackSm,
+    size === 'md' && styles.trackMd,
+    size === 'lg' && styles.trackLg,
+  ].filter(Boolean).join(' ');
+
+  const indicatorClasses = [
+    styles.indicator,
+    variant === 'success' && styles.indicatorSuccess,
+    variant === 'warning' && styles.indicatorWarning,
+    variant === 'danger' && styles.indicatorDanger,
+    isIndeterminate && styles.indicatorIndeterminate,
+  ].filter(Boolean).join(' ');
+
+  const rootClasses = [styles.root, className].filter(Boolean).join(' ');
+
+  const displayValue = formatValue
+    ? formatValue(percentage)
+    : `${percentage}%`;
+
+  return (
+    <BaseProgress.Root
+      value={value}
+      min={min}
+      max={max}
+      className={rootClasses}
+    >
+      {(label || showValue) && (
+        <div className={styles.header}>
+          {label && (
+            <BaseProgress.Label className={styles.label}>
+              {label}
+            </BaseProgress.Label>
+          )}
+          {showValue && !isIndeterminate && (
+            <span className={styles.value}>{displayValue}</span>
+          )}
+        </div>
+      )}
+      <BaseProgress.Track className={trackClasses}>
+        <BaseProgress.Indicator
+          className={indicatorClasses}
+          style={isIndeterminate ? undefined : { width: `${percentage}%` }}
+        />
+      </BaseProgress.Track>
+    </BaseProgress.Root>
+  );
+}
+
+// ============================================
+// Circular Progress
+// ============================================
+
+const CIRCLE_SIZES = {
+  sm: { size: 32, strokeWidth: 3 },
+  md: { size: 48, strokeWidth: 4 },
+  lg: { size: 64, strokeWidth: 5 },
+};
+
+export function CircularProgress({
+  value = null,
+  size = 'md',
+  variant = 'default',
+  showValue = false,
+  strokeWidth: customStrokeWidth,
+  className,
+}: CircularProgressProps) {
+  const isIndeterminate = value === null;
+  const percentage = isIndeterminate ? 0 : Math.min(100, Math.max(0, value));
+
+  const { size: svgSize, strokeWidth: defaultStrokeWidth } = CIRCLE_SIZES[size];
+  const strokeWidth = customStrokeWidth ?? defaultStrokeWidth;
+
+  const radius = (svgSize - strokeWidth) / 2;
+  const circumference = 2 * Math.PI * radius;
+  const offset = circumference - (percentage / 100) * circumference;
+
+  const sizeClass = size === 'sm' ? styles.circularSm
+    : size === 'lg' ? styles.circularLg
+    : styles.circularMd;
+
+  const indicatorClasses = [
+    styles.circularIndicator,
+    variant === 'success' && styles.circularIndicatorSuccess,
+    variant === 'warning' && styles.circularIndicatorWarning,
+    variant === 'danger' && styles.circularIndicatorDanger,
+    isIndeterminate && styles.circularIndicatorIndeterminate,
+  ].filter(Boolean).join(' ');
+
+  const rootClasses = [styles.circular, sizeClass, className]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <BaseProgress.Root
+      value={value}
+      className={rootClasses}
+      aria-valuenow={isIndeterminate ? undefined : percentage}
+    >
+      <svg
+        className={styles.circularSvg}
+        width={svgSize}
+        height={svgSize}
+        viewBox={`0 0 ${svgSize} ${svgSize}`}
+      >
+        {/* Track circle */}
+        <circle
+          className={styles.circularTrack}
+          cx={svgSize / 2}
+          cy={svgSize / 2}
+          r={radius}
+          strokeWidth={strokeWidth}
+        />
+        {/* Indicator circle */}
+        <circle
+          className={indicatorClasses}
+          cx={svgSize / 2}
+          cy={svgSize / 2}
+          r={radius}
+          strokeWidth={strokeWidth}
+          strokeDasharray={circumference}
+          strokeDashoffset={isIndeterminate ? undefined : offset}
+          style={isIndeterminate ? { transformOrigin: 'center' } : undefined}
+        />
+      </svg>
+      {showValue && !isIndeterminate && (
+        <span className={styles.circularValue}>{Math.round(percentage)}%</span>
+      )}
+    </BaseProgress.Root>
+  );
+}

package/src/components/RadioGroup/RadioGroup.fragment.tsx

@@ -0,0 +1,188 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { RadioGroup } from './index.js';
+
+export default defineSegment({
+  component: RadioGroup,
+
+  meta: {
+    name: 'RadioGroup',
+    description: 'Single selection from a list of mutually exclusive options',
+    category: 'forms',
+    status: 'stable',
+    tags: ['form', 'radio', 'selection', 'options'],
+  },
+
+  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 Toggle/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 descriptions for complex options',
+    ],
+    accessibility: [
+      'Group must have an accessible label',
+      'Use arrow keys to navigate between options',
+      'Selected option should be clearly indicated',
+    ],
+  },
+
+  props: {
+    value: {
+      type: 'string',
+      description: 'Controlled selected value',
+    },
+    defaultValue: {
+      type: 'string',
+      description: 'Default value (uncontrolled)',
+    },
+    onValueChange: {
+      type: 'function',
+      description: 'Callback when selection changes',
+    },
+    orientation: {
+      type: 'enum',
+      values: ['horizontal', 'vertical'],
+      default: 'vertical',
+      description: 'Layout orientation',
+    },
+    size: {
+      type: 'enum',
+      values: ['sm', 'md', 'lg'],
+      default: 'md',
+      description: 'Size variant',
+    },
+    disabled: {
+      type: 'boolean',
+      default: false,
+      description: 'Disable all options',
+    },
+    label: {
+      type: 'string',
+      description: 'Group label',
+    },
+    error: {
+      type: 'string',
+      description: 'Error message',
+    },
+  },
+
+  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: 'Toggle',
+      relationship: 'alternative',
+      note: 'Use Toggle for binary on/off choices',
+    },
+  ],
+
+  contract: {
+    propsSummary: [
+      'value: string - selected value',
+      'onValueChange: (value: string) => void',
+      'orientation: horizontal|vertical (default: vertical)',
+      'size: sm|md|lg (default: md)',
+      'disabled: boolean - disable all options',
+    ],
+    scenarioTags: [
+      'form.selection',
+      'form.preference',
+      'form.option',
+    ],
+    a11yRules: [
+      'A11Y_RADIO_GROUP',
+      'A11Y_LABEL_REQUIRED',
+    ],
+    bans: [],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Basic radio group with labels',
+      render: () => (
+        <RadioGroup defaultValue="option1" label="Select an option">
+          <RadioGroup.Item value="option1" label="Option 1" />
+          <RadioGroup.Item value="option2" label="Option 2" />
+          <RadioGroup.Item value="option3" label="Option 3" />
+        </RadioGroup>
+      ),
+    },
+    {
+      name: 'With Descriptions',
+      description: 'Radio items with additional context',
+      render: () => (
+        <RadioGroup defaultValue="standard" label="Shipping Method">
+          <RadioGroup.Item
+            value="standard"
+            label="Standard"
+            description="5-7 business days"
+          />
+          <RadioGroup.Item
+            value="express"
+            label="Express"
+            description="2-3 business days"
+          />
+          <RadioGroup.Item
+            value="overnight"
+            label="Overnight"
+            description="Next business day"
+          />
+        </RadioGroup>
+      ),
+    },
+    {
+      name: 'Horizontal',
+      description: 'Side-by-side layout',
+      render: () => (
+        <RadioGroup orientation="horizontal" defaultValue="small" label="Size">
+          <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>
+      ),
+    },
+    {
+      name: 'With Error',
+      description: 'Validation error state',
+      render: () => (
+        <RadioGroup label="Required selection" error="Please select an option">
+          <RadioGroup.Item value="a" label="Option A" />
+          <RadioGroup.Item value="b" label="Option B" />
+        </RadioGroup>
+      ),
+    },
+    {
+      name: 'Disabled',
+      description: 'Non-interactive state',
+      render: () => (
+        <RadioGroup disabled defaultValue="locked" label="Locked selection">
+          <RadioGroup.Item value="locked" label="This is locked" />
+          <RadioGroup.Item value="other" label="Cannot select" />
+        </RadioGroup>
+      ),
+    },
+  ],
+});

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

@@ -0,0 +1,155 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+// Container wrapper
+.wrapper {
+  display: flex;
+  flex-direction: column;
+  gap: var(--fui-space-2, $fui-space-2);
+}
+
+.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: flex-start;
+  gap: var(--fui-space-2, $fui-space-2);
+  cursor: pointer;
+  font-family: var(--fui-font-sans, $fui-font-sans);
+
+  &[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;
+  width: 1rem;
+  height: 1rem;
+  margin-top: 2px;
+  background-color: var(--fui-bg-elevated, $fui-bg-elevated);
+  border: 1px solid var(--fui-border-strong, $fui-border-strong);
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+  cursor: inherit;
+
+  &:hover:not([data-disabled]) {
+    border-color: var(--fui-text-tertiary, $fui-text-tertiary);
+  }
+
+  &[data-checked] {
+    background-color: var(--fui-bg-elevated, $fui-bg-elevated);
+    border-color: var(--fui-color-accent, $fui-color-accent);
+  }
+
+  &[data-checked]:hover:not([data-disabled]) {
+    border-color: var(--fui-color-accent-hover, $fui-color-accent-hover);
+  }
+
+  &[data-invalid] {
+    border-color: var(--fui-color-danger, $fui-color-danger);
+  }
+}
+
+// Size variants
+.radioSm {
+  width: 0.875rem;
+  height: 0.875rem;
+  margin-top: 3px;
+}
+
+.radioLg {
+  width: 1.25rem;
+  height: 1.25rem;
+  margin-top: 0;
+}
+
+// The indicator dot
+.indicator {
+  width: 0.5rem;
+  height: 0.5rem;
+  background-color: var(--fui-color-accent, $fui-color-accent);
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+
+  // Animation
+  opacity: 0;
+  transform: scale(0);
+  transition:
+    opacity var(--fui-transition-fast, $fui-transition-fast),
+    transform var(--fui-transition-fast, $fui-transition-fast);
+
+  [data-checked] > & {
+    opacity: 1;
+    transform: 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: 2px;
+}
+
+.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);
+}
+
+.description {
+  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, $fui-color-danger);
+}

package/src/components/RadioGroup/index.tsx

@@ -0,0 +1,166 @@
+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 styles from './RadioGroup.module.scss';
+// Import globals to ensure CSS variables are defined
+import '../../styles/globals.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export interface RadioGroupProps {
+  /** Current value (controlled) */
+  value?: string;
+  /** Default value (uncontrolled) */
+  defaultValue?: string;
+  /** Callback when value changes */
+  onValueChange?: (value: string) => void;
+  /** Orientation of the radio group */
+  orientation?: 'horizontal' | 'vertical';
+  /** Whether the group is disabled */
+  disabled?: boolean;
+  /** Form field name */
+  name?: string;
+  /** Label for the group */
+  label?: string;
+  /** Error message */
+  error?: string;
+  /** Size variant */
+  size?: 'sm' | 'md' | 'lg';
+  /** Children (Radio.Item components) */
+  children: React.ReactNode;
+  /** Additional class name */
+  className?: string;
+}
+
+export interface RadioItemProps {
+  /** The value for this radio item */
+  value: string;
+  /** Label text */
+  label?: string;
+  /** Description text below the label */
+  description?: string;
+  /** Whether this item is disabled */
+  disabled?: boolean;
+  /** Additional class name */
+  className?: string;
+}
+
+// ============================================
+// Context for size
+// ============================================
+
+const RadioSizeContext = React.createContext<'sm' | 'md' | 'lg'>('md');
+
+// ============================================
+// Radio Item Component
+// ============================================
+
+function RadioItem({
+  value,
+  label,
+  description,
+  disabled = false,
+  className,
+}: RadioItemProps) {
+  const size = React.useContext(RadioSizeContext);
+
+  const radioClasses = [
+    styles.radio,
+    size === 'sm' && styles.radioSm,
+    size === 'lg' && styles.radioLg,
+  ].filter(Boolean).join(' ');
+
+  const labelClasses = [
+    styles.label,
+    size === 'sm' && styles.labelSm,
+    size === 'lg' && styles.labelLg,
+  ].filter(Boolean).join(' ');
+
+  const wrapperClasses = [styles.itemWrapper, className].filter(Boolean).join(' ');
+
+  // If no label/description, render just the radio
+  if (!label && !description) {
+    return (
+      <BaseRadio.Root
+        value={value}
+        disabled={disabled}
+        className={[radioClasses, className].filter(Boolean).join(' ')}
+      >
+        <BaseRadio.Indicator className={styles.indicator} />
+      </BaseRadio.Root>
+    );
+  }
+
+  return (
+    <label className={wrapperClasses} data-disabled={disabled || undefined}>
+      <BaseRadio.Root
+        value={value}
+        disabled={disabled}
+        className={radioClasses}
+      >
+        <BaseRadio.Indicator className={styles.indicator} />
+      </BaseRadio.Root>
+      <div className={styles.content}>
+        <span className={labelClasses}>{label}</span>
+        {description && (
+          <span className={styles.description}>{description}</span>
+        )}
+      </div>
+    </label>
+  );
+}
+
+// ============================================
+// Radio Group Component
+// ============================================
+
+function RadioGroupRoot({
+  value,
+  defaultValue,
+  onValueChange,
+  orientation = 'vertical',
+  disabled = false,
+  name,
+  label,
+  error,
+  size = 'md',
+  children,
+  className,
+}: RadioGroupProps) {
+  const groupClasses = [
+    styles.group,
+    styles[orientation],
+    className,
+  ].filter(Boolean).join(' ');
+
+  return (
+    <RadioSizeContext.Provider value={size}>
+      <div className={styles.wrapper}>
+        {label && <span className={styles.groupLabel}>{label}</span>}
+        <BaseRadioGroup
+          value={value}
+          defaultValue={defaultValue}
+          onValueChange={onValueChange}
+          disabled={disabled}
+          name={name}
+          className={groupClasses}
+        >
+          {children}
+        </BaseRadioGroup>
+        {error && <span className={styles.error}>{error}</span>}
+      </div>
+    </RadioSizeContext.Provider>
+  );
+}
+
+// ============================================
+// Compound Component Export
+// ============================================
+
+export const RadioGroup = Object.assign(RadioGroupRoot, {
+  Item: RadioItem,
+});
+
+export type { RadioGroupProps as RadioGroupRootProps };