@12-apps/ui 6.20.0 → 6.22.0

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

@@ -0,0 +1,36 @@
+/**
+ * THE CONTRACT BOTH RENDERERS HONOUR — and nothing else.
+ *
+ * No MUI and no react-native here: this file is in BOTH declaration outputs,
+ * and a native consumer has no `@mui/material` to resolve a type import
+ * against. See `Button.base.ts`.
+ */
+export type CheckboxVariant = 'default' | 'rounded' | 'toggle';
+
+/**
+ * The contract both renderers honour.
+ *
+ * `checked`, `defaultChecked` and `onChange` are NOT here: MUI types the change
+ * as a DOM `ChangeEvent` and the native side synthesises the
+ * `{ target: { checked } }` shape those handlers already read. Neither is
+ * `size`, which this component takes in MUI's own words (`small | medium`)
+ * rather than the house scale — narrowing it would reject the callers it has.
+ */
+export interface CheckboxBaseProps {
+  variant?: CheckboxVariant;
+  label?: string;
+  /** Paints the label and the helper text in the danger hue. */
+  error?: boolean;
+  helperText?: string;
+  /** Fades the box, makes it inert and turns a spinner over it. */
+  loading?: boolean;
+  /** The touch ripple. `false` removes it. */
+  ripple?: boolean;
+  glow?: boolean;
+  pulse?: boolean;
+  /** The third state: neither checked nor unchecked, drawn as a dash. */
+  indeterminate?: boolean;
+  disabled?: boolean;
+  testID?: string;
+  dataTestId?: string;
+}

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

@@ -1,27 +1,27 @@
-import type { CheckboxProps } from './Checkbox.types';
+import type { CheckboxBaseProps } from './Checkbox.base';
+import { withDefaults } from '../../../utils/withDefaults';
 
 type CheckboxDefaultedKeys = 'variant' | 'ripple' | 'glow' | 'pulse';
 
-type ResolvedCheckboxProps = CheckboxProps &
-  Required<Pick<CheckboxProps, CheckboxDefaultedKeys>>;
+/**
+ * Generic over the renderer's own props, as `resolveButtonProps` is: the web
+ * and the native `Checkbox` pass different handler types through, and both come
+ * back out untouched.
+ */
+export type ResolvedCheckboxProps<P extends CheckboxBaseProps = CheckboxBaseProps> = P &
+  Required<Pick<CheckboxBaseProps, CheckboxDefaultedKeys>>;
 
