react-native-platform-components 1.4.0 → 1.5.0

package/src/menuItems.ts

@@ -0,0 +1,152 @@
+// menuItems.ts
+//
+// The menu item shape of the library. ContextMenu takes a tree of these
+// actions; native receives them flattened into one list in which each item
+// points at its parent, so menus nest to any depth without a recursive codegen
+// type. Components that show a native menu share this shape and
+// `flattenMenuActions`.
+import type { Haptics } from './haptics';
+import { resolveIcon, type PlatformIcon } from './icons';
+
+/**
+ * Attributes for a menu action.
+ */
+export interface ContextMenuActionAttributes {
+  /** Whether the action is destructive (red styling) */
+  destructive?: boolean;
+  /** Whether the action is disabled (grayed out) */
+  disabled?: boolean;
+  /** Whether the action is hidden */
+  hidden?: boolean;
+  /**
+   * Keeps the menu open after the action is pressed, for steppers and toggles
+   * that update in place (change the action's `title` or `state` in
+   * `onPressAction` and the open menu updates).
+   *
+   * iOS 16+: `UIMenuElement.Attributes.keepsMenuPresented`. Ignored on older
+   * iOS and on Android, where the popup closes on every press.
+   */
+  keepsMenuPresented?: boolean;
+}
+
+/**
+ * A single action in a menu. An action with `subactions` is a submenu, or an
+ * inline section with `displayInline`.
+ */
+export interface ContextMenuAction {
+  /** Unique identifier returned in callbacks */
+  id: string;
+  /** Display title. For an inline section: its header (iOS only; may be empty). */
+  title: string;
+  /** Secondary text (iOS only) */
+  subtitle?: string;
+  /**
+   * Icon. A string is an SF Symbol or asset catalog name on iOS and a
+   * drawable resource name on Android. See {@link PlatformIcon} for image
+   * sources (`require(...)`, `{ uri }`) and per-platform icons.
+   */
+  image?: PlatformIcon;
+  /** Tint color for the icon (hex string, e.g. `'#FF3B30'`) */
+  imageColor?: string;
+  /** Action attributes */
+  attributes?: ContextMenuActionAttributes;
+  /** Checkmark state */
+  state?: 'off' | 'on' | 'mixed';
+  /**
+   * Haptic played when this action is picked, in place of the component's
+   * `haptics` (`'none'` plays nothing). Unset uses the component's. See
+   * {@link Haptics}.
+   */
+  haptics?: Haptics;
+  /** Nested actions: a submenu, or an inline section with `displayInline` */
+  subactions?: readonly ContextMenuAction[];
+  /**
+   * Shows `subactions` inline, as a section set off by separators, instead of
+   * as a submenu.
+   *
+   * - iOS: `UIMenu(options: .displayInline)`; a non-empty `title` is the
+   *   section header.
+   * - Android: a menu group with group dividers; the title is not shown.
+   */
+  displayInline?: boolean;
+}
+
+/**
+ * One menu item as native receives it. Every field is set; empty strings
+ * mean "none" and flags are `'true' | 'false'`. Components declare the same
+ * shape in their codegen spec.
+ */
+export type NativeMenuItem = {
+  id: string;
+  title: string;
+  subtitle: string;
+  /** Index of the parent submenu or section in the list; -1 at the top level */
+  parent: number;
+  /** 'action' | 'menu' | 'section' */
+  kind: string;
+  /** '' | 'sfSymbol' | 'drawable' | 'image' */
+  iconType: string;
+  iconName: string;
+  iconRequest: string;
+  iconUri: string;
+  iconScale: number;
+  iconTinted: string;
+  imageColor: string;
+  destructive: string;
+  disabled: string;
+  keepsMenuPresented: string;
+  /** '' | 'off' | 'on' | 'mixed' */
+  state: string;
+  /** The action's own haptics; '' = the component's */
+  haptics: string;
+};
+
+const flag = (value: boolean | undefined) => (value ? 'true' : 'false');
+
+/**
+ * Flattens an action tree into the list native expects, depth first: a
+ * submenu or section comes before its children, which point back at it
+ * through `parent`. Hidden actions (and their children) are dropped here, so
+ * native never sees them.
+ */
+export function flattenMenuActions(
+  actions: readonly ContextMenuAction[]
+): NativeMenuItem[] {
+  const items: NativeMenuItem[] = [];
+
+  const visit = (list: readonly ContextMenuAction[], parent: number) => {
+    for (const action of list) {
+      const attributes = action.attributes;
+      if (attributes?.hidden) continue;
+
+      const children = action.subactions ?? [];
+      const kind =
+        children.length === 0
+          ? 'action'
+          : action.displayInline
+            ? 'section'
+            : 'menu';
+
+      const index = items.length;
+      items.push({
+        id: action.id,
+        title: action.title,
+        subtitle: action.subtitle ?? '',
+        parent,
+        kind,
+        ...resolveIcon(action.image),
+        imageColor: action.imageColor ?? '',
+        destructive: flag(attributes?.destructive),
+        disabled: flag(attributes?.disabled),
+        keepsMenuPresented: flag(attributes?.keepsMenuPresented),
+        state: action.state ?? '',
+        haptics: action.haptics ?? '',
+      });
+
+      if (kind !== 'action') visit(children, index);
+    }
+  };
+
+  visit(actions, -1);
+  return items;
+}

