expo-interface 0.1.0 → 0.2.0

package/src/slider/index.android.tsx

@@ -0,0 +1,87 @@
+import type {SliderProps} from './types';
+
+import {useEffect, useRef} from 'react';
+import {Row, Slider as ComposeSlider, Text, useMaterialColors} from '@expo/ui/jetpack-compose';
+import {fillMaxWidth, testID as testIDModifier, weight} from '@expo/ui/jetpack-compose/modifiers';
+import {useColor} from '../theme';
+
+/**
+ * Android renders the Material 3 `Slider`, colored with the live accent seed
+ * (matching the iOS `tint` cascade and the web `accent-color`) instead of the
+ * host's tonal M3 primary. With a `label` the row fills the available width
+ * and the slider takes the remaining space, mirroring the iOS Form row.
+ */
+export function Slider({
+  label,
+  value,
+  onValueChange,
+  onSlidingComplete,
+  min = 0,
+  max = 1,
+  step,
+  disabled,
+  accentColor,
+  testID,
+}: SliderProps) {
+  const colors = useMaterialColors();
+  const tint = useColor('tint');
+  const track = useColor('backgroundSelected');
+  const accent = accentColor ?? tint;
+
+  // Compose `steps` is the number of discrete intervals between min and max
+  // (exclusive); the universal `step` is an increment size.
+  let steps: number | undefined;
+  if (step != null && step > 0) {
+    steps = Math.max(0, Math.round((max - min) / step) - 1);
+  }
+  const snap = (next: number) =>
+    step != null && step > 0 ? Math.round((next - min) / step) * step + min : next;
+
+  // The value the drag last reported: `onValueChangeFinished` fires on
+  // release, which can be before a controlling parent re-renders `value`.
+  const latest = useRef(value);
+  useEffect(() => {
+    latest.current = value;
+  }, [value]);
+
+  const slider = (
+    <ComposeSlider
+      value={value}
+      min={min}
+      max={max}
+      steps={steps}
+      enabled={!disabled}
+      onValueChange={
+        disabled ? undefined : next => {
+          const snapped = snap(next);
+          latest.current = snapped;
+          onValueChange(snapped);
+        }
+      }
+      onValueChangeFinished={onSlidingComplete ? () => onSlidingComplete(latest.current) : undefined}
+      colors={{
+        thumbColor: accent,
+        activeTrackColor: accent,
+        inactiveTrackColor: track,
+        activeTickColor: track,
+        inactiveTickColor: accent,
+      }}
+      modifiers={[
+        ...(label != null ? [weight(1)] : [fillMaxWidth()]),
+        ...(testID ? [testIDModifier(testID)] : []),
+      ]}
+    />
+  );
+
+  if (label == null) return slider;
+
+  return (
+    <Row
+      verticalAlignment="center"
+      horizontalArrangement={{spacedBy: 12}}
+      modifiers={[fillMaxWidth()]}>
+      <Text color={disabled ? colors.onSurfaceVariant : colors.onSurface}>{label}</Text>
+      {slider}
+    </Row>
+  );
+}

package/src/slider/index.ios.tsx

