@12-apps/ui 6.19.1 → 6.20.0

package/src/components/data-display/Progress/Progress.native.tsx

@@ -0,0 +1,387 @@
+import * as React from 'react';
+import {
+  Animated,
+  Easing,
+  StyleSheet,
+  Text as RNText,
+  View,
+  type StyleProp,
+  type ViewProps,
+  type ViewStyle,
+} from 'react-native';
+import Svg, { Circle } from 'react-native-svg';
+
+import { progressFraction, progressLabelText, resolveProgressProps } from './Progress.helpers';
+import {
+  barStyle,
+  circularGlowStyle,
+  labelStyle,
+  segmentStyle,
+  trackStyle,
+} from './Progress.look.native';
+import {
+  CIRCULAR_INDETERMINATE,
+  CIRCULAR_ROTATION_DEG,
+  CIRCULAR_VIEWBOX,
+  LABEL_MARGIN_TOP_UNITS,
+  LINEAR_INDETERMINATE,
+  PROGRESS_SIZES,
+  PULSE,
+  SEGMENT_GAP_UNITS,
+  circularCircumference,
+  circularDashOffset,
+  progressPalette,
+} from './Progress.metrics';
+import type { ProgressProps, ProgressSize, ProgressVariant } from './Progress.types.native';
+import { useLoopedProgress } from '../../../platform/animation';
+import { useUiTheme } from '../../../provider/use-ui-theme.native';
+import type { ColorValue } from '../../../tokens/vocabulary';
+
+type ValueAria = Pick<ViewProps, 'aria-valuenow' | 'aria-valuemin' | 'aria-valuemax'>;
+
+/** MUI names the value only when it knows it; an indeterminate bar reports none. */
+const valueAria = (value: number | undefined): ValueAria =>
+  value === undefined
+    ? {}
+    : { 'aria-valuenow': Math.round(value), 'aria-valuemin': 0, 'aria-valuemax': 100 };
+
+/** MUI's `pulseAnimation`, as an opacity the caller can merge into a style. */
+function usePulseStyle(enabled: boolean): { opacity: Animated.AnimatedInterpolation<number> } | null {
+  const progress = useLoopedProgress(enabled, {
+    durationMs: PULSE.durationMs,
+    easing: PULSE_EASING,
+  });
+  if (!enabled) return null;
+  return {
+    opacity: progress.interpolate({ inputRange: [0, 0.5, 1], outputRange: [1, PULSE.dip, 1] }),
+  };
+}
+
+const PULSE_EASING = Easing.inOut(Easing.ease);
+
+interface ViewArgs {
+  size: ProgressSize;
+  color: ColorValue;
+  glow: boolean;
+  pulse: boolean;
+  showLabel: boolean;
+  displayValue: number;
+  displayLabel: string;
+  /** Absent means indeterminate — the bar animates rather than reporting progress. */
+  value?: number;
+  /** The component's own id; the parts derive theirs from it. */
+  testID: string;
+  /** The id the addressed element takes — the caller's `data-testid` when they gave one. */
+  elementTestID: string;
+  style?: StyleProp<ViewStyle>;
+  containerRef?: React.Ref<View>;
+  rest: ViewProps;
+}
+
+function ProgressLabel({
+  size,
+  label,
+  testID,
+  muted = false,
+  spaced = false,
+}: {
+  size: ProgressSize;
+  label: string;
+  testID: string;
+  muted?: boolean;
+  spaced?: boolean;
+}): React.JSX.Element {
+  const theme = useUiTheme();
+  return (
+    <RNText
+      testID={testID}
+      style={[
+        labelStyle(theme, size, muted),
+        spaced ? { marginTop: theme.spacing(LABEL_MARGIN_TOP_UNITS) } : null,
+      ]}
+    >
+      {label}
+    </RNText>
+  );
+}
+
+/**
+ * MUI's `bar1Indeterminate`: a third of the track crossing it every 2.1s.
+ * Two bars on the web, one here — `NATIVE-NOTES.md` records the difference.
+ */
+function useSweepStyle(enabled: boolean): Animated.WithAnimatedValue<ViewStyle> | null {
+  const width = `${LINEAR_INDETERMINATE.width * 100}%` as const;
+  const progress = useLoopedProgress(enabled, {
+    durationMs: LINEAR_INDETERMINATE.durationMs,
+    // `left` is a layout property, which the native driver cannot animate.
+    useNativeDriver: false,
+  });
+  if (!enabled) return null;
+  return {
+    position: 'absolute',
+    top: 0,
+    bottom: 0,
+    width,
+    left: progress.interpolate({ inputRange: [0, 1], outputRange: [`-${width}`, '100%'] }),
+  };
+}
+
+function LinearView({
+  variant,
+  size,
+  color,
+  glow,
+  pulse,
+  showLabel,
+  displayValue,
+  displayLabel,
+  value,
+  testID,
+  elementTestID,
+  style,
+  containerRef,
+  rest,
+}: ViewArgs & { variant: ProgressVariant }): React.JSX.Element {
+  const theme = useUiTheme();
+  const pulseStyle = usePulseStyle(pulse);
+  const sweep = useSweepStyle(value === undefined);
+
+  return (
+    <View ref={containerRef} testID={testID} style={[styles.block, style]}>
+      <View
+        testID={elementTestID}
+        role="progressbar"
+        {...valueAria(value)}
+        style={trackStyle(theme, size, color)}
+        {...rest}
+      >
+        <Animated.View
+          style={[
+            barStyle(theme, { variant, size, color, glow }),
+            sweep ?? { width: `${progressFraction(displayValue)}%` },
+            pulseStyle,
+          ]}
+        />
+      </View>
+      {showLabel ? (
+        <ProgressLabel size={size} label={displayLabel} testID={`${testID}-label`} spaced />
+      ) : null}
+    </View>
+  );
+}
+
+/** MUI's `circular-rotate`: one turn every 1.4s behind an arc that never closes. */
+function useSpinStyle(enabled: boolean): Animated.WithAnimatedValue<ViewStyle> {
+  const progress = useLoopedProgress(enabled, {
+    durationMs: CIRCULAR_INDETERMINATE.rotationMs,
+  });
+  if (!enabled) {
+    return { transform: [{ rotate: `${CIRCULAR_ROTATION_DEG}deg` }] };
+  }
+  return {
+    transform: [
+      { rotate: progress.interpolate({ inputRange: [0, 1], outputRange: ['0deg', '360deg'] }) },
+    ],
+  };
+}
+
+function CircularDial({
+  diameter,
+  thickness,
+  stroke,
+  dashOffset,
+}: {
+  diameter: number;
+  thickness: number;
+  stroke: string;
+  dashOffset: number;
+}): React.JSX.Element {
+  const half = CIRCULAR_VIEWBOX / 2;
+  return (
+    <Svg
+      width={diameter}
+      height={diameter}
+      viewBox={`${half} ${half} ${CIRCULAR_VIEWBOX} ${CIRCULAR_VIEWBOX}`}
+    >
+      <Circle
+        cx={CIRCULAR_VIEWBOX}
+        cy={CIRCULAR_VIEWBOX}
+        r={(CIRCULAR_VIEWBOX - thickness) / 2}
+        fill="none"
+        stroke={stroke}
+        strokeWidth={thickness}
+        strokeDasharray={circularCircumference(thickness)}
+        strokeDashoffset={dashOffset}
+      />
+    </Svg>
+  );
+}
+
+function CircularView({
+  size,
+  color,
+  glow,
+  pulse,
+  showLabel,
+  displayValue,
+  displayLabel,
+  value,
+  testID,
+  elementTestID,
+  style,
+  containerRef,
+  rest,
+  thickness,
+  circularSize,
+}: ViewArgs & { thickness: number; circularSize?: number }): React.JSX.Element {
+  const theme = useUiTheme();
+  const indeterminate = value === undefined;
+  const pulseStyle = usePulseStyle(pulse);
+  const spin = useSpinStyle(indeterminate);
+  const diameter = circularSize || PROGRESS_SIZES[size].circularSize;
+  const box = { width: diameter, height: diameter };
+
+  return (
+    <View ref={containerRef} testID={testID} style={[styles.inline, style]}>
+      <Animated.View
+        testID={elementTestID}
+        role="progressbar"
+        {...valueAria(value)}
+        style={[box, glow ? circularGlowStyle(theme, color) : null, pulseStyle]}
+        {...rest}
+      >
+        <Animated.View style={[box, spin]}>
+          <CircularDial
+            diameter={diameter}
+            thickness={thickness}
+            stroke={progressPalette(theme, color).main}
+            dashOffset={
+              indeterminate
+                ? circularCircumference(thickness) * (1 - CIRCULAR_INDETERMINATE.arc)
+                : circularDashOffset(displayValue, thickness)
+            }
+          />
+        </Animated.View>
+      </Animated.View>
+      {showLabel && !indeterminate ? (
+        <View style={[StyleSheet.absoluteFill, styles.centre]}>
+          <ProgressLabel size={size} label={displayLabel} testID={`${testID}-label`} muted />
+        </View>
+      ) : null}
+    </View>
+  );
+}
+
+function SegmentedView({
+  size,
+  color,
+  glow,
+  pulse,
+  showLabel,
+  displayValue,
+  displayLabel,
+  testID,
+  elementTestID,
+  style,
+  containerRef,
+  rest,
+  segments,
+}: ViewArgs & { segments: number }): React.JSX.Element {
+  const theme = useUiTheme();
+  const pulseStyle = usePulseStyle(pulse);
+  const filled = Math.floor((progressFraction(displayValue) / 100) * segments);
+
+  return (
+    <View ref={containerRef} testID={elementTestID} style={[styles.block, style]} {...rest}>
+      <View
+        testID={`${testID}-segments-container`}
+        style={[styles.segments, { gap: theme.spacing(SEGMENT_GAP_UNITS) }]}
+      >
+        {Array.from({ length: segments }, (_, index) => (
+          <Animated.View
+            key={`segment-${index}`}
+            testID={`${testID}-segment-${index}`}
+            style={[
+              segmentStyle(theme, { size, color, filled: index < filled, glow }),
+              index < filled ? pulseStyle : null,
+            ]}
+          />
+        ))}
+      </View>
+      {showLabel ? (
+        <ProgressLabel size={size} label={displayLabel} testID={`${testID}-label`} spaced />
+      ) : null}
+    </View>
+  );
+}
+
+/**
+ * The native `Progress`: the same track, bar, dial and segments the MUI half
+ * draws, on `View`s and a `react-native-svg` arc.
+ */
+export const Progress = React.forwardRef<View, ProgressProps>((rawProps, ref) => {
+  const {
+    variant,
+    size,
+    color,
+    glow,
+    pulse,
+    showLabel,
+    label,
+    segments,
+    thickness,
+    circularSize,
+    value,
+    dataTestId,
+    testID,
+    style,
+    'data-testid': elementId,
+    ...rest
+  } = resolveProgressProps(rawProps);
+  const displayValue = value || 0;
+  // `testID` is React Native's spelling of `dataTestId` and names the component;
+  // `data-testid` names the ELEMENT, which is where the web puts it.
+  const base = testID ?? dataTestId;
+  const shared: ViewArgs = {
+    size,
+    color,
+    glow,
+    pulse,
+    showLabel,
+    displayValue,
+    displayLabel: progressLabelText(label, showLabel, displayValue),
+    value,
+    testID: base,
+    elementTestID: base,
+    style,
+    containerRef: ref,
+    rest,
+  };
+
+  if (variant === 'circular') {
+    return (
+      <CircularView
+        {...shared}
+        elementTestID={elementId ?? `${base}-circular`}
+        thickness={thickness}
+        circularSize={circularSize}
+      />
+    );
+  }
+
+  if (variant === 'segmented') {
+    return <SegmentedView {...shared} elementTestID={elementId ?? base} segments={segments} />;
+  }
+
+  return <LinearView {...shared} elementTestID={elementId ?? `${base}-linear`} variant={variant} />;
+});
+
+Progress.displayName = 'Progress';
+
+const styles = StyleSheet.create({
+  block: { width: '100%' },
+  /** MUI's `display: inline-flex` on the circular wrapper. */
+  inline: { position: 'relative', alignSelf: 'flex-start' },
+  centre: { alignItems: 'center', justifyContent: 'center' },
+  segments: { flexDirection: 'row', width: '100%' },
+});

