@lotics/ui 1.11.0 → 1.12.0

package/src/popover.tsx

@@ -3,6 +3,7 @@ import React, {
   useCallback,
   useContext,
   useEffect,
+  useLayoutEffect,
   useRef,
   useState,
 } from "react";
@@ -150,10 +151,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 +182,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 +203,58 @@ 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);
+  // Last known trigger geometry. The trigger can unmount while the popover is
+  // open — a hover-revealed menu button stops being rendered the moment our
+  // overlay covers its row and the hover ends — so positioning cannot rely on
+  // `triggerRef.current` still being live when it runs.
+  const triggerRectRef = useRef<DOMRect | null>(null);
 
   const handleClose = useCallback(() => {
     if (!open) return;
     onOpenChange(false);
   }, [onOpenChange, open]);
 
+  // Snapshot the trigger geometry synchronously the moment we open, while it is
+  // guaranteed to still be mounted. `calculatePosition` runs later in a rAF, by
+  // which point a hover-revealed trigger may already be gone (our overlay covers
+  // its row, hover ends, the button unmounts). Capturing here keeps the popover
+  // anchored to where the trigger was instead of stranding it off-screen.
+  useLayoutEffect(() => {
+    if (!open || small) return;
+    if (triggerRef.current) {
+      triggerRectRef.current = triggerRef.current.getBoundingClientRect();
+    }
+  }, [open, small, triggerRef]);
+
+  // 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;
@@ -237,10 +298,17 @@ export function PopoverContent(props: PopoverContentProps) {
   }, [open, small, onOpenChange]);
 
   const calculatePosition = useCallback(() => {
-    if (!triggerRef.current || !popoverRef.current) return;
+    if (!popoverRef.current) return;
     if (small) return;
 
-    const triggerRect = triggerRef.current.getBoundingClientRect();
+    // Prefer the live trigger when it is still mounted (so the popover tracks
+    // scroll/layout); fall back to the rect captured at open time when the
+    // trigger has since unmounted, instead of stranding the popover off-screen.
+    const liveTriggerRect = triggerRef.current?.getBoundingClientRect();
+    if (liveTriggerRect) triggerRectRef.current = liveTriggerRect;
+    const triggerRect = triggerRectRef.current;
+    if (!triggerRect) return;
+
     const popoverRect = popoverRef.current.getBoundingClientRect();
     const viewportWidth = window.innerWidth;
     const viewportHeight = window.innerHeight;
@@ -360,6 +428,7 @@ export function PopoverContent(props: PopoverContentProps) {
     if (!open) {
       setPosition((previous) => (previous === null ? previous : null));
       setIsBottomSheetShown((previous) => (previous ? false : previous));
+      triggerRectRef.current = null;
       return;
     }
 
@@ -438,6 +507,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 +568,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>

package/src/text.tsx

@@ -22,8 +22,25 @@ export interface TextProps {
   decoration?: TextDecorationLine;
   style?: RNTextProps["style"];
   onPress?: () => void;
+  /** ID used to target this element from `accessibilityLabelledBy` / `aria-describedby`. */
+  nativeID?: string;
+  accessibilityRole?: RNTextProps["accessibilityRole"];
+  accessibilityLabel?: string;
+  accessibilityElementsHidden?: boolean;
+  importantForAccessibility?: RNTextProps["importantForAccessibility"];
+  /**
+   * Renders as a heading of this rank (1–6): exposes `accessibilityRole="header"`
+   * and `aria-level`, giving the page a real heading outline. Appearance still
+   * comes from `size`/`weight` — `level` is the semantic rank only. Use one
+   * level-1 per page.
+   */
+  level?: HeadingLevel;
+  "aria-live"?: "off" | "polite" | "assertive";
+  "aria-hidden"?: boolean;
 }
 
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
 type TextSize = "xs" | "sm" | "md" | "lg" | "xl" | "xxl";
 type TextAlign = "left" | "right" | "center";
 type TextDecorationLine = "underline" | "lineThrough" | "underline lineThrough";
@@ -48,6 +65,14 @@ export function Text(props: TextProps) {
     transform,
     onPress,
     style,
+    nativeID,
+    accessibilityRole,
+    accessibilityLabel,
+    accessibilityElementsHidden,
+    importantForAccessibility,
+    level,
+    "aria-live": ariaLive,
+    "aria-hidden": ariaHidden,
   } = props;
 
   // On web, responsive font sizes are applied via CSS using data-text-size attribute.
@@ -57,6 +82,14 @@ export function Text(props: TextProps) {
   return (
     <RNText
       testID={testID}
+      nativeID={nativeID}
+      accessibilityRole={level != null ? "header" : accessibilityRole}
+      accessibilityLabel={accessibilityLabel}
+      accessibilityElementsHidden={accessibilityElementsHidden}
+      importantForAccessibility={importantForAccessibility}
+      aria-level={level}
+      aria-live={ariaLive}
+      aria-hidden={ariaHidden}
       {...webProps}
       style={[
         { color: getTextColor(color) },