@tangible/ui 0.0.1

package/components/Pager/Pager.js

@@ -0,0 +1,151 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from 'react';
+import { cx } from '../../utils/cx.js';
+import { Button } from '../Button/index.js';
+import { IconButton } from '../IconButton/index.js';
+// =============================================================================
+// Pager Component
+// =============================================================================
+//
+// Generic pagination control for any paginated content. Not coupled to any
+// specific data source — just needs current page, total pages, and a callback.
+//
+// Use this for card grids, search results, galleries, or any paginated list.
+// For TanStack Table integration, use TablePagination which wraps this.
+//
+// =============================================================================
+const DEFAULT_MAX_SLOTS = 7;
+/**
+ * Build a stable-width list of page tokens (numbers + ellipses).
+ *
+ * Always shows: first, last, current, current±1
+ * Single-page gaps are filled in (no "1 ... 3" silliness)
+ * Expands symmetrically from current, biased toward center
+ */
+function buildNumberTokens(total, current, maxSlots = DEFAULT_MAX_SLOTS) {
+    if (total <= 1)
+        return [1];
+    if (total <= maxSlots)
+        return Array.from({ length: total }, (_, i) => i + 1);
+    const inRange = (n) => n >= 1 && n <= total;
+    // Start with anchors: first, last, current and neighbors
+    const chosen = new Set([1, total]);
+    if (inRange(current))
+        chosen.add(current);
+    if (inRange(current - 1))
+        chosen.add(current - 1);
+    if (inRange(current + 1))
+        chosen.add(current + 1);
+    /**
+     * Convert chosen pages to tokens, inserting ellipses for gaps.
+     * Single-page gaps get filled in rather than showing an ellipsis.
+     */
+    const materialize = () => {
+        const pages = [...chosen].sort((a, b) => a - b);
+        const tokens = [];
+        for (let i = 0; i < pages.length; i++) {
+            tokens.push(pages[i]);
+            const next = pages[i + 1];
+            if (next == null)
+                break;
+            const gap = next - pages[i];
+            if (gap === 2)
+                tokens.push(pages[i] + 1);
+            else if (gap > 2)
+                tokens.push('...');
+        }
+        return tokens;
+    };
+    /** Try adding a page. Returns true if it fit within maxSlots. */
+    const tryAdd = (p) => {
+        if (!inRange(p) || chosen.has(p))
+            return false;
+        chosen.add(p);
+        if (materialize().length > maxSlots) {
+            chosen.delete(p);
+            return false;
+        }
+        return true;
+    };
+    // Expand symmetrically from current until we fill available slots
+    let offset = 2;
+    while (materialize().length < maxSlots) {
+        const left = current - offset;
+        const right = current + offset;
+        // Bias toward center: if past halfway, try right first
+        const preferRight = current > total / 2;
+        const [first, second] = preferRight ? [right, left] : [left, right];
+        // Try preferred side, then other side
+        const added = tryAdd(first) || tryAdd(second);
+        // If neither side worked, try both explicitly (handles edge cases)
+        if (!added && !tryAdd(left) && !tryAdd(right))
+            break;
+        offset++;
+    }
+    return materialize();
+}
+function buildItems(total, current, mode, maxNumbers) {
+    const items = [];
+    items.push({
+        kind: 'prev',
+        disabled: current <= 1,
+        page: Math.max(1, current - 1),
+    });
+    if (mode === 'full') {
+        for (let p = 1; p <= total; p++) {
+            items.push({ kind: 'page', page: p, current: p === current });
+        }
+    }
+    else if (mode === 'ends') {
+        const set = new Set([1, current - 1, current, current + 1, total].filter((n) => n >= 1 && n <= total));
+        const pages = Array.from(set).sort((a, b) => a - b);
+        pages.forEach((p) => items.push({ kind: 'page', page: p, current: p === current }));
+    }
+    else if (mode === 'smart') {
+        const tokens = buildNumberTokens(total, current, maxNumbers);
+        tokens.forEach((tok) => {
+            if (tok === '...')
+                items.push({ kind: 'ellipsis' });
+            else
+                items.push({ kind: 'page', page: tok, current: tok === current });
+        });
+    }
+    // mode === 'simple' => no page numbers
+    items.push({
+        kind: 'next',
+        disabled: current >= total,
+        page: Math.min(total, current + 1),
+    });
+    return items;
+}
+// -----------------------------------------------------------------------------
+// Component
+// -----------------------------------------------------------------------------
+export function Pager({ currentPage, totalPages, onPageChange, pageSize, pageSizeOptions, onPageSizeChange, mode = 'smart', maxNumbers = DEFAULT_MAX_SLOTS, navStyle = 'text', hidden = false, className, }) {
+    // Normalise inputs
+    const total = Math.max(1, totalPages);
+    const current = Math.min(total, Math.max(1, currentPage));
+    const items = React.useMemo(() => buildItems(total, current, mode, maxNumbers), [total, current, mode, maxNumbers]);
+    const go = React.useCallback((page) => onPageChange(page), [onPageChange]);
+    if (hidden)
+        return null;
+    const showPageSizeSelector = pageSizeOptions && pageSizeOptions.length > 0 && onPageSizeChange;
+    return (_jsxs("div", { className: cx('tui-pager', className), children: [_jsx("nav", { className: "tui-pager__nav", "aria-label": "Pagination", children: items.map((it, i) => {
+                    if (it.kind === 'ellipsis') {
+                        return (_jsx("span", { className: "tui-pager__ellipsis", "aria-hidden": true, children: "..." }, `e${i}`));
+                    }
+                    if (it.kind === 'prev' || it.kind === 'next') {
+                        const isPrev = it.kind === 'prev';
+                        const label = isPrev ? 'Previous page' : 'Next page';
+                        if (navStyle === 'icon') {
+                            return (_jsx(IconButton, { icon: isPrev ? 'system/chevron-left' : 'system/chevron-right', label: label, showTooltip: true, size: "sm", theme: "secondary", variant: "outline", disabled: it.disabled, onClick: () => go(it.page), className: "tui-pager__item" }, it.kind));
+                        }
+                        return (_jsx(Button, { size: "sm", theme: "secondary", variant: "outline", disabled: it.disabled, onClick: () => go(it.page), "aria-label": label, className: "tui-pager__item", children: isPrev ? 'Prev' : 'Next' }, it.kind));
+                    }
+                    // Page number
+                    if (it.kind === 'page') {
+                        return (_jsx(Button, { size: "sm", theme: it.current ? 'primary' : 'secondary', variant: it.current ? 'solid' : 'outline', "aria-current": it.current ? 'page' : undefined, "aria-label": `Page ${it.page}`, onClick: () => go(it.page), className: "tui-pager__item", children: it.page }, it.page));
+                    }
+                    return null;
+                }) }), _jsxs("div", { className: "tui-pager__info", children: [_jsxs("span", { children: ["Page ", _jsx("strong", { children: current }), " of ", total] }), showPageSizeSelector && (_jsxs("label", { className: "tui-pager__page-size-label", children: [_jsx("span", { className: "tui-visually-hidden", children: "Items per page" }), _jsx("select", { className: "tui-input", value: pageSize, onChange: (e) => onPageSizeChange(Number(e.target.value)), children: pageSizeOptions.map((s) => (_jsxs("option", { value: s, children: [s, " / page"] }, s))) })] }))] })] }));
+}

