@usefragments/ui 1.0.0

package/src/components/Progress/Progress.contract.json

@@ -0,0 +1,176 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Progress",
+  "description": "Visual indicator of task completion or loading state. Available in linear and circular variants.",
+  "category": "feedback",
+  "tags": [
+    "progress",
+    "loading",
+    "indicator",
+    "percentage",
+    "status"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Progress/index.tsx",
+  "exportName": "Progress",
+  "propsSummary": [
+    "value: number (default: null)",
+    "min: number (default: 0)",
+    "max: number (default: 100)",
+    "size: sm|md|lg (default: md)",
+    "variant: default|success|warning|danger (default: default)",
+    "label: string",
+    "showValue: boolean (default: false)",
+    "formatValue: function"
+  ],
+  "props": {
+    "value": {
+      "type": "number",
+      "description": "Current progress value (0-100). Null for indeterminate.",
+      "default": "null",
+      "required": false
+    },
+    "min": {
+      "type": "number",
+      "description": "Minimum value",
+      "default": "0",
+      "required": false
+    },
+    "max": {
+      "type": "number",
+      "description": "Maximum value",
+      "default": "100",
+      "required": false
+    },
+    "size": {
+      "type": "enum",
+      "description": "Size of the progress bar",
+      "default": "md",
+      "required": false,
+      "values": [
+        "sm",
+        "md",
+        "lg"
+      ]
+    },
+    "variant": {
+      "type": "enum",
+      "description": "Color variant",
+      "default": "default",
+      "required": false,
+      "values": [
+        "default",
+        "success",
+        "warning",
+        "danger"
+      ]
+    },
+    "label": {
+      "type": "string",
+      "description": "Label text above the progress bar",
+      "required": false
+    },
+    "showValue": {
+      "type": "boolean",
+      "description": "Show percentage value",
+      "default": "false",
+      "required": false
+    },
+    "formatValue": {
+      "type": "function",
+      "description": "Custom formatter for displayed progress value",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Showing upload/download progress",
+      "Displaying task completion percentage",
+      "Form completion indicators",
+      "Loading states with known duration"
+    ],
+    "whenNot": [
+      "Unknown loading duration (use Spinner)",
+      "Step-based progress (use Stepper)",
+      "Status without percentage (use Badge)"
+    ],
+    "guidelines": [
+      "Use determinate progress when you know the completion percentage",
+      "Use indeterminate for unknown durations",
+      "Include a label for context when the purpose isnt obvious",
+      "Use appropriate color variants for success/warning/danger states",
+      "Determinate values are clamped to the min/max range for display"
+    ],
+    "accessibility": [
+      "Uses role=\"progressbar\" with aria-valuenow",
+      "Label is associated with the progress bar",
+      "State changes are announced to screen readers"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic progress bar with percentage",
+      "code": "<Progress value={60} label=\"Uploading...\" showValue />"
+    },
+    {
+      "name": "Variants",
+      "description": "Different color variants for different states",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '16px', width: '300px' }}>\n  <Progress value={75} variant=\"default\" label=\"Processing\" showValue />\n  <Progress value={100} variant=\"success\" label=\"Complete\" showValue />\n  <Progress value={80} variant=\"warning\" label=\"Almost full\" showValue />\n  <Progress value={95} variant=\"danger\" label=\"Storage critical\" showValue />\n</div>"
+    },
+    {
+      "name": "Sizes",
+      "description": "Different progress bar sizes",
+      "code": "<div style={{ display: 'flex', flexDirection: 'column', gap: '16px', width: '300px' }}>\n  <Progress value={50} size=\"sm\" label=\"Small\" />\n  <Progress value={50} size=\"md\" label=\"Medium\" />\n  <Progress value={50} size=\"lg\" label=\"Large\" />\n</div>"
+    },
+    {
+      "name": "Indeterminate",
+      "description": "Loading state with unknown duration",
+      "code": "<Progress value={null} label=\"Loading...\" />"
+    },
+    {
+      "name": "Circular",
+      "description": "Circular progress indicator",
+      "code": "<div style={{ display: 'flex', gap: '24px', alignItems: 'center' }}>\n  <CircularProgress value={25} size=\"sm\" />\n  <CircularProgress value={50} size=\"md\" showValue />\n  <CircularProgress value={75} size=\"lg\" showValue variant=\"success\" />\n  <CircularProgress value={null} size=\"md\" />\n</div>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Badge",
+      "relationship": "alternative",
+      "note": "Use Badge for status without percentage"
+    },
+    {
+      "component": "Alert",
+      "relationship": "sibling",
+      "note": "Use Alert for completion messages"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "value: number|null - progress percentage (null for indeterminate)",
+      "size: sm|md|lg - bar thickness",
+      "variant: default|success|warning|danger - color",
+      "label: string - descriptive label",
+      "showValue: boolean - display percentage",
+      "Determinate display values are clamped (and invalid min/max ranges render as 0%)"
+    ],
+    "a11yRules": [
+      "A11Y_PROGRESS_ROLE",
+      "A11Y_PROGRESS_VALUE"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root",
+      "Circular"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:19:02.339Z"
+  }
+}

