@mihcm/ui 0.14.1

package/src/Progress.native.tsx

@@ -0,0 +1,197 @@
+/**
+ * Progress (React Native variant).
+ *
+ * Renders a progress bar using RN `View` + `Animated` for the
+ * indeterminate shimmer. No Reanimated dependency.
+ *
+ * Wiki: docs/components/Progress.md
+ */
+import { forwardRef, useEffect, useRef } from 'react';
+import { Animated, Text, View, type ViewProps } from 'react-native';
+import { cn } from './internal/cn.js';
+
+const SIZE_CLASSES = {
+  sm: 'h-1.5',
+  md: 'h-2.5',
+  lg: 'h-4',
+} as const;
+
+const TONE_CLASSES = {
+  primary: 'bg-primary',
+  accent: 'bg-accent',
+  success: 'bg-success',
+  warning: 'bg-warning',
+  danger: 'bg-destructive',
+} as const;
+
+const DEFAULT_SEGMENTS: ProgressSegment[] = [
+  { from: 0, to: 25, tone: 'danger' },
+  { from: 25, to: 50, tone: 'warning' },
+  { from: 50, to: 75, tone: 'primary' },
+  { from: 75, to: 100, tone: 'success' },
+];
+
+export interface ProgressSegment {
+  from: number;
+  to: number;
+  tone: keyof typeof TONE_CLASSES;
+}
+
+export type ProgressValueLabelPosition =
+  | 'inline-end'
+  | 'top-left'
+  | 'top-center'
+  | 'top-right'
+  | 'bottom-left'
+  | 'bottom-center'
+  | 'bottom-right';
+
+export interface ProgressProps extends Omit<ViewProps, 'style'> {
+  /** Current value (0–100). Omit for indeterminate mode. */
+  value?: number;
+  /** Maximum value. Defaults to 100. */
+  max?: number;
+  /** Tone of the indicator bar. */
+  tone?: 'primary' | 'accent' | 'success' | 'warning' | 'danger';
+  /** Use value-based semantic color thresholds instead of one fixed tone. */
+  segmented?: boolean;
+  /** Custom percentage thresholds for `segmented` mode. */
+  segments?: ProgressSegment[];
+  /** Size of the bar track. */
+  size?: 'sm' | 'md' | 'lg';
+  /** Accessible label. */
+  label?: string;
+  /** Show percentage text next to, above, or below the bar. */
+  showValue?: boolean;
+  /** Position for the visible value label. */
+  valueLabelPosition?: ProgressValueLabelPosition;
+  /** Override the visible value label. */
+  valueLabel?: string;
+  /** Format the visible value label from the current value. */
+  valueFormatter?: (value: number, percentage: number, max: number) => string;
+  className?: string;
+}
+
+const VALUE_LABEL_ALIGNMENT: Record<Exclude<ProgressValueLabelPosition, 'inline-end'>, string> = {
+  'top-left': 'items-start',
+  'top-center': 'items-center',
+  'top-right': 'items-end',
+  'bottom-left': 'items-start',
+  'bottom-center': 'items-center',
+  'bottom-right': 'items-end',
+};
+
+export const Progress = forwardRef<View, ProgressProps>(function Progress(
+  {
+    className,
+    value,
+    max = 100,
+    tone = 'primary',
+    segmented = false,
+    segments = DEFAULT_SEGMENTS,
+    size = 'md',
+    label,
+    showValue = false,
+    valueLabelPosition = 'inline-end',
+    valueLabel,
+    valueFormatter,
+    ...props
+  },
+  ref,
+) {
+  const isIndeterminate = value === undefined;
+  const safeMax = max > 0 ? max : 100;
+  const clampedValue = isIndeterminate ? 0 : Math.min(safeMax, Math.max(0, value));
+  const percentage = isIndeterminate ? 0 : Math.min(100, Math.max(0, (clampedValue / safeMax) * 100));
+  const resolvedTone = segmented
+    ? segments.find((segment) => percentage >= segment.from && percentage < segment.to)?.tone ??
+      segments.at(-1)?.tone ??
+      tone
+    : tone;
+  const translateX = useRef(new Animated.Value(-1)).current;
+  const formattedValue = valueLabel ?? valueFormatter?.(clampedValue, percentage, safeMax) ?? `${Math.round(percentage)}%`;
+  const showInlineValue = showValue && !isIndeterminate && valueLabelPosition === 'inline-end';
+  const showStackedValue = showValue && !isIndeterminate && valueLabelPosition !== 'inline-end';
+  const stackedValueBefore = showStackedValue && valueLabelPosition.startsWith('top');
+  const stackedValueAfter = showStackedValue && valueLabelPosition.startsWith('bottom');
+  const valueNode = (
+    <Text className="text-xs font-medium text-muted-foreground tabular-nums">
+      {formattedValue}
+    </Text>
+  );
+
+  useEffect(() => {
+    if (!isIndeterminate) return;
+    const loop = Animated.loop(
+      Animated.sequence([
+        Animated.timing(translateX, {
+          toValue: 4,
+          duration: 1500,
+          useNativeDriver: true,
+        }),
+        Animated.timing(translateX, {
+          toValue: -1,
+          duration: 0,
+          useNativeDriver: true,
+        }),
+      ]),
+    );
+    loop.start();
+    return () => loop.stop();
+  }, [isIndeterminate, translateX]);
+
+  const barNode = (
+    <View
+      ref={ref}
+      accessibilityRole="progressbar"
+      accessibilityValue={{
+        min: 0,
+        max: safeMax,
+        now: isIndeterminate ? undefined : clampedValue,
+      }}
+      accessibilityLabel={label}
+      className={cn(
+        'relative w-full overflow-hidden rounded-full bg-muted',
+        SIZE_CLASSES[size],
+        className,
+      )}
+      {...props}
+    >
+      {isIndeterminate ? (
+        <Animated.View
+          className={cn('h-full rounded-full', TONE_CLASSES[resolvedTone])}
+          style={{
+            width: '33%',
+            transform: [
+              {
+                translateX: translateX.interpolate({
+                  inputRange: [-1, 4],
+                  outputRange: ['-100%' as unknown as number, '400%' as unknown as number],
+                }),
+              },
+            ],
+          }}
+        />
+      ) : (
+        <View
+          className={cn('h-full rounded-full', TONE_CLASSES[resolvedTone])}
+          style={{ width: `${percentage}%` }}
+        />
+      )}
+    </View>
+  );
+
+  return (
+    <View
+      className={cn(
+        showInlineValue ? 'flex-row items-center gap-2' : 'w-full flex-col gap-2',
+        showStackedValue && VALUE_LABEL_ALIGNMENT[valueLabelPosition],
+      )}
+    >
+      {stackedValueBefore && valueNode}
+      {barNode}
+      {stackedValueAfter && valueNode}
+      {showInlineValue && valueNode}
+    </View>
+  );
+});

