@12-apps/ui 6.17.1 → 6.19.0

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

@@ -0,0 +1,175 @@
+import * as React from 'react';
+import {
+  ActivityIndicator,
+  Platform,
+  StyleSheet,
+  Text as RNText,
+  View,
+  type StyleProp,
+  type TextStyle,
+  type ViewStyle,
+} from 'react-native';
+
+import { type LoadingStateTestIds, makeTestIds, resolveLoadingStateProps } from './LoadingState.helpers';
+import {
+  IOS_LARGE_SPINNER_FROM,
+  MESSAGE_TYPE,
+  SKELETON_FULL_ROW_WIDTH,
+  SKELETON_LAST_ROW_WIDTH,
+  SKELETON_MESSAGE_MARGIN_TOP_UNITS,
+  SKELETON_PADDING_UNITS,
+  SKELETON_RADIUS,
+  SKELETON_ROW_GAP_UNITS,
+  SKELETON_ROW_HEIGHT,
+  SKELETON_TINT_ALPHA,
+  SPINNER_GAP_UNITS,
+  SPINNER_MIN_HEIGHT,
+  SPINNER_PADDING_UNITS,
+  SPINNER_SIZES,
+} from './LoadingState.metrics';
+import type { LoadingStateProps, LoadingStateSize } from './LoadingState.types.native';
+import { resolveTestId, withoutTestIdProps } from '../../../platform/test-id';
+import { useUiTheme } from '../../../provider/use-ui-theme.native';
+import { alpha } from '../../../tokens/color';
+import { muiTypeStyle } from '../../../tokens/mui-type';
+import type { UiTheme } from '../../../tokens/theme';
+
+/** The message's type: MUI's `body2`/`body1`/`h6` per size, in the muted ink, as the web's `Typography` sets it. */
+export function messageStyle(theme: UiTheme, size: LoadingStateSize): TextStyle {
+  return { ...muiTypeStyle(theme, MESSAGE_TYPE[size]), color: theme.palette.text.secondary };
+}
+
+/** The skeleton rows' tint: the house `Skeleton`'s `medium` intensity. */
+export const skeletonTint = (theme: UiTheme): string =>
+  alpha(theme.palette.text.primary, SKELETON_TINT_ALPHA);
+
+/** iOS has two spinner sizes; everything else takes the px. */
+function spinnerSize(px: number): number | 'small' | 'large' {
+  if (Platform.OS !== 'ios') return px;
+  return px >= IOS_LARGE_SPINNER_FROM ? 'large' : 'small';
+}
+
+interface ViewArgs {
+  message?: string;
+  size: LoadingStateSize;
+  skeletonRows: number;
+  testIds: LoadingStateTestIds;
+  style?: StyleProp<ViewStyle>;
+  rest: Omit<LoadingStateProps, keyof ViewArgs | 'variant' | 'testID' | 'dataTestId'>;
+}
+
+function LoadingMessage({
+  message,
+  size,
+  testIds,
+  style,
+}: Pick<ViewArgs, 'message' | 'size' | 'testIds'> & { style?: TextStyle }): React.JSX.Element | null {
+  const theme = useUiTheme();
+  if (!message) return null;
+  return (
+    <RNText style={[messageStyle(theme, size), style]} testID={testIds.named('message')}>
+      {message}
+    </RNText>
+  );
+}
+
+function SkeletonRows({ size, skeletonRows, testIds }: Pick<ViewArgs, 'size' | 'skeletonRows' | 'testIds'>): React.JSX.Element {
+  const theme = useUiTheme();
+  const tint = skeletonTint(theme);
+  return (
+    <View style={{ gap: theme.spacing(SKELETON_ROW_GAP_UNITS) }}>
+      {Array.from({ length: skeletonRows }, (_, index) => (
+        <View
+          key={`skeleton-row-${index}`}
+          aria-hidden
+          testID={testIds.optional(`skeleton-${index}`)}
+          style={{
+            height: SKELETON_ROW_HEIGHT[size],
+            // The last row is short, so the block reads as a paragraph of text.
+            width: index === skeletonRows - 1 ? SKELETON_LAST_ROW_WIDTH : SKELETON_FULL_ROW_WIDTH,
+            borderRadius: SKELETON_RADIUS,
+            backgroundColor: tint,
+          }}
+        />
+      ))}
+    </View>
+  );
+}
+
+function SkeletonView({ message, size, skeletonRows, testIds, style, rest }: ViewArgs): React.JSX.Element {
+  const theme = useUiTheme();
+  return (
+    <View
+      role="status"
+      aria-busy
+      aria-label={message || 'Loading content'}
+      testID={testIds.base}
+      style={[styles.skeleton, { padding: theme.spacing(SKELETON_PADDING_UNITS) }, style]}
+      {...rest}
+    >
+      <SkeletonRows size={size} skeletonRows={skeletonRows} testIds={testIds} />
+      <LoadingMessage
+        message={message}
+        size={size}
+        testIds={testIds}
+        style={{ marginTop: theme.spacing(SKELETON_MESSAGE_MARGIN_TOP_UNITS), textAlign: 'center' }}
+      />
+    </View>
+  );
+}
+
+function SpinnerView({ message, size, testIds, style, rest }: ViewArgs): React.JSX.Element {
+  const theme = useUiTheme();
+  return (
+    <View
+      role="status"
+      aria-busy
+      aria-label={message || 'Loading'}
+      testID={testIds.base}
+      style={[
+        styles.spinner,
+        {
+          padding: theme.spacing(SPINNER_PADDING_UNITS),
+          minHeight: SPINNER_MIN_HEIGHT,
+          gap: theme.spacing(SPINNER_GAP_UNITS),
+        },
+        style,
+      ]}
+      {...rest}
+    >
+      <ActivityIndicator
+        size={spinnerSize(SPINNER_SIZES[size])}
+        color={theme.palette.primary.main}
+        testID={testIds.named('spinner')}
+      />
+      <LoadingMessage message={message} size={size} testIds={testIds} />
+    </View>
+  );
+}
+
+export const LoadingState: React.FC<LoadingStateProps> = React.memo(function LoadingState(rawProps) {
+  const resolved = resolveLoadingStateProps(rawProps);
+  const { variant, message, size, skeletonRows, style, ...others } = resolved;
+  const args: ViewArgs = {
+    message,
+    size,
+    skeletonRows,
+    style,
+    testIds: makeTestIds(resolveTestId(others)),
+    rest: withoutTestIdProps(others),
+  };
+
+  return variant === 'skeleton' ? <SkeletonView {...args} /> : <SpinnerView {...args} />;
+});
+
+LoadingState.displayName = 'LoadingState';
+
+const styles = StyleSheet.create({
+  skeleton: {
+    width: '100%',
+  },
+  spinner: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+});

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

