@12-apps/ui 6.17.1 → 6.19.0

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

@@ -0,0 +1,193 @@
+import * as React from 'react';
+import { StyleSheet, Text as RNText, View, type TextStyle, type ViewStyle } from 'react-native';
+
+import {
+  ERROR_ICON_BOX,
+  ERROR_ICON_BOX_OPACITY,
+  ERROR_ICON_SIZE,
+  ERROR_MESSAGE_LINE_HEIGHT,
+  ERROR_MESSAGE_MAX_WIDTH,
+  ERROR_STATE_GAP_UNITS,
+  ERROR_STATE_MIN_HEIGHT,
+  ERROR_STATE_PADDING_UNITS,
+  ERROR_TEXT_GAP_UNITS,
+  RETRY_BUTTON,
+  RETRY_MARGIN_TOP_UNITS,
+  RETRY_MIN_WIDTH,
+  errorStatePalette,
+} from './ErrorState.metrics';
+import type { ErrorStateProps, ErrorStateSeverity } from './ErrorState.types.native';
+import { Icon } from '../../../icons/Icon.native';
+import { webAria } from '../../../platform/aria';
+import { resolveTestId, withoutTestIdProps } from '../../../platform/test-id';
+import { useUiTheme } from '../../../provider/use-ui-theme.native';
+import { MUI_FONT_WEIGHT_MEDIUM, MUI_TYPE, muiTypeStyle } from '../../../tokens/mui-type';
+import type { UiTheme } from '../../../tokens/theme';
+import { Button } from '../../form/Button/Button.native';
+
+const makeTestId =
+  (dataTestId?: string) =>
+  (suffix: string): string =>
+    dataTestId ? `${dataTestId}-${suffix}` : `error-state-${suffix}`;
+
+/** MUI's `h6` as an `h3`, medium weight, in the body ink — what the web `Typography` renders. */
+export function titleStyle(theme: UiTheme): TextStyle {
+  return {
+    ...muiTypeStyle(theme, 'h6'),
+    fontWeight: `${MUI_FONT_WEIGHT_MEDIUM}`,
+    color: theme.palette.text.primary,
+    textAlign: 'center',
+  };
+}
+
+/** MUI's `body2` on a 1.6 line height, muted, wrapping at 400px. */
+export function messageStyle(theme: UiTheme): TextStyle {
+  return {
+    ...muiTypeStyle(theme, 'body2'),
+    lineHeight: MUI_TYPE.body2.fontSize * ERROR_MESSAGE_LINE_HEIGHT,
+    color: theme.palette.text.secondary,
+    maxWidth: ERROR_MESSAGE_MAX_WIDTH,
+    textAlign: 'center',
+  };
+}
+
+/** The 80px disc behind the glyph, in the severity's `light` shade. */
+export function iconBoxStyle(theme: UiTheme, severity: ErrorStateSeverity): ViewStyle {
+  return {
+    width: ERROR_ICON_BOX,
+    height: ERROR_ICON_BOX,
+    borderRadius: ERROR_ICON_BOX / 2,
+    backgroundColor: errorStatePalette(theme, severity).light,
+    opacity: ERROR_ICON_BOX_OPACITY,
+    alignItems: 'center',
+    justifyContent: 'center',
+  };
+}
+
+/** The web retry is MUI's medium outlined button; the house `Button` is sized to it here. */
+export function retryStyle(theme: UiTheme): ViewStyle {
+  return {
+    marginTop: theme.spacing(RETRY_MARGIN_TOP_UNITS),
+    minWidth: RETRY_MIN_WIDTH,
+    paddingVertical: RETRY_BUTTON.paddingVertical,
+    paddingHorizontal: RETRY_BUTTON.paddingHorizontal,
+    borderRadius: theme.radius.md,
+  };
+}
+
+function ErrorIcon({
+  severity,
+  icon,
+  testId,
+}: {
+  severity: ErrorStateSeverity;
+  icon?: React.ReactNode;
+  testId: string;
+}): React.JSX.Element {
+  const theme = useUiTheme();
+  const glyph = severity === 'error' ? 'ErrorOutline' : 'WarningAmber';
+  return (
+    <View testID={testId} style={iconBoxStyle(theme, severity)}>
+      {icon || <Icon name={glyph} size={ERROR_ICON_SIZE} color={errorStatePalette(theme, severity).main} />}
+    </View>
+  );
+}
+
+function ErrorText({
+  title,
+  message,
+  titleId,
+  testId,
+}: {
+  title?: string;
+  message: string;
+  titleId: string;
+  testId: (suffix: string) => string;
+}): React.JSX.Element {
+  const theme = useUiTheme();
+  return (
+    <View style={[styles.text, { gap: theme.spacing(ERROR_TEXT_GAP_UNITS) }]}>
+      {title ? (
+        <RNText
+          id={titleId}
+          role="heading"
+          {...webAria({ 'aria-level': 3 })}
+          testID={testId('title')}
+          style={titleStyle(theme)}
+        >
+          {title}
+        </RNText>
+      ) : null}
+      <RNText id={`${titleId}-message`} testID={testId('message')} style={messageStyle(theme)}>
+        {message}
+      </RNText>
+    </View>
+  );
+}
+
+export const ErrorState: React.FC<ErrorStateProps> = React.memo(function ErrorState(props) {
+  const {
+    message,
+    title,
+    onRetry,
+    retryLabel = 'Retry',
+    severity = 'error',
+    icon,
+    style,
+    ...others
+  } = props;
+  const theme = useUiTheme();
+  const titleId = React.useId();
+  const dataTestId = resolveTestId(others);
+  const testId = makeTestId(dataTestId);
+  const rest = withoutTestIdProps(others);
+
+  return (
+    <View
+      role="alert"
+      aria-labelledby={title ? titleId : undefined}
+      {...webAria({ 'aria-describedby': `${titleId}-message` })}
+      testID={dataTestId || 'error-state'}
+      style={[
+        styles.root,
+        {
+          padding: theme.spacing(ERROR_STATE_PADDING_UNITS),
+          minHeight: ERROR_STATE_MIN_HEIGHT,
+          gap: theme.spacing(ERROR_STATE_GAP_UNITS),
+        },
+        style,
+      ]}
+      {...rest}
+    >
+      <ErrorIcon severity={severity} icon={icon} testId={testId('icon')} />
+
+      <ErrorText title={title} message={message} titleId={titleId} testId={testId} />
+
+      {onRetry ? (
+        <Button
+          variant="outline"
+          color={severity === 'error' ? 'danger' : 'warning'}
+          size="sm"
+          icon={<Icon name="Refresh" size={RETRY_BUTTON.iconSize} color={severity === 'error' ? 'danger' : 'warning'} />}
+          onClick={onRetry}
+          testID={testId('retry-button')}
+          style={retryStyle(theme)}
+        >
+          {retryLabel}
+        </Button>
+      ) : null}
+    </View>
+  );
+});
+
+ErrorState.displayName = 'ErrorState';
+
+const styles = StyleSheet.create({
+  root: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  text: {
+    alignItems: 'center',
+  },
+});

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