@@ -0,0 +1,64 @@
+import type {SliderProps} from './types';
+import type {ViewModifier} from '@expo/ui/swift-ui/modifiers';
+
+import {useEffect, useRef} from 'react';
+import {HStack, Slider as SwiftUISlider, Text} from '@expo/ui/swift-ui';
+import {disabled as disabledMod, foregroundStyle, tint} from '@expo/ui/swift-ui/modifiers';
+import {useColor} from '../theme';
+
+/**
+ * iOS renders SwiftUI's `Slider`. The Host-level `tint` cascade colors it with
+ * the accent seed; `accentColor` overrides that per instance. With a `label`
+ * the row is an `HStack` of the label and the slider, the Form row look the
+ * other platforms emulate. Drop it straight into a `FieldGroup.Section`.
+ */
+export function Slider({
+  label,
+  value,
+  onValueChange,
+  onSlidingComplete,
+  min = 0,
+  max = 1,
+  step,
+  disabled,
+  accentColor,
+  testID,
+}: SliderProps) {
+  const labelColor = useColor(disabled ? 'secondaryLabel' : 'label');
+  // The value the drag last reported: `onSlidingComplete` fires on release,
+  // which can be before a controlling parent re-renders the `value` prop.
+  const latest = useRef(value);
+  useEffect(() => {
+    latest.current = value;
+  }, [value]);
+  const modifiers: ViewModifier[] = [];
+  if (accentColor) modifiers.push(tint(accentColor));
+  if (disabled) modifiers.push(disabledMod(true));
+
+  const slider = (
+    <SwiftUISlider
+      value={value}
+      min={min}
+      max={max}
+      step={step}
+      onValueChange={next => {
+        latest.current = next;
+        onValueChange(next);
+      }}
+      onEditingChanged={
+        onSlidingComplete ? editing => { if (!editing) onSlidingComplete(latest.current); } : undefined
+      }
+      modifiers={modifiers}
+      testID={testID}
+    />
+  );
+
+  if (label == null) return slider;
+
+  return (
+    <HStack spacing={12}>
+      <Text modifiers={[foregroundStyle(labelColor)]}>{label}</Text>
+      {slider}
+    </HStack>
+  );
+}

package/src/slider/index.tsx

@@ -0,0 +1,55 @@
+import './slider.css';
+import type {ChangeEvent, CSSProperties} from 'react';
+import type {SliderProps} from './types';
+import {StyleSheet, type TextStyle} from 'react-native';
+import {Label} from '../typography';
+import {flatten} from '../theme';
+
+/**
+ * On web the slider is a native `<input type="range">` element themed through
+ * the `accent-color` CSS property, so it reads as a real web control. The row
+ * mirrors the native layout: a label on the leading edge with the track
+ * filling the remaining width.
+ */
+export function Slider({
+  label,
+  value,
+  onValueChange,
+  onSlidingComplete,
+  min = 0,
+  max = 1,
+  step,
+  disabled,
+  accentColor,
+  testID,
+  style,
+}: SliderProps) {
+  const vars = {
+    ...(accentColor ? {'--ui-slider-accent': accentColor} : null),
+    ...flatten(StyleSheet.flatten(style) as TextStyle),
+  } as CSSProperties;
+  const read = (event: ChangeEvent<HTMLInputElement>) => Number(event.target.value);
+  return (
+    <div
+      className={['ui-slider', disabled && 'ui-slider--disabled'].filter(Boolean).join(' ')}
+      style={vars}
+      data-testid={testID}>
+      {label != null ? (
+        <Label color="label" style={{flexShrink: 1}}>{label}</Label>
+      ) : null}
+      <input
+        className="ui-slider__input"
+        type="range"
+        min={min}
+        max={max}
+        step={step ?? 'any'}
+        value={value}
+        disabled={disabled}
+        aria-label={label}
+        onChange={event => onValueChange(read(event))}
+        onPointerUp={event => onSlidingComplete?.(Number(event.currentTarget.value))}
+        onKeyUp={event => onSlidingComplete?.(Number(event.currentTarget.value))}
+      />
+    </div>
+  );
+}

package/src/slider/slider.css

@@ -0,0 +1,30 @@
+.ui-slider {
+  --ui-slider-accent: var(--color-tint);
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  width: 100%;
+}
+
+.ui-slider__label {
+  flex-shrink: 1;
+}
+
+.ui-slider__input {
+  flex: 1;
+  min-width: 96px;
+  height: 22px;
+  margin: 0;
+  cursor: pointer;
+  accent-color: var(--ui-slider-accent);
+}
+
+.ui-slider__input:disabled {
+  cursor: default;
+}
+
+.ui-slider--disabled {
+  opacity: 0.4;
+}

package/src/slider/types.ts

