@12-apps/ui 6.19.0 → 6.20.0

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

@@ -0,0 +1,8 @@
+export { Chip } from './Chip.native';
+export type {
+  ChipBaseProps,
+  ChipColor,
+  ChipProps,
+  ChipSize,
+  ChipVariant,
+} from './Chip.types.native';

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

@@ -1,2 +1,2 @@
 export { Chip } from './Chip';
-export type { ChipColor, ChipProps, ChipSize, ChipVariant } from './Chip.types';
+export type { ChipBaseProps, ChipColor, ChipProps, ChipSize, ChipVariant } from './Chip.types';

package/src/components/data-display/Progress/NATIVE-NOTES.md

@@ -0,0 +1,10 @@
+# Progress on React Native
+
+Known rendering gaps, one bullet each; `pnpm native:ledger` reads them.
+
+- `gradient` paints its first stop (`main`) flat: React Native core has no gradient fill, so the 90° run to `dark` is lost. `glass` keeps the 80% wash and the 30% hairline but not the 10px backdrop blur, which React Native has no equivalent of.
+- `glow` draws the web's `0 0 10px 2px alpha(main, 0.4)` shadow (and `0 0 6px 1px` on a filled segment) but not the `filter: brightness(1.1)` that goes with it, nor the circular variant's `drop-shadow` — the dial takes a box shadow round its square instead.
+- The indeterminate linear bar is ONE band a third of the track wide crossing every 2.1s; MUI runs two bars on two keyframe tracks. The indeterminate dial spins a quarter-circle arc once every 1.4s rather than growing and shrinking it.
+- The determinate bar is a clamped WIDTH; MUI translates a full-width bar by `value - 100`%. The two agree between 0 and 100 — outside it the web slides the bar off the track and native stops at the ends.
+- MUI's `transition: all 0.3s ease` on the bar and on every segment has no equivalent: a value change is drawn immediately.
+- The label is set in MUI's default `caption` ratios at the size's own step; a host that re-themes MUI's typography variants moves the web only.

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

@@ -0,0 +1,86 @@
+import type { ColorValue, SizeValue } from '../../../tokens/vocabulary';
+
+/**
+ * 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 ProgressVariant = 'linear' | 'circular' | 'segmented' | 'gradient' | 'glass';
+export type ProgressSize = SizeValue;
+
+export interface ProgressBaseProps {
+  /**
+   * The variant of the progress
+   */
+  variant?: ProgressVariant;
+
+  /**
+   * 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;
+
+  /**
+   * How far along, 0 to 100. Absent means INDETERMINATE — the bar animates
+   * rather than reporting progress.
+   */
+  value?: number;
+
+  /**
+   * Test ID for testing purposes. Names the component: the wrapper takes it,
+   * and the bar, the segments and the label derive theirs from it.
+   */
+  dataTestId?: string;
+
+  /** React Native's spelling of {@link ProgressBaseProps.dataTestId}. */
+  testID?: string;
+
+  /**
+   * NOT the component's id. It is an attribute the caller is putting on the
+   * ELEMENT the progress draws — the bar for a linear or circular progress,
+   * the wrapper for a segmented one — which is where it has always landed on
+   * the web, along with every other unrecognised prop.
+   */
+  'data-testid'?: string;
+}

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

@@ -1,4 +1,4 @@
-import type { ProgressProps } from './Progress.types';
+import type { ProgressBaseProps } from './Progress.base';
 
 type ProgressDefaultedKeys =
   | 'variant'
@@ -11,10 +11,15 @@ type ProgressDefaultedKeys =
   | 'thickness'
   | 'dataTestId';
 
-type ResolvedProgressProps = ProgressProps &
-  Required<Pick<ProgressProps, ProgressDefaultedKeys>>;
+/**
+ * Generic over the renderer's own props: the web and the native `Progress`
+ * carry different extras (MUI's `LinearProgress` props against a `View`'s), and
+ * both come back out untouched.
+ */
+type ResolvedProgressProps<P extends ProgressBaseProps> = P &
+  Required<Pick<ProgressBaseProps, ProgressDefaultedKeys>>;
 