package/src/Progress.tsx

@@ -0,0 +1,286 @@
+'use client';
+
+/**
+ * Progress (web variant — React DOM).
+ *
+ * A simple progress bar that indicates completion status. Pass a
+ * `value` (0–100) for determinate mode or omit it for an
+ * indeterminate shimmer animation.
+ *
+ *   <Progress value={60} tone="success" />
+ *   <Progress label="Loading…" />            // indeterminate
+ *
+ * Sets `role="progressbar"` with appropriate ARIA attributes.
+ *
+ * Wiki: docs/components/Progress.md
+ */
+import { forwardRef, type HTMLAttributes } from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { cn } from './internal/cn.js';
+
+export const progressVariants = cva(
+  'relative w-full overflow-hidden rounded-full bg-muted',
+  {
+    variants: {
+      size: {
+        sm: 'h-1.5',
+        md: 'h-2.5',
+        lg: 'h-4',
+      },
+    },
+    defaultVariants: {
+      size: 'md',
+    },
+  },
+);
+
+type ProgressVariantProps = VariantProps<typeof progressVariants>;
+
+const TONE_COLORS = {
+  primary: 'bg-primary',
+  accent: 'bg-accent',
+  success: 'bg-success',
+  warning: 'bg-warning',
+  danger: 'bg-destructive',
+} as const;
+
+const DEFAULT_SEGMENTS: ProgressSegment[] = [
+  { from: 0, to: 25, tone: 'danger' },
+  { from: 25, to: 50, tone: 'warning' },
+  { from: 50, to: 75, tone: 'primary' },
+  { from: 75, to: 100, tone: 'success' },
+];
+
+export type ProgressValueLabelPosition =
+  | 'inline-end'
+  | 'top-left'
+  | 'top-center'
+  | 'top-right'
+  | 'bottom-left'
+  | 'bottom-center'
+  | 'bottom-right';
+export type ProgressTrackLabelPosition = 'none' | 'top' | 'bottom' | 'inline';
+export type ProgressLabelGap = 'none' | 'xs' | 'sm' | 'md';
+
+export interface ProgressSegment {
+  /** Inclusive lower percentage bound. */
+  from: number;
+  /** Exclusive upper percentage bound, except the last segment may include 100. */
+  to: number;
+  /** Semantic tone used while the value is inside this segment. */
+  tone: keyof typeof TONE_COLORS;
+}
+
+export interface ProgressProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, 'role'>,
+    ProgressVariantProps {
+  /** Current value (0–100). Omit for indeterminate mode. */
+  value?: number;
+  /** Maximum value. Defaults to 100. */
+  max?: number;
+  /** Tone of the indicator bar. */
+  tone?: keyof typeof TONE_COLORS;
+  /** Use value-based semantic color thresholds instead of one fixed tone. */
+  segmented?: boolean;
+  /** Custom percentage thresholds for `segmented` mode. */
+  segments?: ProgressSegment[];
+  /** Accessible label (maps to aria-label). */
+  label?: string;
+  /** Show percentage text next to the bar. */
+  showValue?: boolean;
+  /** Position for the visible value label. */
+  valueLabelPosition?: ProgressValueLabelPosition;
+  /** Override the visible value label. */
+  valueLabel?: string;
+  /** Format the visible value label from the current value. */
+  valueFormatter?: (value: number, percentage: number, max: number) => string;
+  /** Show min/max scale labels around the progress bar. */
+  showTrackLabels?: boolean;
+  /** Position for min/max scale labels. */
+  trackLabelPosition?: ProgressTrackLabelPosition;
+  /** Override the visible minimum scale label. */
+  minLabel?: string;
+  /** Override the visible maximum scale label. */
+  maxLabel?: string;
+  /** Format min/max scale labels from the current numeric bounds. */
+  trackLabelFormatter?: (value: number, position: 'min' | 'max') => string;
+  /** Vertical gap between the bar and top/bottom label rows. */
+  labelGap?: ProgressLabelGap;
+  /** Gap between a left/right value label and the adjacent min/max scale label. */
+  labelGroupGap?: ProgressLabelGap;
+  /** Additional className for value and min/max labels. */
+  labelClassName?: string;
+}
+
+const LABEL_ROW_GAP: Record<ProgressLabelGap, string> = {
+  none: 'gap-0',
+  xs: 'gap-1',
+  sm: 'gap-2',
+  md: 'gap-3',
+};
+
+const LABEL_GROUP_GAP: Record<ProgressLabelGap, string> = {
+  none: 'gap-0',
+  xs: 'gap-1',
+  sm: 'gap-1.5',
+  md: 'gap-2',
+};
+
+function resolveProgressTone(
+  percentage: number,
+  tone: keyof typeof TONE_COLORS,
+  segmented: boolean,
+  segments: ProgressSegment[],
+) {
+  if (!segmented) return tone;
+  return segments.find((segment) => percentage >= segment.from && percentage < segment.to)?.tone ??
+    segments.at(-1)?.tone ??
+    tone;
+}
+
+export const Progress = forwardRef<HTMLDivElement, ProgressProps>(function Progress(
+  {
+    className,
+    value,
+    max = 100,
+    tone = 'primary',
+    segmented = false,
+    segments = DEFAULT_SEGMENTS,
+    size,
+    label,
+    showValue,
+    valueLabelPosition = 'inline-end',
+    valueLabel,
+    valueFormatter,
+    showTrackLabels = false,
+    trackLabelPosition = 'none',
+    minLabel,
+    maxLabel,
+    trackLabelFormatter,
+    labelGap = 'xs',
+    labelGroupGap = 'xs',
+    labelClassName,
+    ...props
+  },
+  ref,
+) {
+  const isIndeterminate = value === undefined;
+  const safeMax = max > 0 ? max : 100;
+  const clampedValue = isIndeterminate ? 0 : Math.min(safeMax, Math.max(0, value));
+  const percentage = isIndeterminate ? 0 : Math.min(100, Math.max(0, (clampedValue / safeMax) * 100));
+  const resolvedTone = resolveProgressTone(percentage, tone, segmented, segments);
+  const formattedValue = valueLabel ?? valueFormatter?.(clampedValue, percentage, safeMax) ?? `${Math.round(percentage)}%`;
+  const formattedMin = minLabel ?? trackLabelFormatter?.(0, 'min') ?? '0';
+  const formattedMax = maxLabel ?? trackLabelFormatter?.(safeMax, 'max') ?? `${safeMax}`;
+  const showInlineValue = showValue && !isIndeterminate && valueLabelPosition === 'inline-end';
+  const showStackedValue = showValue && !isIndeterminate && valueLabelPosition !== 'inline-end';
+  const renderScaleLabels = showTrackLabels && trackLabelPosition !== 'none';
+  const valueSide = valueLabelPosition.startsWith('top') ? 'top' : 'bottom';
+  const valueAlign = valueLabelPosition.endsWith('left')
+    ? 'left'
+    : valueLabelPosition.endsWith('right')
+      ? 'right'
+      : 'center';
+  const valueNode = (
+    <span className={cn('text-xs font-medium text-muted-foreground tabular-nums transition-colors duration-300', labelClassName)}>
+      {formattedValue}
+    </span>
+  );
+  const minNode = (
+    <span className={cn('text-xs font-medium text-muted-foreground tabular-nums', labelClassName)}>
+      {formattedMin}
+    </span>
+  );
+  const maxNode = (
+    <span className={cn('text-xs font-medium text-muted-foreground tabular-nums', labelClassName)}>
+      {formattedMax}
+    </span>
+  );
+  const barNode = (
+    <div
+      ref={ref}
+      role="progressbar"
+      aria-valuenow={isIndeterminate ? undefined : clampedValue}
+      aria-valuemin={0}
+      aria-valuemax={safeMax}
+      aria-label={label ?? 'Progress'}
+      className={cn(progressVariants({ size }), className)}
+      {...props}
+    >
+      <div
+        className={cn(
+          'h-full rounded-full transition-[width,background-color] duration-300 ease-out',
+          TONE_COLORS[resolvedTone],
+          isIndeterminate && 'w-1/3 animate-[progress-indeterminate_1.5s_ease-in-out_infinite]',
+        )}
+        style={
+          isIndeterminate
+            ? undefined
+            : { width: `${percentage}%` }
+        }
+      />
+    </div>
+  );
+
+  function renderLabelRow(side: 'top' | 'bottom') {
+    const hasScaleLabels = renderScaleLabels && trackLabelPosition === side;
+    const hasValue = showStackedValue && valueSide === side;
+
+    if (!hasScaleLabels && !hasValue) return null;
+
+    return (
+      <div className="grid w-full grid-cols-[1fr_auto_1fr] items-center">
+        <div className={cn('flex min-w-0 items-center justify-start', LABEL_GROUP_GAP[labelGroupGap])}>
+          {hasScaleLabels ? minNode : null}
+          {hasValue && valueAlign === 'left' ? valueNode : null}
+        </div>
+        <div className="flex min-w-0 justify-center">
+          {hasValue && valueAlign === 'center' ? valueNode : null}
+        </div>
+        <div className={cn('flex min-w-0 items-center justify-end', LABEL_GROUP_GAP[labelGroupGap])}>
+          {hasValue && valueAlign === 'right' ? valueNode : null}
+          {hasScaleLabels ? maxNode : null}
+        </div>
+      </div>
+    );
+  }
+
+  if (trackLabelPosition === 'inline' && renderScaleLabels) {
+    return (
+      <>
+        <div className={cn('flex w-full items-center', LABEL_GROUP_GAP[labelGroupGap])}>
+          {minNode}
+          {barNode}
+          {maxNode}
+          {showInlineValue && valueNode}
+        </div>
+        <style>{`
+          @keyframes progress-indeterminate {
+            0% { transform: translateX(-100%); }
+            100% { transform: translateX(400%); }
+          }
+        `}</style>
+      </>
+    );
+  }
+
+  return (
+    <>
+      <div className={cn(
+        showInlineValue ? 'flex items-center gap-2' : 'flex w-full flex-col',
+        !showInlineValue && LABEL_ROW_GAP[labelGap],
+      )}>
+        {renderLabelRow('top')}
+        {barNode}
+        {renderLabelRow('bottom')}
+        {showInlineValue && valueNode}
+      </div>
+      <style>{`
+        @keyframes progress-indeterminate {
+          0% { transform: translateX(-100%); }
+          100% { transform: translateX(400%); }
+        }
+      `}</style>
+    </>
+  );
+});