package/src/components/data-display/Progress/Progress.styles.ts

@@ -1,15 +1,27 @@
 import type { PaletteColor, CSSObject, Theme } from '@mui/material/styles/index.js';
 import { alpha, keyframes } from '@mui/material/styles/index.js';
 
+import {
+  BAR_GLOW,
+  CIRCULAR_GLOW,
+  GLASS_BAR_ALPHA,
+  GLASS_BAR_BORDER_ALPHA,
+  GLASS_BLUR_PX,
+  GLOW_BRIGHTNESS,
+  PROGRESS_SIZES,
+  PULSE,
+} from './Progress.metrics';
 import type { ProgressSize, ProgressVariant } from './Progress.types';
+import { px } from '../../../tokens/theme';
 
-// Define pulse animation
+// Define pulse animation. The stops and the two seconds are the shared metrics'
+// (`PULSE`), so the native `Progress` breathes on the same cadence.
 export const pulseAnimation = keyframes`
   0% {
     opacity: 1;
   }
   50% {
-    opacity: 0.7;
+    opacity: ${PULSE.dip};
   }
   100% {
     opacity: 1;
@@ -41,13 +53,15 @@ export const getColorFromTheme = (theme: Theme, color: string): PaletteColor =>
   return colorMap[color] || theme.palette.primary;
 };
 
-const SIZE_MAP: Record<ProgressSize, { height: number; circularSize: number; fontSize: string }> = {
-  xs: { height: 2, circularSize: 24, fontSize: '0.625rem' },
-  sm: { height: 4, circularSize: 32, fontSize: '0.75rem' },
-  md: { height: 6, circularSize: 40, fontSize: '0.875rem' },
-  lg: { height: 8, circularSize: 48, fontSize: '1rem' },
-  xl: { height: 10, circularSize: 56, fontSize: '1.125rem' },
-};
+// Derived from the shared metrics, not restated: the native `Progress` reads
+// the same table, so the two renderers cannot disagree on a size.
+const SIZE_MAP: Record<ProgressSize, { height: number; circularSize: number; fontSize: string }> =
+  Object.fromEntries(
+    Object.entries(PROGRESS_SIZES).map(([size, step]) => [
+      size,
+      { height: step.height, circularSize: step.circularSize, fontSize: px(step.fontSize) },
+    ]),
+  ) as Record<ProgressSize, { height: number; circularSize: number; fontSize: string }>;
 
 export const getSizeStyles = (size?: ProgressSize) => SIZE_MAP[size as ProgressSize] || SIZE_MAP.md;
 
@@ -64,9 +78,9 @@ export const barVariantStyles = (
       };
     case 'glass':
       return {
-        backgroundColor: alpha(colorPalette.main, 0.8),
-        backdropFilter: 'blur(10px)',
-        border: `1px solid ${alpha(colorPalette.main, 0.3)}`,
+        backgroundColor: alpha(colorPalette.main, GLASS_BAR_ALPHA),
+        backdropFilter: `blur(${GLASS_BLUR_PX}px)`,
+        border: `1px solid ${alpha(colorPalette.main, GLASS_BAR_BORDER_ALPHA)}`,
       };
     default:
       return {};
@@ -81,11 +95,11 @@ export const barEmphasisStyles = (
   pulse?: boolean,
 ): CSSObject => ({
   ...(glow && {
-    boxShadow: `0 0 10px 2px ${alpha(colorPalette.main, 0.4)}`,
-    filter: 'brightness(1.1)',
+    boxShadow: `0 0 ${BAR_GLOW.blur}px ${BAR_GLOW.spread}px ${alpha(colorPalette.main, BAR_GLOW.alpha)}`,
+    filter: `brightness(${GLOW_BRIGHTNESS})`,
   }),
   ...(pulse && {
-    animation: `${pulseAnimation} 2s infinite`,
+    animation: `${pulseAnimation} ${PULSE.durationMs / 1000}s infinite`,
   }),
 });
 
@@ -95,9 +109,9 @@ export const circularEmphasisStyles = (
   pulse?: boolean,
 ): CSSObject => ({
   ...(glow && {
-    filter: `drop-shadow(0 0 8px ${alpha(colorPalette.main, 0.6)})`,
+    filter: `drop-shadow(0 0 ${CIRCULAR_GLOW.blur}px ${alpha(colorPalette.main, CIRCULAR_GLOW.alpha)})`,
   }),
   ...(pulse && {
-    animation: `${pulseAnimation} 2s infinite`,
+    animation: `${pulseAnimation} ${PULSE.durationMs / 1000}s infinite`,
   }),
 });

package/src/components/data-display/Progress/Progress.tsx

@@ -5,7 +5,7 @@ import Typography from '@mui/material/Typography/index.js';
 import { alpha, styled, useTheme } from '@mui/material/styles/index.js';
 import React from 'react';
 
-import { resolveProgressProps } from './Progress.helpers';
+import { progressLabelText, resolveProgressProps } from './Progress.helpers';
 import {
   barEmphasisStyles,
   barVariantStyles,
@@ -265,9 +265,7 @@ export const Progress = React.forwardRef<HTMLDivElement, ProgressProps>(
       circularSize,
       value,
       dataTestId,
-      // LinearProgressProps carries a `ref` typed for its own element; the
-      // forwarded one below is the ref that matters.
-      ref: _ref,
+      testID,
       ...props
     } = resolveProgressProps(rawProps);
     const displayValue = value || 0;
@@ -278,9 +276,12 @@ export const Progress = React.forwardRef<HTMLDivElement, ProgressProps>(
       pulse,
       showLabel,
       displayValue,
-      displayLabel: label || (showLabel ? `${Math.round(displayValue)}%` : ''),
+      displayLabel: progressLabelText(label, showLabel, displayValue),
       value,
-      dataTestId,
+      // `testID` is React Native's spelling of the same id and names the
+      // component too; `data-testid` is left in `props`, on its way to the
+      // element the caller means to address, where it has always landed.
+      dataTestId: testID ?? dataTestId,
       ...props,
     };
 

package/src/components/data-display/Progress/Progress.types.native.ts

@@ -0,0 +1,11 @@
+import type { StyleProp, ViewProps, ViewStyle } from 'react-native';
+
+import type { ProgressBaseProps } from './Progress.base';
+
+export type { ProgressBaseProps, ProgressSize, ProgressVariant } from './Progress.base';
+
+/** The native `Progress`: the shared contract, plus a `View`'s own props. */
+export type ProgressProps = ProgressBaseProps &
+  Omit<ViewProps, keyof ProgressBaseProps | 'style'> & {
+    style?: StyleProp<ViewStyle>;
+  };

package/src/components/data-display/Progress/Progress.types.ts

@@ -1,62 +1,10 @@
-import type { ColorValue, SizeValue } from '../../../tokens/scales';
 import type { LinearProgressProps } from '@mui/material/LinearProgress/index.js';
 
-export type ProgressVariant = 'linear' | 'circular' | 'segmented' | 'gradient' | 'glass';
-export type ProgressSize = SizeValue;
+import type { ProgressBaseProps } from './Progress.base';
 
-export interface ProgressProps extends Omit<LinearProgressProps, 'variant' | 'color'> {
-  /**
-   * The variant of the progress
-   */
-  variant?: ProgressVariant;
+export type { ProgressBaseProps, ProgressSize, ProgressVariant } from './Progress.base';
 
-  /**
-   * The size of the progress
-   */
-  size?: ProgressSize;
-
-  /**
-   * The color of the progress
-   */
-  color?: ColorValue;
-
-  /**
-   * Whether the progress should have a glow effect
-   */
-  glow?: boolean;
-
-  /**
-   * Whether the progress should have a pulse animation
-   */
-  pulse?: boolean;
-
-  /**
-   * Show percentage text
-   */
-  showLabel?: boolean;
-
-  /**
-   * Custom label text
-   */
-  label?: string;
-
-  /**
-   * Number of segments for segmented variant
-   */
-  segments?: number;
-
-  /**
-   * Thickness for circular variant
-   */
-  thickness?: number;
-
-  /**
-   * Size for circular variant
-   */
-  circularSize?: number;
-
-  /**
-   * Test ID for testing purposes
-   */
-  dataTestId?: string;
-}
+/** The web `Progress`: the shared contract, plus MUI's `LinearProgress` extras. */
+export interface ProgressProps
+  extends ProgressBaseProps,
+    Omit<LinearProgressProps, 'variant' | 'color' | 'value'> {}

package/src/components/data-display/Progress/index.native.ts

@@ -0,0 +1,7 @@
+export { Progress } from './Progress.native';
+export type {
+  ProgressBaseProps,
+  ProgressProps,
+  ProgressSize,
+  ProgressVariant,
+} from './Progress.types.native';

package/src/components/data-display/Progress/index.ts

@@ -1,2 +1,7 @@
 export { Progress } from './Progress';
-export type { ProgressProps, ProgressSize,ProgressVariant } from './Progress.types';
+export type {
+  ProgressBaseProps,
+  ProgressProps,
+  ProgressSize,
+  ProgressVariant,
+} from './Progress.types';

package/src/components/layout/Skeleton/NATIVE-NOTES.md

@@ -0,0 +1,8 @@
+# Skeleton on React Native
+
+Known rendering gaps, one bullet each; `pnpm native:ledger` reads them.
+
+- MUI's `wave` sweep and the `shimmer` overlay are gradient pseudo-elements travelling across the box; React Native core has neither, so both are drawn as the same wash (`action.hover` for the wave, `alpha(#fff, 0.3)` for the shimmer) fading in and out over the whole box on the web's own cadence — 1.6s linear after 0.5s for the wave, 2s for the shimmer.
+- `glassmorphism` paints the 135° gradient's first stop (`alpha(paper, 0.8)`) flat and keeps the hairline and the `0 8px 32px 0 rgba(0, 0, 0, 0.1)` shadow, but not the 20px backdrop blur — React Native has no backdrop filter.
+- The `text` variant is drawn at its FINAL height. MUI gives it a `1.2em` line box and squashes the box to 60% with `transform: scale(1, 0.6)`; React Native transforms do not change layout, so the two are multiplied out (11.52px at the theme's 16px body size) and the elliptical `4px/6.7px` radius the squash rounds off is drawn as the plain 4px it lands on.
+- `width`, `height` and `borderRadius` accept a number or a percentage; any other CSS length (`10rem`, `calc(…)`) has no React Native equivalent and leaves the box to size itself from its content.

package/src/components/layout/Skeleton/Skeleton.base.ts

@@ -0,0 +1,37 @@
+/**
+ * THE CONTRACT BOTH RENDERERS HONOUR — and nothing else.
+ *
+ * This file imports no MUI and no react-native, on purpose: it is in BOTH
+ * declaration outputs (`dist/types` and `dist/types-native`), and a native
+ * consumer has no `@mui/material` to resolve a type import against.
+ */
+export type SkeletonVariant = 'text' | 'circular' | 'rectangular' | 'wave';
+export type SkeletonAnimation = 'pulse' | 'wave' | false;
+export type SkeletonIntensity = 'low' | 'medium' | 'high';
+
+/**
+ * The contract both renderers honour. `className` and a CSS `style` are the
+ * web's own and stay in `Skeleton.types.ts`; `style` on native is a
+ * `ViewStyle` and is declared in `Skeleton.types.native.ts`.
+ */
+export interface SkeletonBaseProps {
+  variant?: SkeletonVariant;
+  animation?: SkeletonAnimation;
+  width?: number | string;
+  height?: number | string;
+  count?: number;
+  /** Between instances, in SPACING UNITS — `theme.spacing(n)` on both sides. */
+  spacing?: number;
+  borderRadius?: number | string;
+  intensity?: SkeletonIntensity;
+  glassmorphism?: boolean;
+  shimmer?: boolean;
+  /**
+   * All three spellings of the same id: the web forwards `data-testid`, React
+   * Native calls it `testID`, and `dataTestId` is the house name. See
+   * `src/platform/test-id.ts`.
+   */
+  testID?: string;
+  dataTestId?: string;
+  'data-testid'?: string;
+}