@12-apps/ui 6.20.0 → 6.21.0

package/src/components/form/Checkbox/Checkbox.native.tsx

@@ -0,0 +1,246 @@
+import * as React from 'react';
+import {
+  ActivityIndicator,
+  Platform,
+  Pressable,
+  StyleSheet,
+  Text as RNText,
+  View,
+  type GestureResponderEvent,
+  type TextStyle,
+  type ViewStyle,
+} from 'react-native';
+
+import { makeTestId, resolveCheckboxProps } from './Checkbox.helpers';
+import {
+  CHECKBOX_GLOW,
+  CHECKBOX_GLYPH,
+  CHECKBOX_HELPER,
+  CHECKBOX_LABEL,
+  CHECKBOX_PADDING,
+  CHECKBOX_SPINNER,
+  CHECKBOX_VARIANT,
+  effectInk,
+  glyphSize,
+} from './Checkbox.metrics';
+import type { CheckboxProps } from './Checkbox.types.native';
+import { Icon } from '../../../icons/Icon.native';
+import type { IconName } from '../../../icons/Icon.types';
+import { webKeyDown } from '../../../platform/aria';
+import { resolveTestId, withoutTestIdProps } from '../../../platform/test-id';
+import { useUiTheme } from '../../../provider/use-ui-theme.native';
+import { alpha } from '../../../tokens/color';
+import type { UiTheme } from '../../../tokens/theme';
+
+/** Which of MUI's three glyphs the box is in right now. */
+function glyphFor(checked: boolean, indeterminate: boolean): IconName {
+  if (indeterminate) return CHECKBOX_GLYPH.indeterminate;
+  return checked ? CHECKBOX_GLYPH.checked : CHECKBOX_GLYPH.unchecked;
+}
+
+/**
+ * The ink the box is drawn in.
+ *
+ * MUI's own rule paints a checked box in `palette[color].main`, but
+ * `Checkbox.tsx` overrides `.Mui-checked` with `primary.main` and wins on
+ * source order — so every colour checks blue on the web, and here too.
+ */
+function glyphInk(theme: UiTheme, checked: boolean, indeterminate: boolean, disabled: boolean): string {
+  if (disabled) return theme.palette.action.disabled;
+  if (checked || indeterminate) return theme.palette.primary.main;
+  return theme.palette.text.secondary;
+}
+
+/** `glow` as a shadow; the web breathes it between two blurs, which needs keyframes. */
+function glowStyle(): ViewStyle {
+  return Platform.select<ViewStyle>({
+    android: { elevation: CHECKBOX_GLOW.blur.to / 2 },
+    default: {
+      shadowColor: effectInk(1),
+      shadowOpacity: CHECKBOX_GLOW.alpha.from,
+      shadowRadius: CHECKBOX_GLOW.blur.from,
+      shadowOffset: { width: 0, height: 0 },
+    },
+  });
+}
+
+/** The `rounded` and `toggle` variants' corner and scale, on the glyph's own box. */
+function variantStyle(variant: keyof typeof CHECKBOX_VARIANT, size: number): ViewStyle {
+  const treatment = CHECKBOX_VARIANT[variant];
+  if (treatment.radius === undefined) return {};
+  return {
+    overflow: 'hidden',
+    borderRadius: typeof treatment.radius === 'number' ? treatment.radius : size / 2,
+    ...(treatment.scale === undefined ? {} : { transform: [{ scale: treatment.scale }] }),
+  };
+}
+
+interface BoxProps {
+  boxRef: React.ForwardedRef<View>;
+  testID: string;
+  checked: boolean;
+  indeterminate: boolean;
+  inactive: boolean;
+  loading: boolean;
+  glow: boolean;
+  ripple: boolean;
+  variant: keyof typeof CHECKBOX_VARIANT;
+  size: number;
+  label?: string;
+  onToggle: (event?: GestureResponderEvent) => void;
+  rest: Record<string, unknown>;
+}
+
+/** The box itself: MUI's glyph inside `SwitchBase`'s 9px of padding. */
+function CheckboxBox(props: BoxProps): React.JSX.Element {
+  const theme = useUiTheme();
+  const { checked, indeterminate, inactive, size, variant } = props;
+  const ink = glyphInk(theme, checked, indeterminate, inactive);
+
+  return (
+    <Pressable
+      ref={props.boxRef}
+      testID={props.testID}
+      role="checkbox"
+      aria-checked={indeterminate ? 'mixed' : checked}
+      aria-disabled={inactive}
+      aria-label={props.label}
+      disabled={inactive}
+      onPress={props.onToggle}
+      android_ripple={
+        props.ripple && !inactive
+          ? { color: alpha(theme.palette.primary.main, 0.2), borderless: true }
+          : undefined
+      }
+      {...webKeyDown((event) => {
+        if (event.key === ' ' || event.key === 'Spacebar') props.onToggle();
+      })}
+      style={[styles.box, props.glow ? glowStyle() : null]}
+      {...props.rest}
+    >
+      <View style={variantStyle(variant, size)}>
+        <Icon name={glyphFor(checked, indeterminate)} size={size} color={ink} />
+      </View>
+      {props.loading ? (
+        <ActivityIndicator
+          style={styles.spinner}
+          size={CHECKBOX_SPINNER.size}
+          color={theme.palette.primary.main}
+          accessibilityLabel="loading"
+        />
+      ) : null}
+    </Pressable>
+  );
+}
+
+/** MUI's `FormControlLabel` label, in `body2` and the error hue when it errs. */
+function labelStyle(theme: UiTheme, error: boolean): TextStyle {
+  return {
+    color: error ? theme.palette.danger.main : theme.palette.text.primary,
+    fontFamily: theme.typography.fontFamily,
+    fontSize: CHECKBOX_LABEL.fontSize,
+    marginLeft: CHECKBOX_LABEL.marginLeft,
+  };
+}
+
+/** `FormHelperText`, four spacing units in and half a unit down. */
+function helperStyle(theme: UiTheme, error: boolean): TextStyle {
+  return {
+    color: error ? theme.palette.danger.main : theme.palette.text.secondary,
+    fontFamily: theme.typography.fontFamily,
+    fontSize: CHECKBOX_HELPER.fontSize,
+    lineHeight: CHECKBOX_HELPER.fontSize * CHECKBOX_HELPER.lineHeight,
+    marginLeft: theme.spacing(CHECKBOX_HELPER.marginLeftUnits),
+    marginTop: theme.spacing(CHECKBOX_HELPER.marginTopUnits),
+  };
+}
+
+/**
+ * The native `Checkbox`.
+ *
+ * The box is the glyph MUI's own `Checkbox` draws — `@12-apps/ui/icons`
+ * generates its path from the same `@mui/icons-material` — inside
+ * `SwitchBase`'s 9px of padding, under a pressable carrying `role="checkbox"`
+ * and `aria-checked`: the state the web's hidden `<input type="checkbox">`
+ * carries. See `NATIVE-NOTES.md`.
+ */
+export const Checkbox = React.forwardRef<View, CheckboxProps>((rawProps, ref) => {
+  const {
+    variant, label, error, helperText, loading, ripple, glow, pulse: _pulse,
+    indeterminate, disabled, size, checked, defaultChecked,
+    onChange, onClick, onPress, style, ...others
+  } = resolveCheckboxProps(rawProps);
+
+  const theme = useUiTheme();
+  // `Boolean()` rather than a destructuring default for each: every `= false`
+  // is a branch, and there are enough of them here to cost the size gate.
+  const [own, setOwn] = React.useState(Boolean(defaultChecked));
+  const current = checked ?? own;
+  const inactive = Boolean(disabled) || Boolean(loading);
+  const testId = makeTestId(resolveTestId(others));
+
+  const toggle = (event?: GestureResponderEvent): void => {
+    const next = !current;
+    setOwn(next);
+    onChange?.({ target: { checked: next } }, next);
+    if (event === undefined) return;
+    onClick?.(event);
+    onPress?.(event);
+  };
+
+  const box = (
+    <CheckboxBox
+      boxRef={ref}
+      testID={resolveTestId(others, 'checkbox') ?? 'checkbox'}
+      checked={current}
+      indeterminate={Boolean(indeterminate)}
+      inactive={inactive}
+      loading={Boolean(loading)}
+      glow={glow}
+      ripple={ripple}
+      variant={variant}
+      size={glyphSize(size)}
+      label={label}
+      onToggle={toggle}
+      rest={withoutTestIdProps(others) as Record<string, unknown>}
+    />
+  );
+
+  if (label === undefined) return box;
+
+  return (
+    <View testID={testId('container')} style={style}>
+      <View style={styles.row}>
+        {box}
+        <RNText style={labelStyle(theme, Boolean(error))}>{label}</RNText>
+      </View>
+      {helperText === undefined ? null : (
+        <RNText testID={testId('helper')} style={helperStyle(theme, Boolean(error))}>
+          {helperText}
+        </RNText>
+      )}
+    </View>
+  );
+});
+
+Checkbox.displayName = 'Checkbox';
+
+const styles = StyleSheet.create({
+  box: {
+    padding: CHECKBOX_PADDING,
+    alignItems: 'center',
+    justifyContent: 'center',
+    position: 'relative',
+  },
+  row: {
+    flexDirection: 'row',
+    alignItems: 'center',
+  },
+  spinner: {
+    position: 'absolute',
+    top: '50%',
+    left: '50%',
+    marginTop: CHECKBOX_SPINNER.offset,
+    marginLeft: CHECKBOX_SPINNER.offset,
+  },
+});