-const CHECKBOX_DEFAULTS: Pick<CheckboxProps, CheckboxDefaultedKeys> = {
+const CHECKBOX_DEFAULTS: Required<Pick<CheckboxBaseProps, CheckboxDefaultedKeys>> = {
   variant: 'default',
   ripple: true,
   glow: false,
   pulse: false,
 };
 
-// Strips explicitly-undefined props before the merge, so `ripple={undefined}` still
-// falls back to the default exactly as a destructuring default would.
-const definedProps = (props: CheckboxProps): Partial<CheckboxProps> =>
-  Object.fromEntries(
-    Object.entries(props).filter(([, value]) => value !== undefined),
-  ) as Partial<CheckboxProps>;
-
-export const resolveCheckboxProps = (props: CheckboxProps): ResolvedCheckboxProps =>
-  ({ ...CHECKBOX_DEFAULTS, ...definedProps(props) }) as ResolvedCheckboxProps;
+export const resolveCheckboxProps = <P extends CheckboxBaseProps>(props: P): ResolvedCheckboxProps<P> =>
+  withDefaults(props, CHECKBOX_DEFAULTS as Partial<P>) as ResolvedCheckboxProps<P>;
 
+/** `${dataTestId}-${suffix}`, or `checkbox-${suffix}` when the caller named nothing. */
 export const makeTestId =
   (dataTestId?: string) =>
   (suffix: string): string =>

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

@@ -0,0 +1,73 @@
+import type { CheckboxVariant } from './Checkbox.base';
+
+/**
+ * THE NUMBERS BOTH `Checkbox` RENDERERS DRAW WITH.
+ *
+ * `Checkbox.tsx` (web, emotion over MUI's `Checkbox`) and
+ * `Checkbox.native.tsx` (React Native) read this one table. As with the other
+ * fields, some of it is what the web writes itself — the two variants' corner
+ * treatment, the glow and pulse keyframes, the helper text's inset — and some
+ * is what MUI supplies underneath: `SwitchBase`'s 9px padding, `SvgIcon`'s
+ * three sizes, and the ink a box is drawn in.
+ */
+
+/** MUI's `SwitchBase`: 9px of padding around the glyph, at every size. */
+export const CHECKBOX_PADDING = 9;
+
+/** `SvgIcon`'s own three steps. MUI passes the `size` prop straight to the glyph. */
+export const CHECKBOX_GLYPH_SIZES = { small: 20, medium: 24, large: 35 } as const;
+export type CheckboxSize = keyof typeof CHECKBOX_GLYPH_SIZES;
+
+export const glyphSize = (size: CheckboxSize | undefined): number =>
+  CHECKBOX_GLYPH_SIZES[size ?? 'medium'] ?? CHECKBOX_GLYPH_SIZES.medium;
+
+/**
+ * The three glyphs MUI draws, by state.
+ *
+ * `@12-apps/ui/icons` generates their paths from the same
+ * `@mui/icons-material` package MUI's own `Checkbox` imports them from, so the
+ * native box is the web box rather than a hand-drawn square.
+ */
+export const CHECKBOX_GLYPH = {
+  checked: 'CheckBox',
+  unchecked: 'CheckBoxOutlineBlank',
+  indeterminate: 'IndeterminateCheckBox',
+} as const;
+
+/**
+ * The corner each variant gives the glyph's box.
+ *
+ * `rounded` is a circle and `toggle` a 12px radius at 1.2 scale — both applied
+ * to the SVG's own box on the web, where they show only through what the box
+ * clips. Native gives them the same radius and the same scale.
+ */
+export const CHECKBOX_VARIANT: Record<CheckboxVariant, { radius?: number | string; scale?: number }> = {
+  default: {},
+  rounded: { radius: '50%' },
+  toggle: { radius: 12, scale: 1.2 },
+};
+
+/** The wash a hovered box takes, and the 0.3s every state change runs over. */
+export const CHECKBOX_HOVER_ALPHA = 0.1;
+export const CHECKBOX_TRANSITION_MS = 300;
+
+/** `loading`: MUI's 20px `CircularProgress`, centred over the box. */
+export const CHECKBOX_SPINNER = { size: 20, offset: -10 } as const;
+
+/**
+ * `glow` and `pulse` are keyed to MUI's DEFAULT blue rather than the theme's
+ * primary — the web writes the rgba out by hand — so both renderers do.
+ */
+export const CHECKBOX_EFFECT_INK = { r: 25, g: 118, b: 210 } as const;
+export const CHECKBOX_GLOW = { blur: { from: 5, to: 20 }, alpha: { from: 0.5, to: 0.8 }, ms: 2000 } as const;
+export const CHECKBOX_PULSE = { spread: 10, alpha: 0.7, ms: 2000 } as const;
+
+/** MUI's default blue at an alpha, as the web's keyframes spell it. */
+export const effectInk = (alphaValue: number): string =>
+  `rgba(${CHECKBOX_EFFECT_INK.r}, ${CHECKBOX_EFFECT_INK.g}, ${CHECKBOX_EFFECT_INK.b}, ${alphaValue})`;
+
+/** `FormControlLabel`: flush left, its label at MUI's `body2` size. */
+export const CHECKBOX_LABEL = { marginLeft: 0, fontSize: 14 } as const;
+
+/** `FormHelperText`: four spacing units in, half a unit down. */
+export const CHECKBOX_HELPER = { marginLeftUnits: 4, marginTopUnits: 0.5, fontSize: 12, lineHeight: 1.66 } as const;

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';