@@ -9,7 +9,21 @@ import { useTheme } from '@mui/material/styles/index.js';
 import type { Theme } from '@mui/material/styles/index.js';
 import React from 'react';
 
+import {
+  ERROR_ICON_BOX,
+  ERROR_ICON_BOX_OPACITY,
+  ERROR_ICON_SIZE,
+  ERROR_MESSAGE_LINE_HEIGHT,
+  ERROR_MESSAGE_MAX_WIDTH,
+  ERROR_STATE_GAP_UNITS,
+  ERROR_STATE_MIN_HEIGHT,
+  ERROR_STATE_PADDING_UNITS,
+  ERROR_TEXT_GAP_UNITS,
+  RETRY_MARGIN_TOP_UNITS,
+  RETRY_MIN_WIDTH,
+} from './ErrorState.metrics';
 import type { ErrorStateProps, ErrorStateSeverity } from './ErrorState.types';
+import { resolveTestId } from '../../../platform/test-id';
 
 const makeTestId =
   (dataTestId?: string) =>
@@ -35,14 +49,14 @@ const ErrorIcon: React.FC<{
         display: 'flex',
         alignItems: 'center',
         justifyContent: 'center',
-        width: 80,
-        height: 80,
+        width: ERROR_ICON_BOX,
+        height: ERROR_ICON_BOX,
         borderRadius: '50%',
         backgroundColor: color.light,
-        opacity: 0.9,
+        opacity: ERROR_ICON_BOX_OPACITY,
       }}
     >
-      {icon || <Fallback sx={{ fontSize: 48, color: color.main }} />}
+      {icon || <Fallback sx={{ fontSize: ERROR_ICON_SIZE, color: color.main }} />}
     </Box>
   );
 };