@@ -13,7 +13,19 @@ import {
   SIZE_MAP,
   SKELETON_ROW_HEIGHT,
 } from './LoadingState.helpers';
+import {
+  SKELETON_FULL_ROW_WIDTH,
+  SKELETON_LAST_ROW_WIDTH,
+  SKELETON_MESSAGE_MARGIN_TOP_UNITS,
+  SKELETON_PADDING_UNITS,
+  SKELETON_RADIUS,
+  SKELETON_ROW_GAP_UNITS,
+  SPINNER_GAP_UNITS,
+  SPINNER_MIN_HEIGHT,
+  SPINNER_PADDING_UNITS,
+} from './LoadingState.metrics';
 import type { LoadingStateProps, LoadingStateSize } from './LoadingState.types';
+import { resolveTestId } from '../../../platform/test-id';
 
 interface ViewProps {
   message?: string;
@@ -58,10 +70,10 @@ const SkeletonView: React.FC<ViewProps> = ({
       data-testid={testIds.base}
       sx={{
         width: '100%',
-        padding: theme.spacing(3),
+        padding: theme.spacing(SKELETON_PADDING_UNITS),
       }}
     >
-      <Stack spacing={2}>
+      <Stack spacing={SKELETON_ROW_GAP_UNITS}>
         {Array.from({ length: skeletonRows }).map((_, index) => (
           <Skeleton
             key={`skeleton-row-${index}`}
@@ -69,8 +81,8 @@ const SkeletonView: React.FC<ViewProps> = ({
             animation="wave"
             height={SKELETON_ROW_HEIGHT[size]}
             // The last row is short, so the block reads as a paragraph of text.
-            width={index === skeletonRows - 1 ? '60%' : '100%'}
-            borderRadius={4}
+            width={index === skeletonRows - 1 ? SKELETON_LAST_ROW_WIDTH : SKELETON_FULL_ROW_WIDTH}
+            borderRadius={SKELETON_RADIUS}
             data-testid={testIds.optional(`skeleton-${index}`)}
           />
         ))}
@@ -79,7 +91,7 @@ const SkeletonView: React.FC<ViewProps> = ({
         message={message}
         size={size}
         testIds={testIds}
-        sx={{ mt: 2, textAlign: 'center' }}
+        sx={{ mt: SKELETON_MESSAGE_MARGIN_TOP_UNITS, textAlign: 'center' }}
       />
     </Box>
   );
@@ -100,9 +112,9 @@ const SpinnerView: React.FC<ViewProps> = ({ message, size, className, testIds })
         flexDirection: 'column',
         alignItems: 'center',
         justifyContent: 'center',
-        padding: theme.spacing(6),
-        minHeight: 200,
-        gap: theme.spacing(2),
+        padding: theme.spacing(SPINNER_PADDING_UNITS),
+        minHeight: SPINNER_MIN_HEIGHT,
+        gap: theme.spacing(SPINNER_GAP_UNITS),
       }}
     >
       <CircularProgress
@@ -115,14 +127,16 @@ const SpinnerView: React.FC<ViewProps> = ({ message, size, className, testIds })
 };
 
 export const LoadingState: React.FC<LoadingStateProps> = React.memo((rawProps) => {
-  const { variant, message, size, skeletonRows, className, dataTestId } =
-    resolveLoadingStateProps(rawProps);
+  const resolved = resolveLoadingStateProps(rawProps);
+  const { variant, message, size, skeletonRows, className } = resolved;
   const viewProps: ViewProps = {
     message,
     size,
     skeletonRows,
     className,
-    testIds: makeTestIds(dataTestId),
+    // `dataTestId` is the documented spelling; `testID`, the shared contract's
+    // other one, resolves to the same id.
+    testIds: makeTestIds(resolveTestId(resolved)),
   };
 
   return variant === 'skeleton' ? (

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

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

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

@@ -1,38 +1,10 @@
-import type { SizeValue } from '../../../tokens/scales';
-export type LoadingStateVariant = 'spinner' | 'skeleton';
-export type LoadingStateSize = SizeValue;
+import type { LoadingStateBaseProps } from './LoadingState.base';
 
-export interface LoadingStateProps {
-  /**
-   * The visual style of the loading indicator
-   * @default 'spinner'
-   */
-  variant?: LoadingStateVariant;
-
-  /**
-   * Optional message to display below the loading indicator
-   */
-  message?: string;
-
-  /**
-   * Size of the loading indicator
-   * @default 'md'
-   */
-  size?: LoadingStateSize;
-
-  /**
-   * Number of skeleton rows to display (only for skeleton variant)
-   * @default 3
-   */
-  skeletonRows?: number;
+export type { LoadingStateBaseProps, LoadingStateSize, LoadingStateVariant } from './LoadingState.base';
 
+export interface LoadingStateProps extends LoadingStateBaseProps {
   /**
    * Custom className for the container
    */
   className?: string;
-
-  /**
-   * Test ID for component testing
-   */
-  dataTestId?: string;
 }

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

@@ -0,0 +1,7 @@
+# LoadingState on React Native
+
+Known rendering gaps, one bullet each; `pnpm native:ledger` reads them.
+
+- The spinner is the platform's `ActivityIndicator`, not MUI's 3.6-unit arc: same diameter and primary colour, the platform's own stroke; on iOS the two built-in sizes stand in for the five (`md` and up draw `large`).
+- The skeleton rows are the static tint (`alpha(text.primary, 0.13)`); MUI's `wave` sweep is a gradient pseudo-element React Native cannot draw.
+- The message is set in MUI's default `body2`/`body1`/`h6` numbers; a host that re-themes MUI's typography variants moves the web only.

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

@@ -0,0 +1,7 @@
+export { LoadingState } from './LoadingState.native';
+export type {
+  LoadingStateBaseProps,
+  LoadingStateProps,
+  LoadingStateSize,
+  LoadingStateVariant,
+} from './LoadingState.types.native';

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

@@ -1,2 +1,7 @@
 export { LoadingState } from './LoadingState';
-export type { LoadingStateProps, LoadingStateSize, LoadingStateVariant } from './LoadingState.types';
+export type {
+  LoadingStateBaseProps,
+  LoadingStateProps,
+  LoadingStateSize,
+  LoadingStateVariant,
+} from './LoadingState.types';

package/src/components/form/Button/Button.base.ts

@@ -0,0 +1,80 @@
+import type * as React from 'react';
+
+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 ButtonVariant = 'solid' | 'outline' | 'ghost' | 'text' | 'glass' | 'gradient';
+
+/**
+ * The contract both renderers honour. 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.
+ */
+export interface ButtonBaseProps {
+  /**
+   * The variant of the button
+   */
+  variant?: ButtonVariant;
+
+  /**
+   * The color of the button
+   */
+  color?: ColorValue;
+
+  /**
+   * The size of the button
+   */
+  size?: SizeValue;
+
+  /**
+   * Whether the button is in loading state
+   */
+  loading?: boolean;
+
+  /**
+   * Icon to display in the button
+   */
+  icon?: React.ReactNode;
+
+  /**
+   * Position of the icon
+   */
+  iconPosition?: 'left' | 'right';
+
+  /**
+   * Whether the button should have a glow effect
+   */
+  glow?: boolean;
+
+  /**
+   * Whether the button should have a pulse animation
+   */
+  pulse?: boolean;
+
+  /**
+   * Whether to show ripple effect on click
+   */
+  ripple?: boolean;
+
+  /**
+   * Whether the button is in active state
+   */
+  active?: boolean;
+
+  disabled?: boolean;
+
+  children?: React.ReactNode;
+
+  /**
+   * Test ID for testing purposes
+   */
+  dataTestId?: string;
+
+  testID?: string;
+}

package/src/components/form/Button/Button.helpers.ts

@@ -1,4 +1,4 @@
-import type { ButtonProps } from './Button.types';
+import type { ButtonBaseProps } from './Button.base';
 
 type ButtonDefaultedKeys =
   | 'variant'
@@ -11,9 +11,14 @@ type ButtonDefaultedKeys =
   | 'ripple'
   | 'active';
 
-type ResolvedButtonProps = ButtonProps & Required<Pick<ButtonProps, ButtonDefaultedKeys>>;
+/**
+ * Generic over the renderer's own props: the web and the native `Button` pass
+ * different handler types through, and both come back out untouched.
+ */
+type ResolvedButtonProps<P extends ButtonBaseProps> = P &
+  Required<Pick<ButtonBaseProps, ButtonDefaultedKeys>>;
 
-const BUTTON_DEFAULTS: Pick<ButtonProps, ButtonDefaultedKeys> = {
+const BUTTON_DEFAULTS: Required<Pick<ButtonBaseProps, ButtonDefaultedKeys>> = {
   variant: 'solid',
   color: 'primary',
   size: 'md',
@@ -27,10 +32,10 @@ const BUTTON_DEFAULTS: Pick<ButtonProps, ButtonDefaultedKeys> = {
 
 // 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: ButtonProps): Partial<ButtonProps> =>
+const definedProps = <P extends ButtonBaseProps>(props: P): Partial<P> =>
   Object.fromEntries(
     Object.entries(props).filter(([, value]) => value !== undefined),
-  ) as Partial<ButtonProps>;
+  ) as Partial<P>;
 
-export const resolveButtonProps = (props: ButtonProps): ResolvedButtonProps =>
-  ({ ...BUTTON_DEFAULTS, ...definedProps(props) }) as ResolvedButtonProps;
+export const resolveButtonProps = <P extends ButtonBaseProps>(props: P): ResolvedButtonProps<P> =>
+  ({ ...BUTTON_DEFAULTS, ...definedProps(props) }) as ResolvedButtonProps<P>;

package/src/components/form/Button/Button.metrics.ts

@@ -0,0 +1,101 @@
+import { darken, lighten } from '../../../tokens/color';
+import type { ColorValue, SizeValue } from '../../../tokens/vocabulary';
+import type { UiPaletteColor, UiTheme } from '../../../tokens/theme';
+
+/**
+ * THE NUMBERS BOTH `Button` RENDERERS DRAW WITH.
+ *
+ * `Button.styles.ts` (web, emotion) and `Button.native.tsx` (React Native)
+ * read this one table. The web turns the px into rem and the padding into a
+ * shorthand string; native uses the numbers as they are. Neither restates a
+ * value, which is what keeps a native `md` button 16px tall of padding and
+ * 16px of type exactly like the web one.
+ */
+export interface ButtonSizeMetrics {
+  paddingVertical: number;
+  paddingHorizontal: number;
+  fontSize: number;
+}
+
+export const BUTTON_SIZES: Record<SizeValue, ButtonSizeMetrics> = {
+  xs: { paddingVertical: 2, paddingHorizontal: 8, fontSize: 12 },
+  sm: { paddingVertical: 6, paddingHorizontal: 12, fontSize: 14 },
+  md: { paddingVertical: 8, paddingHorizontal: 16, fontSize: 16 },
+  lg: { paddingVertical: 10, paddingHorizontal: 20, fontSize: 18 },
+  xl: { paddingVertical: 12, paddingHorizontal: 24, fontSize: 20 },
+};
+
+/** A button that is only an icon is square: uniform padding, no min-width. */
+export const ICON_ONLY_PADDING: Record<SizeValue, number> = {
+  xs: 2,
+  sm: 5,
+  md: 7,
+  lg: 9,
+  xl: 11,
+};
+
+export const BUTTON_FONT_WEIGHT = 500;
+/** `theme.spacing(1)`. */
+export const BUTTON_RADIUS_UNITS = 1;
+/** Between the icon and the label: `theme.spacing(0.5)`. */
+export const BUTTON_ICON_GAP_UNITS = 0.5;
+export const BUTTON_SPINNER_SIZE = 16;
+/** MUI's `line-height` for button text. */
+export const BUTTON_LINE_HEIGHT = 1.75;
+
+/** The wash behind an outline, ghost or text button while it is hovered or pressed. */
+export const BUTTON_WASH_ALPHA = 0.1;
+export const GLASS_BACKGROUND_ALPHA = 0.1;
+export const GLASS_BACKGROUND_ALPHA_PRESSED = 0.2;
+export const GLASS_BORDER_ALPHA = 0.2;
+export const GLOW_INNER_ALPHA = 0.6;
+export const GLOW_OUTER_ALPHA = 0.3;
+export const GLOW_RADIUS = 20;
+export const PULSE_ALPHA = 0.3;
+export const PULSE_DURATION_MS = 2000;
+export const PULSE_SPREAD = 15;
+
+/**
+ * `neutral` has no palette slot of its own in MUI, so `Button.styles.ts` has
+ * always drawn it from three greys. Same three greys here.
+ */
+export function buttonPalette(theme: UiTheme, color: ColorValue): UiPaletteColor {
+  if (color === 'neutral') {
+    return {
+      main: theme.palette.grey[700],
+      dark: theme.palette.grey[800],
+      light: theme.palette.grey[500],
+      contrastText: '#fff',
+    };
+  }
+  return theme.palette[color];
+}
+
+/**
+ * The label colour for `ghost` and `text`: one step darker than `main` in
+ * light mode (lighter in dark), because `main` is chosen to sit UNDER white and
+ * is not legible AS text on a tinted surface. See the web `quietInk`.
+ */
+export const quietInk = (theme: UiTheme, palette: UiPaletteColor): string =>
+  theme.mode === 'dark' ? lighten(palette.main, 0.35) : darken(palette.main, 0.3);
+
+/** Gradients run between two related hues; the named colours pick a specific pair. */
+export function gradientStops(
+  theme: UiTheme,
+  color: ColorValue,
+  palette: UiPaletteColor,
+): [string, string] {
+  switch (color) {
+    case 'primary':
+      return [theme.palette.primary.main, theme.palette.secondary.main];
+    case 'secondary':
+      return [theme.palette.secondary.main, theme.palette.primary.main];
+    case 'success':
+    case 'warning':
+      return [theme.palette[color].light, theme.palette[color].dark];
+    case 'danger':
+      return [theme.palette.danger.light, theme.palette.danger.dark];
+    default:
+      return [palette.main, palette.dark];
+  }
+}