package/src/components/form/Checkbox/Checkbox.tsx

@@ -6,26 +6,39 @@ import { alpha, keyframes, styled } from '@mui/material/styles/index.js';
 import React from 'react';
 
 import { makeTestId, resolveCheckboxProps } from './Checkbox.helpers';
+import {
+  CHECKBOX_GLOW,
+  CHECKBOX_HELPER,
+  CHECKBOX_HOVER_ALPHA,
+  CHECKBOX_LABEL,
+  CHECKBOX_PULSE,
+  CHECKBOX_SPINNER,
+  CHECKBOX_TRANSITION_MS,
+  CHECKBOX_VARIANT,
+  effectInk,
+} from './Checkbox.metrics';
 import type { CheckboxProps } from './Checkbox.types';
+import { splitTestId } from '../../../platform/test-id';
+import { px } from '../../../tokens/theme';
 
 const pulse = keyframes`
   0% {
-    box-shadow: 0 0 0 0 rgba(25, 118, 210, 0.7);
+    box-shadow: 0 0 0 0 ${effectInk(CHECKBOX_PULSE.alpha)};
   }
   70% {
-    box-shadow: 0 0 0 10px rgba(25, 118, 210, 0);
+    box-shadow: 0 0 0 ${CHECKBOX_PULSE.spread}px ${effectInk(0)};
   }
   100% {
-    box-shadow: 0 0 0 0 rgba(25, 118, 210, 0);
+    box-shadow: 0 0 0 0 ${effectInk(0)};
   }
 `;
 
 const glow = keyframes`
   0%, 100% {
-    box-shadow: 0 0 5px rgba(25, 118, 210, 0.5);
+    box-shadow: 0 0 ${CHECKBOX_GLOW.blur.from}px ${effectInk(CHECKBOX_GLOW.alpha.from)};
   }
   50% {
-    box-shadow: 0 0 20px rgba(25, 118, 210, 0.8);
+    box-shadow: 0 0 ${CHECKBOX_GLOW.blur.to}px ${effectInk(CHECKBOX_GLOW.alpha.to)};
   }
 `;
 