package/src/selectionIdentifiers.ts

@@ -0,0 +1,17 @@
+/** Diagnose identifiers reserved by the native selection protocol. */
+export function warnSelectionIdentifiers(
+  component: 'SelectionMenu' | 'SegmentedControl',
+  values: readonly string[]
+): void {
+  if (!__DEV__) return;
+  const seen = new Set<string>();
+  for (const [index, value] of values.entries()) {
+    if (value === '' || seen.has(value)) {
+      console.warn(
+        `react-native-platform-components: ${component} requires unique, non-empty ` +
+          `identifiers; item ${index} has ${value === '' ? 'an empty' : 'a duplicate'} identifier.`
+      );
+    }
+    seen.add(value);
+  }
+}

package/src/submitBehavior.ts

@@ -0,0 +1,16 @@
+// submitBehavior.ts
+import type { TextFieldSubmitBehavior } from './TextField';
+
+/**
+ * The return key behavior of a field: `submitBehavior` if set, else
+ * `'newline'` for multi-line fields and `'blurAndSubmit'` otherwise. A
+ * single-line field has no newline to insert, so `'newline'` blurs and
+ * submits there, as on `TextInput`.
+ */
+export function resolveSubmitBehavior(
+  submitBehavior: TextFieldSubmitBehavior | undefined,
+  multiline: boolean | undefined
+): TextFieldSubmitBehavior {
+  if (multiline) return submitBehavior ?? 'newline';
+  return submitBehavior === 'submit' ? 'submit' : 'blurAndSubmit';
+}

package/src/tabItems.ts

@@ -0,0 +1,113 @@
+// tabItems.ts
+//
+// The tab model of TabBar, and its flattening into the fields the native
+// specs take. Kept apart from the bar so other navigation components can
+// share it.
+import type { TabBarItem as NativeItem } from './TabBarNativeComponent';
+import { resolveIcon, type PlatformIcon } from './icons';
+
+/**
+ * A system tab item on iOS (`UITabBarItem.SystemItem`), with the system's
+ * localized title and icon.
+ */
+export type TabBarSystemItem =
+  | 'bookmarks'
+  | 'contacts'
+  | 'downloads'
+  | 'favorites'
+  | 'featured'
+  | 'history'
+  | 'more'
+  | 'mostRecent'
+  | 'mostViewed'
+  | 'recents'
+  | 'search'
+  | 'topRated';
+
+export interface TabBarItemProps {
+  /**
+   * Tab label. Also the screen-reader label unless `accessibilityLabel` is
+   * set. iOS system items (`role: 'search'`, `systemItem`) show the system's
+   * title instead.
+   */
+  label: string;
+
+  /** Unique value returned in callbacks. */
+  value: string;
+
+  /** Tab icon. See {@link PlatformIcon}. */
+  icon?: PlatformIcon;
+
+  /**
+   * Icon of the selected tab, e.g. the filled variant of an SF Symbol
+   * (`house.fill`). Defaults to `icon`.
+   */
+  selectedIcon?: PlatformIcon;
+
+  /**
+   * Badge on the tab, e.g. an unread count. Numbers are shown as-is; an
+   * empty string shows a dot; `undefined` hides the badge.
+   */
+  badge?: string | number;
+
+  /** Whether the tab can be selected. */
+  disabled?: boolean;
+
+  /** Screen-reader label. Defaults to `label`. */
+  accessibilityLabel?: string;
+
+  /** Test identifier of the tab, for E2E taps. */
+  testID?: string;
+
+  /**
+   * `'search'`: the app's search tab.
+   *
+   * - iOS: the system search item, with its localized title and magnifying
+   *   glass. iOS 26 sets it apart from the other tabs, as its own glass
+   *   circle at the end of the bar.
+   * - Android: a regular tab, with a search icon unless `icon` is set.
+   */
+  role?: 'search';
+
+  /**
+   * iOS: a system item (`UITabBarItem.SystemItem`) with the system's
+   * localized title and icon, in place of `label` and `icon`. Android
+   * has no system items and shows `label` and `icon`.
+   */
+  systemItem?: TabBarSystemItem;
+}
+
+/** Material and iOS tab bars show at most five tabs on a phone. */
+export const MAX_TAB_ITEMS = 5;
+
+/** The tabs as the native specs take them, at most `max`. */
+export function toNativeTabItems(
+  items: readonly TabBarItemProps[],
+  max: number = MAX_TAB_ITEMS
+): NativeItem[] {
+  return items.slice(0, max).map((item) => {
+    const icon = resolveIcon(item.icon);
+    const selected = resolveIcon(item.selectedIcon);
+    return {
+      label: item.label,
+      value: item.value,
+      disabled: item.disabled ? 'disabled' : 'enabled',
+      ...icon,
+      selectedIconType: selected.iconType,
+      selectedIconName: selected.iconName,
+      selectedIconRequest: selected.iconRequest,
+      selectedIconUri: selected.iconUri,
+      selectedIconScale: selected.iconScale,
+      selectedIconTinted: selected.iconTinted,
+      badge:
+        item.badge === undefined || item.badge === null
+          ? ''
+          : // An empty badge is a dot; native tells it from none by a space
+            String(item.badge) || ' ',
+      accessibilityLabel: item.accessibilityLabel ?? '',
+      testID: item.testID ?? '',
+      role: item.role ?? '',
+      systemItem: item.systemItem ?? '',
+    };
+  });
+}

