@12-apps/ui 6.20.0 → 6.22.0

package/src/components/form/field-pulse.native.tsx

@@ -0,0 +1,78 @@
+import * as React from 'react';
+import { Animated, Easing, Platform, StyleSheet } from 'react-native';
+
+import { INPUT_PULSE } from './Input/Input.metrics';
+
+/**
+ * THE BAR THAT PULSES BEHIND A FIELD.
+ *
+ * `Input.styles.ts` and `Select.tsx` declare the same `::after` — a 56px wash
+ * of the primary hue at 0.3, growing a 10px box-shadow ring and fading out
+ * every two seconds — so the native halves draw it from one component rather
+ * than one each. The numbers stay in `Input.metrics.ts`, which `Select.metrics`
+ * re-exports under its own name.
+ *
+ * React Native has no box-shadow spread, so the ring is a scale on the bar.
+ */
+export function FieldPulse({
+  color,
+  radius,
+  testID,
+}: {
+  color: string;
+  radius: number;
+  testID: string;
+}): React.JSX.Element {
+  const progress = React.useRef(new Animated.Value(0)).current;
+
+  React.useEffect(() => {
+    const loop = Animated.loop(
+      Animated.timing(progress, {
+        toValue: 1,
+        duration: INPUT_PULSE.ms,
+        easing: Easing.out(Easing.ease),
+        useNativeDriver: Platform.OS !== 'web',
+      }),
+    );
+    loop.start();
+    return () => loop.stop();
+  }, [progress]);
+
+  return (
+    <Animated.View
+      testID={testID}
+      aria-hidden
+      style={[
+        styles.pulse,
+        {
+          borderRadius: radius,
+          backgroundColor: color,
+          opacity: progress.interpolate({
+            inputRange: [0, 0.7, 1],
+            outputRange: [INPUT_PULSE.opacity, 0, 0],
+          }),
+          transform: [
+            { translateY: -INPUT_PULSE.height / 2 },
+            {
+              scale: progress.interpolate({
+                inputRange: [0, 0.7, 1],
+                outputRange: [1, 1 + INPUT_PULSE.spread / INPUT_PULSE.height, 1],
+              }),
+            },
+          ],
+        },
+      ]}
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  pulse: {
+    position: 'absolute',
+    top: '50%',
+    left: 0,
+    right: 0,
+    height: INPUT_PULSE.height,
+    pointerEvents: 'none',
+  },
+});

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

@@ -0,0 +1,92 @@
+import type * as React from 'react';
+
+/**
+ * THE CONTRACT BOTH `Card` RENDERERS HONOUR — and nothing else.
+ *
+ * This file imports no MUI and no react-native, on purpose: it ships in BOTH
+ * declaration outputs (`dist/types` and `dist/types-native`), and a native
+ * consumer has no `@mui/material` to resolve a type import against.
+ *
+ * Handlers are NOT here. Their names are the same on both sides (`onClick`,
+ * `onFocus`, `onBlur`) but their event types are the renderer's own, so each
+ * side declares them beside its own extras — except {@link
+ * CardBaseProps.onExpandToggle}, whose argument is a boolean rather than an
+ * event and is therefore the same type on both.
+ */
+export type CardVariant = 'elevated' | 'outlined' | 'glass' | 'gradient' | 'neumorphic' | 'section';
+export type CardEntranceAnimation =
+  | 'fade'
+  | 'slide-up'
+  | 'slide-down'
+  | 'slide-left'
+  | 'slide-right'
+  | 'zoom'
+  | 'grow'
+  | 'none';
+
+/** The named radii a card can be cut to. `full` is a percentage, not a length. */
+export type CardBorderRadius = 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
+
+export interface CardBaseProps {
+  children: React.ReactNode;
+  variant?: CardVariant;
+  /** Paints the hover/press surface and marks the card as a pointer target. */
+  interactive?: boolean;
+  glow?: boolean;
+  pulse?: boolean;
+  borderRadius?: CardBorderRadius;
+  /** Dims the card, blocks pointer events and centres a spinner over it. */
+  loading?: boolean;
+  /**
+   * Accepted and ignored on BOTH renderers — reserved, and extracted so they
+   * never reach the underlying element as unknown attributes.
+   */
+  expandable?: boolean;
+  expanded?: boolean;
+  onExpandToggle?: (expanded: boolean) => void;
+  entranceAnimation?: CardEntranceAnimation;
+  animationDelay?: number;
+  skeleton?: boolean;
+  hoverScale?: number;
+  dataTestId?: string;
+  testID?: string;
+}
+
+export interface CardHeaderBaseProps {
+  title?: React.ReactNode;
+  subtitle?: React.ReactNode;
+  action?: React.ReactNode;
+  avatar?: React.ReactNode;
+  /** Custom header content; when given it replaces the title/subtitle layout. */
+  children?: React.ReactNode;
+  dataTestId?: string;
+  testID?: string;
+}
+
+export interface CardContentBaseProps {
+  children: React.ReactNode;
+  dense?: boolean;
+  dataTestId?: string;
+  testID?: string;
+}
+
+export type CardActionsAlignment = 'left' | 'center' | 'right' | 'space-between';
+
+export interface CardActionsBaseProps {
+  children: React.ReactNode;
+  disableSpacing?: boolean;
+  alignment?: CardActionsAlignment;
+  dataTestId?: string;
+  testID?: string;
+}
+
+export interface CardMediaBaseProps {
+  /** The image URL. */
+  image?: string;
+  /** The media's accessible name. */
+  title?: string;
+  height?: number | string;
+  children?: React.ReactNode;
+  dataTestId?: string;
+  testID?: string;
+}