@@ -40,32 +53,32 @@ const StyledCheckbox = styled(MuiCheckbox, {
   ({ theme, customVariant, ripple, glow: glowProp, pulse: pulseProp }) => ({
     ...(customVariant === 'rounded' && {
       '& .MuiSvgIcon-root': {
-        borderRadius: '50%',
+        borderRadius: CHECKBOX_VARIANT.rounded.radius,
       },
     }),
     
     ...(customVariant === 'toggle' && {
       '& .MuiSvgIcon-root': {
-        borderRadius: '12px',
-        transform: 'scale(1.2)',
+        borderRadius: `${CHECKBOX_VARIANT.toggle.radius}px`,
+        transform: `scale(${CHECKBOX_VARIANT.toggle.scale})`,
       },
     }),
     
     '&.MuiCheckbox-root': {
-      transition: 'all 0.3s ease',
+      transition: `all ${CHECKBOX_TRANSITION_MS / 1000}s ease`,
       ...(ripple === false && {
         '& .MuiTouchRipple-root': {
           display: 'none',
         },
       }),
       ...(glowProp && {
-        animation: `${glow} 2s ease-in-out infinite`,
+        animation: `${glow} ${CHECKBOX_GLOW.ms / 1000}s ease-in-out infinite`,
       }),
       ...(pulseProp && {
-        animation: `${pulse} 2s infinite`,
+        animation: `${pulse} ${CHECKBOX_PULSE.ms / 1000}s infinite`,
       }),
       '&:hover': {
-        backgroundColor: alpha(theme.palette.primary.main, 0.1),
+        backgroundColor: alpha(theme.palette.primary.main, CHECKBOX_HOVER_ALPHA),
       },
     },
     
@@ -83,17 +96,17 @@ const StyledFormControlLabel = styled(FormControlLabel, {
   shouldForwardProp: (prop) => prop !== 'error',
 })<{ error?: boolean }>(
   ({ theme, error }) => ({
-    marginLeft: 0,
+    marginLeft: CHECKBOX_LABEL.marginLeft,
     '& .MuiFormControlLabel-label': {
       color: error ? theme.palette.error.main : theme.palette.text.primary,
-      fontSize: '0.875rem',
+      fontSize: px(CHECKBOX_LABEL.fontSize),
     },
   })
 );
 
 const StyledFormHelperText = styled(FormHelperText)(({ theme }) => ({
-  marginLeft: theme.spacing(4),
-  marginTop: theme.spacing(0.5),
+  marginLeft: theme.spacing(CHECKBOX_HELPER.marginLeftUnits),
+  marginTop: theme.spacing(CHECKBOX_HELPER.marginTopUnits),
 }));
 
 export const Checkbox = React.forwardRef<HTMLButtonElement, CheckboxProps>(
@@ -108,10 +121,10 @@ export const Checkbox = React.forwardRef<HTMLButtonElement, CheckboxProps>(
       glow,
       pulse,
       disabled,
-      'data-testid': dataTestId,
-      ...props
+      ...others
     } = resolveCheckboxProps(rawProps);
     const isDisabled = disabled || loading;
+    const { testId: dataTestId, rest: props } = splitTestId(others);
     const testId = makeTestId(dataTestId);
 
     const checkbox = (
@@ -128,13 +141,13 @@ export const Checkbox = React.forwardRef<HTMLButtonElement, CheckboxProps>(
         />
         {loading && (
           <CircularProgress
-            size={20}
+            size={CHECKBOX_SPINNER.size}
             sx={{
               position: 'absolute',
               top: '50%',
               left: '50%',
-              marginTop: '-10px',
-              marginLeft: '-10px',
+              marginTop: `${CHECKBOX_SPINNER.offset}px`,
+              marginLeft: `${CHECKBOX_SPINNER.offset}px`,
               color: 'primary.main',
             }}
           />

package/src/components/form/Checkbox/Checkbox.types.native.ts

@@ -0,0 +1,29 @@
+import type { GestureResponderEvent, StyleProp, ViewProps, ViewStyle } from 'react-native';
+
+import type { CheckboxBaseProps } from './Checkbox.base';
+import type { CheckboxSize } from './Checkbox.metrics';
+
+export type { CheckboxBaseProps, CheckboxVariant } from './Checkbox.base';
+export type { CheckboxSize } from './Checkbox.metrics';
+
+/**
+ * The change a native `Checkbox` reports: the `{ target: { checked } }` shape
+ * MUI's `ChangeEvent` gives, and the resolved flag second, as MUI passes it.
+ */
+export interface CheckboxChangeEvent {
+  target: { checked: boolean };
+}
+
+/** The native `Checkbox`: the shared contract, plus a `View`'s own props. */
+export type CheckboxProps = CheckboxBaseProps &
+  Omit<ViewProps, keyof CheckboxBaseProps | 'style'> & {
+    checked?: boolean;
+    defaultChecked?: boolean;
+    /** MUI's own words for the glyph's size, which is what this component takes. */
+    size?: CheckboxSize;
+    onChange?: (event: CheckboxChangeEvent, checked: boolean) => void;
+    /** Both spellings fire, as `Button`'s do. */
+    onClick?: (event: GestureResponderEvent) => void;
+    onPress?: (event: GestureResponderEvent) => void;
+    style?: StyleProp<ViewStyle>;
+  };

package/src/components/form/Checkbox/Checkbox.types.ts

@@ -1,17 +1,18 @@
 import type { CheckboxProps as MuiCheckboxProps } from '@mui/material/Checkbox/index.js';
-import type { ChangeEvent, FocusEventHandler,MouseEventHandler } from 'react';
+import type { ChangeEvent, FocusEventHandler, MouseEventHandler } from 'react';
 
-export type CheckboxVariant = 'default' | 'rounded' | 'toggle';
+import type { CheckboxBaseProps } from './Checkbox.base';
 
-export interface CheckboxProps extends Omit<MuiCheckboxProps, 'variant'> {
-  variant?: CheckboxVariant;
-  label?: string;
-  error?: boolean;
-  helperText?: string;
-  loading?: boolean;
-  ripple?: boolean;
-  glow?: boolean;
-  pulse?: boolean;
+export type { CheckboxBaseProps, CheckboxVariant } from './Checkbox.base';
+
+/**
+ * The web `Checkbox`: the shared contract, plus everything MUI's `Checkbox`
+ * accepts that the contract does not already name — `checked`,
+ * `defaultChecked`, `size`, `color`, `icon`, `inputProps`, `sx`.
+ */
+export interface CheckboxProps
+  extends CheckboxBaseProps,
+    Omit<MuiCheckboxProps, 'variant' | keyof CheckboxBaseProps> {
   'data-testid'?: string;
   onClick?: MouseEventHandler<HTMLButtonElement>;
   onFocus?: FocusEventHandler<HTMLButtonElement>;

package/src/components/form/Checkbox/NATIVE-NOTES.md

@@ -0,0 +1,11 @@
+# Checkbox on React Native
+
+Known rendering gaps, one bullet each; `pnpm native:ledger` reads them.
+
+- The control is a pressable carrying `role="checkbox"` and `aria-checked` — the state the web's hidden `<input type="checkbox">` announces — rather than a real form element. So it is a tab stop and a screen reader reads it correctly, but the `disabled` ATTRIBUTE a DOM assertion like `toBeDisabled()` looks for is `aria-disabled` here.
+- The box itself IS MUI's glyph: `@12-apps/ui/icons` generates `CheckBox`, `CheckBoxOutlineBlank` and `IndeterminateCheckBox` from the same `@mui/icons-material` package MUI's own `Checkbox` imports them from.
+- `glow` is a static shadow of MUI's default blue rather than one breathing between a 5px and a 20px blur, and `pulse` — an expanding ring drawn with `box-shadow` spread — is not drawn at all: React Native has neither keyframes on a shadow nor shadow spread.
+- Hover has no touch equivalent, so the 0.1 wash the web puts behind a hovered box is not drawn; `ripple` becomes Android's own ripple and is nothing on iOS.
+- `rounded` and `toggle` clip and scale the glyph's own box, as the web does — which on a transparent glyph shows only where the box would have clipped it. The web's `borderRadius` on an `<svg>` is the same near-invisible change.
+- Both renderers check in `primary.main` whatever `color` says: `Checkbox.tsx` overrides MUI's per-colour rule with primary and wins on source order. Fixing that is a web change.
+- The label and the helper text are set in MUI's own numbers (`body2` at 14px, `caption` at 12px, four spacing units of helper inset); a host that re-themes MUI's typography moves the web only.

package/src/components/form/Checkbox/index.native.ts

@@ -0,0 +1,8 @@
+export { Checkbox } from './Checkbox.native';
+export type {
+  CheckboxBaseProps,
+  CheckboxChangeEvent,
+  CheckboxProps,
+  CheckboxSize,
+  CheckboxVariant,
+} from './Checkbox.types.native';

package/src/components/form/Checkbox/index.ts

@@ -1,2 +1,2 @@
 export { Checkbox } from './Checkbox';
-export type { CheckboxProps, CheckboxVariant } from './Checkbox.types';
+export type { CheckboxBaseProps, CheckboxProps, CheckboxVariant } from './Checkbox.types';

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

@@ -0,0 +1,84 @@
+import type { HTMLInputTypeAttribute, ReactNode } from 'react';
+
+import type { SizeValue } from '../../../tokens/vocabulary';
+
+/**
+ * THE CONTRACT BOTH RENDERERS HONOUR — and nothing else.
+ *
+ * No MUI and no react-native here on purpose: this file 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. See `Button.base.ts`.
+ */
+export type InputVariant = 'outlined' | 'filled' | 'glass' | 'underline' | 'gradient';
+export type InputSize = SizeValue;
+
+/**
+ * The contract both renderers honour.
+ *
+ * `value`, `defaultValue` and the handlers are NOT here. Their NAMES are the
+ * same on both sides, but a web `value` is `string | number | readonly
+ * string[]` and a native one is a `string`, so each side inherits its own from
+ * the element it wraps — the same rule `Button.base.ts` applies to `onClick`.
+ *
+ * `type` keeps the full `HTMLInputTypeAttribute` union rather than the seven
+ * kinds a native field can honour: narrowing it would reject the `type="date"`
+ * and `type="time"` call sites the web already has (FUT-729). A native `Input`
+ * maps `text`, `search`, `email`, `tel`, `url`, `number` and `password` onto
+ * the keyboard and secure-entry props and treats every other type as text.
+ */
+export interface InputBaseProps {
+  /** The visual variant of the field. */
+  variant?: InputVariant;
+
+  /** A step of the house size scale. */
+  size?: InputSize;
+
+  /** What the field collects; on native it picks the keyboard and secure entry. */
+  type?: HTMLInputTypeAttribute;
+
+  /** The label above (native) or inside (web) the field. */
+  label?: string;
+
+  placeholder?: string;
+
+  /** Paints the field, the label and the helper text in the danger hue. */
+  error?: boolean;
+
+  /** The line under the field: the error message, or a hint. */
+  helperText?: string;
+
+  /** Content before the value — an icon, a currency symbol. */
+  startAdornment?: ReactNode;
+
+  /** Content after the value. Replaced by the spinner while `loading`. */
+  endAdornment?: ReactNode;
+
+  /** Stretch to the width of the parent. Defaults to true, as MUI's does not. */
+  fullWidth?: boolean;
+
+  /** The label animates into the border rather than sitting over the field. */
+  floating?: boolean;
+
+  /** A halo of the primary hue around the field, stronger while focused. */
+  glow?: boolean;
+
+  /** A bar behind the field that pulses outward every two seconds. */
+  pulse?: boolean;
+
+  /** Fades the field, makes it inert and puts a spinner where the end adornment goes. */
+  loading?: boolean;
+
+  disabled?: boolean;
+
+  readOnly?: boolean;
+
+  required?: boolean;
+
+  autoFocus?: boolean;
+
+  maxLength?: number;
+
+  testID?: string;
+
+  dataTestId?: string;
+}

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

@@ -0,0 +1,43 @@
+import type { InputBaseProps } from './Input.base';
+import { withDefaults } from '../../../utils/withDefaults';
+
+type InputDefaultedKeys =
+  | 'variant'
+  | 'size'
+  | 'error'
+  | 'fullWidth'
+  | 'floating'
+  | 'glow'
+  | 'pulse'
+  | 'loading'
+  | 'disabled'
+  | 'required';
+
+/**
+ * Generic over the renderer's own props, as `resolveButtonProps` is: the web
+ * and the native `Input` pass different handler and `value` types through, and
+ * both come back out untouched.
+ */
+export type ResolvedInputProps<P extends InputBaseProps> = P &
+  Required<Pick<InputBaseProps, InputDefaultedKeys>>;
+
+/**
+ * The defaults the web `Input` declares in its destructuring. `fullWidth` is
+ * true here and false in MUI: a field in this package fills its column unless
+ * it is told not to.
+ */
+const INPUT_DEFAULTS: Required<Pick<InputBaseProps, InputDefaultedKeys>> = {
+  variant: 'outlined',
+  size: 'md',
+  error: false,
+  fullWidth: true,
+  floating: false,
+  glow: false,
+  pulse: false,
+  loading: false,
+  disabled: false,
+  required: false,
+};
+
+export const resolveInputProps = <P extends InputBaseProps>(props: P): ResolvedInputProps<P> =>
+  withDefaults(props, INPUT_DEFAULTS as Partial<P>) as ResolvedInputProps<P>;