@12-apps/ui 6.20.0 → 6.22.0

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

package/src/components/form/Input/Input.look.native.ts

@@ -0,0 +1,246 @@
+import type { TextStyle, ViewStyle } from 'react-native';
+
+import type { InputVariant } from './Input.base';
+import {
+  FILLED_WASH,
+  HELPER_TEXT,
+  INPUT_MUI_SIZE,
+  INPUT_BORDER,
+  INPUT_FONT_SIZE,
+  INPUT_GLASS,
+  INPUT_GRADIENT,
+  INPUT_LABEL,
+  INPUT_LINE_HEIGHT,
+  UNDERLINE_COLOR,
+  inputPadding,
+  placeholderInk,
+} from './Input.metrics';
+import { alpha } from '../../../tokens/color';
+import { resolveFieldEdge } from '../../../tokens/field-edge.core';
+import type { UiTheme } from '../../../tokens/theme';
+import type { SizeValue } from '../../../tokens/vocabulary';
+
+/**
+ * WHAT A NATIVE `Input` PAINTS, AS ARITHMETIC.
+ *
+ * Kept out of `Input.native.tsx` so that file reads as structure — label, box,
+ * value, helper — and this one reads as the decisions: which border, how thick,
+ * what colour, and where the value sits inside it.
+ */
+export interface FieldState {
+  focused: boolean;
+  error: boolean;
+  disabled: boolean;
+}
+
+/** Which edges a variant draws. `filled` and `underline` rule only the bottom. */
+const BORDER_SIDES: Record<InputVariant, 'all' | 'bottom'> = {
+  outlined: 'all',
+  glass: 'all',
+  gradient: 'all',
+  filled: 'bottom',
+  underline: 'bottom',
+};
+
+/**
+ * Whether the web draws this border on an absolutely positioned element.
+ *
+ * MUI's `notchedOutline` fieldset and the `::before` / `::after` underlines
+ * cost no height — the field is 56px tall WITH its border. `glass` and
+ * `gradient` instead put a real `border` on the input root, which does add to
+ * the box, so the web field is 2px and 4px taller respectively. React Native
+ * has only the second kind, so the first three compensate below.
+ */
+const BORDER_IS_FREE: Record<InputVariant, boolean> = {
+  outlined: true,
+  filled: true,
+  underline: true,
+  glass: false,
+  gradient: false,
+};
+
+/**
+ * How thick. Only the outline family thickens on focus (MUI's `borderWidth: 2`
+ * on `.Mui-focused .notchedOutline`); `glass` and `gradient` declare their own
+ * constant border and change only its colour.
+ */
+export function borderWidthFor(variant: InputVariant, focused: boolean): number {
+  if (variant === 'gradient') return INPUT_GRADIENT.borderWidth;
+  if (variant === 'glass') return INPUT_BORDER.rest;
+  return focused ? INPUT_BORDER.focused : INPUT_BORDER.rest;
+}
+
+/**
+ * The width the border takes out of the horizontal inset — 0 where the web's
+ * border adds to the box rather than floating over it. Exported because the
+ * `Select` draws the same box and has to place its arrow inside the same edge.
+ */
+export function horizontalBorderInset(variant: InputVariant, focused: boolean): number {
+  if (BORDER_SIDES[variant] !== 'all' || !BORDER_IS_FREE[variant]) return 0;
+  return borderWidthFor(variant, focused);
+}
+
+/**
+ * What colour. Error and disabled outrank focus, as they do in MUI's source
+ * order; a resting `filled` keeps MUI's own underline grey because the web
+ * override only replaces its background.
+ */
+function borderColorFor(theme: UiTheme, variant: InputVariant, state: FieldState): string {
+  if (state.disabled) return theme.palette.action.disabled;
+  if (state.error) return theme.palette.danger.main;
+  if (variant === 'gradient') {
+    return state.focused ? theme.palette.primary.dark : theme.palette.primary.main;
+  }
+  if (state.focused) return theme.palette.primary.main;
+  if (variant === 'filled') {
+    return theme.mode === 'dark' ? UNDERLINE_COLOR.dark : UNDERLINE_COLOR.light;
+  }
+  return resolveFieldEdge(theme.palette.divider, theme.palette.background.paper);
+}
+
+/** The fill behind the value. `outlined` and `underline` have none. */
+function backgroundFor(theme: UiTheme, variant: InputVariant, state: FieldState): string | undefined {
+  switch (variant) {
+    case 'filled':
+      return alpha(theme.palette.action.hover, state.focused ? FILLED_WASH.focused : FILLED_WASH.rest);
+    case 'glass':
+      return alpha(
+        theme.palette.background.paper,
+        state.focused ? INPUT_GLASS.background.focused : INPUT_GLASS.background.rest,
+      );
+    case 'gradient':
+      // The first stop of the web's 135° fill; React Native core has no gradient.
+      return alpha(
+        theme.palette.primary.main,
+        state.focused ? INPUT_GRADIENT.fill.focused : INPUT_GRADIENT.fill.rest,
+      );
+    default:
+      return undefined;
+  }
+}
+
+/** `filled` rounds its top two corners, `underline` none, the rest all four. */
+function radiusFor(theme: UiTheme, variant: InputVariant): ViewStyle {
+  if (variant === 'underline') return {};
+  if (variant === 'filled') {
+    return { borderTopLeftRadius: theme.radius.md, borderTopRightRadius: theme.radius.md };
+  }
+  return { borderRadius: theme.radius.md };
+}
+
+/** The border as React Native writes it: a width per side, one colour, one style. */
+function borderStyle(variant: InputVariant, width: number, color: string, state: FieldState): ViewStyle {
+  // MUI draws a disabled `filled` or `standard` underline dotted.
+  const style: ViewStyle['borderStyle'] =
+    state.disabled && BORDER_SIDES[variant] === 'bottom' ? 'dotted' : 'solid';
+  const sides: ViewStyle =
+    BORDER_SIDES[variant] === 'bottom' ? { borderBottomWidth: width } : { borderWidth: width };
+  return { ...sides, borderColor: color, borderStyle: style };
+}
+
+export interface FieldLook {
+  /** The row the border is drawn on: fill, edges, corners and horizontal inset. */
+  box: ViewStyle;
+  /** The `TextInput` itself: type, ink and the vertical inset. */
+  value: TextStyle;
+  placeholder: string;
+}
+
+/**
+ * The field, in absolute numbers.
+ *
+ * The horizontal inset sits on the ROW rather than on the `TextInput`, which is
+ * what MUI does the moment an adornment appears (`paddingLeft: 14` moves to the
+ * input root and the input's own goes to 0) — so one rule serves a field with
+ * adornments and one without.
+ *
+ * Where the web's border costs no height, the inset gives the border back its
+ * width, so the box is the height MUI draws (56px medium, 40px small) and the
+ * value does not shift by a pixel when the focused border thickens.
+ */
+export function fieldLook(
+  theme: UiTheme,
+  variant: InputVariant,
+  size: SizeValue,
+  state: FieldState,
+): FieldLook {
+  const padding = inputPadding(variant, size);
+  const width = borderWidthFor(variant, state.focused);
+  const inset = BORDER_IS_FREE[variant] ? width : 0;
+  const sides = BORDER_SIDES[variant];
+  const horizontal = sides === 'all' ? inset : 0;
+
+  return {
+    box: {
+      flexDirection: 'row',
+      alignItems: 'center',
+      paddingLeft: padding.left - horizontal,
+      paddingRight: padding.right - horizontal,
+      backgroundColor: backgroundFor(theme, variant, state),
+      ...radiusFor(theme, variant),
+      ...borderStyle(variant, width, borderColorFor(theme, variant, state), state),
+    },
+    value: {
+      flex: 1,
+      minWidth: 0,
+      fontFamily: theme.typography.fontFamily,
+      fontSize: INPUT_FONT_SIZE,
+      lineHeight: INPUT_LINE_HEIGHT,
+      color: state.disabled ? theme.palette.text.disabled : theme.palette.text.primary,
+      paddingTop: padding.top - (sides === 'all' ? inset : 0),
+      paddingBottom: padding.bottom - inset,
+      paddingHorizontal: 0,
+    },
+    placeholder: placeholderInk(theme),
+  };
+}
+
+/**
+ * The label's ink. MUI's `FormLabel` is `text.secondary`, the focus colour is
+ * the palette's `main`, and error and disabled are declared after it and win.
+ */
+export function labelStyle(theme: UiTheme, variant: InputVariant, size: SizeValue, state: FieldState): TextStyle {
+  const ink = state.disabled
+    ? theme.palette.text.disabled
+    : state.error
+      ? theme.palette.danger.main
+      : state.focused
+        ? theme.palette.primary.main
+        : theme.palette.text.secondary;
+
+  return {
+    color: ink,
+    fontFamily: theme.typography.fontFamily,
+    fontSize: INPUT_FONT_SIZE * INPUT_LABEL.scale,
+    marginBottom: INPUT_LABEL.gap,
+    // Aligned with the value it names: the web's floating label and the input
+    // share one left inset (14px outlined, 12px filled, 0 standard).
+    marginLeft: inputPadding(variant, size).left,
+  };
+}
+
+/**
+ * `FormHelperText`: caption type, 3px below the field, inset 14px when
+ * contained — and 4px below at MUI's `small` density, which `INPUT_MUI_SIZE`
+ * selects for `xs` and `sm` (`FormHelperText.js`: `marginTop: 3`, then a
+ * `size: 'small'` variant raising it to 4).
+ */
+export function helperStyle(
+  theme: UiTheme,
+  variant: InputVariant,
+  size: SizeValue,
+  state: FieldState,
+): TextStyle {
+  return {
+    color: state.disabled
+      ? theme.palette.text.disabled
+      : state.error
+        ? theme.palette.danger.main
+        : theme.palette.text.secondary,
+    fontFamily: theme.typography.fontFamily,
+    fontSize: HELPER_TEXT.fontSize,
+    lineHeight: HELPER_TEXT.fontSize * HELPER_TEXT.lineHeight,
+    marginTop: INPUT_MUI_SIZE[size] === 'small' ? HELPER_TEXT.marginTopSmall : HELPER_TEXT.marginTop,
+    marginHorizontal: variant === 'underline' ? 0 : HELPER_TEXT.marginHorizontal,
+  };
+}

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