package/components/Pager/index.d.ts

@@ -0,0 +1,2 @@
+export { Pager } from './Pager';
+export type { PagerProps, PagerMode } from './Pager';

package/components/Pager/index.js

@@ -0,0 +1 @@
+export { Pager } from './Pager.js';

package/components/Progress/Progress.d.ts

@@ -0,0 +1,2 @@
+import type { ProgressProps } from './types';
+export declare function Progress(props: ProgressProps): import("react/jsx-runtime").JSX.Element;

package/components/Progress/Progress.js

@@ -0,0 +1,100 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import React from 'react';
+import { useProgressSegments } from './useProgressSegments.js';
+import { cx } from '../../utils/cx.js';
+// =============================================================================
+// COMPONENT
+// =============================================================================
+export function Progress(props) {
+    const { children, mode = 'line', size = 'md', max = 100, showLabels = true, labelledBy, ariaLabel, defaultLabel, className, } = props;
+    // Determine mode
+    const isSegmented = 'segments' in props && Array.isArray(props.segments);
+    // Standard mode props
+    const value = !isSegmented ? (props.value ?? 0) : 0;
+    const indeterminate = !isSegmented ? (props.indeterminate ?? false) : false;
+    const labelPosition = !isSegmented ? (props.labelPosition ?? 'inline') : 'inline';
+    const labelStart = !isSegmented ? props.labelStart : undefined;
+    const labelEnd = !isSegmented ? props.labelEnd : undefined;
+    const variant = !isSegmented && 'variant' in props ? (props.variant ?? 'ring') : 'ring';
+    // Segments (for segmented mode) — fallback ensures type safety
+    const segments = ('segments' in props && props.segments) || [];
+    // Process segments via hook
+    const { processedSegments, ariaValueText, primaryValue, primaryPct, } = useProgressSegments({ segments, max });
+    // Calculate percentages for standard mode
+    const pct = Math.max(0, Math.min(100, (value / max) * 100));
+    // Dev warning: inside position only supports labelStart (or children)
+    if (import.meta.env.DEV && labelPosition === 'inside' && labelStart && labelEnd) {
+        console.warn('Progress: labelPosition="inside" only supports a single label. ' +
+            'labelEnd will be ignored. Use labelStart or children for inside content.');
+    }
+    // Check if we have any label content to show
+    const hasLabels = !!(labelStart || labelEnd || children);
+    // Determine accessible name props for progressbar
+    const ariaProps = {};
+    if (labelledBy) {
+        ariaProps['aria-labelledby'] = labelledBy;
+    }
+    else if (ariaLabel) {
+        ariaProps['aria-label'] = ariaLabel;
+    }
+    else if (defaultLabel) {
+        ariaProps['aria-label'] = defaultLabel;
+    }
+    // Add valuetext for segmented mode
+    if (isSegmented && ariaValueText) {
+        ariaProps['aria-valuetext'] = ariaValueText;
+    }
+    // aria-valuenow, aria-valuemin, aria-valuemax
+    const ariaValueProps = indeterminate
+        ? {
+            'aria-valuenow': undefined,
+            'aria-valuemin': undefined,
+            'aria-valuemax': undefined,
+            'aria-busy': true,
+        }
+        : {
+            'aria-valuenow': Math.round(isSegmented ? primaryValue : value),
+            'aria-valuemin': 0,
+            'aria-valuemax': max,
+            'aria-busy': undefined,
+        };
+    // Build CSS custom properties
+    const styleVars = {
+        '--tui-progress-value': String(isSegmented ? primaryValue : value),
+        '--tui-progress-max': String(max),
+        '--tui-progress-pct': String(isSegmented ? primaryPct : pct),
+    };
+    // Add segment-specific vars
+    processedSegments.forEach((seg, i) => {
+        styleVars[`--tui-progress-z${i + 1}-pct`] = String(seg.pct);
+        styleVars[`--tui-progress-z${i + 1}-width`] = String(seg.width);
+    });
+    const rootProps = {
+        role: 'progressbar',
+        ...ariaProps,
+        ...ariaValueProps,
+        className: cx('tui-progress', `is-mode-${mode}`, `is-size-${size}`, !isSegmented && showLabels && hasLabels && `is-label-${labelPosition}`, indeterminate && 'is-indeterminate', isSegmented && 'is-segmented', mode === 'circle' && `is-variant-${variant}`, className),
+        style: styleVars,
+    };
+    // Inside label content (for line integrated or circle center)
+    const insideContent = children ?? labelStart;
+    // Content for line variant
+    const lineContent = isSegmented ? (_jsxs(_Fragment, { children: [_jsx("div", { className: "tui-progress__track", children: processedSegments.map((seg, i) => (_jsx("div", { className: cx('tui-progress__bar', `is-z${seg.zIndex}`), style: { '--tui-segment-width': `${seg.width}%` } }, i))) }), showLabels && (children ? (_jsx("div", { className: "tui-progress__segment-labels", children: children })) : (_jsx("div", { className: "tui-progress__segment-labels", children: processedSegments.map((seg, i) => (seg.visible && (_jsxs("span", { className: cx('tui-progress__segment-label', `is-z${seg.zIndex}`), children: [seg.label && _jsx("span", { className: "tui-progress__segment-label-text", children: seg.label }), _jsxs("span", { className: "tui-progress__segment-label-value", children: [seg.roundedPct, "%"] })] }, i)))) })))] })) : (_jsxs("div", { className: "tui-progress__track", children: [_jsx("div", { className: "tui-progress__bar" }), !indeterminate && showLabels && labelPosition === 'inside' && insideContent && (_jsx("div", { className: "tui-progress__label-wrapper", children: _jsx("div", { className: "tui-progress__label is-inside", children: insideContent }) }))] }));
+    // Content for circle variant (segmented not supported — enforced by TypeScript)
+    const circleContent = (_jsxs("div", { className: "tui-progress__circle", children: [_jsx("div", { className: "tui-progress__circle__bar" }), !indeterminate && showLabels && labelPosition === 'inside' && insideContent && (_jsx("div", { className: "tui-progress__label is-inside", children: insideContent }))] }));
+    const trackContent = mode === 'line' ? lineContent : circleContent;
+    // ==========================================================================
+    // Render based on label position
+    // ==========================================================================
+    // No labels to show
+    if (!showLabels || !hasLabels || isSegmented) {
+        return (_jsxs("div", { ...rootProps, children: [trackContent, !labelledBy && !ariaLabel && defaultLabel && (_jsx("span", { className: "visually-hidden", children: defaultLabel }))] }));
+    }
+    // Inside position: labels are rendered within trackContent above
+    if (labelPosition === 'inside') {
+        return (_jsxs("div", { ...rootProps, children: [trackContent, !labelledBy && !ariaLabel && defaultLabel && (_jsx("span", { className: "visually-hidden", children: defaultLabel }))] }));
+    }
+    // Above/below/inline positions: render labels outside the track
+    const labelRow = (_jsxs("div", { className: "tui-progress__labels", children: [labelStart && _jsx("span", { className: "tui-progress__label is-start", children: labelStart }), labelEnd && _jsx("span", { className: "tui-progress__label is-end", children: labelEnd })] }));
+    return (_jsxs("div", { ...rootProps, children: [labelPosition === 'above' && labelRow, labelPosition === 'inline' ? (_jsxs("div", { className: "tui-progress__inline", children: [labelStart && _jsx("span", { className: "tui-progress__label is-start", children: labelStart }), trackContent, labelEnd && _jsx("span", { className: "tui-progress__label is-end", children: labelEnd })] })) : (trackContent), labelPosition === 'below' && labelRow, !labelledBy && !ariaLabel && defaultLabel && (_jsx("span", { className: "visually-hidden", children: defaultLabel }))] }));
+}