package/src/components/Progress/Progress.module.scss

@@ -0,0 +1,185 @@
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
+
+// Root container
+.root {
+  display: flex;
+  flex-direction: column;
+  gap: var(--fui-space-1, $fui-space-1);
+  width: 100%;
+  font-family: var(--fui-font-sans, $fui-font-sans);
+}
+
+// Header with label and value
+.header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--fui-space-2, $fui-space-2);
+}
+
+// Label text
+.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);
+}
+
+// Value display
+.value {
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  font-variant-numeric: tabular-nums;
+}
+
+// Track (background bar)
+.track {
+  position: relative;
+  width: 100%;
+  overflow: hidden;
+  background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+}
+
+// Size variants for track (using closest 7px grid values)
+.trackSm {
+  height: calc(var(--fui-space-1, $fui-space-1) / 2); // ~3.5px
+}
+
+.trackMd {
+  height: var(--fui-space-1, $fui-space-1); // 7px
+}
+
+.trackLg {
+  height: var(--fui-space-2, $fui-space-2); // 14px
+}
+
+// Indicator (filled portion)
+.indicator {
+  height: 100%;
+  background-color: var(--fui-color-accent, $fui-color-accent);
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+  transition: width var(--fui-transition-normal, $fui-transition-normal);
+}
+
+// Color variants
+.indicatorSuccess {
+  background-color: var(--fui-color-success-text, $fui-color-success-text);
+}
+
+.indicatorWarning {
+  background-color: var(--fui-color-warning-text, $fui-color-warning-text);
+}
+
+.indicatorDanger {
+  background-color: var(--fui-color-danger-text, $fui-color-danger-text);
+}
+
+// Indeterminate animation
+.indicatorIndeterminate {
+  width: 50% !important;
+  animation: indeterminate 1.5s ease-in-out infinite;
+}
+
+@keyframes indeterminate {
+  0% {
+    transform: translateX(-100%);
+  }
+  50% {
+    transform: translateX(100%);
+  }
+  100% {
+    transform: translateX(-100%);
+  }
+}
+
+// Complete state
+.root[data-complete] .indicator {
+  background-color: var(--fui-color-success-text, $fui-color-success-text);
+}
+
+// Circular progress variant
+.circular {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.circularSvg {
+  transform: rotate(-90deg);
+}
+
+.circularTrack {
+  stroke: var(--fui-bg-tertiary, $fui-bg-tertiary);
+  fill: none;
+}
+
+.circularIndicator {
+  stroke: var(--fui-color-accent, $fui-color-accent);
+  fill: none;
+  stroke-linecap: round;
+  transition: stroke-dashoffset var(--fui-transition-normal, $fui-transition-normal);
+}
+
+.circularIndicatorSuccess {
+  stroke: var(--fui-color-success-text, $fui-color-success-text);
+}
+
+.circularIndicatorWarning {
+  stroke: var(--fui-color-warning-text, $fui-color-warning-text);
+}
+
+.circularIndicatorDanger {
+  stroke: var(--fui-color-danger-text, $fui-color-danger-text);
+}
+
+.circularIndicatorIndeterminate {
+  animation: circularIndeterminate 1.5s ease-in-out infinite;
+}
+
+@keyframes circularIndeterminate {
+  0% {
+    stroke-dashoffset: 280;
+    transform: rotate(0deg);
+  }
+  50% {
+    stroke-dashoffset: 70;
+  }
+  100% {
+    stroke-dashoffset: 280;
+    transform: rotate(360deg);
+  }
+}
+
+.circularValue {
+  position: absolute;
+  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);
+  font-variant-numeric: tabular-nums;
+}
+
+// Size variants for circular (using closest 7px grid values)
+.circularSm {
+  width: var(--fui-space-4, $fui-space-4); // 28px
+  height: var(--fui-space-4, $fui-space-4);
+
+  .circularValue {
+    font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  }
+}
+
+.circularMd {
+  width: var(--fui-space-6, $fui-space-6); // 42px
+  height: var(--fui-space-6, $fui-space-6);
+}
+
+.circularLg {
+  width: var(--fui-space-8, $fui-space-8); // 56px
+  height: var(--fui-space-8, $fui-space-8);
+
+  .circularValue {
+    font-size: var(--fui-font-size-base, $fui-font-size-base);
+  }
+}

package/src/components/Progress/Progress.stories.tsx