@@ -56,7 +70,7 @@ const ErrorText: React.FC<{
   const theme = useTheme();
 
   return (
-    <Stack spacing={1} alignItems="center">
+    <Stack spacing={ERROR_TEXT_GAP_UNITS} alignItems="center">
       {title && (
         <Typography
           id={titleId}
@@ -78,8 +92,8 @@ const ErrorText: React.FC<{
         color="text.secondary"
         data-testid={testId('message')}
         sx={{
-          maxWidth: 400,
-          lineHeight: 1.6,
+          maxWidth: ERROR_MESSAGE_MAX_WIDTH,
+          lineHeight: ERROR_MESSAGE_LINE_HEIGHT,
         }}
       >
         {message}
@@ -88,8 +102,8 @@ const ErrorText: React.FC<{
   );
 };
 
-export const ErrorState: React.FC<ErrorStateProps> = React.memo(
-  ({
+export const ErrorState: React.FC<ErrorStateProps> = React.memo((props) => {
+  const {
     message,
     title,
     onRetry,
@@ -97,53 +111,54 @@ export const ErrorState: React.FC<ErrorStateProps> = React.memo(
     severity = 'error',
     icon,
     className,
-    dataTestId,
-  }) => {
-    const theme = useTheme();
-    const titleId = React.useId();
-    const testId = makeTestId(dataTestId);
+  } = props;
+  const theme = useTheme();
+  const titleId = React.useId();
+  // `dataTestId` is the documented spelling; `testID`, the shared contract's
+  // other one, resolves to the same id.
+  const dataTestId = resolveTestId(props);
+  const testId = makeTestId(dataTestId);
 
-    return (
-      <Box
-        role="alert"
-        aria-labelledby={title ? titleId : undefined}
-        aria-describedby={`${titleId}-message`}
-        className={className}
-        data-testid={dataTestId || 'error-state'}
-        sx={{
-          display: 'flex',
-          flexDirection: 'column',
-          alignItems: 'center',
-          justifyContent: 'center',
-          textAlign: 'center',
-          padding: theme.spacing(6),
-          minHeight: 200,
-          gap: theme.spacing(2),
-        }}
-      >
-        <ErrorIcon severity={severity} icon={icon} testId={testId('icon')} />
+  return (
+    <Box
+      role="alert"
+      aria-labelledby={title ? titleId : undefined}
+      aria-describedby={`${titleId}-message`}
+      className={className}
+      data-testid={dataTestId || 'error-state'}
+      sx={{
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        justifyContent: 'center',
+        textAlign: 'center',
+        padding: theme.spacing(ERROR_STATE_PADDING_UNITS),
+        minHeight: ERROR_STATE_MIN_HEIGHT,
+        gap: theme.spacing(ERROR_STATE_GAP_UNITS),
+      }}
+    >
+      <ErrorIcon severity={severity} icon={icon} testId={testId('icon')} />
 
-        <ErrorText title={title} message={message} titleId={titleId} testId={testId} />
+      <ErrorText title={title} message={message} titleId={titleId} testId={testId} />
 
-        {onRetry && (
-          <Button
-            variant="outlined"
-            color={severity}
-            onClick={onRetry}
-            startIcon={<RefreshIcon />}
-            data-testid={testId('retry-button')}
-            sx={{
-              mt: theme.spacing(1),
-              minWidth: 120,
-            }}
-          >
-            {retryLabel}
-          </Button>
-        )}
-      </Box>
-    );
-  },
-);
+      {onRetry && (
+        <Button
+          variant="outlined"
+          color={severity}
+          onClick={onRetry}
+          startIcon={<RefreshIcon />}
+          data-testid={testId('retry-button')}
+          sx={{
+            mt: theme.spacing(RETRY_MARGIN_TOP_UNITS),
+            minWidth: RETRY_MIN_WIDTH,
+          }}
+        >
+          {retryLabel}
+        </Button>
+      )}
+    </Box>
+  );
+});
 
 ErrorState.displayName = 'ErrorState';
 

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

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

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

@@ -1,45 +1,10 @@
-export type ErrorStateSeverity = 'error' | 'warning';
+import type { ErrorStateBaseProps } from './ErrorState.base';
 
-export interface ErrorStateProps {
-  /**
-   * The error message to display
-   */
-  message: string;
-
-  /**
-   * Optional title for the error state
-   */
-  title?: string;
-
-  /**
-   * Callback function when retry button is clicked
-   */
-  onRetry?: () => void;
-
-  /**
-   * Custom label for the retry button
-   * @default 'Retry'
-   */
-  retryLabel?: string;
-
-  /**
-   * Visual severity of the error
-   * @default 'error'
-   */
-  severity?: ErrorStateSeverity;
-
-  /**
-   * Optional custom icon to display
-   */
-  icon?: React.ReactNode;
+export type { ErrorStateBaseProps, ErrorStateSeverity } from './ErrorState.base';
 
+export interface ErrorStateProps extends ErrorStateBaseProps {
   /**
    * Custom className for the container
    */
   className?: string;
-
-  /**
-   * Test ID for component testing
-   */
-  dataTestId?: string;
 }

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

@@ -0,0 +1,6 @@
+# ErrorState on React Native
+
+Known rendering gaps, one bullet each; `pnpm native:ledger` reads them.
+
+- The retry is the house `Button` (outline, `sm`) sized to MUI's medium outlined button — same 5px/15px padding, 14px type, radius, 20px icon and 120px floor; MUI additionally uppercases the label, draws its border at `alpha(main, 0.5)`, and sets the icon 8px from the label where the house button sets 4.
+- Title and message are set in MUI's default `h6`/`body2` numbers; a host that re-themes MUI's typography variants moves the web only.

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

@@ -0,0 +1,2 @@
+export { ErrorState } from './ErrorState.native';
+export type { ErrorStateBaseProps, ErrorStateProps, ErrorStateSeverity } from './ErrorState.types.native';

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

@@ -1,2 +1,2 @@
 export { ErrorState } from './ErrorState';
-export type { ErrorStateProps, ErrorStateSeverity } from './ErrorState.types';
+export type { ErrorStateBaseProps, ErrorStateProps, ErrorStateSeverity } from './ErrorState.types';

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

@@ -0,0 +1,43 @@
+import type { SizeValue } from '../../../tokens/vocabulary';
+
+/**
+ * THE CONTRACT BOTH RENDERERS HONOUR — and nothing else.
+ *
+ * Imports no MUI and no react-native, on purpose: it ships in both
+ * declaration outputs. The web adds `className`; the native side adds a
+ * `View`'s own props in `LoadingState.types.native.ts`.
+ */
+export type LoadingStateVariant = 'spinner' | 'skeleton';
+export type LoadingStateSize = SizeValue;
+
+export interface LoadingStateBaseProps {
+  /**
+   * 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;
+
+  /**
+   * Test ID for component testing
+   */
+  dataTestId?: string;
+
+  testID?: string;
+}

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

@@ -1,30 +1,27 @@
-import type { LoadingStateProps, LoadingStateSize } from './LoadingState.types';
-
-export const SIZE_MAP: Record<
-  LoadingStateSize,
-  { spinner: number; text: 'body2' | 'body1' | 'h6' }
-> = {
-  xs: { spinner: 16, text: 'body2' },
-  sm: { spinner: 24, text: 'body2' },
-  md: { spinner: 40, text: 'body1' },
-  lg: { spinner: 56, text: 'h6' },
-  xl: { spinner: 64, text: 'h6' },
-};
+import type { LoadingStateBaseProps, LoadingStateSize } from './LoadingState.base';
+import { MESSAGE_TYPE, SKELETON_ROW_HEIGHT, SPINNER_SIZES } from './LoadingState.metrics';
+import type { MuiTypeVariantName } from '../../../tokens/mui-type';
+import { SIZE_VALUES } from '../../../tokens/vocabulary';
 
-export const SKELETON_ROW_HEIGHT: Record<LoadingStateSize, number> = {
-  xs: 14,
-  sm: 20,
-  md: 28,
-  lg: 36,
-  xl: 44,
-};
+export { SKELETON_ROW_HEIGHT };
+
+// Derived from the shared metrics, not restated: the native `LoadingState`
+// reads the same two tables, so the renderers cannot disagree on a size.
+export const SIZE_MAP: Record<LoadingStateSize, { spinner: number; text: MuiTypeVariantName }> =
+  Object.fromEntries(
+    SIZE_VALUES.map((size) => [size, { spinner: SPINNER_SIZES[size], text: MESSAGE_TYPE[size] }]),
+  ) as Record<LoadingStateSize, { spinner: number; text: MuiTypeVariantName }>;
 
 type LoadingStateDefaultedKeys = 'variant' | 'size' | 'skeletonRows';
 
-type ResolvedLoadingStateProps = LoadingStateProps &
-  Required<Pick<LoadingStateProps, LoadingStateDefaultedKeys>>;
+/**
+ * Generic over the renderer's own props: the web and the native `LoadingState`
+ * pass different extras through, and both come back out untouched.
+ */
+type ResolvedLoadingStateProps<P extends LoadingStateBaseProps> = P &
+  Required<Pick<LoadingStateBaseProps, LoadingStateDefaultedKeys>>;
 
-const LOADING_STATE_DEFAULTS: Pick<LoadingStateProps, LoadingStateDefaultedKeys> = {
+const LOADING_STATE_DEFAULTS: Required<Pick<LoadingStateBaseProps, LoadingStateDefaultedKeys>> = {
   variant: 'spinner',
   size: 'md',
   skeletonRows: 3,
@@ -32,15 +29,15 @@ const LOADING_STATE_DEFAULTS: Pick<LoadingStateProps, LoadingStateDefaultedKeys>
 
 // 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: LoadingStateProps): Partial<LoadingStateProps> =>
+const definedProps = <P extends LoadingStateBaseProps>(props: P): Partial<P> =>
   Object.fromEntries(
     Object.entries(props).filter(([, value]) => value !== undefined),
-  ) as Partial<LoadingStateProps>;
+  ) as Partial<P>;
 
-export const resolveLoadingStateProps = (
-  props: LoadingStateProps,
-): ResolvedLoadingStateProps =>
-  ({ ...LOADING_STATE_DEFAULTS, ...definedProps(props) }) as ResolvedLoadingStateProps;
+export const resolveLoadingStateProps = <P extends LoadingStateBaseProps>(
+  props: P,
+): ResolvedLoadingStateProps<P> =>
+  ({ ...LOADING_STATE_DEFAULTS, ...definedProps(props) }) as ResolvedLoadingStateProps<P>;
 
 /**
  * Test ids come in three flavours here: the container falls back to a bare
@@ -54,3 +51,5 @@ export const makeTestIds = (dataTestId?: string) => ({
   named: (suffix: string): string =>
     dataTestId ? `${dataTestId}-${suffix}` : `loading-state-${suffix}`,
 });
+
+export type LoadingStateTestIds = ReturnType<typeof makeTestIds>;

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

@@ -0,0 +1,67 @@
+import type { MuiTypeVariantName } from '../../../tokens/mui-type';
+import type { SizeValue } from '../../../tokens/vocabulary';
+
+/**
+ * THE NUMBERS BOTH `LoadingState` RENDERERS DRAW WITH.
+ *
+ * `LoadingState.tsx` (MUI) and `LoadingState.native.tsx` (React Native) read
+ * this one table. Spacing is in SPACING UNITS where the web writes
+ * `theme.spacing(n)`, so a host with a different unit moves both renderers;
+ * everything else is px.
+ */
+
+/** MUI's `CircularProgress` diameter per size. */
+export const SPINNER_SIZES: Record<SizeValue, number> = {
+  xs: 16,
+  sm: 24,
+  md: 40,
+  lg: 56,
+  xl: 64,
+};
+
+/** The MUI `Typography` variant the message is set in, per size. */
+export const MESSAGE_TYPE: Record<SizeValue, MuiTypeVariantName> = {
+  xs: 'body2',
+  sm: 'body2',
+  md: 'body1',
+  lg: 'h6',
+  xl: 'h6',
+};
+
+export const SKELETON_ROW_HEIGHT: Record<SizeValue, number> = {
+  xs: 14,
+  sm: 20,
+  md: 28,
+  lg: 36,
+  xl: 44,
+};
+
+/** The spinner view: a centred column, `theme.spacing(6)` of padding, at least 200px tall. */
+export const SPINNER_PADDING_UNITS = 6;
+export const SPINNER_MIN_HEIGHT = 200;
+/** Between the spinner and its message. */
+export const SPINNER_GAP_UNITS = 2;
+
+/** The skeleton view: full width, `theme.spacing(3)` of padding. */
+export const SKELETON_PADDING_UNITS = 3;
+/** Between rows (MUI `Stack spacing={2}`), and above the message (`mt: 2`). */
+export const SKELETON_ROW_GAP_UNITS = 2;
+export const SKELETON_MESSAGE_MARGIN_TOP_UNITS = 2;
+export const SKELETON_RADIUS = 4;
+/** The last row is short, so the block reads as a paragraph of text. */
+export const SKELETON_LAST_ROW_WIDTH = '60%';
+export const SKELETON_FULL_ROW_WIDTH = '100%';
+/**
+ * The house `Skeleton`'s `medium` intensity, which this component never
+ * overrides: `alpha(text.primary, 0.13)` in light mode, `alpha(#fff, 0.13)`
+ * in dark — and dark mode's `text.primary` IS `#fff`, so one expression
+ * covers both.
+ */
+export const SKELETON_TINT_ALPHA = 0.13;
+
+/**
+ * iOS's `ActivityIndicator` has two sizes, `small` (20pt) and `large`
+ * (36pt); a diameter from this threshold up draws `large`. Android and the
+ * web take the exact px.
+ */
+export const IOS_LARGE_SPINNER_FROM = 40;