react-native-tinyui 0.5.0 → 1.0.0

package/src/SFSymbol/options.ts

@@ -0,0 +1,116 @@
+import { processColor } from 'react-native';
+
+import type { SFSymbolEffect, SFSymbolProps } from './types';
+
+function finite(name: string, value: number | undefined, minimum: number) {
+  if (value !== undefined && (!Number.isFinite(value) || value < minimum)) {
+    throw new RangeError(
+      `[TinyUI] SFSymbol ${name} must be finite and >= ${minimum}.`
+    );
+  }
+}
+
+function positive(name: string, value: number | undefined) {
+  finite(name, value, 0);
+  if (value === 0) {
+    throw new RangeError(`[TinyUI] SFSymbol ${name} must be greater than 0.`);
+  }
+}
+
+export function serializeSFSymbol(props: SFSymbolProps, fontScale: number) {
+  positive('size', props.size);
+  finite('variableValue', props.variableValue, 0);
+  if (props.variableValue !== undefined && props.variableValue > 1) {
+    throw new RangeError('[TinyUI] SFSymbol variableValue must be <= 1.');
+  }
+  if (props.maxFontSizeMultiplier !== 0) {
+    finite('maxFontSizeMultiplier', props.maxFontSizeMultiplier, 1);
+  }
+  if (
+    props.paletteColors &&
+    (props.paletteColors.length < 1 ||
+      props.paletteColors.length > 3 ||
+      props.paletteColors.some((color) => color === undefined))
+  ) {
+    throw new RangeError(
+      '[TinyUI] SFSymbol paletteColors needs 1 to 3 colors.'
+    );
+  }
+
+  const effects: readonly SFSymbolEffect[] = props.effect
+    ? Array.isArray(props.effect)
+      ? props.effect
+      : [props.effect as SFSymbolEffect]
+    : [];
+  const types = new Set<string>();
+  for (const effect of effects) {
+    if (types.has(effect.type)) {
+      throw new Error(
+        `[TinyUI] SFSymbol has duplicate ${effect.type} effects.`
+      );
+    }
+    types.add(effect.type);
+    positive('effect.options.speed', effect.options?.speed);
+    finite('effect.options.repeatDelay', effect.options?.repeatDelay, 0);
+    const repeat = effect.options?.repeat;
+    if (typeof repeat === 'number') {
+      positive('effect.options.repeat', repeat);
+      if (!Number.isSafeInteger(repeat)) {
+        throw new RangeError(
+          '[TinyUI] SFSymbol repeat must be a safe integer.'
+        );
+      }
+    }
+    if (
+      effect.options?.repeatBehavior === 'continuous' &&
+      ((repeat !== undefined && repeat !== 'forever') ||
+        effect.options.repeatDelay !== undefined)
+    ) {
+      throw new Error(
+        '[TinyUI] SFSymbol continuous repetition cannot have a count or delay.'
+      );
+    }
+    if (
+      effect.type === 'wiggle' &&
+      effect.angle !== undefined &&
+      !Number.isFinite(effect.angle)
+    ) {
+      throw new RangeError('[TinyUI] SFSymbol wiggle angle must be finite.');
+    }
+    if (
+      typeof effect.trigger === 'number' &&
+      !Number.isFinite(effect.trigger)
+    ) {
+      throw new RangeError('[TinyUI] SFSymbol effect trigger must be finite.');
+    }
+  }
+  positive('contentTransition.speed', props.contentTransition?.speed);
+
+  return {
+    configuration: {
+      name: props.name,
+      source: props.source ?? 'system',
+      size: props.size ?? 17,
+      weight: props.weight ?? 'unspecified',
+      scale: props.scale ?? 'default',
+      textStyle: props.textStyle,
+      fontFamily: props.fontFamily,
+      fontScale:
+        props.allowFontScaling === false
+          ? 1
+          : Math.min(fontScale, props.maxFontSizeMultiplier || Infinity),
+      renderingMode: props.renderingMode ?? 'automatic',
+      color: props.color === undefined ? undefined : processColor(props.color),
+      paletteColors: props.paletteColors?.map((color) => processColor(color)),
+      variableValue: props.variableValue,
+      variableValueMode: props.variableValueMode ?? 'automatic',
+      colorRenderingMode: props.colorRenderingMode ?? 'automatic',
+    },
+    effects: effects.map((effect) => ({
+      ...effect,
+      active: effect.active ?? true,
+      animated: effect.animated ?? true,
+    })),
+    contentTransition: props.contentTransition ?? {},
+  };
+}