package/src/ProgressCircle.tsx

@@ -0,0 +1,200 @@
+'use client';
+
+/**
+ * ProgressCircle (web variant).
+ *
+ * Circular progress indicator for compact KPI cards and status summaries.
+ *
+ * Wiki: docs/components/ProgressCircle.md
+ */
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+import { cn } from './internal/cn.js';
+
+const SIZE = {
+  sm: 64,
+  md: 88,
+  lg: 120,
+  xl: 160,
+} as const;
+
+const STROKE = {
+  sm: 6,
+  md: 8,
+  lg: 10,
+  xl: 12,
+} as const;
+
+const TONE_CLASS = {
+  primary: 'stroke-primary',
+  accent: 'stroke-accent',
+  success: 'stroke-success',
+  warning: 'stroke-warning',
+  danger: 'stroke-destructive',
+} as const;
+
+const VALUE_TONE_CLASS = {
+  foreground: 'text-foreground',
+  primary: 'text-primary',
+  accent: 'text-accent',
+  success: 'text-success',
+  warning: 'text-warning',
+  danger: 'text-destructive',
+} as const;
+
+const VALUE_SIZE_CLASS = {
+  xs: 'text-xs',
+  sm: 'text-sm',
+  md: 'text-base',
+  lg: 'text-lg',
+  xl: 'text-xl',
+} as const;
+
+const DEFAULT_SEGMENTS: ProgressCircleSegment[] = [
+  { from: 0, to: 25, tone: 'danger' },
+  { from: 25, to: 50, tone: 'warning' },
+  { from: 50, to: 75, tone: 'primary' },
+  { from: 75, to: 100, tone: 'success' },
+];
+
+export type ProgressCircleTone = keyof typeof TONE_CLASS;
+export type ProgressCircleValueTone = keyof typeof VALUE_TONE_CLASS | 'auto';
+export type ProgressCircleValueSize = keyof typeof VALUE_SIZE_CLASS;
+
+export interface ProgressCircleSegment {
+  /** Inclusive lower percentage bound. */
+  from: number;
+  /** Exclusive upper percentage bound, except the last segment may include 100. */
+  to: number;
+  /** Semantic tone used while the value is inside this segment. */
+  tone: ProgressCircleTone;
+}
+
+export interface ProgressCircleProps extends HTMLAttributes<HTMLDivElement> {
+  value: number;
+  max?: number;
+  size?: keyof typeof SIZE;
+  tone?: ProgressCircleTone;
+  /** Use value-based semantic color thresholds instead of one fixed tone. */
+  segmented?: boolean;
+  /** Custom percentage thresholds for `segmented` mode. */
+  segments?: ProgressCircleSegment[];
+  showValue?: boolean;
+  /** Center value font-size preset. */
+  valueSize?: ProgressCircleValueSize;
+  /** Center value tone. Defaults to percentage tone when `segmented` is true. */
+  valueTone?: ProgressCircleValueTone;
+  valueFormatter?: (value: number, percentage: number) => ReactNode;
+  /** Additional Tailwind classes on the center value label. */
+  valueClassName?: string;
+  label?: string;
+}
+
+function resolveProgressCircleTone(
+  percentage: number,
+  tone: ProgressCircleTone,
+  segmented: boolean,
+  segments: ProgressCircleSegment[],
+) {
+  if (!segmented) return tone;
+  return (
+    segments.find((segment) => percentage >= segment.from && percentage < segment.to)?.tone ??
+    segments.at(-1)?.tone ??
+    tone
+  );
+}
+
+export const ProgressCircle = forwardRef<HTMLDivElement, ProgressCircleProps>(
+  function ProgressCircle(
+    {
+      value,
+      max = 100,
+      size = 'md',
+      tone = 'primary',
+      segmented = false,
+      segments = DEFAULT_SEGMENTS,
+      showValue = true,
+      valueSize = 'sm',
+      valueTone,
+      valueFormatter,
+      valueClassName,
+      label = 'Progress',
+      className,
+      ...props
+    },
+    ref,
+  ) {
+    const dimension = SIZE[size];
+    const strokeWidth = STROKE[size];
+    const radius = (dimension - strokeWidth) / 2;
+    const circumference = 2 * Math.PI * radius;
+    const safeMax = max > 0 ? max : 100;
+    const clamped = Math.min(safeMax, Math.max(0, value));
+    const percentage = (clamped / safeMax) * 100;
+    const dashOffset = circumference - (percentage / 100) * circumference;
+    const resolvedTone = resolveProgressCircleTone(percentage, tone, segmented, segments);
+    const resolvedValueTone =
+      valueTone === undefined
+        ? segmented
+          ? resolvedTone
+          : 'foreground'
+        : valueTone === 'auto'
+          ? resolvedTone
+          : valueTone;
+
+    return (
+      <div
+        ref={ref}
+        className={cn('relative inline-grid place-items-center text-foreground', className)}
+        role="progressbar"
+        aria-label={label}
+        aria-valuemin={0}
+        aria-valuemax={safeMax}
+        aria-valuenow={clamped}
+        {...props}
+      >
+        <svg
+          width={dimension}
+          height={dimension}
+          viewBox={`0 0 ${dimension} ${dimension}`}
+          aria-hidden
+        >
+          <circle
+            cx={dimension / 2}
+            cy={dimension / 2}
+            r={radius}
+            fill="none"
+            className="stroke-muted"
+            strokeWidth={strokeWidth}
+          />
+          <circle
+            cx={dimension / 2}
+            cy={dimension / 2}
+            r={radius}
+            fill="none"
+            className={cn(
+              'transition-[stroke-dashoffset,stroke] duration-500 ease-out',
+              TONE_CLASS[resolvedTone],
+            )}
+            strokeWidth={strokeWidth}
+            strokeLinecap="round"
+            strokeDasharray={circumference}
+            strokeDashoffset={dashOffset}
+            transform={`rotate(-90 ${dimension / 2} ${dimension / 2})`}
+          />
+        </svg>
+        {showValue ? (
+          <span
+            className={cn(
+              'absolute font-semibold tabular-nums transition-colors duration-500 ease-out',
+              VALUE_SIZE_CLASS[valueSize],
+              VALUE_TONE_CLASS[resolvedValueTone],
+              valueClassName,
+            )}
+          >
+            {valueFormatter?.(clamped, percentage) ?? `${Math.round(percentage)}%`}
+          </span>
+        ) : null}
+      </div>
+    );
+  },
+);