package/components/Progress/index.d.ts

@@ -0,0 +1,4 @@
+export { Progress } from './Progress';
+export { useProgressSegments } from './useProgressSegments';
+export type { ProgressProps, ProgressSegment, SegmentedProgressProps, StandardProgressProps, Mode, Size, LabelPos, } from './types';
+export type { ProcessedSegment } from './useProgressSegments';

package/components/Progress/index.js

@@ -0,0 +1,2 @@
+export { Progress } from './Progress.js';
+export { useProgressSegments } from './useProgressSegments.js';

package/components/Progress/types.d.ts

@@ -0,0 +1,251 @@
+import type React from 'react';
+import type { Size } from '../../types';
+export type { Size };
+export type Mode = 'line' | 'circle';
+export type LabelPos = 'above' | 'inline' | 'below' | 'inside';
+/**
+ * A single segment in segmented progress mode.
+ *
+ * Segments are rendered front-to-back (z1, z2, z3...) with each segment
+ * showing the portion from the previous segment's value to its own value.
+ *
+ * @example
+ * // Student is at 24%, should be at 38%
+ * { value: 24, label: 'Progress' }   // z1: 0-24%
+ * { value: 38, label: 'Expected' }   // z2: 24-38%
+ */
+export type ProgressSegment = {
+    /**
+     * Cumulative value for this segment (0–100, or use with `max` prop).
+     * Each segment's visual width = its value minus the previous segment's value.
+     */
+    value: number;
+    /**
+     * Label text shown before the percentage in the label below the bar.
+     * If omitted, only the percentage is shown.
+     */
+    label?: string;
+};
+/**
+ * Base props shared by all Progress variants.
+ */
+export type BaseProgressProps = {
+    /**
+     * Custom content to render inside the progress indicator.
+     * - Line mode with `inside`: Replaces default content inside the bar
+     * - Circle mode with `inside`: Replaces centered content
+     * - Segmented mode: Replaces the segment labels area below the bar
+     */
+    children?: React.ReactNode;
+    /**
+     * Size of the progress bar, affecting height and font size.
+     * - `'xs'`: 12px font, thinnest bar (for dense step indicators)
+     * - `'sm'`: 14px font, thinner bar
+     * - `'md'`: 16px font, standard bar (default)
+     * - `'lg'`: 20px font, thicker bar
+     * @default 'md'
+     */
+    size?: Size;
+    /**
+     * Maximum value for the progress calculation.
+     * Progress percentage = (value / max) × 100
+     * @default 100
+     */
+    max?: number;
+    /**
+     * Whether to display labels.
+     * When false, hides all label content regardless of other props.
+     * @default true
+     */
+    showLabels?: boolean;
+    /**
+     * ARIA: ID of an element that labels this progress bar.
+     * Takes precedence over `ariaLabel` and `defaultLabel`.
+     */
+    labelledBy?: string;
+    /**
+     * ARIA: Accessible name for the progress bar.
+     * Use when no visible label exists. Takes precedence over `defaultLabel`.
+     */
+    ariaLabel?: string;
+    /**
+     * Fallback accessible name, rendered as visually-hidden text.
+     * Only used if neither `labelledBy` nor `ariaLabel` is provided.
+     */
+    defaultLabel?: string;
+    /**
+     * Additional CSS class names to apply to the root element.
+     */
+    className?: string;
+};
+/**
+ * Props for segmented mode — displays multiple stacked segments (z1, z2, z3...).
+ *
+ * Each segment shows the portion from the previous segment's value to its value.
+ * Useful for showing actual vs expected progress, or multi-phase completion.
+ *
+ * **Restricted in segmented mode:**
+ * - `variant` — only `'line'` is supported (enforced by TypeScript)
+ * - `labelPosition`, `labelStart`, `labelEnd` — use segment-level labels instead
+ * - `indeterminate` — not supported
+ * - `value` — derived from segments array
+ *
+ * @example
+ * ```tsx
+ * <Progress
+ *   segments={[
+ *     { value: 24, label: 'Progress' },
+ *     { value: 38, label: 'Expected' },
+ *   ]}
+ *   ariaLabel="Student progress"
+ * />
+ * ```
+ */
+export type SegmentedProgressProps = BaseProgressProps & {
+    /**
+     * Display mode. Segmented progress only supports line mode.
+     * @default 'line'
+     */
+    mode?: 'line';
+    /**
+     * Segments to display, ordered front-to-back (z1, z2, z3...).
+     * Maximum 5 segments have default colors; beyond that, override via CSS.
+     */
+    segments: ProgressSegment[];
+    /** Not available in segmented mode. */
+    value?: never;
+    /** Not supported in segmented mode. */
+    indeterminate?: never;
+    /** Not available in segmented mode. Labels appear below the bar. */
+    labelPosition?: never;
+    /** Not available in segmented mode. */
+    labelStart?: never;
+    /** Not available in segmented mode. */
+    labelEnd?: never;
+};
+/**
+ * Props for standard single-value progress mode.
+ *
+ * @example
+ * ```tsx
+ * // Basic bar with no label
+ * <Progress value={42} ariaLabel="Upload progress" />
+ *
+ * // With labels above the bar (split left/right)
+ * <Progress
+ *   value={33}
+ *   labelPosition="above"
+ *   labelStart="33% Complete"
+ *   labelEnd="3/9 Steps"
+ * />
+ *
+ * // Indeterminate (loading)
+ * <Progress indeterminate ariaLabel="Loading" />
+ * ```
+ */
+export type StandardProgressProps = BaseProgressProps & {
+    /**
+     * Display mode of the progress indicator.
+     * - `'line'`: Horizontal bar (default)
+     * - `'circle'`: Circular/ring indicator
+     * @default 'line'
+     */
+    mode?: Mode;
+    /**
+     * Visual variant for circle mode.
+     * - `'ring'`: Hollow centre (default) — shows progress as a ring/donut
+     * - `'solid'`: Filled centre — shows as a solid filled circle
+     *
+     * Only applies when `mode="circle"`. Ignored in line mode.
+     * @default 'ring'
+     */
+    variant?: 'ring' | 'solid';
+    /**
+     * Current progress value (0–100, or use with `max` prop).
+     * @default 0
+     */
+    value?: number;
+    /**
+     * When true, shows an animated indeterminate state.
+     * Use for operations where progress percentage is unknown.
+     * Ignores `value` when enabled.
+     * @default false
+     */
+    indeterminate?: boolean;
+    /**
+     * Where to display the labels relative to the progress bar.
+     * - `'above'`: Labels in a row above the bar
+     * - `'inline'`: Labels beside the bar horizontally (default)
+     * - `'below'`: Labels in a row below the bar
+     * - `'inside'`: Label content inside/overlapping the bar (or centered in circle)
+     *
+     * When both `labelStart` and `labelEnd` are provided with `above`, `inline`,
+     * or `below`, they appear on opposite sides (space-between).
+     *
+     * @default 'inline'
+     */
+    labelPosition?: LabelPos;
+    /**
+     * Label content for the start (left) position.
+     * Use with `labelPosition` to control placement.
+     * @example labelStart="33% Complete"
+     */
+    labelStart?: React.ReactNode;
+    /**
+     * Label content for the end (right) position.
+     * Use with `labelPosition` to control placement.
+     * @example labelEnd="3/9 Steps"
+     */
+    labelEnd?: React.ReactNode;
+    /** Not available in standard mode. Use segmented mode instead. */
+    segments?: never;
+};
+/**
+ * Progress bar component with support for single-value and segmented modes.
+ *
+ * ## Modes
+ *
+ * **Standard mode** — Single progress value with optional labels:
+ * ```tsx
+ * <Progress
+ *   value={42}
+ *   labelPosition="above"
+ *   labelStart="42%"
+ *   labelEnd="Progress"
+ * />
+ * ```
+ *
+ * **Segmented mode** — Multiple stacked segments for comparing values:
+ * ```tsx
+ * <Progress
+ *   segments={[
+ *     { value: 24, label: 'Actual' },
+ *     { value: 38, label: 'Expected' },
+ *   ]}
+ * />
+ * ```
+ *
+ * ## Styling
+ *
+ * Customise via CSS custom properties on the component or a parent:
+ *
+ * | Property | Description | Default |
+ * |----------|-------------|---------|
+ * | `--tui-progress-fill` | Bar fill color (standard mode) | Primary theme color |
+ * | `--tui-progress-track` | Track background color | Border color |
+ * | `--tui-progress-radius` | Border radius | Medium radius |
+ * | `--tui-progress-z1-fill` | Segment 1 color | Primary |
+ * | `--tui-progress-z2-fill` | Segment 2 color | Warning (amber) |
+ * | `--tui-progress-z3-fill` | Segment 3 color | Success (green) |
+ * | `--tui-progress-z4-fill` | Segment 4 color | Danger (red) |
+ * | `--tui-progress-z5-fill` | Segment 5 color | Info (blue) |
+ *
+ * ## Accessibility
+ *
+ * - Uses `role="progressbar"` with proper ARIA attributes
+ * - `aria-valuenow`, `aria-valuemin`, `aria-valuemax` for screen readers
+ * - `aria-valuetext` in segmented mode announces all segment values
+ * - `aria-busy` set during indeterminate state
+ * - Respects `prefers-reduced-motion` for animations
+ */
+export type ProgressProps = SegmentedProgressProps | StandardProgressProps;