package/src/web/Button.tsx

@@ -0,0 +1,201 @@
+// web/Button.tsx
+import React, { useEffect, useRef } from 'react';
+import { View } from 'react-native';
+
+import type { ButtonProps } from '../Button';
+import { Icon } from './Icon';
+import {
+  BUTTON_BASE,
+  BUTTON_SIZES,
+  buttonColors,
+  cssColor,
+  cssFont,
+  usePrimaryColor,
+  warnOnce,
+} from './shared';
+
+/** The Web Animations API surface the spinner uses (no DOM lib here). */
+type AnimatableElement = {
+  animate?: (
+    keyframes: object[],
+    options: { duration: number; iterations: number }
+  ) => { cancel: () => void };
+};
+
+/**
+ * A `<button>`, styled after the Material 3 button variants. A toggle
+ * (`selected`) sets `aria-pressed` and takes the filled look when selected.
+ * Browsers have no native menu, so a button with a `menu` calls `onPress`.
+ */
+export function Button(props: ButtonProps): React.ReactElement {
+  const {
+    label,
+    icon,
+    iconPosition = 'leading',
+    variant = 'filled',
+    size = 'small',
+    shape = 'round',
+    cornerRadius,
+    disabled,
+    loading,
+    color,
+    tintColor,
+    disabledColor,
+    disabledTintColor,
+    labelStyle,
+    // Browsers scale text with page zoom, which has no cap
+    maxFontSizeMultiplier: _maxFontSizeMultiplier,
+    accessibilityLabel,
+    onPress,
+    selected,
+    onSelectedChange,
+    menu,
+    onMenuSelect: _onMenuSelect,
+    onMenuOpen: _onMenuOpen,
+    onMenuClose: _onMenuClose,
+    // SF Symbols don't exist on the web
+    ios: _ios,
+    android,
+    style,
+    ...viewProps
+  } = props;
+
+  if (menu && menu.length > 0) {
+    warnOnce(
+      'Button.menu',
+      'Button menus have no web implementation; the button calls onPress instead. ' +
+        'See https://jarx-concepts.github.io/react-native-platform-components/guides/web'
+    );
+  }
+
+  const isToggle = selected !== undefined;
+  const primary = usePrimaryColor();
+  const metrics = BUTTON_SIZES[size] ?? BUTTON_SIZES.small!;
+  // A toggle is filled when selected; a filled toggle is tonal when not, as
+  // Material's toggle buttons are
+  const look = !isToggle
+    ? variant
+    : selected
+      ? 'filled'
+      : variant === 'filled'
+        ? 'tonal'
+        : variant;
+  const colors = buttonColors(
+    look,
+    primary,
+    isToggle && selected ? undefined : cssColor(color),
+    isToggle && selected ? undefined : cssColor(tintColor)
+  );
+  const vertical = iconPosition === 'top' || iconPosition === 'bottom';
+  const direction = (
+    {
+      leading: 'row',
+      trailing: 'row-reverse',
+      top: 'column',
+      bottom: 'column-reverse',
+    } as const
+  )[iconPosition];
+
+  const handleClick = () => {
+    if (isToggle) onSelectedChange?.(!selected);
+    onPress?.();
+  };
+  // Custom disabled colors replace the default faded look.
+  const customDisabled =
+    disabled &&
+    (disabledColor !== undefined || disabledTintColor !== undefined);
+  if (disabled) {
+    if (disabledColor !== undefined) {
+      colors.backgroundColor = cssColor(disabledColor);
+    }
+    if (disabledTintColor !== undefined) {
+      colors.color = cssColor(disabledTintColor);
+    }
+  }
+
+  const iconElement = (
+    <Icon icon={icon} color={colors.color as string | undefined} />
+  );
+
+  // The Web Animations API spins the indicator without a stylesheet.
+  const spinnerRef = useRef<AnimatableElement | null>(null);
+  useEffect(() => {
+    const spinner = spinnerRef.current;
+    if (!loading || !spinner?.animate) return undefined;
+    const animation = spinner.animate(
+      [{ transform: 'rotate(0deg)' }, { transform: 'rotate(360deg)' }],
+      { duration: 800, iterations: Infinity }
+    );
+    return () => animation.cancel();
+  }, [loading]);
+  const spinnerSize = Math.round(metrics.fontSize * 1.3);
+
+  return (
+    <View {...viewProps} style={[{ alignSelf: 'flex-start' }, style]}>
+      <button
+        type="button"
+        disabled={disabled}
+        aria-label={accessibilityLabel ?? label}
+        aria-busy={loading || undefined}
+        aria-pressed={isToggle ? !!selected : undefined}
+        onClick={loading ? undefined : handleClick}
+        style={{
+          ...BUTTON_BASE,
+          ...colors,
+          // An icon above or below the label makes the button taller
+          ...(vertical
+            ? { minHeight: metrics.height, gap: 4 }
+            : { height: metrics.height }),
+          minWidth: metrics.height,
+          padding: label ? `${vertical ? 8 : 0}px ${metrics.padding}px` : 0,
+          flexDirection: direction,
+          borderRadius:
+            cornerRadius ?? (shape === 'square' ? 12 : metrics.height / 2),
+          fontSize: metrics.fontSize,
+          opacity: disabled && !customDisabled ? 0.38 : 1,
+          cursor: disabled || loading ? 'default' : 'pointer',
+          position: 'relative',
+          ...cssFont(labelStyle),
+        }}
+      >
+        {!loading && iconElement}
+        {!loading && label}
+        {loading && (
+          <>
+            {/* Hidden, not removed, so the button keeps its width */}
+            <span
+              style={{
+                display: 'inline-flex',
+                alignItems: 'center',
+                gap: BUTTON_BASE.gap,
+                flexDirection: 'inherit',
+                visibility: 'hidden',
+              }}
+            >
+              {iconElement}
+              {label}
+            </span>
+            <span
+              ref={(element) => {
+                spinnerRef.current = element as unknown as AnimatableElement;
+              }}
+              aria-hidden
+              style={{
+                position: 'absolute',
+                top: '50%',
+                left: '50%',
+                width: spinnerSize,
+                height: spinnerSize,
+                margin: -spinnerSize / 2,
+                boxSizing: 'border-box',
+                borderRadius: '50%',
+                border: `2px solid ${colors.color ?? 'currentColor'}`,
+                borderTopColor: 'transparent',
+              }}
+            />
+          </>
+        )}
+      </button>
+    </View>
+  );
+}

