@12-apps/ui 6.19.1 → 6.20.0

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

@@ -0,0 +1,102 @@
+import type { ChipSize } from './Chip.base';
+
+/**
+ * THE NUMBERS BOTH `Chip` RENDERERS DRAW WITH.
+ *
+ * Most of them are MUI's own `Chip` geometry rather than anything this package
+ * writes — the 32px pill, the 13px label, the 5px/-6px icon tuck — because the
+ * web half hands the drawing to `MuiChip` and the native half has to draw it.
+ * Restated here once, read by both, so the two cannot disagree about a chip's
+ * height. What THIS package adds (`Chip.styles.tsx`'s hover lift, its shadow
+ * and its transition) is at the bottom, and the web derives its CSS from it.
+ */
+
+/** MUI draws two chip sizes; ours are the house abbreviations for them. */
+export type ChipMuiSize = 'small' | 'medium';
+
+export const chipMuiSize = (size: ChipSize): ChipMuiSize =>
+  size === 'xs' || size === 'sm' ? 'small' : 'medium';
+
+export interface ChipSizeMetrics {
+  height: number;
+  /** The label's own side padding, filled and outlined (outlined is 1px tighter). */
+  labelPadding: number;
+  labelPaddingOutlined: number;
+  /** The leading icon's box, and how far it tucks under the label. */
+  iconSize: number;
+  iconMarginLeft: number;
+  iconMarginLeftOutlined: number;
+  iconMarginRight: number;
+  /** The avatar's round box and the type inside it. */
+  avatarSize: number;
+  avatarFontSize: number;
+  avatarMarginLeft: number;
+  avatarMarginLeftOutlined: number;
+  avatarMarginRight: number;
+  /** The delete glyph's box and its own tuck. */
+  deleteSize: number;
+  deleteMarginLeft: number;
+  deleteMarginRight: number;
+  deleteMarginRightOutlined: number;
+}
+
+export const CHIP_SIZES: Record<ChipMuiSize, ChipSizeMetrics> = {
+  medium: {
+    height: 32,
+    labelPadding: 12,
+    labelPaddingOutlined: 11,
+    iconSize: 24,
+    iconMarginLeft: 5,
+    iconMarginLeftOutlined: 4,
+    iconMarginRight: -6,
+    avatarSize: 24,
+    avatarFontSize: 12,
+    avatarMarginLeft: 5,
+    avatarMarginLeftOutlined: 4,
+    avatarMarginRight: -6,
+    deleteSize: 22,
+    deleteMarginLeft: -6,
+    deleteMarginRight: 5,
+    deleteMarginRightOutlined: 5,
+  },
+  small: {
+    height: 24,
+    labelPadding: 8,
+    labelPaddingOutlined: 7,
+    iconSize: 18,
+    iconMarginLeft: 4,
+    iconMarginLeftOutlined: 2,
+    iconMarginRight: -4,
+    avatarSize: 18,
+    avatarFontSize: 10,
+    avatarMarginLeft: 4,
+    avatarMarginLeftOutlined: 2,
+    avatarMarginRight: -4,
+    deleteSize: 16,
+    deleteMarginLeft: -4,
+    deleteMarginRight: 4,
+    deleteMarginRightOutlined: 3,
+  },
+};
+
+/** MUI's `borderRadius: 32 / 2` — a pill at either height, since the box clamps it. */
+export const CHIP_RADIUS = 16;
+/** The label's type, in px. MUI sets it on the root and the small size keeps it. */
+export const CHIP_FONT_SIZE = 13;
+/** MUI's `palette.action.disabledOpacity`. */
+export const CHIP_DISABLED_OPACITY = 0.38;
+/** An outlined chip's hairline: the hue at 0.7, or the grey ramp for `neutral`. */
+export const OUTLINED_BORDER_ALPHA = 0.7;
+/** The delete glyph over an unaccented chip, and over a coloured one. */
+export const DELETE_ICON_ALPHA = 0.26;
+export const DELETE_ICON_ON_COLOR_ALPHA = 0.7;
+/** MUI's `action.hoverOpacity`, the wash a clickable outlined chip takes. */
+export const OUTLINED_HOVER_ALPHA = 0.04;
+
+/* ── What this package adds on top of MUI's chip ──────────────────────────── */
+
+/** The lift a clickable chip takes on hover, and the shadow under it. */
+export const HOVER_LIFT_PX = 1;
+export const HOVER_SHADOW = { offsetY: 4, blur: 12, alphaLight: 0.15, alphaDark: 0.3 } as const;
+export const CHIP_TRANSITION_MS = 200;
+export const CHIP_TRANSITION_EASING = 'cubic-bezier(0.4, 0, 0.2, 1)';

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