package/components/Progress/types.js

@@ -0,0 +1 @@
+export {};

package/components/Progress/useProgressSegments.d.ts

@@ -0,0 +1,40 @@
+import type { ProgressSegment } from './types';
+export type { ProgressSegment };
+export type ProcessedSegment = ProgressSegment & {
+    /** Percentage value (0-100) */
+    pct: number;
+    /** Rounded percentage for display */
+    roundedPct: number;
+    /** Visual width as percentage (this segment's portion) */
+    width: number;
+    /** Whether segment has visible width (width > 0) */
+    visible: boolean;
+    /** Z-index identifier (1, 2, 3...) */
+    zIndex: number;
+};
+type UseProgressSegmentsOptions = {
+    segments: ProgressSegment[];
+    max: number;
+};
+type UseProgressSegmentsResult = {
+    /** Processed segments with calculated widths and visibility */
+    processedSegments: ProcessedSegment[];
+    /** Accessible description of all segments for screen readers */
+    ariaValueText: string;
+    /** Primary value (first segment) for aria-valuenow */
+    primaryValue: number;
+    /** Primary percentage (first segment) */
+    primaryPct: number;
+};
+/**
+ * Hook to process progress segments into renderable data.
+ *
+ * Calculates each segment's visual width based on cumulative values:
+ * - Segment 1 (z1): width = segment[0].value
+ * - Segment 2 (z2): width = segment[1].value - segment[0].value
+ * - etc.
+ *
+ * Segments with zero or negative width (when a later segment has lower value)
+ * are marked as not visible.
+ */
+export declare function useProgressSegments({ segments, max, }: UseProgressSegmentsOptions): UseProgressSegmentsResult;