package/src/SFSymbol/types.ts

@@ -0,0 +1,158 @@
+import type { ColorValue, ViewProps } from 'react-native';
+
+export type SFSymbolWeight =
+  | 'unspecified'
+  | 'ultraLight'
+  | 'thin'
+  | 'light'
+  | 'regular'
+  | 'medium'
+  | 'semibold'
+  | 'bold'
+  | 'heavy'
+  | 'black';
+
+export type SFSymbolScale =
+  'default' | 'unspecified' | 'small' | 'medium' | 'large';
+export type SFSymbolRenderingMode =
+  'automatic' | 'monochrome' | 'hierarchical' | 'palette' | 'multicolor';
+export type SFSymbolTextStyle =
+  | 'extraLargeTitle'
+  | 'extraLargeTitle2'
+  | 'largeTitle'
+  | 'title1'
+  | 'title2'
+  | 'title3'
+  | 'headline'
+  | 'subheadline'
+  | 'body'
+  | 'callout'
+  | 'footnote'
+  | 'caption1'
+  | 'caption2';
+
+export interface SFSymbolEffectOptions {
+  /** Positive speed multiplier. Defaults to the system speed (1). */
+  speed?: number;
+  /** Play count, forever, or false for one play. Omit for the system default. */
+  repeat?: number | 'forever' | false;
+  /** iOS 18+. Continuous repeats forever; periodic supports count and delay. */
+  repeatBehavior?: 'periodic' | 'continuous';
+  /** Seconds between periodic repetitions (iOS 18+). */
+  repeatDelay?: number;
+}
+
+interface EffectPlayback {
+  /** Whether this effect is applied. Defaults to true. */
+  active?: boolean;
+  /** Change this value to replay the same effect. Stable values do not replay. */
+  trigger?: string | number;
+  /** Animate applying/removing the effect. Defaults to true. */
+  animated?: boolean;
+  options?: SFSymbolEffectOptions;
+}
+
+type LayerBehavior = 'byLayer' | 'wholeSymbol';
+type VerticalDirection = 'up' | 'down';
+
+/** Only modifiers supported by each Apple preset are accepted. */
+export type SFSymbolEffect = EffectPlayback &
+  (
+    | { type: 'pulse'; scope?: LayerBehavior }
+    | {
+        type: 'bounce' | 'scale' | 'appear' | 'disappear';
+        direction?: VerticalDirection;
+        scope?: LayerBehavior;
+      }
+    | {
+        type: 'variableColor';
+        iteration?: 'iterative' | 'cumulative';
+        reversing?: boolean;
+        inactiveLayers?: 'hide' | 'dim';
+      }
+    | {
+        /** iOS 18+. */
+        type: 'wiggle';
+        direction?:
+          | VerticalDirection
+          | 'left'
+          | 'right'
+          | 'forward'
+          | 'backward'
+          | 'clockwise'
+          | 'counterClockwise';
+        /** Custom angle in degrees, clockwise from +x; overrides direction. */
+        angle?: number;
+        scope?: LayerBehavior;
+      }
+    | {
+        /** iOS 18+. */
+        type: 'rotate';
+        direction?: 'clockwise' | 'counterClockwise';
+        scope?: LayerBehavior;
+      }
+    | {
+        /** iOS 18+. */
+        type: 'breathe';
+        style?: 'plain' | 'pulse';
+        scope?: LayerBehavior;
+      }
+    | {
+        /** iOS 26+. */
+        type: 'drawOn';
+        scope?: LayerBehavior | 'individually';
+      }
+    | {
+        /** iOS 26+. */
+        type: 'drawOff';
+        scope?: LayerBehavior | 'individually';
+        reversed?: boolean;
+      }
+  );
+
+export interface SFSymbolContentTransition {
+  /** Magic Replace requires iOS 18; earlier versions use the configured replace. */
+  type: 'automatic' | 'replace' | 'magicReplace';
+  /** Replace style, also used as the Magic Replace fallback. */
+  direction?: 'downUp' | 'upUp' | 'offUp';
+  scope?: LayerBehavior;
+  /** Positive transition speed multiplier. Defaults to 1. */
+  speed?: number;
+}
+
+export interface SFSymbolProps extends Omit<ViewProps, 'children'> {
+  /** Full SF Symbol name, including variants such as .circle.fill. */
+  name: string;
+  /** Load a system symbol (default) or a custom symbol in the app asset catalog. */
+  source?: 'system' | 'asset';
+  /** Point size before font scaling. Defaults to 17. textStyle takes precedence. */
+  size?: number;
+  weight?: SFSymbolWeight;
+  scale?: SFSymbolScale;
+  textStyle?: SFSymbolTextStyle;
+  /** Font/PostScript name used to derive the symbol's font metrics. */
+  fontFamily?: string;
+  /** Apply React Native's fontScale to the point size. Defaults to true. */
+  allowFontScaling?: boolean;
+  /** Maximum font scale, >= 1. Zero/undefined means no limit. */
+  maxFontSizeMultiplier?: number;
+  renderingMode?: SFSymbolRenderingMode;
+  /** Tint / primary hierarchical color. Defaults to the semantic label color. */
+  color?: ColorValue;
+  /** One to three colors for palette rendering, in primary-to-tertiary order. */
+  paletteColors?: readonly [ColorValue, ColorValue?, ColorValue?];
+  /** Variable color/draw progress, from 0 to 1. Omit for the symbol default. */
+  variableValue?: number;
+  /** iOS 26+. Earlier versions retain the system's variable color behavior. */
+  variableValueMode?: 'automatic' | 'color' | 'draw';
+  /** iOS 26+. Earlier versions use flat colors. */
+  colorRenderingMode?: 'automatic' | 'flat' | 'gradient';
+  /** Native image fitting within an explicitly sized frame. Defaults to center. */
+  resizeMode?: 'center' | 'contain' | 'cover' | 'stretch';
+  /** One preset or multiple distinct presets. Unsupported OS presets are ignored. */
+  effect?: SFSymbolEffect | readonly SFSymbolEffect[];
+  /** Animate changes to the name or image configuration. Omit to update instantly. */
+  contentTransition?: SFSymbolContentTransition;
+  /** Honor the system Reduce Motion setting. Defaults to true. */
+  respectReduceMotion?: boolean;
+}