package/src/components/layout/Card/Card.helpers.ts

@@ -1,4 +1,4 @@
-import type { CardProps } from './Card.types';
+import type { CardBaseProps } from './Card.base';
 
 type CardDefaultedKeys =
   | 'variant'
@@ -8,9 +8,15 @@ type CardDefaultedKeys =
   | 'borderRadius'
   | 'loading';
 
-type ResolvedCardProps = CardProps & Required<Pick<CardProps, CardDefaultedKeys>>;
+/**
+ * Generic over the renderer's own props: the web and the native `Card` pass
+ * different handler types (and different style props) through, and both come
+ * back out untouched.
+ */
+type ResolvedCardProps<P extends CardBaseProps> = P &
+  Required<Pick<CardBaseProps, CardDefaultedKeys>>;
 
-const CARD_DEFAULTS: Pick<CardProps, CardDefaultedKeys> = {
+const CARD_DEFAULTS: Required<Pick<CardBaseProps, CardDefaultedKeys>> = {
   variant: 'elevated',
   interactive: false,
   glow: false,
@@ -21,10 +27,10 @@ const CARD_DEFAULTS: Pick<CardProps, CardDefaultedKeys> = {
 
 // Strips explicitly-undefined props before the merge, so `glow={undefined}` still
 // falls back to the default exactly as a destructuring default would.
-const definedProps = (props: CardProps): Partial<CardProps> =>
+const definedProps = <P extends CardBaseProps>(props: P): Partial<P> =>
   Object.fromEntries(
     Object.entries(props).filter(([, value]) => value !== undefined),
-  ) as Partial<CardProps>;
+  ) as Partial<P>;
 
-export const resolveCardProps = (props: CardProps): ResolvedCardProps =>
-  ({ ...CARD_DEFAULTS, ...definedProps(props) }) as ResolvedCardProps;
+export const resolveCardProps = <P extends CardBaseProps>(props: P): ResolvedCardProps<P> =>
+  ({ ...CARD_DEFAULTS, ...definedProps(props) }) as ResolvedCardProps<P>;

package/src/components/layout/Card/Card.look.native.ts

@@ -0,0 +1,204 @@
+import type { ViewStyle } from 'react-native';
+
+import type { CardBorderRadius, CardVariant } from './Card.base';
+import {
+  CARD_BORDER_WIDTH,
+  CARD_GLASS,
+  CARD_GLOW,
+  CARD_GRADIENT,
+  CARD_LOADING,
+  CARD_NEUMORPHIC,
+  CARD_PAPER_SHADOW,
+  CARD_RADIUS_FULL,
+  CARD_RADIUS_UNITS,
+  CARD_SECTION_BACKGROUND,
+  neumorphicShadows,
+} from './Card.metrics';
+import { alpha } from '../../../tokens/color';
+import { BLACK, WHITE, drop, halo, type UiShadow } from '../../../tokens/shadow';
+import type { UiTheme } from '../../../tokens/theme';
+
+/**
+ * WHAT THE NATIVE `Card` PAINTS — the arithmetic, with no JSX in sight.
+ *
+ * The web builds one `sx` object by spreading base, `interactive`, `glow`,
+ * `pulse` and finally the variant's own surface over each other; whichever
+ * wrote a property last wins. The composition here spreads the SAME things in
+ * the SAME order, which is why `glow` shows through an `elevated` card (whose
+ * surface declares no shadow) and is buried by a `glass` one (whose surface
+ * does) on both renderers.
+ */
+
+/** The named radius as a length. `full` stays a percentage of the box. */
+export function cardRadius(theme: UiTheme, radius: CardBorderRadius): number | string {
+  if (radius === 'full') return CARD_RADIUS_FULL;
+  return theme.spacing(CARD_RADIUS_UNITS[radius] ?? CARD_RADIUS_UNITS.md);
+}
+
+interface Surface {
+  surface: ViewStyle;
+  /** What the web changes on `:hover`; native applies it while pressed. */
+  hover: ViewStyle;
+}
+
+function glassSurface(theme: UiTheme, lifted: boolean): Surface {
+  return {
+    surface: {
+      backgroundColor: alpha(theme.palette.background.paper, CARD_GLASS.backgroundAlpha.rest),
+      borderWidth: CARD_BORDER_WIDTH,
+      borderStyle: 'solid',
+      borderColor: alpha(theme.palette.primary.main, CARD_GLASS.borderAlpha.rest),
+      boxShadow: drop(
+        CARD_GLASS.shadow.offsetY,
+        CARD_GLASS.shadow.blurRadius,
+        alpha(BLACK, CARD_GLASS.shadow.alpha),
+      ),
+    },
+    hover: {
+      backgroundColor: alpha(
+        theme.palette.background.paper,
+        lifted ? CARD_GLASS.backgroundAlpha.lifted : CARD_GLASS.backgroundAlpha.rest,
+      ),
+      borderColor: alpha(theme.palette.primary.main, CARD_GLASS.borderAlpha.lifted),
+    },
+  };
+}
+
+function neumorphicSurface(theme: UiTheme, lifted: boolean): Surface {
+  const { dark, light } = CARD_NEUMORPHIC.alpha;
+  const pair = (raised: boolean): UiShadow[] =>
+    theme.mode === 'dark'
+      ? neumorphicShadows(raised, alpha(BLACK, dark.near), alpha(WHITE, dark.far))
+      : neumorphicShadows(
+          raised,
+          alpha(theme.palette.grey[400], raised ? light.near.lifted : light.near.rest),
+          alpha(WHITE, raised ? light.far.lifted : light.far.rest),
+        );
+
+  return {
+    surface: {
+      backgroundColor: theme.mode === 'dark' ? theme.palette.grey[800] : theme.palette.grey[100],
+      boxShadow: pair(false),
+      borderWidth: 0,
+    },
+    hover: { boxShadow: pair(lifted) },
+  };
+}
+
+function sectionSurface(theme: UiTheme, lifted: boolean): Surface {
+  const wash = CARD_SECTION_BACKGROUND[theme.mode === 'dark' ? 'dark' : 'light'];
+  return {
+    surface: { backgroundColor: wash.rest, borderWidth: 0, boxShadow: undefined },
+    hover: { backgroundColor: lifted ? wash.lifted : wash.rest },
+  };
+}
+
+/**
+ * Each variant's resting surface and whatever it changes on hover — the same
+ * split `Card.styles.ts` makes, in React Native's property names.
+ *
+ * `gradient` is the one honest gap: React Native core has no gradient fill, so
+ * it paints the gradient's FIRST stop. The parity ledger records it.
+ */
+export function cardSurface(theme: UiTheme, variant: CardVariant, lifted: boolean): Surface {
+  switch (variant) {
+    case 'outlined':
+      return {
+        surface: {
+          borderWidth: CARD_BORDER_WIDTH,
+          borderStyle: 'solid',
+          borderColor: theme.palette.divider,
+          boxShadow: undefined,
+        },
+        hover: { borderColor: lifted ? theme.palette.primary.main : theme.palette.divider },
+      };
+    case 'glass':
+      return glassSurface(theme, lifted);
+    case 'gradient':
+      return {
+        surface: {
+          backgroundColor: theme.palette.primary.main,
+          boxShadow: drop(
+            CARD_GRADIENT.shadow.offsetY,
+            CARD_GRADIENT.shadow.blurRadius,
+            alpha(theme.palette.primary.main, CARD_GRADIENT.shadow.alpha),
+          ),
+        },
+        hover: {
+          backgroundColor: lifted ? theme.palette.primary.dark : theme.palette.primary.main,
+        },
+      };
+    case 'neumorphic':
+      return neumorphicSurface(theme, lifted);
+    case 'section':
+      return sectionSurface(theme, lifted);
+    default:
+      // `elevated` declares only MUI's inert `elevation`, so the paper shadow
+      // the base laid down (or a `glow` over it) is what shows.
+      return { surface: {}, hover: {} };
+  }
+}
+
+/** The ink a card's own text inherits: `gradient` flips it, everything else is body ink. */
+export const cardInk = (theme: UiTheme, variant: CardVariant): string =>
+  variant === 'gradient' ? theme.palette.primary.contrastText : theme.palette.text.primary;
+
+export interface CardLookArgs {
+  variant: CardVariant;
+  interactive: boolean;
+  glow: boolean;
+  pulse: boolean;
+  loading: boolean;
+  borderRadius: CardBorderRadius;
+}
+
+export interface CardLook {
+  container: ViewStyle;
+  /** Applied while pressed, standing in for the web's `:hover`. */
+  pressed: ViewStyle;
+  radius: number | string;
+  ink: string;
+}
+
+/**
+ * Everything the card paints, decided once per render.
+ *
+ * `overflow` is the one place native needs a rule the web does not. MUI's
+ * `Card` clips its children, and the pulse ring has to reach 15px past the
+ * edge — but a view's own shadow is clipped by its own overflow on a device,
+ * so a `glow` the caller asked for would simply not paint. Both decorations
+ * therefore turn the clip off, exactly as `Button.native.tsx` does.
+ */
+export function cardLook(theme: UiTheme, a: CardLookArgs): CardLook {
+  const radius = cardRadius(theme, a.borderRadius);
+  const chosen = cardSurface(theme, a.variant, a.interactive);
+
+  const base: ViewStyle = {
+    position: 'relative',
+    borderRadius: radius,
+    backgroundColor: theme.palette.background.paper,
+    overflow: a.pulse || a.glow ? 'visible' : 'hidden',
+    opacity: a.loading ? CARD_LOADING.opacity : 1,
+    pointerEvents: a.loading ? 'none' : 'auto',
+  };
+
+  return {
+    radius,
+    ink: cardInk(theme, a.variant),
+    container: {
+      ...base,
+      boxShadow: CARD_PAPER_SHADOW,
+      ...(a.interactive ? { cursor: 'pointer' } : null),
+      ...(a.glow
+        ? { boxShadow: halo(CARD_GLOW.rest.blurRadius, alpha(theme.palette.primary.main, CARD_GLOW.rest.alpha)) }
+        : null),
+      ...chosen.surface,
+    },
+    pressed: {
+      ...(a.glow
+        ? { boxShadow: halo(CARD_GLOW.lifted.blurRadius, alpha(theme.palette.primary.main, CARD_GLOW.lifted.alpha)) }
+        : null),
+      ...chosen.hover,
+    },
+  };
+}

package/src/components/layout/Card/Card.metrics.ts

@@ -0,0 +1,171 @@
+import type { CardBorderRadius } from './Card.base';
+import type { UiShadow } from '../../../tokens/shadow';
+
+/**
+ * THE NUMBERS BOTH `Card` RENDERERS DRAW WITH.
+ *
+ * `Card.styles.ts` (web, emotion over MUI) and `Card.native.tsx` /
+ * `Card.look.native.ts` (React Native) read this one table. The web turns the
+ * radii into `theme.spacing()` and the shadows into CSS strings (`shadowCss`
+ * in `src/tokens/shadow.ts` writes exactly the text it always has); native
+ * hands the same shadow objects to `boxShadow` and the same numbers to a
+ * `StyleSheet`.
+ *
+ * Nothing here imports a renderer, a theme or a colour: a shadow's COLOUR is
+ * the caller's, because the two sides reach for the same arithmetic through
+ * different doors (`alpha` from `@mui/material/styles` on the web, from
+ * `src/tokens/color` natively — a port of it, asserted equal).
+ */
+
+/* ── The envelope ─────────────────────────────────────────────────────────── */
+
+/**
+ * `theme.spacing(n)` per named radius. `none` is written as a bare `0` by the
+ * web rather than `spacing(0)`, so it is spelled that way on both sides.
+ */
+export const CARD_RADIUS_UNITS: Record<Exclude<CardBorderRadius, 'full'>, number> = {
+  none: 0,
+  sm: 0.5,
+  md: 1,
+  lg: 2,
+  xl: 3,
+};
+
+/** `full` is a percentage of the box, not a length. */
+export const CARD_RADIUS_FULL = '50%';
+
+/** The hairline `outlined` and `glass` draw. */
+export const CARD_BORDER_WIDTH = 1;
+
+/* ── Shadows ──────────────────────────────────────────────────────────────── */
+
+/** A card's shadows are `UiShadow`s; `src/tokens/shadow.ts` says why they have a shape. */
+export type CardShadow = UiShadow;
+
+/**
+ * MUI's `theme.shadows[1]` — the elevation a `Paper` paints and therefore the
+ * shadow every `elevated` card on the web already has.
+ *
+ * It is restated here rather than derived because the web never names it: it
+ * arrives through `MuiCard` -> `MuiPaper`, and React Native has no Paper to
+ * inherit it from. (`variant="elevated"`'s own `elevation: 4` is not a CSS
+ * property and paints nothing — see {@link CARD_ELEVATION}.)
+ */
+export const CARD_PAPER_SHADOW: readonly UiShadow[] = [
+  { offsetX: 0, offsetY: 2, blurRadius: 1, spreadDistance: -1, color: 'rgba(0, 0, 0, 0.2)' },
+  { offsetX: 0, offsetY: 1, blurRadius: 1, spreadDistance: 0, color: 'rgba(0, 0, 0, 0.14)' },
+  { offsetX: 0, offsetY: 1, blurRadius: 3, spreadDistance: 0, color: 'rgba(0, 0, 0, 0.12)' },
+];
+
+/**
+ * What `elevated` declares at rest and on hover.
+ *
+ * `elevation` is not a CSS property, so on the web these paint NOTHING and an
+ * elevated card shows `MuiPaper`'s own elevation-1 shadow. Kept because they
+ * are what the source says, and mirrored natively by leaving
+ * {@link CARD_PAPER_SHADOW} in place for both states.
+ */
+export const CARD_ELEVATION = { rest: 4, lifted: 8 } as const;
+
+/* ── Variant surfaces ─────────────────────────────────────────────────────── */
+
+/** `glass`: a 0.1 wash of the paper behind a 20px blur, inside a primary hairline. */
+export const CARD_GLASS = {
+  backgroundAlpha: { rest: 0.1, lifted: 0.15 },
+  borderAlpha: { rest: 0.2, lifted: 0.3 },
+  blurPx: 20,
+  shadow: { offsetY: 8, blurRadius: 32, alpha: 0.1 },
+} as const;
+
+/** `gradient`: primary into secondary at 135°, over a hue-tinted drop shadow. */
+export const CARD_GRADIENT = {
+  angleDeg: 135,
+  shadow: { offsetY: 4, blurRadius: 20, alpha: 0.3 },
+} as const;
+
+/** `neumorphic`: two opposed shadows, blurred twice their offset. */
+export const CARD_NEUMORPHIC = {
+  spread: { rest: 8, lifted: 12 },
+  blurFactor: 2,
+  alpha: {
+    dark: { near: 0.3, far: 0.1 },
+    light: { near: { rest: 0.2, lifted: 0.3 }, far: { rest: 0.8, lifted: 0.9 } },
+  },
+} as const;
+
+/**
+ * The offset pair `neumorphic` paints, given the two colours the mode picked:
+ * `near` down-right, `far` up-left, both blurred twice the offset.
+ */
+export function neumorphicShadows(lifted: boolean, near: string, far: string): UiShadow[] {
+  const spread = lifted ? CARD_NEUMORPHIC.spread.lifted : CARD_NEUMORPHIC.spread.rest;
+  const blurRadius = spread * CARD_NEUMORPHIC.blurFactor;
+  return [
+    { offsetX: spread, offsetY: spread, blurRadius, spreadDistance: 0, color: near },
+    { offsetX: -spread, offsetY: -spread, blurRadius, spreadDistance: 0, color: far },
+  ];
+}
+
+/**
+ * `section`: a flat ink wash rather than a palette slot, so a section reads as
+ * a recess in whatever surface it sits on.
+ */
+export const CARD_SECTION_BACKGROUND = {
+  dark: { rest: 'rgba(0, 0, 0, 0.2)', lifted: 'rgba(0, 0, 0, 0.25)' },
+  light: { rest: 'rgba(0, 0, 0, 0.02)', lifted: 'rgba(0, 0, 0, 0.04)' },
+} as const;
+
+/* ── Decorations ──────────────────────────────────────────────────────────── */
+
+/** `glow`: a haloed primary shadow that widens under the pointer. */
+export const CARD_GLOW = {
+  rest: { blurRadius: 20, alpha: 0.3 },
+  lifted: { blurRadius: 30, alpha: 0.4 },
+} as const;
+
+/**
+ * `pulse`: a ring of the primary hue that grows 15px out of the card's edge and
+ * fades, every two seconds. The web draws it as an `::after` box-shadow spread
+ * behind the paper (`z-index: -1`).
+ */
+export const CARD_PULSE = {
+  alpha: 0.3,
+  durationMs: 2000,
+  spread: 15,
+  /** The fraction of the cycle the ring is still visible for. */
+  fadeAt: 0.7,
+  zIndex: -1,
+} as const;
+
+/** `interactive`: the card rises 2px under the pointer and settles while pressed. */
+export const CARD_INTERACTIVE_LIFT = 2;
+
+/** `loading`: the card dims, stops taking pointers and centres a spinner over itself. */
+export const CARD_LOADING = { opacity: 0.6, spinnerZIndex: 10, spinnerSize: 40 } as const;
+
+/* ── The slots ────────────────────────────────────────────────────────────── */
+
+/** `CardContent`: `theme.spacing(2)`, halved by `dense`. */
+export const CARD_CONTENT_PADDING_UNITS = { normal: 2, dense: 1 } as const;
+
+/**
+ * `CardHeader`, in MUI's own px: 16 all round, the avatar 16 from the content,
+ * the action pulled back out of the padding on three sides.
+ */
+export const CARD_HEADER = {
+  padding: 16,
+  avatarGap: 16,
+  action: { marginTop: -4, marginRight: -8, marginBottom: -4 },
+} as const;
+
+/** A `CardHeader` given raw `children` is a plain `theme.spacing(2)` box instead. */
+export const CARD_HEADER_CHILDREN_PADDING_UNITS = 2;
+
+/**
+ * `CardActions`, in MUI's own px: 8 all round, and 8 between the actions unless
+ * `disableSpacing` turns the run off.
+ */
+export const CARD_ACTIONS = { padding: 8, gap: 8 } as const;
+
+/** `CardMedia`'s default height. */
+export const CARD_MEDIA_HEIGHT = 200;