package/components/Progress/useProgressSegments.js

@@ -0,0 +1,42 @@
+import { useMemo } from 'react';
+/**
+ * Hook to process progress segments into renderable data.
+ *
+ * Calculates each segment's visual width based on cumulative values:
+ * - Segment 1 (z1): width = segment[0].value
+ * - Segment 2 (z2): width = segment[1].value - segment[0].value
+ * - etc.
+ *
+ * Segments with zero or negative width (when a later segment has lower value)
+ * are marked as not visible.
+ */
+export function useProgressSegments({ segments, max, }) {
+    return useMemo(() => {
+        const processedSegments = segments.map((seg, i) => {
+            const segPct = Math.max(0, Math.min(100, (seg.value / max) * 100));
+            const prevPct = i === 0
+                ? 0
+                : Math.max(0, Math.min(100, (segments[i - 1].value / max) * 100));
+            const width = Math.max(0, segPct - prevPct);
+            return {
+                ...seg,
+                pct: segPct,
+                roundedPct: Math.round(segPct),
+                width,
+                visible: width > 0,
+                zIndex: i + 1,
+            };
+        });
+        const ariaValueText = processedSegments
+            .map(seg => `${seg.label ?? `Segment ${seg.zIndex}`} ${seg.roundedPct}%`)
+            .join(', ');
+        const primaryValue = segments[0]?.value ?? 0;
+        const primaryPct = processedSegments[0]?.pct ?? 0;
+        return {
+            processedSegments,
+            ariaValueText,
+            primaryValue,
+            primaryPct,
+        };
+    }, [segments, max]);
+}

