@12-apps/ui 6.17.1 → 6.19.0

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

@@ -0,0 +1,277 @@
+import * as React from 'react';
+import {
+  Linking,
+  Platform,
+  StyleSheet,
+  Text as RNText,
+  useWindowDimensions,
+  View,
+  type TextStyle,
+  type ViewStyle,
+} from 'react-native';
+
+import { type ActionSpec, actionsOf, makeTestId } from './EmptyState.helpers';
+import {
+  ACTION_BUTTON,
+  ACTION_MIN_WIDTH,
+  ACTIONS_GAP_UNITS,
+  ACTIONS_MARGIN_TOP_UNITS,
+  ACTIONS_ROW_FROM,
+  CONTENT_GAP_UNITS,
+  DESCRIPTION_LINE_HEIGHT,
+  DESCRIPTION_MAX_WIDTH,
+  EMPTY_STATE_GAP_UNITS,
+  EMPTY_STATE_MIN_HEIGHT,
+  EMPTY_STATE_PADDING_UNITS,
+  EXTERNAL_LINK_MARK,
+  HELP_LINK_MARGIN_TOP_UNITS,
+  illustrationMaxWidth,
+  illustrationOpacity,
+  MUI_CONTAINED_SHADOW,
+  TITLE_MAX_WIDTH,
+} from './EmptyState.metrics';
+import type { EmptyStateHelpLink, EmptyStateProps, EmptyStateVariant } from './EmptyState.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 { alpha } from '../../../tokens/color';
+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';
+
+/** MUI's `h6` as an `h3`, medium weight, in the body ink, wrapping at 400px. */
+export function titleStyle(theme: UiTheme): TextStyle {
+  return {
+    ...muiTypeStyle(theme, 'h6'),
+    fontWeight: `${MUI_FONT_WEIGHT_MEDIUM}`,
+    color: theme.palette.text.primary,
+    maxWidth: TITLE_MAX_WIDTH,
+    textAlign: 'center',
+  };
+}
+
+/** MUI's `body2` on a 1.6 line height, muted, wrapping at 480px. */
+export function descriptionStyle(theme: UiTheme): TextStyle {
+  return {
+    ...muiTypeStyle(theme, 'body2'),
+    lineHeight: MUI_TYPE.body2.fontSize * DESCRIPTION_LINE_HEIGHT,
+    color: theme.palette.text.secondary,
+    maxWidth: DESCRIPTION_MAX_WIDTH,
+    textAlign: 'center',
+  };
+}
+
+/** The web `Link` inherits the page's `body1`; primary ink, no underline until hovered. */
+export function helpLinkStyle(theme: UiTheme): TextStyle {
+  return {
+    ...muiTypeStyle(theme, 'body1'),
+    color: theme.palette.primary.main,
+    textDecorationLine: 'none',
+    marginTop: theme.spacing(HELP_LINK_MARGIN_TOP_UNITS),
+    textAlign: 'center',
+  };
+}
+
+export function illustrationStyle(variant: EmptyStateVariant): ViewStyle {
+  return {
+    maxWidth: illustrationMaxWidth(variant),
+    width: '100%',
+    opacity: illustrationOpacity(variant),
+    display: variant === 'minimal' ? 'none' : 'flex',
+  };
+}
+
+/**
+ * The web actions are MUI's medium contained/outlined buttons; the house
+ * `Button` is sized to them here. The shadow needs the button's overflow
+ * visible — a view clips its own shadow otherwise.
+ */
+export function actionStyle(theme: UiTheme, variant: ActionSpec['variant']): ViewStyle {
+  const padding = ACTION_BUTTON[variant];
+  return {
+    minWidth: ACTION_MIN_WIDTH,
+    borderRadius: theme.radius.md,
+    paddingVertical: padding.paddingVertical,
+    paddingHorizontal: padding.paddingHorizontal,
+    ...(variant === 'contained'
+      ? { boxShadow: MUI_CONTAINED_SHADOW, overflow: 'visible' }
+      : { borderColor: alpha(theme.palette.primary.main, ACTION_BUTTON.outlinedBorderAlpha) }),
+  };
+}
+
+/** MUI's `sm` breakpoint decides the action row's axis: a row from 600px up, a column below. */
+export const actionsDirection = (windowWidth: number): 'row' | 'column' =>
+  windowWidth >= ACTIONS_ROW_FROM ? 'row' : 'column';
+
+/** react-native-web's anchor props for a `Text`, which React Native's `TextProps` do not declare. */
+function anchorProps(href: string, external: boolean): object {
+  if (Platform.OS !== 'web') return {};
+  return { href, hrefAttrs: external ? { target: '_blank', rel: 'noopener noreferrer' } : undefined };
+}
+
+function ActionButton({ spec, testID }: { spec: ActionSpec; testID: string }): React.JSX.Element {
+  const theme = useUiTheme();
+  const contained = spec.variant === 'contained';
+  const glyph = spec.icon ? (
+    <Icon
+      name={spec.icon}
+      size={ACTION_BUTTON.iconSize}
+      color={contained ? theme.palette.primary.contrastText : 'primary'}
+    />
+  ) : undefined;
+  return (
+    <Button
+      variant={contained ? 'solid' : 'outline'}
+      color="primary"
+      size="sm"
+      icon={glyph}
+      onClick={spec.onClick}
+      testID={testID}
+      style={actionStyle(theme, spec.variant)}
+    >
+      {spec.label}
+    </Button>
+  );
+}
+
+function Actions({ specs, testId }: { specs: ActionSpec[]; testId: (suffix: string) => string }): React.JSX.Element {
+  const theme = useUiTheme();
+  const { width } = useWindowDimensions();
+  return (
+    <View
+      style={[
+        styles.actions,
+        {
+          flexDirection: actionsDirection(width),
+          gap: theme.spacing(ACTIONS_GAP_UNITS),
+          marginTop: theme.spacing(ACTIONS_MARGIN_TOP_UNITS),
+        },
+      ]}
+    >
+      {specs.map((spec) => (
+        <ActionButton key={spec.key} spec={spec} testID={testId(spec.key)} />
+      ))}
+    </View>
+  );
+}
+
+function HelpLink({ helpLink, testId }: { helpLink: EmptyStateHelpLink; testId: string }): React.JSX.Element {
+  const theme = useUiTheme();
+  const external = helpLink.external === true;
+  // On the web the anchor navigates by itself; a device has no anchor and opens the URL.
+  const open = Platform.OS === 'web' ? undefined : () => void Linking.openURL(helpLink.href);
+  return (
+    <RNText role="link" testID={testId} style={helpLinkStyle(theme)} onPress={open} {...anchorProps(helpLink.href, external)}>
+      {helpLink.label}
+      {external ? EXTERNAL_LINK_MARK : null}
+    </RNText>
+  );
+}
+
+interface ContentProps {
+  title: string;
+  description?: string;
+  titleId: string;
+  testId: (suffix: string) => string;
+  actions: ActionSpec[];
+  showActions: boolean;
+  helpLink?: EmptyStateHelpLink;
+}
+
+function Content({ title, description, titleId, testId, actions, showActions, helpLink }: ContentProps): React.JSX.Element {
+  const theme = useUiTheme();
+  return (
+    <View style={[styles.content, { gap: theme.spacing(CONTENT_GAP_UNITS) }]}>
+      <RNText id={titleId} role="heading" {...webAria({ 'aria-level': 3 })} testID={testId('title')} style={titleStyle(theme)}>
+        {title}
+      </RNText>
+
+      {description ? (
+        <RNText testID={testId('description')} style={descriptionStyle(theme)}>
+          {description}
+        </RNText>
+      ) : null}
+
+      {showActions ? <Actions specs={actions} testId={testId} /> : null}
+
+      {helpLink ? <HelpLink helpLink={helpLink} testId={testId('help-link')} /> : null}
+    </View>
+  );
+}
+
+export const EmptyState: React.FC<EmptyStateProps> = React.memo(function EmptyState(props) {
+  const {
+    variant = 'default',
+    title,
+    description,
+    illustration,
+    helpLink,
+    refreshLabel = 'Refresh',
+    createLabel = 'Create New',
+    primaryAction: _primary,
+    secondaryAction: _secondary,
+    onCreate: _onCreate,
+    onRefresh: _onRefresh,
+    style,
+    ...others
+  } = props;
+  const theme = useUiTheme();
+  const titleId = React.useId();
+  const dataTestId = resolveTestId(others);
+  const testId = makeTestId(dataTestId);
+  const rest = withoutTestIdProps(others);
+
+  const actions = actionsOf(props, refreshLabel, createLabel);
+  // The `action` variant reserves the action row even when nothing fills it.
+  const showActions = variant === 'action' || actions.length > 0;
+
+  return (
+    <View
+      role="region"
+      aria-labelledby={titleId}
+      testID={dataTestId || 'empty-state'}
+      style={[
+        styles.root,
+        {
+          padding: theme.spacing(EMPTY_STATE_PADDING_UNITS),
+          minHeight: EMPTY_STATE_MIN_HEIGHT,
+          gap: theme.spacing(EMPTY_STATE_GAP_UNITS),
+        },
+        style,
+      ]}
+      {...rest}
+    >
+      {illustration ? (
+        <View testID={testId('icon')} style={illustrationStyle(variant)}>
+          {illustration}
+        </View>
+      ) : null}
+
+      <Content
+        title={title}
+        description={description}
+        titleId={titleId}
+        testId={testId}
+        actions={actions}
+        showActions={showActions}
+        helpLink={helpLink}
+      />
+    </View>
+  );
+});
+
+EmptyState.displayName = 'EmptyState';
+
+const styles = StyleSheet.create({
+  root: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  content: {
+    alignItems: 'center',
+  },
+  actions: {
+    alignItems: 'center',
+  },
+});

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

