@lotics/ui 1.10.0 → 1.11.1

package/src/menu_button.tsx

@@ -18,6 +18,18 @@ export interface MenuButtonProps {
   tooltip?: string;
   style?: StyleProp<ViewStyle>;
   testID?: string;
+  /** DOM ID, used by combobox patterns via `aria-activedescendant`. */
+  nativeID?: string;
+  /**
+   * Accessible name when `title` is a React node (so no string is available)
+   * or when you need a name that differs from the visible title.
+   */
+  accessibilityLabel?: string;
+  /**
+   * Override the ARIA role. Defaults to `menuitem` when pressable, matching
+   * the common popover-menu usage.
+   */
+  role?: "menuitem" | "button" | "option";
 }
 
 export function MenuButton(props: MenuButtonProps) {
@@ -35,8 +47,13 @@ export function MenuButton(props: MenuButtonProps) {
     tooltip,
     style,
     testID,
+    accessibilityLabel,
+    role = "menuitem",
+    nativeID,
   } = props;
 
+  const resolvedLabel = accessibilityLabel ?? (typeof title === "string" ? title : undefined) ?? tooltip;
+
   const resolvedIcon =
     typeof icon === "string" ? (
       <Icon size={20} name={icon as IconName} color={danger ? colors.red["900"] : undefined} />
@@ -78,6 +95,7 @@ export function MenuButton(props: MenuButtonProps) {
       <PressableHighlight
         ref={ref}
         testID={testID}
+        nativeID={nativeID}
         onPress={() => {
           onPress?.();
         }}
@@ -85,6 +103,9 @@ export function MenuButton(props: MenuButtonProps) {
         disabled={disabled}
         tooltip={tooltip}
         style={containerStyle}
+        role={role}
+        accessibilityLabel={resolvedLabel}
+        accessibilityState={{ selected: !!selected, disabled: !!disabled }}
       >
         {inner}
       </PressableHighlight>

package/src/menu_list_item.tsx

@@ -49,6 +49,9 @@ export function MenuListItem(props: MenuListItemProps) {
         onPress={onPress}
         disabled={disabled}
         style={containerStyle}
+        accessibilityRole="button"
+        accessibilityLabel={description ? `${title}, ${description}` : title}
+        accessibilityState={{ disabled: !!disabled }}
       >
         {inner}
       </PressableHighlight>

package/src/number_input.tsx

@@ -1,5 +1,6 @@
 import { colors } from "./colors";
 import { fontFamilyRegular, inputTextStyleWeb } from "./text_utils";
+import { useFormField } from "./form_field";
 
 export interface NumberInputProps {
   value: number | null;
@@ -9,14 +10,22 @@ export interface NumberInputProps {
   onBlur?: () => void;
   disabled?: boolean;
   testID?: string;
+  accessibilityLabel?: string;
 }
 
 export function NumberInput(props: NumberInputProps) {
-  const { value, onValueChange, min, max, disabled, onBlur, testID } = props;
+  const { value, onValueChange, min, max, disabled, onBlur, testID, accessibilityLabel } = props;
+  const binding = useFormField();
+  const describedBy = [binding?.descriptionId, binding?.errorId].filter(Boolean).join(" ") || undefined;
 
   return (
     <input
       data-testid={testID}
+      id={binding?.inputId}
+      aria-labelledby={binding?.labelId}
+      aria-label={!binding ? accessibilityLabel : undefined}
+      aria-describedby={describedBy}
+      aria-invalid={binding?.invalid || undefined}
       value={value ?? ""}
       onChange={(e) =>
         e.target.value !== "" ? onValueChange(Number(e.target.value)) : onValueChange(null)

package/src/pill_button.tsx

@@ -30,6 +30,7 @@ export function PillButton(props: PillButtonProps) {
           <IconButton
             icon="x"
             tooltip={dismissTooltip}
+            accessibilityLabel={dismissTooltip ?? "Remove"}
             onPress={onDismiss}
             testID={testID ? `${testID}-remove` : undefined}
           />

package/src/popover.tsx

@@ -150,10 +150,14 @@ export function PopoverTrigger({ children }: PopoverTriggerProps) {
     children as React.ReactElement<{
       ref?: React.Ref<HTMLDivElement>;
       onPress?: () => void;
+      "aria-haspopup"?: "dialog" | "menu" | "listbox" | "true";
+      "aria-expanded"?: boolean;
     }>,
     {
       ref: triggerRef as React.Ref<HTMLDivElement>,
       onPress: handlePress,
+      "aria-haspopup": "dialog",
+      "aria-expanded": open,
     },
   );
 }
@@ -177,10 +181,20 @@ export interface PopoverContentProps {
   disableBodyScroll?: boolean;
   /** When true, renders as bottom sheet on small screens (close button, slide-up animation) */
   small?: boolean;
+  /** Accessible name for the bottom-sheet close button. Default: "Close". Pass a translated string from the consumer. */
+  closeLabel?: string;
 }
 
 export function PopoverContent(props: PopoverContentProps) {
-  const { testID, children, style, contentContainerStyle, disableBodyScroll, small = false } = props;
+  const {
+    testID,
+    children,
+    style,
+    contentContainerStyle,
+    disableBodyScroll,
+    small = false,
+    closeLabel = "Close",
+  } = props;
   const { open, onOpenChange, triggerRef, side, align, offset, inheritTriggerWidth } =
     usePopoverContext();
 
@@ -188,12 +202,41 @@ export function PopoverContent(props: PopoverContentProps) {
   const [position, setPosition] = useState<Position | null>(null);
   const [triggerWidth, setTriggerWidth] = useState<number>(0);
   const [isBottomSheetShown, setIsBottomSheetShown] = useState(false);
+  const returnFocusRef = useRef<HTMLElement | null>(null);
 
   const handleClose = useCallback(() => {
     if (!open) return;
     onOpenChange(false);
   }, [onOpenChange, open]);
 
+  // Focus management: when the popover opens, remember what had focus and move
+  // focus into the popover (the content div is tab-able via `tabIndex=-1`).
+  // When it closes, restore focus to the prior element so keyboard users don't
+  // land at the top of the page.
+  useEffect(() => {
+    if (!open) return;
+    const previouslyFocused = document.activeElement as HTMLElement | null;
+    returnFocusRef.current = previouslyFocused;
+
+    const focusFrame = requestAnimationFrame(() => {
+      const content = popoverRef.current;
+      if (!content) return;
+      const firstFocusable = content.querySelector<HTMLElement>(
+        'input, select, textarea, button, [role="button"], [role="menuitem"], [role="option"], [tabindex]:not([tabindex="-1"])',
+      );
+      (firstFocusable ?? content).focus();
+    });
+
+    return () => {
+      cancelAnimationFrame(focusFrame);
+      const target = returnFocusRef.current;
+      returnFocusRef.current = null;
+      if (target && typeof target.focus === "function") {
+        target.focus();
+      }
+    };
+  }, [open]);
+
   // Separate header, footer, and body from children
   let header: React.ReactNode = null;
   let footer: React.ReactNode = null;
@@ -438,6 +481,8 @@ export function PopoverContent(props: PopoverContentProps) {
         ref={popoverRef}
         data-popover="true"
         data-testid={testID}
+        role="dialog"
+        aria-modal={small ? true : undefined}
         tabIndex={small ? undefined : -1}
         style={{
           position: "fixed",
@@ -497,7 +542,7 @@ export function PopoverContent(props: PopoverContentProps) {
               justifyContent: "flex-end",
             }}
           >
-            <IconButton icon="x" onPress={handleClose} />
+            <IconButton icon="x" tooltip={closeLabel} onPress={handleClose} />
           </View>
         )}
         {header}

package/src/popover_header.tsx

@@ -7,16 +7,18 @@ import { usePopoverNav } from "./popover_nav";
 interface PopoverHeaderProps {
   title: string;
   right?: ReactNode;
+  /** Accessible name for the back button. Default: "Back". Pass a translated string from the consumer. */
+  backLabel?: string;
 }
 
 export function PopoverHeader(props: PopoverHeaderProps) {
-  const { title, right } = props;
+  const { title, right, backLabel = "Back" } = props;
   const { goBack, canGoBack } = usePopoverNav();
 
   return (
     <View style={styles.container}>
       {canGoBack && (
-        <Button icon="chevron-left" color="secondary" onPress={goBack} />
+        <Button icon="chevron-left" color="secondary" accessibilityLabel={backLabel} onPress={goBack} />
       )}
       <Text size="sm" weight="medium" style={{ flex: 1 }}>
         {title}

package/src/pressable_highlight.tsx

@@ -10,10 +10,28 @@ import { Ref, useCallback } from "react";
 import { TooltipSide, useTooltip } from "./tooltip";
 import { colors } from "./colors";
 
+function composeHandler<E>(
+  a: ((event: E) => void) | undefined,
+  b: ((event: E) => void) | undefined,
+): ((event: E) => void) | undefined {
+  if (!a) return b;
+  if (!b) return a;
+  return (event: E) => {
+    a(event);
+    b(event);
+  };
+}
+
 export interface PressableHighlightProps extends PressableProps {
   ref?: Ref<View>;
   tooltip?: string;
   tooltipSide?: TooltipSide;
+  /**
+   * Web-only keyboard handler. `react-native-web`'s `Pressable` forwards this
+   * to the rendered DOM element; native platforms ignore it. Exposed
+   * explicitly because the base React Native `PressableProps` type omits it.
+   */
+  onKeyDown?: (event: { key: string; preventDefault?: () => void }) => void;
 }
 
 /**
@@ -63,7 +81,13 @@ export function PressableHighlight(props: PressableHighlightProps) {
       }}
       onPress={handlePress}
       {...restPressableProps}
+      // `onFocus` / `onBlur` are part of `PressableProps`, so a trailing
+      // `{...tooltipProps}` spread would silently overwrite caller-provided
+      // handlers. Compose instead. Mouse handlers (not in the RN types but
+      // passed through on web) come along with the tooltipProps spread.
       {...tooltipProps}
+      onFocus={composeHandler(restPressableProps.onFocus ?? undefined, tooltipProps.onFocus)}
+      onBlur={composeHandler(restPressableProps.onBlur ?? undefined, tooltipProps.onBlur)}
     >
       {(state) => {
         const hovered = (state as { hovered?: boolean }).hovered;

package/src/radio_picker.tsx

@@ -1,4 +1,4 @@
-import { useCallback } from "react";
+import { useCallback, useRef } from "react";
 import { View } from "react-native";
 import { colors } from "./colors";
 import { Text } from "./text";
@@ -14,25 +14,72 @@ export interface RadioPickerOption<T extends string | number | symbol = string>
 }
 
 export interface RadioPickerProps<T extends string | number | symbol> {
+  /**
+   * Accessible name for the group. Announced by screen readers before
+   * stepping into the individual options.
+   */
+  accessibilityLabel: string;
   options: RadioPickerOption<T>[];
   value: T;
   onValueChange: (value: T) => void;
 }
 
 export function RadioPicker<T extends string | number | symbol>(props: RadioPickerProps<T>) {
-  const { options, value, onValueChange } = props;
+  const { accessibilityLabel, options, value, onValueChange } = props;
+  const itemRefs = useRef<Array<View | null>>([]);
+
+  // Roving tabindex: arrow keys move focus between options and select, matching
+  // the WAI-ARIA Radio Group pattern. Home/End jump to the ends.
+  const handleKeyDown = useCallback(
+    (event: { key: string; preventDefault?: () => void }, index: number) => {
+      const last = options.length - 1;
+      let next = index;
+      switch (event.key) {
+        case "ArrowDown":
+        case "ArrowRight":
+          next = index === last ? 0 : index + 1;
+          break;
+        case "ArrowUp":
+        case "ArrowLeft":
+          next = index === 0 ? last : index - 1;
+          break;
+        case "Home":
+          next = 0;
+          break;
+        case "End":
+          next = last;
+          break;
+        default:
+          return;
+      }
+      event.preventDefault?.();
+      onValueChange(options[next].value);
+      itemRefs.current[next]?.focus();
+    },
+    [onValueChange, options],
+  );
+
+  // When no option matches the current value, the first option becomes the
+  // tab-stop so the group stays keyboard-reachable. ARIA Radio Group spec.
+  const selectedIndex = options.findIndex((option) => option.value === value);
+  const tabStopIndex = selectedIndex === -1 ? 0 : selectedIndex;
 
   return (
-    <View>
-      {options.map((option) => (
+    <View accessibilityRole="radiogroup" accessibilityLabel={accessibilityLabel}>
+      {options.map((option, index) => (
         <RadioOption
+          ref={(node: View | null) => {
+            itemRefs.current[index] = node;
+          }}
           key={option.value.toString()}
           label={option.label}
           value={option.value}
           description={option.description}
           testID={option.testID}
           selected={value === option.value}
+          isTabStop={index === tabStopIndex}
           onSelect={() => onValueChange(option.value)}
+          onKeyDown={(event) => handleKeyDown(event, index)}
         />
       ))}
     </View>
@@ -41,11 +88,14 @@ export function RadioPicker<T extends string | number | symbol>(props: RadioPick
 
 function RadioOption<T extends string | number | symbol>(
   props: RadioPickerOption<T> & {
+    ref: (node: View | null) => void;
     selected: boolean;
+    isTabStop: boolean;
     onSelect: () => void;
+    onKeyDown: (event: { key: string; preventDefault?: () => void }) => void;
   },
 ) {
-  const { label, description, selected, onSelect, value, testID } = props;
+  const { ref, label, description, selected, isTabStop, onSelect, value, testID, onKeyDown } = props;
 
   const handlePress = useCallback(() => {
     onSelect();
@@ -53,6 +103,8 @@ function RadioOption<T extends string | number | symbol>(
 
   return (
     <PressableHighlight
+      ref={ref}
+      testID={testID}
       style={{
         flexDirection: "row",
         alignItems: "center",
@@ -61,6 +113,12 @@ function RadioOption<T extends string | number | symbol>(
         gap: 16,
       }}
       onPress={handlePress}
+      accessibilityRole="radio"
+      accessibilityLabel={description ? `${label}, ${description}` : label}
+      accessibilityState={{ checked: selected }}
+      // Roving tabindex: exactly one radio is the tab-stop. Arrow keys cycle.
+      focusable={isTabStop}
+      onKeyDown={onKeyDown}
     >
       <View
         style={{

package/src/section_heading.tsx

@@ -1,5 +1,5 @@
 import { View } from "react-native";
-import { Text } from "./text";
+import { Text, HeadingLevel } from "./text";
 import { Icon, IconName } from "./icon";
 
 export interface SectionHeadingProps {
@@ -7,10 +7,12 @@ export interface SectionHeadingProps {
   title: string;
   description?: string;
   right?: React.ReactNode;
+  /** Heading rank. Defaults to 2 — typical for page-level section titles. */
+  level?: HeadingLevel;
 }
 
 export function SectionHeading(props: SectionHeadingProps) {
-  const { icon, title, description, right } = props;
+  const { icon, title, description, right, level = 2 } = props;
 
   return (
     <View
@@ -23,7 +25,7 @@ export function SectionHeading(props: SectionHeadingProps) {
       <View style={{ flex: 1 }}>
         <View style={{ flexDirection: "row", alignItems: "center", gap: 4 }}>
           {icon && <Icon name={icon} size={18} />}
-          <Text weight="medium" size="md">
+          <Text level={level} weight="medium" size="md">
             {title}
           </Text>
         </View>

package/src/skip_link.tsx

@@ -0,0 +1,46 @@
+import { Platform } from "react-native";
+import { colors } from "./colors";
+
+export interface SkipLinkProps {
+  /** DOM id of the main region to jump to, e.g. `"main-content"`. */
+  targetId: string;
+  /** Visible label. Localize. */
+  label: string;
+}
+
+/**
+ * Keyboard-first link that lets assistive tech and keyboard users bypass
+ * repeated navigation and land directly in the main region. Hidden visually
+ * until focused. Web-only; returns null on native where there is no tab
+ * traversal through a persistent nav.
+ */
+export function SkipLink(props: SkipLinkProps) {
+  const { targetId, label } = props;
+  if (Platform.OS !== "web") return null;
+  return (
+    <a
+      href={`#${targetId}`}
+      style={{
+        position: "absolute",
+        top: 0,
+        left: 0,
+        padding: "8px 16px",
+        backgroundColor: colors.zinc["900"],
+        color: colors.white,
+        textDecoration: "none",
+        borderRadius: 4,
+        zIndex: 10001,
+        transform: "translateY(-200%)",
+        transition: "transform 0.15s ease",
+      }}
+      onFocus={(e) => {
+        e.currentTarget.style.transform = "translateY(8px)";
+      }}
+      onBlur={(e) => {
+        e.currentTarget.style.transform = "translateY(-200%)";
+      }}
+    >
+      {label}
+    </a>
+  );
+}

package/src/switch.tsx

@@ -4,13 +4,18 @@ import { colors } from "./colors";
 import { Icon } from "./icon";
 export interface SwitchProps {
   testID?: string;
+  /**
+   * Accessible name. Required on interactive switches (those with `onChange`);
+   * optional when the switch is rendered as a read-only indicator.
+   */
+  accessibilityLabel?: string;
   value?: boolean | null;
   disabled?: boolean;
   onChange?: (value: boolean) => void;
 }
 
 export function Switch(props: SwitchProps) {
-  const { testID, value, disabled, onChange } = props;
+  const { testID, accessibilityLabel, value, disabled, onChange } = props;
   const checked = useRef(new Animated.Value(value ? 1 : 0)).current;
 
   const handlePress = useCallback(() => {
@@ -69,6 +74,9 @@ export function Switch(props: SwitchProps) {
       onPress={handlePress}
       style={styles.root}
       disabled={disabled}
+      accessibilityRole="switch"
+      accessibilityLabel={accessibilityLabel}
+      accessibilityState={{ checked: !!value, disabled: !!disabled }}
     >
       {content}
     </Pressable>

package/src/switch_button.tsx

@@ -26,6 +26,9 @@ export function SwitchButton(props: SwitchButtonProps) {
       }}
       onPress={() => onChange?.(!value)}
       tooltip={tooltip}
+      accessibilityRole="switch"
+      accessibilityLabel={title}
+      accessibilityState={{ checked: !!value }}
     >
       <View style={{ flexDirection: "row", gap: 8, alignItems: "center", flex: 1 }}>
         {!!icon && <Icon name={icon} size={20} />}

package/src/tabs.tsx

@@ -1,8 +1,9 @@
-import { useCallback } from "react";
+import { useCallback, useRef } from "react";
 import { View } from "react-native";
 import { PressableHighlight } from "./pressable_highlight";
 import { Text } from "./text";
 import { colors } from "./colors";
+
 export interface TabOption<T extends string> {
   label: string;
   value: T;
@@ -10,22 +11,70 @@ export interface TabOption<T extends string> {
 }
 
 interface TabsProps<T extends string> {
+  /** Accessible name of the tablist. */
+  accessibilityLabel: string;
   options: TabOption<T>[];
   selectedTab: T;
   onSelectTab?: (value: T) => void;
 }
 
 export function Tabs<T extends string>(props: TabsProps<T>) {
-  const { options, selectedTab, onSelectTab } = props;
+  const { accessibilityLabel, options, selectedTab, onSelectTab } = props;
+  const tabRefs = useRef<Array<View | null>>([]);
+
+  // Roving tabindex + arrow-key navigation per the WAI-ARIA Tabs pattern.
+  // Home/End jump to the ends; Left/Right cycle.
+  const handleKeyDown = useCallback(
+    (event: { key: string; preventDefault?: () => void }, index: number) => {
+      const last = options.length - 1;
+      let next = index;
+      switch (event.key) {
+        case "ArrowRight":
+        case "ArrowDown":
+          next = index === last ? 0 : index + 1;
+          break;
+        case "ArrowLeft":
+        case "ArrowUp":
+          next = index === 0 ? last : index - 1;
+          break;
+        case "Home":
+          next = 0;
+          break;
+        case "End":
+          next = last;
+          break;
+        default:
+          return;
+      }
+      event.preventDefault?.();
+      onSelectTab?.(options[next].value);
+      tabRefs.current[next]?.focus();
+    },
+    [onSelectTab, options],
+  );
+
+  // When no tab matches the current selection, the first tab becomes the
+  // tab-stop so keyboard users can still enter the group.
+  const selectedIndex = options.findIndex((option) => option.value === selectedTab);
+  const tabStopIndex = selectedIndex === -1 ? 0 : selectedIndex;
 
   return (
-    <View style={{ flexDirection: "row", gap: 4 }}>
-      {options.map((option) => (
+    <View
+      style={{ flexDirection: "row", gap: 4 }}
+      accessibilityRole="tablist"
+      accessibilityLabel={accessibilityLabel}
+    >
+      {options.map((option, index) => (
         <TabButton
+          ref={(node: View | null) => {
+            tabRefs.current[index] = node;
+          }}
           key={option.value}
           option={option}
           selected={selectedTab === option.value}
+          isTabStop={index === tabStopIndex}
           onSelectTab={onSelectTab}
+          onKeyDown={(event) => handleKeyDown(event, index)}
         />
       ))}
     </View>
@@ -33,13 +82,16 @@ export function Tabs<T extends string>(props: TabsProps<T>) {
 }
 
 interface TabButtonProps<T extends string> {
+  ref: (node: View | null) => void;
   option: TabOption<T>;
   selected: boolean;
+  isTabStop: boolean;
   onSelectTab?: (value: T) => void;
+  onKeyDown: (event: { key: string; preventDefault?: () => void }) => void;
 }
 
 function TabButton<T extends string>(props: TabButtonProps<T>) {
-  const { option, selected, onSelectTab } = props;
+  const { ref, option, selected, isTabStop, onSelectTab, onKeyDown } = props;
 
   const handlePress = useCallback(() => {
     onSelectTab?.(option.value);
@@ -57,6 +109,7 @@ function TabButton<T extends string>(props: TabButtonProps<T>) {
 
   return (
     <PressableHighlight
+      ref={ref}
       style={{
         borderBottomWidth: 3,
         borderBottomColor: selected ? colors.zinc["700"] : "transparent",
@@ -64,26 +117,35 @@ function TabButton<T extends string>(props: TabButtonProps<T>) {
         paddingBottom: 4,
       }}
       onPress={handlePress}
+      onKeyDown={onKeyDown}
       testID={option.testID}
+      accessibilityRole="tab"
+      accessibilityLabel={option.label}
+      accessibilityState={{ selected }}
+      // Roving tabindex: the selected tab is the tab-stop, others are reachable
+      // via arrow keys. When no tab matches the current selection (props.value
+      // is stale), the first tab is the fallback so the group stays keyboard-
+      // reachable.
+      focusable={isTabStop}
     >
       {(state) => {
         const { pressed } = state;
         const hovered = (state as { hovered?: boolean }).hovered;
         return (
-        <View
-          style={{
-            paddingVertical: 8,
-            paddingHorizontal: 16,
-            borderRadius: 8,
-            backgroundColor: pressed
-              ? colors.zinc["100"]
-              : hovered
-                ? colors.zinc["50"]
-                : "transparent",
-          }}
-        >
-          {inner}
-        </View>
+          <View
+            style={{
+              paddingVertical: 8,
+              paddingHorizontal: 16,
+              borderRadius: 8,
+              backgroundColor: pressed
+                ? colors.zinc["100"]
+                : hovered
+                  ? colors.zinc["50"]
+                  : "transparent",
+            }}
+          >
+            {inner}
+          </View>
         );
       }}
     </PressableHighlight>