package/components/Rating/Rating.d.ts

@@ -0,0 +1,32 @@
+import type { SizeStandard, Theme as ThemeFull } from '../../types';
+type Size = SizeStandard;
+type Theme = ThemeFull;
+export type RatingProps = {
+    /** Controlled value (1..max). Use with onChange */
+    value?: number;
+    /** Uncontrolled initial value */
+    defaultValue?: number;
+    /** Maximum icons shown */
+    max?: number;
+    /** Disable interaction (keeps semantics) */
+    disabled?: boolean;
+    /** Presentational readOnly (no form semantics) */
+    readOnly?: boolean;
+    /** Name for the radio group (if you care about form posts) */
+    name?: string;
+    /** Size maps to icon + spacing */
+    size?: Size;
+    /** Theme feeds foreground color tokens */
+    theme?: Theme;
+    /** Called on change (controlled or uncontrolled) */
+    onChange?: (value: number) => void;
+    /** Allow clicking the current selection to clear back to 0 */
+    allowClear?: boolean;
+    className?: string;
+    /** Gap override (e.g. '0.25rem') – otherwise uses density utilities */
+    gap?: string;
+    /** Accessible label for the rating group. Defaults to "Rating: X of Y" */
+    ariaLabel?: string;
+};
+export declare function Rating({ value, defaultValue, max, disabled, readOnly, name, size, theme, onChange, allowClear, className, gap, ariaLabel, }: RatingProps): import("react/jsx-runtime").JSX.Element;
+export {};