package/src/Stepper/StepperNativeComponent.ts

@@ -0,0 +1,29 @@
+import {
+  codegenNativeComponent,
+  type CodegenTypes,
+  type ViewProps,
+} from 'react-native';
+
+type StepperChangeEvent = Readonly<{
+  value: CodegenTypes.Double;
+  eventCount: CodegenTypes.Int32;
+}>;
+
+export interface NativeStepperProps extends ViewProps {
+  value?: CodegenTypes.WithDefault<CodegenTypes.Double, 0>;
+  minimumValue?: CodegenTypes.WithDefault<CodegenTypes.Double, 0>;
+  maximumValue?: CodegenTypes.WithDefault<CodegenTypes.Double, 100>;
+  stepValue?: CodegenTypes.WithDefault<CodegenTypes.Double, 1>;
+  isContinuous?: CodegenTypes.WithDefault<boolean, true>;
+  autorepeat?: CodegenTypes.WithDefault<boolean, true>;
+  wraps?: CodegenTypes.WithDefault<boolean, false>;
+  disabled?: CodegenTypes.WithDefault<boolean, false>;
+  controlled?: CodegenTypes.WithDefault<boolean, false>;
+  mostRecentEventCount?: CodegenTypes.WithDefault<CodegenTypes.Int32, 0>;
+  // Match the bubbling topChange event inherited from React Native's base view.
+  onChange?: CodegenTypes.BubblingEventHandler<StepperChangeEvent>;
+}
+
+export default codegenNativeComponent<NativeStepperProps>('TinyuiStepperView', {
+  excludedPlatforms: ['android'],
+});

package/src/Stepper/index.tsx