@@ -0,0 +1,269 @@
+import * as React from 'react';
+import {
+  Image,
+  Pressable,
+  Text as RNText,
+  View,
+  type GestureResponderEvent,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
+
+import { chipKeyAction, chipRole, isClickable, makeTestId } from './Chip.helpers';
+import {
+  chipAvatarStyle,
+  chipContainerStyle,
+  chipDeleteSlotStyle,
+  chipLabelStyle,
+  chipLeadingSlotStyle,
+  chipMetrics,
+  chipPaint,
+  type ChipPaint,
+} from './Chip.look.native';
+import { chipMuiSize, type ChipSizeMetrics } from './Chip.metrics';
+import type { ChipProps, ChipVariant } from './Chip.types.native';
+import { Icon } from '../../../icons/Icon.native';
+import { webKeyDown, type WebKeyHandler } from '../../../platform/web-keys';
+import { useUiTheme } from '../../../provider/use-ui-theme.native';
+
+interface SlotArgs {
+  metrics: ChipSizeMetrics;
+  variant: ChipVariant;
+}
+
+/**
+ * The leading slot. MUI restyles the icon ELEMENT through a class — 24px, or
+ * 18px when small — which a native renderer cannot do to an arbitrary node, so
+ * the slot carries the margins and the glyph keeps the size it was given.
+ */
+function LeadingSlot({
+  metrics,
+  variant,
+  avatar,
+  avatarSrc,
+  icon,
+  testID,
+}: SlotArgs &
+  Pick<ChipProps, 'avatar' | 'avatarSrc' | 'icon'> & { testID: string }): React.JSX.Element | null {
+  if (avatar) {
+    return <View style={chipLeadingSlotStyle(metrics, variant, 'avatar')}>{avatar}</View>;
+  }
+  if (avatarSrc) {
+    return (
+      <View style={chipLeadingSlotStyle(metrics, variant, 'avatar')}>
+        <Image
+          source={{ uri: avatarSrc }}
+          style={chipAvatarStyle(metrics)}
+          accessibilityIgnoresInvertColors
+        />
+      </View>
+    );
+  }
+  if (icon) {
+    return (
+      <View style={chipLeadingSlotStyle(metrics, variant, 'icon')} testID={testID}>
+        {icon}
+      </View>
+    );
+  }
+  return null;
+}
+
+/** MUI's `deleteIcon`: the `Cancel` glyph, pressable, tucked under the label. */
+function DeleteSlot({
+  metrics,
+  variant,
+  color,
+  onDelete,
+  disabled,
+  testID,
+}: SlotArgs & {
+  color: string;
+  onDelete?: () => void;
+  disabled?: boolean;
+  testID: string;
+}): React.JSX.Element {
+  return (
+    <Pressable
+      testID={testID}
+      role="button"
+      aria-label="delete"
+      disabled={disabled}
+      onPress={onDelete}
+      style={chipDeleteSlotStyle(metrics, variant)}
+    >
+      <Icon name="Cancel" size={metrics.deleteSize} color={color} />
+    </Pressable>
+  );
+}
+
+interface ChipBodyProps extends SlotArgs {
+  paint: ChipPaint;
+  label: string;
+  avatar?: ChipProps['avatar'];
+  avatarSrc?: string;
+  icon?: ChipProps['icon'];
+  deletable?: boolean;
+  disabled?: boolean;
+  onDelete?: () => void;
+  idFor: (suffix: string) => string;
+}
+
+/** Everything inside the pill: the leading slot, the label, the delete button. */
+function ChipBody({
+  metrics,
+  variant,
+  paint,
+  label,
+  avatar,
+  avatarSrc,
+  icon,
+  deletable,
+  disabled,
+  onDelete,
+  idFor,
+}: ChipBodyProps): React.JSX.Element {
+  const theme = useUiTheme();
+  return (
+    <>
+      <LeadingSlot
+        metrics={metrics}
+        variant={variant}
+        avatar={avatar}
+        avatarSrc={avatarSrc}
+        icon={icon}
+        testID={idFor('icon')}
+      />
+      <RNText
+        testID={idFor('label')}
+        numberOfLines={1}
+        style={[chipLabelStyle(theme, metrics, variant), paint.label]}
+      >
+        {label}
+      </RNText>
+      {deletable ? (
+        <DeleteSlot
+          metrics={metrics}
+          variant={variant}
+          color={paint.deleteColor}
+          onDelete={onDelete}
+          disabled={disabled}
+          testID={idFor('delete')}
+        />
+      ) : null}
+    </>
+  );
+}
+
+interface KeyDownArgs {
+  role: 'option' | 'button' | undefined;
+  disabled?: boolean;
+  deletable?: boolean;
+  selectable?: boolean;
+  /** Whether the chip acts at all, under either handler spelling. */
+  acts?: unknown;
+  onClick?: () => void;
+  onDelete?: () => void;
+}
+
+/**
+ * The half of the chip's keyboard contract react-native-web does NOT already
+ * cover. Its `Pressable` turns Enter into a press on any role, and Space into
+ * one only on a `button` role (`isValidKeyPress`) — so a selectable chip, which
+ * is an `option`, needs Space wiring here, and Delete/Backspace is never its.
+ * On a device none of this is ever called.
+ */
+function makeChipKeyDown(args: KeyDownArgs): WebKeyHandler {
+  return (event) => {
+    const action = chipKeyAction(event.key, { ...args, onClick: args.acts });
+    if (action === null) return;
+    if (action === 'delete') {
+      event.preventDefault();
+      args.onDelete?.();
+      return;
+    }
+    if (event.key === 'Enter' || args.role === 'button') return;
+    event.preventDefault();
+    args.onClick?.();
+  };
+}
+
+/**
+ * The native `Chip`: MUI's pill on a `Pressable`, reachable by keyboard only
+ * when it acts — which is the same rule MUI applies through `clickable`.
+ */
+export const Chip = React.forwardRef<View, ChipProps>((props, ref) => {
+  const {
+    label,
+    variant = 'filled',
+    size = 'md',
+    color = 'primary',
+    avatarSrc,
+    avatar,
+    icon,
+    selected,
+    selectable,
+    deletable,
+    disabled,
+    onClick,
+    onPress,
+    onDelete,
+    dataTestId,
+    testID,
+    style,
+    ...rest
+  } = props;
+  const theme = useUiTheme();
+  const chipId = testID ?? dataTestId;
+  const metrics = chipMetrics(chipMuiSize(size));
+  const paint = chipPaint(theme, variant, color, Boolean(selected));
+  const acts = onClick ?? onPress;
+  const clickable = isClickable(disabled, acts, selectable);
+  const role = chipRole(selectable, acts);
+
+  const base: StyleProp<ViewStyle> = [
+    chipContainerStyle(metrics, Boolean(disabled)),
+    paint.container,
+    style,
+  ];
+
+  const press = (event: GestureResponderEvent): void => {
+    onClick?.();
+    onPress?.(event);
+  };
+
+  return (
+    <Pressable
+      ref={ref}
+      testID={chipId || 'chip'}
+      role={role}
+      aria-selected={selectable ? selected : undefined}
+      disabled={disabled}
+      // MUI makes only a clickable chip keyboard-reachable; react-native-web
+      // would otherwise give every Pressable a tab stop.
+      tabIndex={clickable ? 0 : -1}
+      onPress={clickable ? press : undefined}
+      {...webKeyDown(
+        makeChipKeyDown({ role, disabled, deletable, selectable, acts, onClick, onDelete }),
+      )}
+      style={(state) => [base, state.pressed && clickable ? paint.pressed : null]}
+      {...rest}
+    >
+      <ChipBody
+        metrics={metrics}
+        variant={variant}
+        paint={paint}
+        label={label}
+        avatar={avatar}
+        avatarSrc={avatarSrc}
+        icon={icon}
+        deletable={deletable}
+        disabled={disabled}
+        onDelete={onDelete}
+        idFor={makeTestId(chipId)}
+      />
+    </Pressable>
+  );
+});
+
+Chip.displayName = 'Chip';

package/src/components/data-display/Chip/{Chip.helpers.tsx → Chip.styles.tsx}

@@ -3,43 +3,26 @@ import type { SxProps, Theme } from '@mui/material/styles/index.js';
 import type { KeyboardEvent, ReactElement } from 'react';
 import React from 'react';
 
+import { chipKeyAction, type ChipKeyArgs } from './Chip.helpers';
+import { CHIP_SIZES, CHIP_TRANSITION_EASING, CHIP_TRANSITION_MS, HOVER_LIFT_PX, HOVER_SHADOW } from './Chip.metrics';
 import type { ChipProps } from './Chip.types';
 
-export const makeTestId =
-  (dataTestId?: string) =>
-  (suffix: string): string =>
-    dataTestId ? `${dataTestId}-${suffix}` : `chip-${suffix}`;
-
-interface KeyHandlerArgs {
-  disabled?: boolean;
-  deletable?: boolean;
-  selectable?: boolean;
-  onClick?: () => void;
-  onDelete?: () => void;
-}
-
-const DELETE_KEYS = new Set(['Delete', 'Backspace']);
-const ACTIVATE_KEYS = new Set(['Enter', ' ']);
-
 /**
- * A chip is not a native control, so the two keyboard conventions it stands in for
- * are wired by hand: Delete/Backspace removes it, Enter/Space activates it.
+ * A chip is not a native control, so the two keyboard conventions it stands in
+ * for are wired by hand: Delete/Backspace removes it, Enter/Space activates it.
+ * The DECISION is `chipKeyAction`, which the native half reads too.
  */
 export const makeKeyDownHandler =
-  ({ disabled, deletable, selectable, onClick, onDelete }: KeyHandlerArgs) =>
+  (args: ChipKeyArgs & { onClick?: () => void; onDelete?: () => void }) =>
   (event: KeyboardEvent): void => {
-    if (disabled) return;
-
-    if (DELETE_KEYS.has(event.key) && deletable && onDelete) {
-      event.preventDefault();
-      onDelete();
+    const action = chipKeyAction(event.key, args);
+    if (action === null) return;
+    event.preventDefault();
+    if (action === 'delete') {
+      args.onDelete?.();
       return;
     }
-
-    if (ACTIVATE_KEYS.has(event.key) && (onClick || selectable)) {
-      event.preventDefault();
-      onClick?.();
-    }
+    args.onClick?.();
   };
 
 export const avatarFor = (
@@ -50,7 +33,8 @@ export const avatarFor = (
     return avatar;
   }
   if (avatarSrc) {
-    return <Avatar src={avatarSrc} sx={{ width: 24, height: 24 }} />;
+    const { avatarSize } = CHIP_SIZES.medium;
+    return <Avatar src={avatarSrc} sx={{ width: avatarSize, height: avatarSize }} />;
   }
   return undefined;
 };
@@ -62,6 +46,12 @@ interface ChipStyleArgs {
   disabled?: boolean;
 }
 
+/** The lift's shadow, per mode — the same numbers the native chip reads. */
+const hoverShadow = (mode: Theme['palette']['mode']): string =>
+  `0 ${HOVER_SHADOW.offsetY}px ${HOVER_SHADOW.blur}px rgba(0, 0, 0, ${
+    mode === 'dark' ? HOVER_SHADOW.alphaDark : HOVER_SHADOW.alphaLight
+  })`;
+
 /**
  * Selection styling uses SEMANTIC palette tokens (not hardcoded rgba). A filled
  * selected chip keeps MUI's solid `color.main` + contrast text (clear active
@@ -89,11 +79,8 @@ export const chipStyles = ({
       }),
     '&:hover': {
       ...(lifts && {
-        transform: 'translateY(-1px)',
-        boxShadow: (theme: Theme) =>
-          theme.palette.mode === 'dark'
-            ? '0 4px 12px rgba(0, 0, 0, 0.3)'
-            : '0 4px 12px rgba(0, 0, 0, 0.15)',
+        transform: `translateY(-${HOVER_LIFT_PX}px)`,
+        boxShadow: (theme: Theme) => hoverShadow(theme.palette.mode),
       }),
     },
     '&:active': {
@@ -101,25 +88,10 @@ export const chipStyles = ({
         transform: 'translateY(0px)',
       }),
     },
-    transition: 'all 0.2s cubic-bezier(0.4, 0, 0.2, 1)',
+    transition: `all ${CHIP_TRANSITION_MS / 1000}s ${CHIP_TRANSITION_EASING}`,
   };
 };
 
-/** `option` when the chip belongs to a selectable set, `button` when it merely acts. */
-export const chipRole = (
-  selectable?: boolean,
-  onClick?: () => void,
-): 'option' | 'button' | undefined => {
-  if (selectable) return 'option';
-  return onClick ? 'button' : undefined;
-};
-
-export const isClickable = (
-  disabled?: boolean,
-  onClick?: () => void,
-  selectable?: boolean,
-): boolean => !disabled && (Boolean(onClick) || Boolean(selectable));
-
 export const iconWithTestId = (
   icon: ChipProps['icon'],
   testId: string,

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

@@ -2,21 +2,16 @@ import CancelIcon from '@mui/icons-material/Cancel';
 import MuiChip from '@mui/material/Chip/index.js';
 import { forwardRef } from 'react';
 
+import { chipRole, isClickable, makeTestId } from './Chip.helpers';
+import { chipMuiSize } from './Chip.metrics';
 import {
   avatarFor,
-  chipRole,
   chipStyles,
   iconWithTestId,
-  isClickable,
   makeKeyDownHandler,
-  makeTestId,
-} from './Chip.helpers';
+} from './Chip.styles';
 import type { ChipProps } from './Chip.types';
 
-/** MUI draws two chip sizes; ours are the house abbreviations for them. */
-const muiSizeFor = (size: NonNullable<ChipProps['size']>): 'small' | 'medium' =>
-  size === 'xs' || size === 'sm' ? 'small' : 'medium';
-
 type MuiChipColor =
   | 'primary'
   | 'secondary'
@@ -58,9 +53,13 @@ export const Chip = forwardRef<HTMLDivElement, ChipProps>(({
   onDelete,
   className,
   dataTestId,
+  // React Native's spelling of the same id; it names the component on both
+  // sides and must not reach the DOM as an attribute.
+  testID,
   ...props
 }, ref) => {
-  const testId = makeTestId(dataTestId);
+  const chipId = testID ?? dataTestId;
+  const testId = makeTestId(chipId);
   const clickable = isClickable(disabled, onClick, selectable);
 
   return (
@@ -68,7 +67,7 @@ export const Chip = forwardRef<HTMLDivElement, ChipProps>(({
       ref={ref}
       label={<span data-testid={testId('label')}>{label}</span>}
       variant={variant}
-      size={muiSizeFor(size)}
+      size={chipMuiSize(size)}
       color={muiColorFor(color)}
       avatar={avatarFor(avatar, avatarSrc)}
       icon={iconWithTestId(icon, testId('icon'))}
@@ -81,7 +80,7 @@ export const Chip = forwardRef<HTMLDivElement, ChipProps>(({
       className={className}
       role={chipRole(selectable, onClick)}
       aria-selected={selectable ? selected : undefined}
-      data-testid={dataTestId || 'chip'}
+      data-testid={chipId || 'chip'}
       sx={chipStyles({ variant, selected, clickable, disabled })}
       {...props}
     />

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

@@ -0,0 +1,28 @@
+import type {
+  GestureResponderEvent,
+  PressableProps,
+  StyleProp,
+  ViewStyle,
+} from 'react-native';
+
+import type { ChipBaseProps } from './Chip.base';
+
+export type { ChipBaseProps, ChipColor, ChipSize, ChipVariant } from './Chip.base';
+
+/**
+ * The native `Chip`. `onClick` keeps its web name — a shared screen should not
+ * have to know which renderer it is on — and `onPress` is accepted too, because
+ * that is what a React Native developer will reach for.
+ *
+ * A press fires BOTH. A keyboard activation fires only `onClick`: it exists
+ * solely under react-native-web, where a selectable chip is an `option` and
+ * `Pressable` answers Space only on a `button` role, so the chip synthesizes
+ * the activation itself and has no `GestureResponderEvent` to hand `onPress`.
+ * That matches the web, whose chip has no `onPress` at all, and costs nothing
+ * on a device, which has no keyboard to activate from.
+ */
+export type ChipProps = ChipBaseProps &
+  Omit<PressableProps, keyof ChipBaseProps | 'style' | 'onPress'> & {
+    onPress?: (event: GestureResponderEvent) => void;
+    style?: StyleProp<ViewStyle>;
+  };

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

@@ -1,88 +1,9 @@
-import type { ColorValue, SizeValue } from '../../../tokens/scales';
-import type { ReactNode } from 'react';
+import type { ChipBaseProps } from './Chip.base';
 
-export type ChipVariant = 'filled' | 'outlined';
+export type { ChipBaseProps, ChipColor, ChipSize, ChipVariant } from './Chip.base';
 
-/**
- * The house size scale, abbreviated like every other component's.
- *
- * `Avatar`, `Badge`, `Progress`, `Input`, `Modal` and `Dialog` all use `sm`/`md`;
- * this was `'small' | 'medium'`, MUI's spelling, and the sole outlier in the
- * package. That was not merely inconsistent — callers wrote `size="sm"` because
- * every neighbouring component taught them to, it type-checked against the old
- * `ChipSize` nowhere and reached MUI as an unknown value, and the chip silently
- * rendered at the default `medium`. Twelve of them are doing that today.
- *
- * All five stops, and `Chip.tsx` draws them: MUI gives a chip two heights, so
- * `xs`/`sm` map to small and `md` and up to medium. Offering fewer than five
- * here is what made callers write `size="sm"` against a type that did not have
- * it — the scale is the vocabulary, and a component that speaks a dialect of it
- * is the problem, not the solution.
- */
-export type ChipSize = SizeValue;
-
-/**
- * The colours a chip can draw — THE HOUSE VOCABULARY, identical to `ButtonProps`.
- *
- * `danger` and `neutral` are ours; the rest are MUI's own names already. That is
- * the same sentence `Button.tsx` carries, and deliberately so: `Button`, `Alert`,
- * `Text`, `Heading`, `Paragraph` and `Blockquote` all speak this vocabulary, so a
- * chip is the odd one out if it does not.
- *
- * This prop was `string`, and the widening was not free. `danger` — the house
- * word for the destructive meaning, and what every neighbouring component
- * accepts — reached MUI as an unknown value and fell back to the default grey.
- * The chip that most needed emphasis rendered without any, and nothing said so.
- *
- * The fix is NOT to reject `danger`. Rejecting it would punish a caller for
- * using the vocabulary the rest of the system taught them. The fix is for the
- * chip to speak it and translate at the MUI boundary, exactly as `Button` does.
- */
-export type ChipColor = ColorValue;
-
-export interface ChipProps {
-  /** Text content displayed in the chip */
-  label: string;
-  
-  /** Visual style variant */
-  variant?: ChipVariant;
-  
-  /** Size of the chip */
-  size?: ChipSize;
-  
-  /** Theme color token. See {@link ChipColor} for why this is a closed set. */
-  color?: ChipColor;
-  
-  /** Source URL for avatar image */
-  avatarSrc?: string;
-  
-  /** Custom avatar React node (overrides avatarSrc) */
-  avatar?: ReactNode;
-  
-  /** Leading icon React node */
-  icon?: ReactNode;
-  
-  /** Current selection state */
-  selected?: boolean;
-  
-  /** Enables selection toggle capability */
-  selectable?: boolean;
-  
-  /** Shows delete button */
-  deletable?: boolean;
-  
-  /** Disables all interactions */
-  disabled?: boolean;
-  
-  /** Click/selection handler */
-  onClick?: () => void;
-  
-  /** Delete action handler */
-  onDelete?: () => void;
-  
+/** The web `Chip`: the shared contract, plus the DOM's own styling hook. */
+export interface ChipProps extends ChipBaseProps {
   /** Additional CSS classes */
   className?: string;
-
-  /** Test ID for component testing */
-  dataTestId?: string;
-}
+}

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

@@ -0,0 +1,10 @@
+# Chip on React Native
+
+Known rendering gaps, one bullet each; `pnpm native:ledger` reads them.
+
+- Hover has no touch equivalent, so a press stands in for it: the chip takes MUI's hover wash (`palette[color].dark` filled, `alpha(main, 0.04)` outlined) while pressed, but not this package's own 1px lift or the `0 4px 12px` shadow under it, which are `:hover`-only.
+- The keyboard contract — Enter and Space activate, Delete and Backspace remove — is shared (`chipKeyAction`) and answered under react-native-web, half by its `Pressable` and half by the chip's own handler. On a DEVICE none of it runs: React Native delivers no key events to a `View`, so a chip there is pressed and removed by touch.
+- MUI restyles the leading icon ELEMENT through a class — 24px, 18px when small, and `inherit` ink on a coloured chip. A native renderer cannot restyle an arbitrary node, so the slot carries MUI's margins and the glyph keeps the size and colour it was given.
+- An `avatarSrc` is drawn as a round `Image` at MUI's 24px (18px small) box; MUI's own `Avatar` additionally shows an initials fallback and repaints itself in `primary.dark`/`secondary.dark` for those two colours.
+- MUI's `transition: background-color, box-shadow` and this package's `all 0.2s cubic-bezier(0.4, 0, 0.2, 1)` have no equivalent: a colour change is drawn immediately.
+- A keyboard activation (Space on a selectable chip, Delete on a deletable one) fires `onClick` and `onDelete` but not `onPress`: it only exists under react-native-web, where the chip synthesizes the activation `Pressable` will not, and so has no `GestureResponderEvent` to pass. A press on a device fires both.

package/src/components/data-display/Chip/chip.md

@@ -6,7 +6,7 @@
 interface ChipProps {
   label: string;
   variant?: 'filled' | 'outlined';
-  size?: SizeValue narrowed to 'sm' | 'md';
+  size?: SizeValue; // all five stops; MUI's two heights, xs/sm small and md up medium
   /**
    * The house vocabulary, identical to Button's. `danger` and `neutral` are
    * ours and are translated at the MUI boundary. See `ColorValue`.