@usefragments/ui 1.4.0 → 1.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usefragments/ui",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "license": "MIT",
   "description": "Customizable UI components built on Base UI headless primitives",
   "author": "Conan McNicholl",
@@ -241,7 +241,7 @@
     "vite": "^6.0.0",
     "vitest": "^2.1.8",
     "vitest-axe": "^0.1.0",
-    "@usefragments/core": "1.7.1"
+    "@usefragments/core": "1.9.0"
   },
   "files": [
     "src",

package/src/components/Card/Card.contract.json

@@ -77,6 +77,11 @@
     ]
   },
   "examples": [
+    {
+      "name": "Nested Heading",
+      "description": "Select the heading level required by the surrounding document outline",
+      "code": "<Card variant=\"panel\" padding=\"none\">\n  <Card.Header divided>\n    <Card.Title as=\"h4\">Nested panel</Card.Title>\n  </Card.Header>\n  <Card.Body padding=\"md\">Panel content</Card.Body>\n</Card>"
+    },
     {
       "name": "Default",
       "description": "Standard quiet card surface",

package/src/components/Card/index.tsx

@@ -42,6 +42,9 @@ export interface CardHeaderProps extends React.HTMLAttributes<HTMLDivElement> {
 
 export interface CardTitleProps extends React.HTMLAttributes<HTMLHeadingElement> {
   children: React.ReactNode;
+  /** Semantic heading level.
+   * @default "h3" */
+  as?: "h2" | "h3" | "h4" | "h5" | "h6";
 }
 
 export interface CardDescriptionProps extends React.HTMLAttributes<HTMLParagraphElement> {
@@ -179,12 +182,12 @@ function CardHeader({ children, divided, className, ...htmlProps }: CardHeaderPr
   );
 }
 
-function CardTitle({ children, className, ...htmlProps }: CardTitleProps) {
+function CardTitle({ children, as: Component = "h3", className, ...htmlProps }: CardTitleProps) {
   const classes = [styles.title, className].filter(Boolean).join(" ");
   return (
-    <h3 {...htmlProps} className={classes}>
+    <Component {...htmlProps} className={classes}>
       {children}
-    </h3>
+    </Component>
   );
 }
 

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

@@ -3,13 +3,7 @@
   "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"
-  ],
+  "tags": ["progress", "loading", "indicator", "percentage", "status"],
   "status": "stable",
   "sourcePath": "src/components/Progress/index.tsx",
   "exportName": "Progress",
@@ -18,7 +12,8 @@
     "min: number (default: 0)",
     "max: number (default: 100)",
     "size: sm|md|lg (default: md)",
-    "variant: default|success|warning|danger (default: default)",
+    "variant: default|neutral|success|warning|danger (default: default)",
+    "role: progressbar|meter (default: progressbar)",
     "label: string",
     "showValue: boolean (default: false)",
     "formatValue: function"
@@ -47,23 +42,14 @@
       "description": "Size of the progress bar",
       "default": "md",
       "required": false,
-      "values": [
-        "sm",
-        "md",
-        "lg"
-      ]
+      "values": ["sm", "md", "lg"]
     },
     "variant": {
       "type": "enum",
       "description": "Color variant",
       "default": "default",
       "required": false,
-      "values": [
-        "default",
-        "success",
-        "warning",
-        "danger"
-      ]
+      "values": ["default", "neutral", "success", "warning", "danger"]
     },
     "label": {
       "type": "string",
@@ -99,10 +85,12 @@
       "Use indeterminate for unknown durations",
       "Include a label for context when the purpose isnt obvious",
       "Use appropriate color variants for success/warning/danger states",
+      "Use variant=\"neutral\" with role=\"meter\" for magnitude or distribution values where reaching the maximum is not a success state",
       "Determinate values are clamped to the min/max range for display"
     ],
     "accessibility": [
       "Uses role=\"progressbar\" with aria-valuenow",
+      "Accepts role=\"meter\" for scalar measurements within a known range",
       "Label is associated with the progress bar",
       "State changes are announced to screen readers"
     ]
@@ -155,17 +143,11 @@
       "showValue: boolean - display percentage",
       "Determinate display values are clamped (and invalid min/max ranges render as 0%)"
     ],
-    "a11yRules": [
-      "A11Y_PROGRESS_ROLE",
-      "A11Y_PROGRESS_VALUE"
-    ]
+    "a11yRules": ["A11Y_PROGRESS_ROLE", "A11Y_PROGRESS_VALUE"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Root",
-      "Circular"
-    ]
+    "subComponents": ["Root", "Circular"]
   },
   "provenance": {
     "source": "migrated",

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

@@ -63,6 +63,10 @@
 }
 
 // Color variants
+.indicatorNeutral {
+  background-color: var(--fui-text-tertiary, $fui-text-tertiary);
+}
+
 .indicatorSuccess {
   background-color: var(--fui-color-success-text, $fui-color-success-text);
 }
@@ -94,7 +98,7 @@
 }
 
 // Complete state