@@ -0,0 +1,39 @@
+import type {StyleProp, ViewStyle} from 'react-native';
+
+/**
+ * Cross-platform slider for picking a value from a continuous or stepped range.
+ *
+ * Bridges the SwiftUI `Slider` on iOS, the Jetpack Compose Material 3 `Slider`
+ * on Android, and the HTML `<input type="range">` element on web. A controlled
+ * control: pair `value` with `onValueChange`.
+ */
+export interface SliderProps {
+  /** Label rendered at the leading edge of the row, mirroring an iOS Form row. */
+  label?: string;
+  /** Current value, between `min` and `max`. */
+  value: number;
+  /** Called continuously while the user drags the thumb. */
+  onValueChange: (value: number) => void;
+  /** Called once when the user releases the thumb. */
+  onSlidingComplete?: (value: number) => void;
+  /**
+   * Minimum value of the range.
+   * @default 0
+   */
+  min?: number;
+  /**
+   * Maximum value of the range.
+   * @default 1
+   */
+  max?: number;
+  /** Increment size. Omit for a continuous slider. */
+  step?: number;
+  /** Disables interaction. */
+  disabled?: boolean;
+  /** Tint applied to the thumb and filled track (overrides the theme accent). */
+  accentColor?: string;
+  /** Identifier used to locate the component in end-to-end tests. */
+  testID?: string;
+  /** Style applied to the row container (web only). */
+  style?: StyleProp<ViewStyle>;
+}

package/src/stepper/index.android.tsx

@@ -0,0 +1,58 @@
+import type {StepperProps} from './types';
+
+import add from '@expo/material-symbols/add.xml';
+import remove from '@expo/material-symbols/remove.xml';
+import {Icon, OutlinedIconButton, Row, Text, useMaterialColors} from '@expo/ui/jetpack-compose';
+import {fillMaxWidth, size, testID as testIDModifier} from '@expo/ui/jetpack-compose/modifiers';
+import {useColor} from '../theme';
+import {clampStep, stepBounds} from './shared';
+
+const BUTTON = 36;
+const ICON = 18;
+
+/**
+ * Jetpack Compose has no stepper control, so Android composes one from two
+ * Material 3 `OutlinedIconButton`s tinted with the live accent, with the
+ * value shown beside them. The row fills the available width and pins the
+ * control to the trailing edge, mirroring the iOS Form row.
+ */
+export function Stepper(props: StepperProps) {
+  const {label, value, onValueChange, step = 1, min, max, formatValue, disabled, testID} = props;
+  const colors = useMaterialColors();
+  const tint = useColor('tint');
+  const {canDecrement, canIncrement} = stepBounds(props);
+  const buttonColors = {
+    contentColor: tint,
+    disabledContentColor: colors.onSurfaceVariant,
+  };
+
+  return (
+    <Row
+      verticalAlignment="center"
+      horizontalArrangement="spaceBetween"
+      modifiers={[fillMaxWidth(), ...(testID ? [testIDModifier(testID)] : [])]}>
+      {label != null ? (
+        <Text color={disabled ? colors.onSurfaceVariant : colors.onSurface}>{label}</Text>
+      ) : null}
+      <Row verticalAlignment="center" horizontalArrangement={{spacedBy: 8}}>
+        <Text color={colors.onSurfaceVariant}>
+          {formatValue ? formatValue(value) : String(value)}
+        </Text>
+        <OutlinedIconButton
+          enabled={canDecrement}
+          colors={buttonColors}
+          onClick={canDecrement ? () => onValueChange(clampStep(value - step, min, max)) : undefined}
+          modifiers={[size(BUTTON, BUTTON)]}>
+          <Icon source={remove} size={ICON} contentDescription="Decrement"/>
+        </OutlinedIconButton>
+        <OutlinedIconButton
+          enabled={canIncrement}
+          colors={buttonColors}
+          onClick={canIncrement ? () => onValueChange(clampStep(value + step, min, max)) : undefined}
+          modifiers={[size(BUTTON, BUTTON)]}>
+          <Icon source={add} size={ICON} contentDescription="Increment"/>
+        </OutlinedIconButton>
+      </Row>
+    </Row>
+  );
+}