package/src/web/ButtonGroup.tsx

@@ -0,0 +1,154 @@
+// web/ButtonGroup.tsx
+import React from 'react';
+import { View } from 'react-native';
+
+import type { ButtonGroupProps } from '../ButtonGroup';
+import { Icon } from './Icon';
+import {
+  BUTTON_BASE,
+  BUTTON_SIZES,
+  buttonColors,
+  cssColor,
+  cssFont,
+  usePrimaryColor,
+} from './shared';
+
+/**
+ * The selection after pressing `value`, in button order. Mirrors the native
+ * rules: `single` swaps the selection, `multiple` toggles, and a required
+ * selection never becomes empty.
+ */
+export function nextSelection(
+  values: readonly string[],
+  selected: readonly string[],
+  value: string,
+  selection: 'single' | 'multiple',
+  required: boolean
+): string[] {
+  const isSelected = selected.includes(value);
+  let next: string[];
+  if (selection === 'single') {
+    next = isSelected ? [] : [value];
+  } else {
+    next = isSelected
+      ? selected.filter((v) => v !== value)
+      : [...selected, value];
+  }
+  if (required && next.length === 0) return [...selected];
+  return values.filter((v) => next.includes(v));
+}
+
+/** A row of `<button>`s, with toggle semantics when `selection` is set. */
+export function ButtonGroup(props: ButtonGroupProps): React.ReactElement {
+  const {
+    buttons,
+    variant = 'outlined',
+    size = 'small',
+    shape = 'round',
+    connected: connectedProp,
+    spacing,
+    selection = 'none',
+    selectedValues = [],
+    selectionRequired,
+    disabled,
+    color,
+    tintColor,
+    labelStyle,
+    overflow,
+    onPress,
+    onSelectionChange,
+    android,
+    style,
+    ...viewProps
+  } = props;
+
+  const primary = usePrimaryColor();
+  const metrics = BUTTON_SIZES[size] ?? BUTTON_SIZES.small!;
+  const selectable = selection !== 'none';
+  const connected = connectedProp ?? selectable;
+  const required = selectionRequired ?? selection === 'single';
+  const selected =
+    selection === 'single' ? selectedValues.slice(0, 1) : selectedValues;
+  const radius = shape === 'square' ? 12 : metrics.height / 2;
+  const innerRadius = 8;
+  const gap = spacing ?? (connected ? 2 : 8);
+  // Browsers have no overflow menu; 'wrap' wraps the row
+  const wrap = (overflow ?? android?.overflow) === 'wrap';
+
+  const handlePress = (value: string, index: number) => {
+    onPress?.(value, index);
+    if (selection === 'none') return;
+    const next = nextSelection(
+      buttons.map((b) => b.value),
+      selected,
+      value,
+      selection,
+      required
+    );
+    const changed =
+      next.length !== selected.length ||
+      next.some((v) => !selected.includes(v));
+    if (changed) onSelectionChange?.(next);
+  };
+
+  return (
+    <View
+      {...viewProps}
+      role={selection === 'single' ? 'radiogroup' : 'group'}
+      style={[
+        {
+          flexDirection: 'row',
+          flexWrap: wrap ? 'wrap' : 'nowrap',
+          gap,
+          alignSelf: 'flex-start',
+        },
+        style,
+      ]}
+    >
+      {buttons.map((button, index) => {
+        const isSelected = selectable && selected.includes(button.value);
+        const isDisabled = disabled || button.disabled;
+        const colors = buttonColors(
+          isSelected ? 'filled' : variant,
+          primary,
+          isSelected ? undefined : cssColor(color),
+          isSelected ? undefined : cssColor(tintColor)
+        );
+        const first = index === 0;
+        const last = index === buttons.length - 1;
+        const start = !connected || first ? radius : innerRadius;
+        const end = !connected || last ? radius : innerRadius;
+        return (
+          <button
+            key={button.value}
+            type="button"
+            disabled={isDisabled}
+            role={selection === 'single' ? 'radio' : undefined}
+            aria-checked={selection === 'single' ? isSelected : undefined}
+            aria-pressed={selection === 'multiple' ? isSelected : undefined}
+            aria-label={button.accessibilityLabel ?? button.label}
+            onClick={() => handlePress(button.value, index)}
+            style={{
+              ...BUTTON_BASE,
+              ...colors,
+              height: metrics.height,
+              minWidth: metrics.height,
+              padding: button.label ? `0 ${metrics.padding}px` : 0,
+              borderRadius: `${start}px ${end}px ${end}px ${start}px`,
+              fontSize: metrics.fontSize,
+              opacity: isDisabled ? 0.38 : 1,
+              cursor: isDisabled ? 'default' : 'pointer',
+              ...cssFont(labelStyle),
+            }}
+          >
+            <Icon
+              icon={button.icon}
+              color={colors.color as string | undefined}
+            />
+            {button.label}
+          </button>
+        );
+      })}
+    </View>
+  );
+}