@@ -8,69 +8,30 @@ import Typography from '@mui/material/Typography/index.js';
 import { useTheme } from '@mui/material/styles/index.js';
 import React from 'react';
 
-import type { EmptyStateProps } from './EmptyState.types';
-
-type EmptyStateVariant = NonNullable<EmptyStateProps['variant']>;
-
-const makeTestId =
-  (dataTestId?: string) =>
-  (suffix: string): string =>
-    dataTestId ? `${dataTestId}-${suffix}` : `empty-state-${suffix}`;
-
-interface ActionSpec {
-  key: string;
-  variant: 'contained' | 'outlined';
-  onClick: () => void;
-  label: string;
-  icon?: React.ReactNode;
-}
-
-// The four buttons are one button with different props. Listing them keeps their
-// order — primary, create, secondary, refresh — visible in one place.
-const actionsOf = (
-  props: EmptyStateProps,
-  refreshLabel: string,
-  createLabel: string,
-): ActionSpec[] => {
-  const { primaryAction, secondaryAction, onCreate, onRefresh } = props;
-  const specs: ActionSpec[] = [];
-
-  if (primaryAction) {
-    specs.push({
-      key: 'primary-action',
-      variant: 'contained',
-      onClick: primaryAction.onClick,
-      label: primaryAction.label,
-    });
-  }
-  if (onCreate) {
-    specs.push({
-      key: 'create-button',
-      variant: 'contained',
-      onClick: onCreate,
-      label: createLabel,
-      icon: <AddIcon />,
-    });
-  }
-  if (secondaryAction) {
-    specs.push({
-      key: 'secondary-action',
-      variant: 'outlined',
-      onClick: secondaryAction.onClick,
-      label: secondaryAction.label,
-    });
-  }
-  if (onRefresh) {
-    specs.push({
-      key: 'refresh-button',
-      variant: 'outlined',
-      onClick: onRefresh,
-      label: refreshLabel,
-      icon: <RefreshIcon />,
-    });
-  }
-
-  return specs;
+import { type ActionIconName, type ActionSpec, actionsOf, makeTestId } from './EmptyState.helpers';
+import {
+  ACTION_MIN_WIDTH,
+  ACTIONS_GAP_UNITS,
+  ACTIONS_MARGIN_TOP_UNITS,
+  CONTENT_GAP_UNITS,
+  DESCRIPTION_LINE_HEIGHT,
+  DESCRIPTION_MAX_WIDTH,
+  EMPTY_STATE_GAP_UNITS,
+  EMPTY_STATE_MIN_HEIGHT,
+  EMPTY_STATE_PADDING_UNITS,
+  EXTERNAL_LINK_MARK,
+  HELP_LINK_MARGIN_TOP_UNITS,
+  illustrationMaxWidth,
+  illustrationOpacity,
+  TITLE_MAX_WIDTH,
+} from './EmptyState.metrics';
+import type { EmptyStateProps, EmptyStateVariant } from './EmptyState.types';
+import { resolveTestId } from '../../../platform/test-id';
+
+/** The shared action list names its glyph; the web draws it with MUI's icon. */
+const ACTION_ICONS: Record<ActionIconName, React.ReactNode> = {
+  Add: <AddIcon />,
+  Refresh: <RefreshIcon />,
 };
 
 const Illustration: React.FC<{
@@ -81,10 +42,10 @@ const Illustration: React.FC<{
   <Box
     data-testid={testId}
     sx={{
-      maxWidth: variant === 'illustrated' ? 240 : 120,
+      maxWidth: illustrationMaxWidth(variant),
       width: '100%',
       height: 'auto',
-      opacity: variant === 'minimal' ? 0.6 : 0.8,
+      opacity: illustrationOpacity(variant),
       display: variant === 'minimal' ? 'none' : 'block',
     }}
   >
@@ -101,18 +62,18 @@ const Actions: React.FC<{
   return (
     <Stack
       direction={{ xs: 'column', sm: 'row' }}
-      spacing={2}
+      spacing={ACTIONS_GAP_UNITS}
       alignItems="center"
-      sx={{ mt: theme.spacing(2) }}
+      sx={{ mt: theme.spacing(ACTIONS_MARGIN_TOP_UNITS) }}
     >
       {specs.map((spec) => (
         <Button
           key={spec.key}
           variant={spec.variant}
           onClick={spec.onClick}
-          startIcon={spec.icon}
+          startIcon={spec.icon && ACTION_ICONS[spec.icon]}
           data-testid={testId(spec.key)}
-          sx={{ minWidth: 120 }}
+          sx={{ minWidth: ACTION_MIN_WIDTH }}
         >
           {spec.label}
         </Button>
@@ -134,7 +95,7 @@ const HelpLink: React.FC<{
       rel={helpLink.external ? 'noopener noreferrer' : undefined}
       data-testid={testId}
       sx={{
-        mt: theme.spacing(1),
+        mt: theme.spacing(HELP_LINK_MARGIN_TOP_UNITS),
         color: theme.palette.primary.main,
         textDecoration: 'none',
         '&:hover': {
@@ -143,7 +104,7 @@ const HelpLink: React.FC<{
       }}
     >
       {helpLink.label}
-      {helpLink.external && ' ↗'}
+      {helpLink.external && EXTERNAL_LINK_MARK}
     </Link>
   );
 };
@@ -160,7 +121,7 @@ const Content: React.FC<{
   const theme = useTheme();
 
   return (
-    <Stack spacing={2} alignItems="center">
+    <Stack spacing={CONTENT_GAP_UNITS} alignItems="center">
       <Typography
         id={titleId}
         variant="h6"
@@ -169,7 +130,7 @@ const Content: React.FC<{
         sx={{
           fontWeight: theme.typography.fontWeightMedium,
           color: theme.palette.text.primary,
-          maxWidth: 400,
+          maxWidth: TITLE_MAX_WIDTH,
         }}
       >
         {title}
@@ -181,8 +142,8 @@ const Content: React.FC<{
           color="text.secondary"
           data-testid={testId('description')}
           sx={{
-            maxWidth: 480,
-            lineHeight: 1.6,
+            maxWidth: DESCRIPTION_MAX_WIDTH,
+            lineHeight: DESCRIPTION_LINE_HEIGHT,
           }}
         >
           {description}
@@ -206,10 +167,12 @@ export const EmptyState: React.FC<EmptyStateProps> = React.memo((props) => {
     refreshLabel = 'Refresh',
     createLabel = 'Create New',
     className,
-    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);
 
   const actions = actionsOf(props, refreshLabel, createLabel);
@@ -228,9 +191,9 @@ export const EmptyState: React.FC<EmptyStateProps> = React.memo((props) => {
         alignItems: 'center',
         justifyContent: 'center',
         textAlign: 'center',
-        padding: theme.spacing(6),
-        minHeight: 200,
-        gap: theme.spacing(3),
+        padding: theme.spacing(EMPTY_STATE_PADDING_UNITS),
+        minHeight: EMPTY_STATE_MIN_HEIGHT,
+        gap: theme.spacing(EMPTY_STATE_GAP_UNITS),
       }}
     >
       {/* Illustration */}

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

@@ -0,0 +1,16 @@
+import type { StyleProp, ViewProps, ViewStyle } from 'react-native';
+
+import type { EmptyStateBaseProps } from './EmptyState.base';
+
+export type {
+  EmptyStateAction,
+  EmptyStateBaseProps,
+  EmptyStateHelpLink,
+  EmptyStateVariant,
+} from './EmptyState.base';
+
+/** The native `EmptyState`: the shared contract, plus a `View`'s own props. */
+export type EmptyStateProps = EmptyStateBaseProps &
+  Omit<ViewProps, keyof EmptyStateBaseProps | 'style'> & {
+    style?: StyleProp<ViewStyle>;
+  };

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

@@ -1,31 +1,12 @@
-export interface EmptyStateProps {
-  variant?: 'default' | 'illustrated' | 'minimal' | 'action';
-  title: string;
-  description?: string;
-  illustration?: React.ReactNode; // SVG/Lottie/etc
-  primaryAction?: { label: string; onClick: () => void };
-  secondaryAction?: { label: string; onClick: () => void };
-  helpLink?: { label: string; href: string; external?: boolean };
-  /**
-   * Callback for the refresh button
-   * Displays a refresh button in the action area when provided
-   */
-  onRefresh?: () => void;
-  /**
-   * Custom label for the refresh button
-   * @default 'Refresh'
-   */
-  refreshLabel?: string;
-  /**
-   * Callback for the create/add new button
-   * Displays a create button in the action area when provided
-   */
-  onCreate?: () => void;
-  /**
-   * Custom label for the create button
-   * @default 'Create New'
-   */
-  createLabel?: string;
+import type { EmptyStateBaseProps } from './EmptyState.base';
+
+export type {
+  EmptyStateAction,
+  EmptyStateBaseProps,
+  EmptyStateHelpLink,
+  EmptyStateVariant,
+} from './EmptyState.base';
+
+export interface EmptyStateProps extends EmptyStateBaseProps {
   className?: string;
-  dataTestId?: string;
-}
+}

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

@@ -0,0 +1,7 @@
+# EmptyState on React Native
+
+Known rendering gaps, one bullet each; `pnpm native:ledger` reads them.
+
+- The actions are house `Button`s (solid/outline, `sm`) sized to MUI's medium contained and outlined buttons — same padding, 14px type, radius, half-alpha border, elevation-2 shadow, 20px icon and 120px floor; MUI additionally uppercases the label and sets the icon 8px from the label where the house button sets 4.
+- The help link opens through `Linking.openURL` on a device; `target`/`rel` are web-only and reach the DOM through react-native-web's anchor.
+- Title, description and link are set in MUI's default `h6`/`body2`/`body1` numbers; a host that re-themes MUI's typography variants moves the web only.

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

@@ -0,0 +1,8 @@
+export { EmptyState } from './EmptyState.native';
+export type {
+  EmptyStateAction,
+  EmptyStateBaseProps,
+  EmptyStateHelpLink,
+  EmptyStateProps,
+  EmptyStateVariant,
+} from './EmptyState.types.native';

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

@@ -1,2 +1,8 @@
 export { default, EmptyState } from './EmptyState';
-export type { EmptyStateProps } from './EmptyState.types';
+export type {
+  EmptyStateAction,
+  EmptyStateBaseProps,
+  EmptyStateHelpLink,
+  EmptyStateProps,
+  EmptyStateVariant,
+} from './EmptyState.types';

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

@@ -0,0 +1,51 @@
+import type * as React from 'react';
+
+/**
+ * THE CONTRACT BOTH RENDERERS HONOUR — and nothing else.
+ *
+ * Imports no MUI and no react-native, on purpose: it ships in both
+ * declaration outputs. `onRetry` takes no event on either side, so it lives
+ * here; the web adds `className`, the native side a `View`'s own props.
+ */
+export type ErrorStateSeverity = 'error' | 'warning';
+
+export interface ErrorStateBaseProps {
+  /**
+   * 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;
+
+  /**
+   * Test ID for component testing
+   */
+  dataTestId?: string;
+
+  testID?: string;
+}

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

@@ -0,0 +1,44 @@
+import type { ErrorStateSeverity } from './ErrorState.base';
+import type { UiPaletteColor, UiTheme } from '../../../tokens/theme';
+
+/**
+ * THE NUMBERS BOTH `ErrorState` RENDERERS DRAW WITH.
+ *
+ * `ErrorState.tsx` (MUI) and `ErrorState.native.tsx` (React Native) read this
+ * one table. Spacing is in SPACING UNITS where the web writes
+ * `theme.spacing(n)`; everything else is px or a ratio.
+ */
+
+/** The region: a centred column, `theme.spacing(6)` of padding, at least 200px tall, its parts 16px apart. */
+export const ERROR_STATE_PADDING_UNITS = 6;
+export const ERROR_STATE_MIN_HEIGHT = 200;
+export const ERROR_STATE_GAP_UNITS = 2;
+
+/** The glyph sits in an 80px disc of the severity's `light` shade at 0.9 opacity. */
+export const ERROR_ICON_BOX = 80;
+export const ERROR_ICON_BOX_OPACITY = 0.9;
+export const ERROR_ICON_SIZE = 48;
+
+/** Title and message are 8px apart; the message wraps at 400px on a 1.6 line height. */
+export const ERROR_TEXT_GAP_UNITS = 1;
+export const ERROR_MESSAGE_MAX_WIDTH = 400;
+export const ERROR_MESSAGE_LINE_HEIGHT = 1.6;
+
+/** The retry button: 8px below the text, no narrower than 120px. */
+export const RETRY_MARGIN_TOP_UNITS = 1;
+export const RETRY_MIN_WIDTH = 120;
+/**
+ * The web retry IS MUI's medium outlined `Button`: 5px 15px inside its 1px
+ * border, 14px type, the theme's radius, a 20px start icon. The native side
+ * sizes the house `Button` to these.
+ */
+export const RETRY_BUTTON = {
+  paddingVertical: 5,
+  paddingHorizontal: 15,
+  iconSize: 20,
+} as const;
+
+/** `error` is MUI's name for the `danger` slot; `warning` is its own. */
+export function errorStatePalette(theme: UiTheme, severity: ErrorStateSeverity): UiPaletteColor {
+  return severity === 'error' ? theme.palette.danger : theme.palette.warning;
+}