@@ -0,0 +1,91 @@
+import { forwardRef, useState, type ComponentRef } from 'react';
+import { StyleSheet, type View } from 'react-native';
+
+import { assertComponentEnabled } from '../utils';
+import NativeStepperView from './StepperNativeComponent';
+import type { StepperProps } from './types';
+
+export const Stepper = forwardRef<ComponentRef<typeof View>, StepperProps>(
+  function StepperRoot(
+    {
+      value,
+      defaultValue = 0,
+      minimumValue = 0,
+      maximumValue = 100,
+      stepValue = 1,
+      isContinuous = true,
+      autorepeat = true,
+      wraps = false,
+      disabled,
+      onValueChange,
+      style,
+      accessibilityState,
+      ...viewProps
+    },
+    ref
+  ) {
+    assertComponentEnabled('Stepper');
+
+    const [initialValue] = useState(defaultValue);
+    const [mostRecentEventCount, setMostRecentEventCount] = useState(0);
+    const resolvedValue = value ?? initialValue;
+    const resolvedDisabled = disabled ?? accessibilityState?.disabled ?? false;
+
+    for (const [name, number] of Object.entries({
+      value: resolvedValue,
+      minimumValue,
+      maximumValue,
+      stepValue,
+    })) {
+      if (!Number.isFinite(number)) {
+        throw new RangeError(
+          `[TinyUI] Stepper ${name} must be a finite number.`
+        );
+      }
+    }
+    if (maximumValue < minimumValue) {
+      throw new RangeError(
+        '[TinyUI] Stepper maximumValue must be greater than or equal to minimumValue.'
+      );
+    }
+    if (stepValue <= 0) {
+      throw new RangeError(
+        '[TinyUI] Stepper stepValue must be greater than 0.'
+      );
+    }
+
+    return (
+      <NativeStepperView
+        {...viewProps}
+        ref={ref}
+        accessibilityState={{
+          ...accessibilityState,
+          disabled: resolvedDisabled,
+        }}
+        autorepeat={autorepeat}
+        isContinuous={isContinuous}
+        controlled={value !== undefined}
+        disabled={resolvedDisabled}
+        maximumValue={maximumValue}
+        minimumValue={minimumValue}
+        mostRecentEventCount={mostRecentEventCount}
+        onChange={(event) => {
+          // Acknowledge every event, even if the parent rejects a controlled
+          // change by keeping the same value. Native ignores stale replies.
+          setMostRecentEventCount(event.nativeEvent.eventCount);
+          onValueChange?.(event.nativeEvent.value);
+        }}
+        stepValue={stepValue}
+        style={[styles.stepper, style]}
+        value={Math.min(maximumValue, Math.max(minimumValue, resolvedValue))}
+        wraps={wraps}
+      />
+    );
+  }
+);
+
+const styles = StyleSheet.create({
+  stepper: { alignSelf: 'flex-start' },
+});
+
+export type { StepperProps } from './types';

package/src/Stepper/types.ts

@@ -0,0 +1,24 @@
+import type { ViewProps } from 'react-native';
+
+export interface StepperProps extends Omit<ViewProps, 'children'> {
+  /** Controlled value. Update it from onValueChange to accept user changes. */
+  value?: number;
+  /** Initial uncontrolled value. Defaults to 0. */
+  defaultValue?: number;
+  /** Lower bound. Defaults to 0. */
+  minimumValue?: number;
+  /** Upper bound, greater than or equal to minimumValue. Defaults to 100. */
+  maximumValue?: number;
+  /** Positive increment/decrement amount. Defaults to 1. */
+  stepValue?: number;
+  /** Emit changes while interacting, rather than only on release. Defaults to true. */
+  isContinuous?: boolean;
+  /** Repeatedly step while holding either button. Defaults to true. */
+  autorepeat?: boolean;
+  /** Wrap between the bounds instead of stopping at them. Defaults to false. */
+  wraps?: boolean;
+  /** Disable user interaction. Defaults to false. */
+  disabled?: boolean;
+  /** Called with the new value after a user interaction. */
+  onValueChange?: (value: number) => void;
+}

package/src/TipKit/Popover.tsx