package/src/stepper/index.ios.tsx

@@ -0,0 +1,55 @@
+import type {StepperProps} from './types';
+import type {ViewModifier} from '@expo/ui/swift-ui/modifiers';
+
+import {HStack, Spacer, Stepper as SwiftUIStepper, Text} from '@expo/ui/swift-ui';
+import {disabled as disabledMod, foregroundStyle, labelsHidden} from '@expo/ui/swift-ui/modifiers';
+import {fillWidth} from '../fill';
+import {useColor} from '../theme';
+import {clampStep} from './shared';
+
+/**
+ * iOS renders SwiftUI's `Stepper`. Its own label is hidden so the row can be
+ * composed like the other platforms — label leading, value and the `− +`
+ * control trailing — exactly the iOS Settings look. Drop it straight into a
+ * `FieldGroup.Section`.
+ */
+export function Stepper({
+  label,
+  value,
+  onValueChange,
+  step = 1,
+  min,
+  max,
+  formatValue,
+  disabled,
+  testID,
+}: StepperProps) {
+  const labelColor = useColor(disabled ? 'secondaryLabel' : 'label');
+  const valueColor = useColor('secondaryLabel');
+  const modifiers: ViewModifier[] = [labelsHidden()];
+  if (disabled) modifiers.push(disabledMod(true));
+
+  const control = (
+    <SwiftUIStepper
+      label={label ?? ''}
+      value={value}
+      step={step}
+      min={min}
+      max={max}
+      onValueChange={next => onValueChange(clampStep(next, min, max))}
+      modifiers={modifiers}
+      testID={testID}
+    />
+  );
+
+  return (
+    <HStack spacing={12} modifiers={fillWidth}>
+      {label != null ? <Text modifiers={[foregroundStyle(labelColor)]}>{label}</Text> : null}
+      <Spacer/>
+      <Text modifiers={[foregroundStyle(valueColor)]}>
+        {formatValue ? formatValue(value) : String(value)}
+      </Text>
+      {control}
+    </HStack>
+  );
+}

package/src/stepper/index.tsx