@@ -0,0 +1,64 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Progress } from '.';
+
+/**
+ * Progress is a visual indicator of task completion or loading state.
+ * Determinate values render a filled bar; a null value renders an
+ * indeterminate animation. Includes a Circular subcomponent.
+ */
+const meta = {
+  title: 'Feedback/Progress',
+  component: Progress,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Visual indicator of task completion or loading state in linear and circular variants.',
+      },
+    },
+  },
+  argTypes: {
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg'],
+      description: 'Size of the progress bar',
+    },
+    variant: {
+      control: 'select',
+      options: ['default', 'success', 'warning', 'danger'],
+      description: 'Color variant',
+    },
+    showValue: { control: 'boolean', description: 'Show percentage value' },
+  },
+  args: { value: 60, size: 'md', variant: 'default', label: 'Uploading', showValue: true },
+} satisfies Meta<typeof Progress>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { value: 60, label: 'Uploading', showValue: true },
+};
+
+export const Success: Story = {
+  args: { value: 100, variant: 'success', label: 'Complete', showValue: true },
+};
+
+export const Danger: Story = {
+  args: { value: 95, variant: 'danger', label: 'Storage critical', showValue: true },
+};
+
+export const Large: Story = {
+  args: { value: 40, size: 'lg', label: 'Processing', showValue: true },
+};
+
+export const Indeterminate: Story = {
+  args: { value: null, label: 'Loading', showValue: false },
+};
+
+export const Circular: Story = {
+  args: { value: 75, showValue: true },
+  render: (args) => <Progress.Circular {...args} variant="success" />,
+};

package/src/components/Progress/index.tsx

@@ -0,0 +1,238 @@
+'use client';
+
+import * as React from 'react';
+import { Progress as BaseProgress } from '@base-ui/react/progress';
+import styles from './Progress.module.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export interface ProgressProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'defaultValue'> {
+  /** 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;
+}
+
+export interface CircularProgressProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** 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;
+}
+
+// ============================================
+// Horizontal progress bar
+// ============================================
+
+function ProgressRoot({
+  value = null,
+  min = 0,
+  max = 100,
+  size = 'md',
+  variant = 'default',
+  label,
+  showValue = false,
+  formatValue,
+  className,
+  'aria-label': ariaLabel,
+  'aria-valuetext': ariaValueText,
+  ...htmlProps
+}: ProgressProps) {
+  const isIndeterminate = value === null;
+  const range = max - min;
+  const normalizedPercentage = isIndeterminate
+    ? 0
+    : range <= 0
+      ? 0
+      : ((value - min) / range) * 100;
+  const percentage = isIndeterminate
+    ? 0
+    : Math.round(Math.min(100, Math.max(0, normalizedPercentage)));
+
+  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}%`;
+
+  // Default value text for screen readers
+  const effectiveValueText = ariaValueText || (
+    isIndeterminate ? 'Loading' : `${percentage} percent`
+  );
+
+  return (
+    <BaseProgress.Root
+      {...htmlProps}
+      value={value}
+      min={min}
+      max={max}
+      className={rootClasses}
+      aria-label={ariaLabel || (label ? undefined : 'Progress')}
+      aria-valuetext={effectiveValueText}
+      aria-busy={isIndeterminate}
+    >
+      {(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 },
+};
+
+function CircularProgressRoot({
+  value = null,
+  size = 'md',
+  variant = 'default',
+  showValue = false,
+  strokeWidth: customStrokeWidth,
+  className,
+  'aria-label': ariaLabel,
+  'aria-labelledby': ariaLabelledBy,
+  'aria-valuetext': ariaValueText,
+  ...htmlProps
+}: 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(' ');
+
+  // Default value text for screen readers
+  const effectiveValueText = ariaValueText || (
+    isIndeterminate ? 'Loading' : `${Math.round(percentage)} percent`
+  );
+
+  return (
+    <BaseProgress.Root
+      {...htmlProps}
+      value={value}
+      min={0}
+      max={100}
+      className={rootClasses}
+      aria-label={ariaLabel}
+      aria-labelledby={ariaLabelledBy}
+      aria-valuenow={isIndeterminate ? undefined : percentage}
+      aria-valuemin={0}
+      aria-valuemax={100}
+      aria-valuetext={effectiveValueText}
+      aria-busy={isIndeterminate}
+    >
+      <svg
+        className={styles.circularSvg}
+        width={svgSize}
+        height={svgSize}
+        viewBox={`0 0 ${svgSize} ${svgSize}`}
+        aria-hidden="true"
+      >
+        {/* 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} aria-hidden="true">{Math.round(percentage)}%</span>
+      )}
+    </BaseProgress.Root>
+  );
+}
+
+export const CircularProgress = CircularProgressRoot;
+
+export const Progress = Object.assign(ProgressRoot, {
+  Root: ProgressRoot,
+  Circular: CircularProgressRoot,
+});