@@ -0,0 +1,87 @@
+import { forwardRef, type ComponentRef } from 'react';
+import { View } from 'react-native';
+
+import { assertComponentEnabled } from '../utils';
+import NativeTipPopoverView from './TipPopoverNativeComponent';
+import type { TipPopoverProps, TipStatus } from './types';
+import { validateTip } from './validation';
+
+export const Popover = forwardRef<ComponentRef<typeof View>, TipPopoverProps>(
+  function TipPopoverRoot(props, ref) {
+    assertComponentEnabled('TipKit');
+    validateTip(props);
+    const {
+      children,
+      tipId,
+      title,
+      message,
+      systemImage,
+      actions,
+      enabled = true,
+      maxDisplayCount,
+      ignoresDisplayFrequency = false,
+      arrowEdge = 'auto',
+      onStatusChange,
+      onVisibleChange,
+      onActionPress,
+      onError,
+      ...viewProps
+    } = props;
+
+    return (
+      <NativeTipPopoverView
+        {...viewProps}
+        ref={ref}
+        collapsable={false}
+        tipId={tipId}
+        title={title}
+        message={message}
+        systemImage={systemImage}
+        actions={actions}
+        enabled={enabled}
+        maxDisplayCount={maxDisplayCount ?? 0}
+        ignoresDisplayFrequency={ignoresDisplayFrequency}
+        arrowEdge={arrowEdge}
+        onTipStatusChange={({ nativeEvent }) => {
+          if (nativeEvent.tipId !== tipId) return;
+          if (nativeEvent.status === 'invalidated') {
+            onStatusChange?.({
+              status: 'invalidated',
+              reason: nativeEvent.reason,
+            } as TipStatus);
+          } else if (
+            nativeEvent.status === 'pending' ||
+            nativeEvent.status === 'available'
+          ) {
+            onStatusChange?.({ status: nativeEvent.status });
+          }
+        }}
+        onTipVisibleChange={({ nativeEvent }) => {
+          if (nativeEvent.tipId === tipId)
+            onVisibleChange?.(nativeEvent.visible);
+        }}
+        onTipAction={({ nativeEvent }) => {
+          if (nativeEvent.tipId === tipId) {
+            onActionPress?.({ id: nativeEvent.id, title: nativeEvent.title });
+          }
+        }}
+        onTipError={({ nativeEvent }) => {
+          if (nativeEvent.tipId !== tipId) return;
+          const error = {
+            code: nativeEvent.code,
+            message: nativeEvent.message,
+          };
+          if (onError) onError(error);
+          else
+            console.warn(
+              `[TinyUI] TipKit.Popover ${error.code}: ${error.message}`
+            );
+        }}
+      >
+        <View collapsable={false}>{children}</View>
+      </NativeTipPopoverView>
+    );
+  }
+);
+
+Popover.displayName = 'TipKit.Popover';

package/src/TipKit/TipPopoverNativeComponent.ts

@@ -0,0 +1,37 @@
+import {
+  codegenNativeComponent,
+  type CodegenTypes,
+  type ViewProps,
+} from 'react-native';
+import type { DirectEventHandler } from 'react-native/Libraries/Types/CodegenTypes';
+
+export interface NativeTipPopoverProps extends ViewProps {
+  tipId: string;
+  title: string;
+  message?: string;
+  systemImage?: string;
+  actions?: ReadonlyArray<Readonly<{ id: string; title: string }>>;
+  enabled?: boolean;
+  maxDisplayCount?: CodegenTypes.Int32;
+  ignoresDisplayFrequency?: boolean;
+  arrowEdge?: string;
+  onTipStatusChange?: DirectEventHandler<
+    Readonly<{ tipId: string; status: string; reason: string }>
+  >;
+  onTipVisibleChange?: DirectEventHandler<
+    Readonly<{ tipId: string; visible: boolean }>
+  >;
+  onTipAction?: DirectEventHandler<
+    Readonly<{ tipId: string; id: string; title: string }>
+  >;
+  onTipError?: DirectEventHandler<
+    Readonly<{ tipId: string; code: string; message: string }>
+  >;
+}
+
+export default codegenNativeComponent<NativeTipPopoverProps>(
+  'TinyuiTipPopoverView',
+  {
+    excludedPlatforms: ['android'],
+  }
+);

package/src/TipKit/index.ts

@@ -0,0 +1,47 @@
+import { assertComponentEnabled, getNativeTinyui } from '../utils';
+import type { TipInvalidationReason, TipKitConfiguration } from './types';
+import { validateTipId } from './validation';
+import { Popover } from './Popover';
+
+export const TipKit = {
+  Popover,
+  /** Configure TipKit once before mounting tips. Repeating the same options is safe. */
+  async configure({
+    displayFrequency = 'daily',
+  }: TipKitConfiguration = {}): Promise<void> {
+    assertComponentEnabled('TipKit');
+    if (
+      !['immediate', 'hourly', 'daily', 'weekly', 'monthly'].includes(
+        displayFrequency
+      )
+    ) {
+      throw new Error(
+        '[TinyUI] TipKit.configure received an invalid displayFrequency.'
+      );
+    }
+    await getNativeTinyui().configureTips(displayFrequency);
+  },
+
+  /** Persistently invalidate a tip, including when its view is not mounted. */
+  async invalidate(
+    tipId: string,
+    reason: TipInvalidationReason = 'actionPerformed'
+  ): Promise<void> {
+    assertComponentEnabled('TipKit');
+    validateTipId(tipId);
+    if (reason !== 'actionPerformed' && reason !== 'tipClosed') {
+      throw new Error('[TinyUI] TipKit.invalidate received an invalid reason.');
+    }
+    await getNativeTinyui().invalidateTip(tipId, reason);
+  },
+};
+
+export type {
+  TipAction,
+  TipDisplayFrequency,
+  TipError,
+  TipInvalidationReason,
+  TipKitConfiguration,
+  TipPopoverProps,
+  TipStatus,
+} from './types';