@@ -0,0 +1,47 @@
+import './stepper.css';
+import type {CSSProperties} from 'react';
+import type {StepperProps} from './types';
+import {StyleSheet, type TextStyle} from 'react-native';
+import {Label} from '../typography';
+import {flatten} from '../theme';
+import {clampStep, stepBounds} from './shared';
+
+/**
+ * On web the control is two native `<button>` elements in an iOS-style pill,
+ * with the value shown beside them. The row mirrors the native layout: label
+ * on the leading edge, control pinned to the trailing edge.
+ */
+export function Stepper(props: StepperProps) {
+  const {label, value, onValueChange, step = 1, min, max, formatValue, disabled, testID, style} = props;
+  const {canDecrement, canIncrement} = stepBounds(props);
+  const vars = flatten(StyleSheet.flatten(style) as TextStyle) as CSSProperties;
+  return (
+    <div
+      className={['ui-stepper', disabled && 'ui-stepper--disabled'].filter(Boolean).join(' ')}
+      style={vars}
+      data-testid={testID}>
+      {label != null ? <Label color="label" style={{flexShrink: 1}}>{label}</Label> : null}
+      <div className="ui-stepper__control">
+        <Label color="secondaryLabel">{formatValue ? formatValue(value) : String(value)}</Label>
+        <div className="ui-stepper__buttons" role="group" aria-label={label}>
+          <button
+            type="button"
+            className="ui-stepper__button"
+            aria-label="Decrement"
+            disabled={!canDecrement}
+            onClick={() => onValueChange(clampStep(value - step, min, max))}>
+            −
+          </button>
+          <button
+            type="button"
+            className="ui-stepper__button"
+            aria-label="Increment"
+            disabled={!canIncrement}
+            onClick={() => onValueChange(clampStep(value + step, min, max))}>
+            +
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/stepper/shared.ts

@@ -0,0 +1,17 @@
+import type {StepperProps} from './types';
+
+/** Clamps `next` into `[min, max]`, rounding away float drift from repeated steps. */
+export function clampStep(next: number, min?: number, max?: number): number {
+  let value = Math.round(next * 1e6) / 1e6;
+  if (min != null) value = Math.max(min, value);
+  if (max != null) value = Math.min(max, value);
+  return value;
+}
+
+/** Whether each button is pressable given the bounds and disabled state. */
+export function stepBounds({value, min, max, disabled}: StepperProps) {
+  return {
+    canDecrement: !disabled && (min == null || value > min),
+    canIncrement: !disabled && (max == null || value < max),
+  };
+}

package/src/stepper/stepper.css

@@ -0,0 +1,61 @@
+.ui-stepper {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  width: 100%;
+}
+
+.ui-stepper__control {
+  display: inline-flex;
+  flex-shrink: 0;
+  flex-direction: row;
+  align-items: center;
+  gap: 12px;
+}
+
+.ui-stepper__buttons {
+  display: inline-flex;
+  flex-direction: row;
+  border-radius: 8px;
+  background: var(--color-pill-background);
+  overflow: hidden;
+}
+
+.ui-stepper__button {
+  -webkit-appearance: none;
+  appearance: none;
+  width: 42px;
+  height: 30px;
+  margin: 0;
+  padding: 0;
+  border: none;
+  background: transparent;
+  color: var(--color-label);
+  font-family: var(--font-display);
+  font-size: 18px;
+  line-height: 1;
+  cursor: pointer;
+}
+
+.ui-stepper__button + .ui-stepper__button {
+  border-left: 1px solid var(--color-separator);
+}
+
+.ui-stepper__button:hover:not(:disabled) {
+  background: color-mix(in srgb, var(--color-label) 8%, transparent);
+}
+
+.ui-stepper__button:active:not(:disabled) {
+  background: color-mix(in srgb, var(--color-label) 16%, transparent);
+}
+
+.ui-stepper__button:disabled {
+  opacity: 0.35;
+  cursor: default;
+}
+
+.ui-stepper--disabled {
+  opacity: 0.4;
+}

package/src/stepper/types.ts

@@ -0,0 +1,35 @@
+import type {StyleProp, ViewStyle} from 'react-native';
+
+/**
+ * Cross-platform stepper: a numeric value with increment/decrement buttons.
+ *
+ * Bridges the SwiftUI `Stepper` on iOS, a pair of Jetpack Compose Material 3
+ * icon buttons on Android (Compose has no stepper control), and native
+ * `<button>` elements on web. A controlled control: pair `value` with
+ * `onValueChange`.
+ */
+export interface StepperProps {
+  /** Label rendered at the leading edge of the row, mirroring an iOS Form row. */
+  label?: string;
+  /** Current value. */
+  value: number;
+  /** Called with the new value when a button is pressed. */
+  onValueChange: (value: number) => void;
+  /**
+   * Amount added or subtracted per press.
+   * @default 1
+   */
+  step?: number;
+  /** Lower bound; the decrement button disables at this value. */
+  min?: number;
+  /** Upper bound; the increment button disables at this value. */
+  max?: number;
+  /** Formats the displayed value (web/android; iOS shows the raw number). */
+  formatValue?: (value: number) => string;
+  /** Disables interaction. */
+  disabled?: boolean;
+  /** Identifier used to locate the component in end-to-end tests. */
+  testID?: string;
+  /** Style applied to the row container (web only). */
+  style?: StyleProp<ViewStyle>;
+}

package/src/switch/index.tsx

@@ -28,6 +28,8 @@ export function Switch({
       value={value}
       onValueChange={onValueChange}
       disabled={disabled}
+      // The label is a sibling, not a <label>, so name the input directly.
+      accessibilityLabel={label}
       thumbColor={THUMB}
       trackColor={{true: onColor, false: offColor}}
       testID={label == null ? testID : undefined}

package/src/text-field/shared.ts

@@ -53,6 +53,8 @@ export function useTextValue(
 export function useSyncedState(state: ObservableState<string>, value: string | undefined): void {
   useEffect(() => {
     if (value !== undefined && state.value !== value) {
+      // Writing `.value` is the `@expo/ui` observable's API, not a prop mutation.
+      // eslint-disable-next-line react-hooks/immutability
       state.value = value;
     }
   }, [state, value]);

package/src/tooltip/index.android.tsx

@@ -0,0 +1,23 @@
+import type {TooltipProps} from './types';
+
+import {Text, TooltipBox} from '@expo/ui/jetpack-compose';
+import {testID as testIDModifier} from '@expo/ui/jetpack-compose/modifiers';
+import {useColor} from '../theme';
+
+/**
+ * Android renders the Material 3 `TooltipBox` with a `PlainTooltip`: a
+ * long-press on `children` shows the hint, colored like the web hint
+ * (inverse surface) from the theme tokens.
+ */
+export function Tooltip({text, children, testID}: TooltipProps) {
+  const container = useColor('label');
+  const content = useColor('background');
+  return (
+    <TooltipBox modifiers={testID ? [testIDModifier(testID)] : undefined}>
+      <TooltipBox.PlainTooltip containerColor={container} contentColor={content}>
+        <Text color={content}>{text}</Text>
+      </TooltipBox.PlainTooltip>
+      {children}
+    </TooltipBox>
+  );
+}

package/src/tooltip/index.ios.tsx

@@ -0,0 +1,17 @@
+import type {TooltipProps} from './types';
+
+import {Group} from '@expo/ui/swift-ui';
+import {accessibilityHint} from '@expo/ui/swift-ui/modifiers';
+
+/**
+ * iOS has no tooltip idiom (SwiftUI's `help()` is macOS/visionOS only), so
+ * the content renders unchanged inside a `Group` that exposes `text` to
+ * VoiceOver as an accessibility hint.
+ */
+export function Tooltip({text, children, testID}: TooltipProps) {
+  return (
+    <Group modifiers={[accessibilityHint(text)]} testID={testID}>
+      {children}
+    </Group>
+  );
+}

package/src/tooltip/index.tsx

@@ -0,0 +1,41 @@
+import './tooltip.css';
+import type {CSSProperties} from 'react';
+import type {TooltipProps} from './types';
+import {useId} from 'react';
+
+/**
+ * Whether the browser implements the Interest Invoker API (`interestfor`).
+ * When it does, the hint is a real `popover="hint"` (top layer, shown on
+ * hover / focus / long-press, dismissed by the browser); otherwise the
+ * `title` attribute provides the platform tooltip.
+ */
+const INTEREST_SUPPORTED =
+  typeof HTMLButtonElement !== 'undefined' && 'interestForElement' in HTMLButtonElement.prototype;
+
+export function Tooltip({text, children, testID}: TooltipProps) {
+  const ident = `ui-tooltip-${useId().replace(/[^A-Za-z0-9_-]/g, '_')}`;
+  const anchor = `--${ident}`;
+  return (
+    <>
+      <button
+        type="button"
+        className="ui-tooltip"
+        title={INTEREST_SUPPORTED ? undefined : text}
+        style={{anchorName: anchor} as CSSProperties}
+        data-testid={testID}
+        {...(INTEREST_SUPPORTED ? {interestfor: ident} : null)}>
+        {children}
+      </button>
+      {INTEREST_SUPPORTED ? (
+        <div
+          id={ident}
+          role="tooltip"
+          popover="hint"
+          className="ui-tooltip__hint"
+          style={{positionAnchor: anchor} as CSSProperties}>
+          {text}
+        </div>
+      ) : null}
+    </>
+  );
+}