@@ -0,0 +1,229 @@
+import type { InputVariant } from './Input.base';
+import { decomposeColor, recomposeColor } from '../../../tokens/color';
+import type { UiTheme } from '../../../tokens/theme';
+import { SIZE_VALUES, type SizeValue } from '../../../tokens/vocabulary';
+
+/**
+ * THE NUMBERS BOTH `Input` RENDERERS DRAW WITH.
+ *
+ * `Input.styles.ts` (web, emotion over MUI's `TextField`) and
+ * `Input.native.tsx` (React Native) read this one table. The web turns the px
+ * into the padding shorthands and rem it has always emitted; native uses the
+ * numbers as they are.
+ *
+ * Two kinds of number live here, and the difference matters:
+ *
+ *  - the ones `Input.styles.ts` writes itself — the size overrides, the glow,
+ *    the pulse, the glass and gradient alphas, the filled wash;
+ *  - the ones MUI supplies UNDER those overrides — `OutlinedInput`'s
+ *    `16.5px 14px`, `InputBase`'s 23px line box, `FormHelperText`'s 3px lift.
+ *    The web never writes them, but it draws them, so a native field that
+ *    wants the same box has to know them. They are MUI 6.5's own values,
+ *    copied with their source named; a host that re-themes MUI's components
+ *    moves the web only, which the parity ledger records.
+ */
+
+export interface InputInset {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+/** MUI gives a text field two heights; the house scale has five. */
+export type MuiInputSize = 'small' | 'medium';
+export type MuiInputVariant = 'outlined' | 'filled' | 'standard';
+
+/** Our five variants map onto MUI's three; `glass` and `gradient` restyle an outline. */
+export const muiVariantFor = (variant: InputVariant): MuiInputVariant => {
+  switch (variant) {
+    case 'underline':
+      return 'standard';
+    case 'glass':
+    case 'gradient':
+      return 'outlined';
+    default:
+      return variant;
+  }
+};
+
+/** Which of MUI's two heights each step of the house scale asks for. */
+export const INPUT_MUI_SIZE: Record<SizeValue, MuiInputSize> = {
+  xs: 'small',
+  sm: 'small',
+  md: 'medium',
+  lg: 'medium',
+  xl: 'medium',
+};
+
+/**
+ * The three steps MUI has no height for, as `padding` on the input itself.
+ *
+ * `sm` and `md` are absent on purpose — they ARE MUI's two heights, so they
+ * fall through to {@link MUI_INPUT_PADDING} below rather than restating it.
+ * (`lg`'s 16px is a hair under `md`'s 16.5px: the override is a round number
+ * where MUI's is derived from a 56px box. Kept as written — this table is what
+ * the web draws, not what it ought to draw.)
+ */
+export const INPUT_SIZE_OVERRIDES: Partial<Record<SizeValue, { vertical: number; horizontal: number }>> = {
+  xs: { vertical: 6, horizontal: 10 },
+  lg: { vertical: 16, horizontal: 14 },
+  xl: { vertical: 20, horizontal: 16 },
+};
+
+/**
+ * MUI's own input padding per variant and height (`OutlinedInput`,
+ * `FilledInput`, `InputBase`). The filled insets are lopsided because the
+ * floating label sits inside the box on the web.
+ */
+export const MUI_INPUT_PADDING: Record<MuiInputVariant, Record<MuiInputSize, InputInset>> = {
+  outlined: {
+    small: { top: 8.5, right: 14, bottom: 8.5, left: 14 },
+    medium: { top: 16.5, right: 14, bottom: 16.5, left: 14 },
+  },
+  filled: {
+    small: { top: 21, right: 12, bottom: 4, left: 12 },
+    medium: { top: 25, right: 12, bottom: 8, left: 12 },
+  },
+  standard: {
+    small: { top: 1, right: 0, bottom: 5, left: 0 },
+    medium: { top: 4, right: 0, bottom: 5, left: 0 },
+  },
+};
+
+/** The inset the value is drawn at: the size override where there is one, MUI's otherwise. */
+export function inputPadding(variant: InputVariant, size: SizeValue): InputInset {
+  const override = INPUT_SIZE_OVERRIDES[size];
+  if (override) {
+    return {
+      top: override.vertical,
+      right: override.horizontal,
+      bottom: override.vertical,
+      left: override.horizontal,
+    };
+  }
+  return MUI_INPUT_PADDING[muiVariantFor(variant)][INPUT_MUI_SIZE[size]];
+}
+
+/** `theme.typography.body1` and `InputBase`'s `lineHeight: '1.4375em'`, in px. */
+export const INPUT_FONT_SIZE = 16;
+export const INPUT_LINE_HEIGHT = 23;
+
+/** MUI's `::placeholder` opacity, which multiplies the ink's own alpha. */
+export const PLACEHOLDER_OPACITY = { light: 0.42, dark: 0.5 } as const;
+
+/**
+ * The placeholder's colour: the field's ink faded by MUI's opacity.
+ *
+ * `alpha()` REPLACES an alpha channel, and `text.primary` already carries one
+ * (`rgba(0, 0, 0, 0.87)`), so `alpha(ink, 0.42)` would be a different grey from
+ * the one the browser composites. React Native has no per-placeholder opacity —
+ * only `placeholderTextColor` — so the multiplication happens here.
+ */
+export function placeholderInk(theme: UiTheme): string {
+  const opacity = theme.mode === 'dark' ? PLACEHOLDER_OPACITY.dark : PLACEHOLDER_OPACITY.light;
+  const { type, values } = decomposeColor(theme.palette.text.primary);
+  const [first = 0, second = 0, third = 0, own = 1] = values;
+  return recomposeColor({
+    type: type.startsWith('hsl') ? 'hsla' : 'rgba',
+    values: [first, second, third, own * opacity],
+  });
+}
+
+/** The outline: 1px at rest, 2px focused, as MUI's `notchedOutline` draws it. */
+export const INPUT_BORDER = { rest: 1, focused: 2 } as const;
+
+/** `FilledInput`'s and `Input`'s resting underline, MUI's own two greys. */
+export const UNDERLINE_COLOR = {
+  light: 'rgba(0, 0, 0, 0.42)',
+  dark: 'rgba(255, 255, 255, 0.7)',
+} as const;
+
+/**
+ * The label. It floats into the border on the web and sits above the field on
+ * native, but it is the SAME label: 16px body type at MUI's shrunk scale, and
+ * left-aligned with the value it names ({@link inputPadding}'s `left`).
+ *
+ * The 4px gap is MUI's own: a standard field puts 16px between the control's
+ * top and the input, and the shrunk label's 12px line box takes the first 12.
+ */
+export const INPUT_LABEL = { scale: 0.75, gap: 4 } as const;
+
+/** `FormHelperText`: `theme.typography.caption` lifted 3px, inset 14px when contained. */
+export const HELPER_TEXT = {
+  fontSize: 12,
+  lineHeight: 1.66,
+  marginTop: 3,
+  marginTopSmall: 4,
+  marginHorizontal: 14,
+} as const;
+
+/** `InputAdornment`: 8px between the glyph and the value, on whichever side it is. */
+export const ADORNMENT_GAP = 8;
+
+/** `loading`: the field fades and MUI's 20px `CircularProgress` takes the end slot. */
+export const INPUT_LOADING = { opacity: 0.7, spinnerSize: 20 } as const;
+
+/** `glow`: a halo of the primary hue, wider and stronger while focused. */
+export const INPUT_GLOW = {
+  rest: { blur: 15, alpha: 0.3 },
+  focused: { blur: 20, alpha: 0.5 },
+} as const;
+
+/** `pulse`: a 56px bar behind the field, fading outward every two seconds. */
+export const INPUT_PULSE = {
+  height: 56,
+  radiusUnits: 0.5,
+  opacity: 0.3,
+  ms: 2000,
+  spread: 10,
+} as const;
+
+/** `floating`: where the label rests and where it shrinks to, on the web. */
+export const FLOATING_LABEL = {
+  rest: { x: 14, y: 16 },
+  shrink: { x: 14, y: -9 },
+  scale: 0.75,
+  paddingX: 4,
+} as const;
+
+/** `glass`: a wash of paper under a blur, brighter as the field is engaged. */
+export const INPUT_GLASS = {
+  background: { rest: 0.1, hover: 0.15, focused: 0.2 },
+  blur: 20,
+  hoverBorderAlpha: 0.3,
+  focusRing: { width: 2, alpha: 0.1 },
+} as const;
+
+/** `gradient`: a 135° fill between the two brand hues, inside a 2px masked ring. */
+export const INPUT_GRADIENT = {
+  angleDeg: 135,
+  fill: { rest: 0.1, hover: 0.15, focused: 0.2 },
+  borderWidth: 2,
+} as const;
+
+/** `filled`: MUI's own grey replaced by a wash of `action.hover`. */
+export const FILLED_WASH = { rest: 0.04, hover: 0.08, focused: 0.12 } as const;
+
+/**
+ * The `sx` the web spreads onto the `TextField` for a size: MUI's height, plus
+ * the input padding for the three steps MUI has no height for.
+ */
+export interface InputSizeProps {
+  size: MuiInputSize;
+  sx?: { '& .MuiInputBase-input': { padding: string } };
+}
+
+const sizeProps = (size: SizeValue): InputSizeProps => {
+  const override = INPUT_SIZE_OVERRIDES[size];
+  return {
+    size: INPUT_MUI_SIZE[size],
+    ...(override
+      ? { sx: { '& .MuiInputBase-input': { padding: `${override.vertical}px ${override.horizontal}px` } } }
+      : {}),
+  };
+};
+
+export const SIZE_MAP: Record<SizeValue, InputSizeProps> = Object.fromEntries(
+  SIZE_VALUES.map((size) => [size, sizeProps(size)]),
+) as Record<SizeValue, InputSizeProps>;