package/src/TipKit/types.ts

@@ -0,0 +1,57 @@
+import type { ReactNode } from 'react';
+import type { ViewProps } from 'react-native';
+
+export type TipDisplayFrequency =
+  'immediate' | 'hourly' | 'daily' | 'weekly' | 'monthly';
+
+export interface TipKitConfiguration {
+  /** App-wide interval between new tips. Defaults to `daily`. */
+  displayFrequency?: TipDisplayFrequency;
+}
+
+export type TipInvalidationReason = 'actionPerformed' | 'tipClosed';
+
+export type TipStatus =
+  | { status: 'pending' | 'available' }
+  | {
+      status: 'invalidated';
+      reason:
+        | TipInvalidationReason
+        | 'displayCountExceeded'
+        | 'displayDurationExceeded'
+        | 'unknown';
+    };
+
+export interface TipAction {
+  id: string;
+  title: string;
+}
+
+export interface TipError {
+  code: string;
+  message: string;
+}
+
+export interface TipPopoverProps extends Omit<ViewProps, 'children'> {
+  /** Anchor content. Its existing touch handlers are preserved. */
+  children: ReactNode;
+  /** Stable identity used by TipKit to persist this tip's history. */
+  tipId: string;
+  title: string;
+  message?: string;
+  systemImage?: string;
+  actions?: readonly TipAction[];
+  /** Allows presentation when TipKit is also eligible. Defaults to true. */
+  enabled?: boolean;
+  /** Omit to leave the number of presentations unlimited. */
+  maxDisplayCount?: number;
+  ignoresDisplayFrequency?: boolean;
+  /** Preferred arrow edge on the bubble; UIKit may adapt to available space. */
+  arrowEdge?: 'top' | 'bottom' | 'leading' | 'trailing' | 'auto';
+  /** TipKit eligibility, independent of whether the bubble is on screen. */
+  onStatusChange?: (status: TipStatus) => void;
+  onVisibleChange?: (visible: boolean) => void;
+  /** Actions do not automatically invalidate the tip. */
+  onActionPress?: (action: TipAction) => void;
+  onError?: (error: TipError) => void;
+}

package/src/TipKit/validation.ts

@@ -0,0 +1,39 @@
+import type { TipPopoverProps } from './types';
+
+export function validateTipId(tipId: string): void {
+  if (typeof tipId !== 'string' || tipId.trim().length === 0) {
+    throw new Error('[TinyUI] TipKit tipId must be a nonempty string.');
+  }
+}
+
+export function validateTip(props: TipPopoverProps): void {
+  validateTipId(props.tipId);
+  if (typeof props.title !== 'string' || props.title.trim().length === 0) {
+    throw new Error('[TinyUI] TipKit.Popover title must be a nonempty string.');
+  }
+  if (
+    props.maxDisplayCount !== undefined &&
+    (!Number.isInteger(props.maxDisplayCount) ||
+      props.maxDisplayCount < 1 ||
+      props.maxDisplayCount > 2147483647)
+  ) {
+    throw new Error(
+      '[TinyUI] TipKit.Popover maxDisplayCount must be a positive 32-bit integer.'
+    );
+  }
+  const ids = new Set<string>();
+  for (const action of props.actions ?? []) {
+    if (
+      typeof action.id !== 'string' ||
+      action.id.trim().length === 0 ||
+      typeof action.title !== 'string' ||
+      action.title.trim().length === 0 ||
+      ids.has(action.id)
+    ) {
+      throw new Error(
+        '[TinyUI] TipKit.Popover actions need unique nonempty ids and nonempty titles.'
+      );
+    }
+    ids.add(action.id);
+  }
+}