-const PROGRESS_DEFAULTS: Pick<ProgressProps, ProgressDefaultedKeys> = {
+const PROGRESS_DEFAULTS: Required<Pick<ProgressBaseProps, ProgressDefaultedKeys>> = {
   variant: 'linear',
   size: 'md',
   color: 'primary',
@@ -28,10 +33,26 @@ const PROGRESS_DEFAULTS: Pick<ProgressProps, ProgressDefaultedKeys> = {
 
 // Strips explicitly-undefined props before the merge, so `size={undefined}` still
 // falls back to the default exactly as a destructuring default would.
-const definedProps = (props: ProgressProps): Partial<ProgressProps> =>
+const definedProps = <P extends ProgressBaseProps>(props: P): Partial<P> =>
   Object.fromEntries(
     Object.entries(props).filter(([, value]) => value !== undefined),
-  ) as Partial<ProgressProps>;
+  ) as Partial<P>;
 
-export const resolveProgressProps = (props: ProgressProps): ResolvedProgressProps =>
-  ({ ...PROGRESS_DEFAULTS, ...definedProps(props) }) as ResolvedProgressProps;
+export const resolveProgressProps = <P extends ProgressBaseProps>(
+  props: P,
+): ResolvedProgressProps<P> =>
+  ({ ...PROGRESS_DEFAULTS, ...definedProps(props) }) as ResolvedProgressProps<P>;
+
+/**
+ * The label the caller asked for, or the rounded percentage when they only
+ * asked for one. Empty when there is nothing to show.
+ */
+export const progressLabelText = (
+  label: string | undefined,
+  showLabel: boolean,
+  displayValue: number,
+): string => label || (showLabel ? `${Math.round(displayValue)}%` : '');
+
+/** How much of the track the bar covers, 0 to 100 — a value outside that is clamped. */
+export const progressFraction = (value: number): number =>
+  Number.isFinite(value) ? Math.min(100, Math.max(0, value)) : 0;

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

@@ -0,0 +1,111 @@
+import type { TextStyle, ViewStyle } from 'react-native';
+
+import type { ProgressSize, ProgressVariant } from './Progress.base';
+import {
+  BAR_GLOW,
+  CIRCULAR_GLOW,
+  GLASS_BAR_ALPHA,
+  GLASS_BAR_BORDER_ALPHA,
+  LABEL_FONT_WEIGHT,
+  PROGRESS_SIZES,
+  SEGMENT_GLOW,
+  TRACK_ALPHA,
+  progressPalette,
+} from './Progress.metrics';
+import { MUI_TYPE } from '../../../tokens/mui-type';
+import { alpha } from '../../../tokens/color';
+import type { UiPaletteColor, UiTheme } from '../../../tokens/theme';
+import type { ColorValue } from '../../../tokens/vocabulary';
+
+/** `0 0 <blur>px <spread>px alpha(main, a)`, the string both renderers write. */
+const glowShadow = (
+  main: string,
+  { blur, spread, alpha: a }: { blur: number; spread: number; alpha: number },
+): string => `0 0 ${blur}px ${spread}px ${alpha(main, a)}`;
+
+/** The unfilled track a linear bar runs in. */
+export function trackStyle(theme: UiTheme, size: ProgressSize, color: ColorValue): ViewStyle {
+  const { height } = PROGRESS_SIZES[size];
+  return {
+    width: '100%',
+    height,
+    borderRadius: height / 2,
+    backgroundColor: alpha(progressPalette(theme, color).main, TRACK_ALPHA),
+    // The bar inherits the track's radius on the web; here it is clipped to it.
+    overflow: 'hidden',
+  };
+}
+
+/**
+ * What the web's `barVariantStyles` paint. `gradient` is the one honest gap:
+ * React Native core has no gradient fill, so it takes the first stop.
+ */
+function barPaint(variant: ProgressVariant, palette: UiPaletteColor): ViewStyle {
+  switch (variant) {
+    case 'gradient':
+      return { backgroundColor: palette.main };
+    case 'glass':
+      return {
+        backgroundColor: alpha(palette.main, GLASS_BAR_ALPHA),
+        borderWidth: 1,
+        borderColor: alpha(palette.main, GLASS_BAR_BORDER_ALPHA),
+      };
+    default:
+      return { backgroundColor: palette.main };
+  }
+}
+
+/** The bar itself: the variant's paint, the glow, and the height of its track. */
+export function barStyle(
+  theme: UiTheme,
+  a: { variant: ProgressVariant; size: ProgressSize; color: ColorValue; glow: boolean },
+): ViewStyle {
+  const palette = progressPalette(theme, a.color);
+  const { height } = PROGRESS_SIZES[a.size];
+  return {
+    height: '100%',
+    borderRadius: height / 2,
+    ...barPaint(a.variant, palette),
+    ...(a.glow ? { boxShadow: glowShadow(palette.main, BAR_GLOW) } : {}),
+  };
+}
+
+/** One segment of the segmented variant: filled with the hue, or a tenth of it. */
+export function segmentStyle(
+  theme: UiTheme,
+  a: { size: ProgressSize; color: ColorValue; filled: boolean; glow: boolean },
+): ViewStyle {
+  const palette = progressPalette(theme, a.color);
+  const { height } = PROGRESS_SIZES[a.size];
+  return {
+    flex: 1,
+    height,
+    borderRadius: height / 2,
+    backgroundColor: a.filled ? palette.main : alpha(palette.main, TRACK_ALPHA),
+    ...(a.glow && a.filled ? { boxShadow: glowShadow(palette.main, SEGMENT_GLOW) } : {}),
+  };
+}
+
+/** The circular arc's glow: the web's `drop-shadow`, as a box shadow round the dial. */
+export function circularGlowStyle(theme: UiTheme, color: ColorValue): ViewStyle {
+  const main = progressPalette(theme, color).main;
+  return { boxShadow: `0 0 ${CIRCULAR_GLOW.blur}px ${alpha(main, CIRCULAR_GLOW.alpha)}` };
+}
+
+/**
+ * The label: MUI's `caption` ratios at the size's own step, in semibold. The
+ * circular variant sets it in the muted ink, as `color="text.secondary"` does.
+ */
+export function labelStyle(theme: UiTheme, size: ProgressSize, muted = false): TextStyle {
+  const fontSize = PROGRESS_SIZES[size].fontSize;
+  const caption = MUI_TYPE.caption;
+  return {
+    fontFamily: theme.typography.fontFamily,
+    fontSize,
+    lineHeight: fontSize * caption.lineHeight,
+    letterSpacing: fontSize * caption.letterSpacingEm,
+    fontWeight: String(LABEL_FONT_WEIGHT) as TextStyle['fontWeight'],
+    textAlign: 'center',
+    color: muted ? theme.palette.text.secondary : theme.palette.text.primary,
+  };
+}

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

@@ -0,0 +1,101 @@
+import type { ProgressSize } from './Progress.base';
+import { contrastText, GREY, type UiPaletteColor, type UiTheme } from '../../../tokens/theme';
+import type { ColorValue } from '../../../tokens/vocabulary';
+
+/**
+ * THE NUMBERS BOTH `Progress` RENDERERS DRAW WITH.
+ *
+ * `Progress.styles.ts` (web, emotion over MUI's `LinearProgress` and
+ * `CircularProgress`) and `Progress.native.tsx` (React Native, with
+ * `react-native-svg` for the arc) read this one table. The web turns the px
+ * into rem and the shadows into CSS strings; native uses the numbers.
+ *
+ * The `CIRCULAR_*` group is MUI's OWN geometry, restated because the native
+ * half draws the arc itself: a 44-unit viewBox whose circle is inset by the
+ * stroke, with the value expressed as a dash offset — the same arithmetic
+ * MUI's `CircularProgress` runs, so the two draw the same sweep.
+ */
+export interface ProgressSizeMetrics {
+  /** The linear track's height, in px. The bar's radius is half of it. */
+  height: number;
+  /** The circular variant's diameter, in px. */
+  circularSize: number;
+  /** The label's type size, in px. */
+  fontSize: number;
+}
+
+export const PROGRESS_SIZES: Record<ProgressSize, ProgressSizeMetrics> = {
+  xs: { height: 2, circularSize: 24, fontSize: 10 },
+  sm: { height: 4, circularSize: 32, fontSize: 12 },
+  md: { height: 6, circularSize: 40, fontSize: 14 },
+  lg: { height: 8, circularSize: 48, fontSize: 16 },
+  xl: { height: 10, circularSize: 56, fontSize: 18 },
+};
+
+/** The unfilled track, and an unfilled segment: the hue at a tenth. */
+export const TRACK_ALPHA = 0.1;
+
+/** The label is MUI's `caption` at the size's own step, in semibold. */
+export const LABEL_FONT_WEIGHT = 600;
+/** `mt: 1` between a linear or segmented bar and its label. */
+export const LABEL_MARGIN_TOP_UNITS = 1;
+/** `gap: 0.5` between segments. */
+export const SEGMENT_GAP_UNITS = 0.5;
+
+/** `glass`: the hue at 80% behind a 10px blur, inside a 30% hairline. */
+export const GLASS_BAR_ALPHA = 0.8;
+export const GLASS_BAR_BORDER_ALPHA = 0.3;
+export const GLASS_BLUR_PX = 10;
+
+/** `glow` on a bar: `0 0 10px 2px alpha(main, 0.4)` and a 1.1 brightness lift. */
+export const BAR_GLOW = { blur: 10, spread: 2, alpha: 0.4 } as const;
+export const GLOW_BRIGHTNESS = 1.1;
+/** `glow` on a filled segment: the same shadow, one step tighter. */
+export const SEGMENT_GLOW = { blur: 6, spread: 1, alpha: 0.4 } as const;
+/** `glow` on the circular arc: `drop-shadow(0 0 8px alpha(main, 0.6))`. */
+export const CIRCULAR_GLOW = { blur: 8, alpha: 0.6 } as const;
+
+/** MUI's `pulseAnimation`: opacity 1 → 0.7 → 1, every two seconds. */
+export const PULSE = { durationMs: 2000, dip: 0.7 } as const;
+
+/** `transition: all 0.3s ease` on the bar and on every segment. */
+export const TRANSITION_MS = 300;
+
+/* ── MUI's `CircularProgress`, restated for the renderer that has no MUI ──── */
+
+/** MUI's `SIZE`: the arc is drawn in a 44-unit box and scaled to the px size. */
+export const CIRCULAR_VIEWBOX = 44;
+/** MUI puts the determinate arc's start at twelve o'clock. */
+export const CIRCULAR_ROTATION_DEG = -90;
+/** The circumference of the circle a `thickness` leaves room for. */
+export const circularCircumference = (thickness: number): number =>
+  2 * Math.PI * ((CIRCULAR_VIEWBOX - thickness) / 2);
+/** MUI's `strokeDashoffset`: the share of the circumference still to run. */
+export const circularDashOffset = (value: number, thickness: number): number =>
+  ((100 - value) / 100) * circularCircumference(thickness);
+
+/**
+ * MUI's indeterminate `CircularProgress` never closes the ring: it draws
+ * roughly a fifth of it and spins. One turn every 1.4s, as MUI's
+ * `circular-rotate` keyframes do.
+ */
+export const CIRCULAR_INDETERMINATE = { arc: 0.25, rotationMs: 1400 } as const;
+/** MUI's `bar1Indeterminate` keyframes: 2.1s a lap, over about a third of the track. */
+export const LINEAR_INDETERMINATE = { width: 0.35, durationMs: 2100 } as const;
+
+/**
+ * `neutral` has no palette slot of its own in MUI, so `Progress.styles.ts` has
+ * always drawn it from three greys; `danger` is MUI's `error`, which is what
+ * the shared theme calls `danger`. Same colours here.
+ */
+export function progressPalette(theme: UiTheme, color: ColorValue): UiPaletteColor {
+  if (color === 'neutral') {
+    return {
+      light: GREY[300],
+      main: GREY[500],
+      dark: GREY[700],
+      contrastText: contrastText(GREY[500]),
+    };
+  }
+  return theme.palette[color];
+}