-.root[data-complete] .indicator {
+.root[data-complete] .indicator:not(.indicatorNeutral) {
   background-color: var(--fui-color-success-text, $fui-color-success-text);
 }
 

package/src/components/Progress/index.tsx

@@ -1,14 +1,14 @@
-'use client';
+"use client";
 
-import * as React from 'react';
-import { Progress as BaseProgress } from '@base-ui/react/progress';
-import styles from './Progress.module.scss';
+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'> {
+export interface ProgressProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "defaultValue"> {
   /** Current progress value (0-100). Null for indeterminate. */
   value?: number | null;
   /** Minimum value */
@@ -16,9 +16,9 @@ export interface ProgressProps extends Omit<React.HTMLAttributes<HTMLDivElement>
   /** Maximum value */
   max?: number;
   /** Size of the progress bar */
-  size?: 'sm' | 'md' | 'lg';
+  size?: "sm" | "md" | "lg";
   /** Color variant */
-  variant?: 'default' | 'success' | 'warning' | 'danger';
+  variant?: "default" | "neutral" | "success" | "warning" | "danger";
   /** Label text */
   label?: string;
   /** Show percentage value */
@@ -31,9 +31,9 @@ export interface CircularProgressProps extends React.HTMLAttributes<HTMLDivEleme
   /** Current progress value (0-100). Null for indeterminate. */
   value?: number | null;
   /** Size of the circular progress */
-  size?: 'sm' | 'md' | 'lg';
+  size?: "sm" | "md" | "lg";
   /** Color variant */
-  variant?: 'default' | 'success' | 'warning' | 'danger';
+  variant?: "default" | "success" | "warning" | "danger";
   /** Show percentage in center */
   showValue?: boolean;
   /** Stroke width */
@@ -48,52 +48,51 @@ function ProgressRoot({
   value = null,
   min = 0,
   max = 100,
-  size = 'md',
-  variant = 'default',
+  size = "md",
+  variant = "default",
   label,
   showValue = false,
   formatValue,
   className,
-  'aria-label': ariaLabel,
-  'aria-valuetext': ariaValueText,
+  role,
+  "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 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(' ');
+    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,
+    variant === "neutral" && styles.indicatorNeutral,
+    variant === "success" && styles.indicatorSuccess,
+    variant === "warning" && styles.indicatorWarning,
+    variant === "danger" && styles.indicatorDanger,
     isIndeterminate && styles.indicatorIndeterminate,
-  ].filter(Boolean).join(' ');
+  ]
+    .filter(Boolean)
+    .join(" ");
 
-  const rootClasses = [styles.root, className].filter(Boolean).join(' ');
+  const rootClasses = [styles.root, className].filter(Boolean).join(" ");
 
-  const displayValue = formatValue
-    ? formatValue(percentage)
-    : `${percentage}%`;
+  const displayValue = formatValue ? formatValue(percentage) : `${percentage}%`;
 
   // Default value text for screen readers
-  const effectiveValueText = ariaValueText || (
-    isIndeterminate ? 'Loading' : `${percentage} percent`
-  );
+  const effectiveValueText =
+    ariaValueText || (isIndeterminate ? "Loading" : `${percentage} percent`);
 
   return (
     <BaseProgress.Root
@@ -102,20 +101,15 @@ function ProgressRoot({
       min={min}
       max={max}
       className={rootClasses}
-      aria-label={ariaLabel || (label ? undefined : 'Progress')}
+      role={role ?? "progressbar"}
+      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>
-          )}
+          {label && <BaseProgress.Label className={styles.label}>{label}</BaseProgress.Label>}
+          {showValue && !isIndeterminate && <span className={styles.value}>{displayValue}</span>}
         </div>
       )}
       <BaseProgress.Track className={trackClasses}>
@@ -140,14 +134,14 @@ const CIRCLE_SIZES = {
 
 function CircularProgressRoot({
   value = null,
-  size = 'md',
-  variant = 'default',
+  size = "md",
+  variant = "default",
   showValue = false,
   strokeWidth: customStrokeWidth,
   className,
-  'aria-label': ariaLabel,
-  'aria-labelledby': ariaLabelledBy,
-  'aria-valuetext': ariaValueText,
+  "aria-label": ariaLabel,
+  "aria-labelledby": ariaLabelledBy,
+  "aria-valuetext": ariaValueText,
   ...htmlProps
 }: CircularProgressProps) {
   const isIndeterminate = value === null;
@@ -160,26 +154,24 @@ function CircularProgressRoot({
   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 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,
+    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(' ');
+    .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`
-  );
+  const effectiveValueText =
+    ariaValueText || (isIndeterminate ? "Loading" : `${Math.round(percentage)} percent`);
 
   return (
     <BaseProgress.Root
@@ -220,11 +212,13 @@ function CircularProgressRoot({
           strokeWidth={strokeWidth}
           strokeDasharray={circumference}
           strokeDashoffset={isIndeterminate ? undefined : offset}
-          style={isIndeterminate ? { transformOrigin: 'center' } : undefined}
+          style={isIndeterminate ? { transformOrigin: "center" } : undefined}
         />
       </svg>
       {showValue && !isIndeterminate && (
-        <span className={styles.circularValue} aria-hidden="true">{Math.round(percentage)}%</span>
+        <span className={styles.circularValue} aria-hidden="true">
+          {Math.round(percentage)}%
+        </span>
       )}
     </BaseProgress.Root>
   );