@lotics/ui 1.11.0 → 1.11.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "1.11.0",
+  "version": "1.11.1",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -118,6 +118,8 @@
     "./command_menu": "./src/command_menu.tsx",
     "./switch_button": "./src/switch_button.tsx",
     "./alert": "./src/alert.tsx",
+    "./landmark": "./src/landmark.tsx",
+    "./skip_link": "./src/skip_link.tsx",
     "./text_utils": "./src/text_utils.ts",
     "./cell_text": "./src/cell_text.tsx",
     "./cell_number": "./src/cell_number.tsx",
@@ -133,7 +135,9 @@
     "./grid/data_grid_context": "./src/grid/data_grid_context.ts",
     "./grid/search_highlight": "./src/grid/search_highlight.ts"
   },
-  "files": ["src"],
+  "files": [
+    "src"
+  ],
   "publishConfig": {
     "access": "public"
   },
@@ -156,11 +160,21 @@
     "recharts": ">=3.0.0"
   },
   "peerDependenciesMeta": {
-    "expo-image": { "optional": true },
-    "@react-native-picker/picker": { "optional": true },
-    "lucide-react-native": { "optional": true },
-    "react-native-svg": { "optional": true },
-    "recharts": { "optional": true }
+    "expo-image": {
+      "optional": true
+    },
+    "@react-native-picker/picker": {
+      "optional": true
+    },
+    "lucide-react-native": {
+      "optional": true
+    },
+    "react-native-svg": {
+      "optional": true
+    },
+    "recharts": {
+      "optional": true
+    }
   },
   "scripts": {
     "typecheck": "tsgo --noEmit",

package/src/alert.tsx

@@ -1,4 +1,4 @@
-import React, { useEffect, useState, useCallback } from "react";
+import React, { useEffect, useId, useRef, useState, useCallback } from "react";
 import { createRoot, Root } from "react-dom/client";
 import "./alert.css";
 import { Text } from "./text";
@@ -81,6 +81,11 @@ class Alert {
 
     const AlertComponent = () => {
       const [visible, setVisible] = useState(true);
+      const dialogId = useId();
+      const titleId = `${dialogId}-title`;
+      const messageId = `${dialogId}-message`;
+      const dialogRef = useRef<HTMLDivElement>(null);
+      const returnFocusRef = useRef<HTMLElement | null>(null);
 
       useOverlayScope(visible);
 
@@ -106,6 +111,29 @@ class Alert {
         }
       }, [visible]);
 
+      // Focus management: remember what had focus so it can be restored when
+      // the dialog dismisses. Move focus to the preferred button on mount so
+      // keyboard users do not land outside the dialog.
+      useEffect(() => {
+        returnFocusRef.current = document.activeElement as HTMLElement | null;
+        const frame = requestAnimationFrame(() => {
+          // The primary/positive button is conventionally rightmost in the
+          // row, so default focus lands there. Users can Shift-Tab to the
+          // cancel/neutral buttons if they need them.
+          const buttons = dialogRef.current?.querySelectorAll<HTMLElement>(
+            ".lotics-alert-buttons [role='button']",
+          );
+          const preferred = buttons ? buttons[buttons.length - 1] : undefined;
+          preferred?.focus();
+        });
+        return () => {
+          cancelAnimationFrame(frame);
+          const target = returnFocusRef.current;
+          returnFocusRef.current = null;
+          if (target && typeof target.focus === "function") target.focus();
+        };
+      }, []);
+
       useEffect(() => {
         const handleEscape = (e: KeyboardEvent) => {
           if (e.key === "Escape" && alertOptions.cancelable !== false) {
@@ -124,19 +152,21 @@ class Alert {
       return (
         <div className="lotics-alert-overlay" onClick={handleDismiss}>
           <div
+            ref={dialogRef}
             className="lotics-alert-dialog"
             onClick={(e) => e.stopPropagation()}
             role="alertdialog"
-            aria-labelledby={title && title.trim() ? "alert-title" : undefined}
-            aria-describedby={message ? "alert-message" : undefined}
+            aria-modal="true"
+            aria-labelledby={title && title.trim() ? titleId : undefined}
+            aria-describedby={message ? messageId : undefined}
           >
             {title && title.trim() && (
-              <Text size="md" weight="medium">
+              <Text nativeID={titleId} size="md" weight="medium">
                 {title}
               </Text>
             )}
             {message && (
-              <Text size="sm" color="zinc-500">
+              <Text nativeID={messageId} size="sm" color="zinc-500">
                 {message}
               </Text>
             )}

package/src/avatar.tsx

@@ -10,21 +10,44 @@ interface AvatarProps {
   name?: string;
   style?: StyleProp<ViewStyle | ImageStyle>;
   contentFit?: ImageContentFit;
+  /**
+   * When true, the avatar announces its `name` to assistive tech. Default
+   * false because avatars almost always appear adjacent to the name text —
+   * announcing the image as well would double-read. Pass `announce` when the
+   * avatar is standalone (with no visible name nearby).
+   */
+  announce?: boolean;
 }
 
 export function Avatar(props: AvatarProps) {
-  const { source, size = 32, name = "Unknown", style, contentFit } = props;
+  const { source, size = 32, name = "Unknown", style, contentFit, announce } = props;
+  const decorative = !announce;
 
   if (!source || !source.uri) {
     return (
       <View
+        accessible={!decorative}
+        accessibilityLabel={decorative ? undefined : name}
+        accessibilityElementsHidden={decorative}
+        importantForAccessibility={decorative ? "no-hide-descendants" : undefined}
+        aria-hidden={decorative || undefined}
         style={[
           styles.base,
           { backgroundColor: colors.blue["600"], width: size, height: size },
           style,
         ]}
       >
-        <Text userSelect="none" size="xs" weight="medium" color="inverted">
+        {/* Initials are a visual shorthand for the name; the accessible name is
+            on the container so the SR does not read "HM" in addition. */}
+        <Text
+          userSelect="none"
+          size="xs"
+          weight="medium"
+          color="inverted"
+          accessibilityElementsHidden
+          importantForAccessibility="no-hide-descendants"
+          aria-hidden
+        >
           {getInitials(name, size)}
         </Text>
       </View>
@@ -33,7 +56,9 @@ export function Avatar(props: AvatarProps) {
 
   return (
     <Image
-      alt={name}
+      alt={decorative ? "" : name}
+      accessibilityElementsHidden={decorative}
+      importantForAccessibility={decorative ? "no-hide-descendants" : undefined}
       style={[styles.base, { width: size, height: size }, style as ImageStyle]}
       source={source}
       contentFit={contentFit}

package/src/back_button.tsx

@@ -1,18 +1,20 @@
 import { Button } from "./button";
-import { Text } from "./text";
 import { View } from "react-native";
 
 interface BackButtonProps {
   onPress: () => void;
+  /** Accessible name. Default: "Back". Pass a translated string from the consumer. */
+  accessibilityLabel?: string;
 }
 
 export function BackButton(props: BackButtonProps) {
-  const { onPress } = props;
+  const { onPress, accessibilityLabel = "Back" } = props;
   return (
     <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
       <Button
         icon="chevron-left"
         color="secondary"
+        accessibilityLabel={accessibilityLabel}
         onPress={onPress}
         style={{ alignSelf: "flex-start" }}
       />

package/src/button.tsx

@@ -16,10 +16,9 @@ import { useTooltip, UseTooltipOptions } from "./tooltip";
 export type ButtonColor = "primary" | "secondary" | "danger" | "muted" | "danger-secondary";
 export type ButtonIconPosition = "left" | "right";
 
-export interface ButtonProps {
+interface ButtonPropsBase {
   ref?: Ref<View>;
   testID?: string;
-  title?: string | boolean;
   icon?: IconName;
   alignSelf?: "flex-start" | "flex-end" | "center" | "stretch" | "auto";
   color?: ButtonColor;
@@ -30,9 +29,34 @@ export interface ButtonProps {
   style?: StyleProp<ViewStyle>;
 }
 
+/**
+ * A button must have an accessible name. The compiler enforces it by
+ * requiring at least one of: a string `title`, an explicit
+ * `accessibilityLabel`, or a `tooltip` that carries a visible name. The
+ * runtime derives `accessibilityLabel` in that precedence order.
+ */
+export type ButtonProps = ButtonPropsBase &
+  (
+    | { title: string; accessibilityLabel?: string; tooltip?: string | UseTooltipOptions }
+    | { title?: boolean | undefined; accessibilityLabel: string; tooltip?: string | UseTooltipOptions }
+    | { title?: boolean | undefined; accessibilityLabel?: string; tooltip: string | UseTooltipOptions }
+  );
+
 export function Button(props: ButtonProps) {
-  const { ref, icon, alignSelf, title, color, style, disabled, tooltip, loading, onPress, testID } =
-    props;
+  const {
+    ref,
+    icon,
+    alignSelf,
+    title,
+    color,
+    style,
+    disabled,
+    tooltip,
+    loading,
+    onPress,
+    testID,
+    accessibilityLabel,
+  } = props;
 
   const disabledOrLoading = disabled || loading;
   const tooltipProps = useTooltip(tooltip);
@@ -74,7 +98,13 @@ export function Button(props: ButtonProps) {
       ref={ref}
       testID={testID}
       accessibilityRole="button"
-      accessibilityState={{ disabled: disabledOrLoading }}
+      accessibilityLabel={
+        accessibilityLabel ||
+        (typeof title === "string" ? title : "") ||
+        (typeof tooltip === "string" ? tooltip : tooltip?.text) ||
+        undefined
+      }
+      accessibilityState={{ disabled: disabledOrLoading, busy: loading }}
       disabled={disabledOrLoading}
       // @ts-ignore hovered is a react-native-web extension not in base RN types
       style={({ pressed, hovered }) => {

package/src/calendar/calendar_view.tsx

@@ -5,9 +5,9 @@ import { colors } from "../colors";
 import { MonthView } from "./month_view";
 import { TimeGridView } from "./time_grid_view";
 import { addDays, addMonths, viewTitle } from "./dates";
-import type { CalendarEvent, CalendarViewMode, Weekday } from "./types";
+import { DEFAULT_CALENDAR_LABELS } from "./types";
+import type { CalendarEvent, CalendarLabels, CalendarViewMode, Weekday } from "./types";
 
-const VIEW_LABELS: Record<CalendarViewMode, string> = { month: "Tháng", week: "Tuần", day: "Ngày" };
 const VIEW_ORDER: CalendarViewMode[] = ["month", "week", "day"];
 
 export interface CalendarViewProps<T = unknown> {
@@ -16,6 +16,8 @@ export interface CalendarViewProps<T = unknown> {
   defaultDate?: Date;
   weekStartsOn?: Weekday;
   locale?: string;
+  /** User-facing chrome strings; defaults to English. */
+  labels?: Partial<CalendarLabels>;
   onEventPress?: (event: CalendarEvent<T>) => void;
   onDayPress?: (day: Date) => void;
 }
@@ -27,6 +29,7 @@ export interface CalendarViewProps<T = unknown> {
  */
 export function CalendarView<T = unknown>(props: CalendarViewProps<T>) {
   const { events, defaultView = "month", defaultDate, weekStartsOn = 1, locale, onEventPress, onDayPress } = props;
+  const L = { ...DEFAULT_CALENDAR_LABELS, ...props.labels };
   const [view, setView] = useState<CalendarViewMode>(defaultView);
   const [date, setDate] = useState<Date>(defaultDate ?? new Date());
 
@@ -44,13 +47,13 @@ export function CalendarView<T = unknown>(props: CalendarViewProps<T>) {
     <View style={styles.root}>
       <View style={styles.toolbar}>
         <View style={styles.navGroup}>
-          <Pressable onPress={() => step(-1)} accessibilityRole="button" accessibilityLabel="Trước" style={styles.iconBtn}>
+          <Pressable onPress={() => step(-1)} accessibilityRole="button" accessibilityLabel={L.previous} style={styles.iconBtn}>
             <Text size="lg" color="muted">‹</Text>
           </Pressable>
           <Pressable onPress={() => setDate(new Date())} accessibilityRole="button" style={styles.todayBtn}>
-            <Text size="sm" weight="medium">Hôm nay</Text>
+            <Text size="sm" weight="medium">{L.today}</Text>
           </Pressable>
-          <Pressable onPress={() => step(1)} accessibilityRole="button" accessibilityLabel="Sau" style={styles.iconBtn}>
+          <Pressable onPress={() => step(1)} accessibilityRole="button" accessibilityLabel={L.next} style={styles.iconBtn}>
             <Text size="lg" color="muted">›</Text>
           </Pressable>
         </View>
@@ -68,7 +71,7 @@ export function CalendarView<T = unknown>(props: CalendarViewProps<T>) {
               style={[styles.viewBtn, view === v && styles.viewBtnActive]}
             >
               <Text size="sm" weight={view === v ? "medium" : "regular"} color={view === v ? "default" : "muted"}>
-                {VIEW_LABELS[v]}
+                {L[v]}
               </Text>
             </Pressable>
           ))}
@@ -82,6 +85,7 @@ export function CalendarView<T = unknown>(props: CalendarViewProps<T>) {
             events={events}
             weekStartsOn={weekStartsOn}
             locale={locale}
+            moreLabel={L.more}
             onEventPress={onEventPress}
             onDayPress={drillToDay}
           />
@@ -92,6 +96,7 @@ export function CalendarView<T = unknown>(props: CalendarViewProps<T>) {
             events={events}
             weekStartsOn={weekStartsOn}
             locale={locale}
+            allDayLabel={L.allDay}
             onEventPress={onEventPress}
           />
         )}

package/src/calendar/index.ts

@@ -6,7 +6,8 @@ export { MonthView } from "./month_view";
 export type { MonthViewProps } from "./month_view";
 export { layoutDayColumns, packEventLanes } from "./layout";
 export type { LaneBar } from "./layout";
-export type { CalendarEvent, CalendarViewMode, Weekday, EventColumn } from "./types";
+export { DEFAULT_CALENDAR_LABELS } from "./types";
+export type { CalendarEvent, CalendarViewMode, Weekday, EventColumn, CalendarLabels } from "./types";
 export {
   addDays,
   addMonths,

package/src/calendar/month_view.tsx

@@ -15,12 +15,14 @@ export interface MonthViewProps<T = unknown> {
   events: CalendarEvent<T>[];
   weekStartsOn?: Weekday;
   locale?: string;
+  /** Overflow chip label, e.g. (3) => "+3 more". Defaults to English. */
+  moreLabel?: (count: number) => string;
   onEventPress?: (event: CalendarEvent<T>) => void;
   onDayPress?: (day: Date) => void;
 }
 
 export function MonthView<T = unknown>(props: MonthViewProps<T>) {
-  const { date, events, weekStartsOn = 1, locale, onEventPress, onDayPress } = props;
+  const { date, events, weekStartsOn = 1, locale, moreLabel = (n) => `+${n} more`, onEventPress, onDayPress } = props;
   const days = useMemo(() => daysInView("month", date, weekStartsOn), [date, weekStartsOn]);
   const weeks = useMemo(() => Array.from({ length: 6 }, (_, w) => days.slice(w * 7, w * 7 + 7)), [days]);
   const weekdayLabels = useMemo(() => days.slice(0, 7).map((d) => weekdayShort(d, locale)), [days, locale]);
@@ -133,7 +135,7 @@ export function MonthView<T = unknown>(props: MonthViewProps<T>) {
                     onPress={onDayPress ? () => onDayPress(day) : undefined}
                     style={{ position: "absolute", top: MAX_LANES * (LANE_H + LANE_GAP), left: `${(col / 7) * 100}%`, width: `${100 / 7}%`, paddingHorizontal: 6 }}
                   >
-                    <Text size="xs" color="muted">+{overflow[col]} nữa</Text>
+                    <Text size="xs" color="muted">{moreLabel(overflow[col])}</Text>
                   </Pressable>
                 ) : null,
               )}

package/src/calendar/time_grid_view.tsx

@@ -31,6 +31,8 @@ export interface TimeGridViewProps<T = unknown> {
   locale?: string;
   /** Hour to scroll to on mount. Default: an hour before now (clamped). */
   scrollToHour?: number;
+  /** All-day lane label; defaults to English ("all-day"). */
+  allDayLabel?: string;
   onEventPress?: (event: CalendarEvent<T>) => void;
 }
 
@@ -161,7 +163,7 @@ export function TimeGridView<T = unknown>(props: TimeGridViewProps<T>) {
         <View style={[styles.allDayRow, { height: allDayPacked.lanes * (ALLDAY_LANE_H + 2) + 6 }]}>
           <View style={{ width: GUTTER, justifyContent: "center" }}>
             <Text size="xs" style={{ color: colors.zinc[400], textAlign: "right", paddingRight: 6 }}>
-              cả ngày
+              {props.allDayLabel ?? "all-day"}
             </Text>
           </View>
           <View style={{ flex: 1 }}>

package/src/calendar/types.ts

@@ -19,6 +19,35 @@ export interface CalendarEvent<T = unknown> {
 
 export type CalendarViewMode = "month" | "week" | "day";
 
+/**
+ * User-facing chrome strings. Primitives default to English and take these as a
+ * prop — i18n is the consumer's responsibility (see the @lotics/ui convention in
+ * grid/data_grid.tsx). Dates/weekday/month names come from `locale` via Intl and
+ * are not part of this set.
+ */
+export interface CalendarLabels {
+  today: string;
+  month: string;
+  week: string;
+  day: string;
+  previous: string;
+  next: string;
+  allDay: string;
+  /** Month-cell overflow chip, e.g. (3) => "+3 more". */
+  more: (count: number) => string;
+}
+
+export const DEFAULT_CALENDAR_LABELS: CalendarLabels = {
+  today: "Today",
+  month: "Month",
+  week: "Week",
+  day: "Day",
+  previous: "Previous",
+  next: "Next",
+  allDay: "all-day",
+  more: (n) => `+${n} more`,
+};
+
 /** 0 = Sunday … 6 = Saturday. */
 export type Weekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;
 

package/src/checkbox_input.tsx

@@ -2,6 +2,11 @@ import { useCallback } from "react";
 import { Pressable } from "react-native";
 import { Checkbox } from "./checkbox";
 interface CheckboxInputProps {
+  /**
+   * Accessible name. Required because an unlabelled checkbox only announces
+   * its state, leaving the user with no idea what is being checked.
+   */
+  accessibilityLabel: string;
   checked: boolean;
   onChange?: (checked: boolean) => void;
   disabled?: boolean;
@@ -10,7 +15,7 @@ interface CheckboxInputProps {
 }
 
 export function CheckboxInput(props: CheckboxInputProps) {
-  const { indeterminate, checked, onChange, disabled, testID } = props;
+  const { accessibilityLabel, indeterminate, checked, onChange, disabled, testID } = props;
 
   const handlePress = useCallback(() => {
     if (!disabled) {
@@ -24,8 +29,9 @@ export function CheckboxInput(props: CheckboxInputProps) {
       onPress={handlePress}
       disabled={disabled}
       style={{ opacity: disabled ? 0.5 : 1 }}
-      role="checkbox"
-      aria-checked={checked}
+      accessibilityRole="checkbox"
+      accessibilityLabel={accessibilityLabel}
+      accessibilityState={{ checked: indeterminate ? "mixed" : checked, disabled: !!disabled }}
     >
       <Checkbox checked={checked} indeterminate={indeterminate} />
     </Pressable>

package/src/command_menu.tsx

@@ -1,7 +1,6 @@
 import { StyleSheet, View, ScrollView } from "react-native";
-import { useState, useCallback, useMemo, useRef } from "react";
+import { useState, useCallback, useMemo, useRef, useId } from "react";
 import { colors } from "./colors";
-import { Icon } from "./icon";
 import { TextInputField } from "./text_input_field";
 import { MenuButton } from "./menu_button";
 import { Text } from "./text";
@@ -20,14 +19,27 @@ interface CommandMenuProps {
   enableSearch?: boolean;
   /** Search input placeholder. Default: "Search...". Pass a translated string from the consumer. */
   searchPlaceholder?: string;
+  /** Accessible name for the list. Default: "Options". Pass a translated string from the consumer. */
+  accessibilityLabel?: string;
 }
 
 export function CommandMenu(props: CommandMenuProps) {
-  const { options, onSelect, onRequestClose, enableSearch, searchPlaceholder = "Search..." } = props;
+  const {
+    options,
+    onSelect,
+    onRequestClose,
+    enableSearch,
+    searchPlaceholder = "Search...",
+    accessibilityLabel,
+  } = props;
   const scrollViewRef = useRef<ScrollView>(null);
   const screenSize = useScreenSize();
   const OPTION_HEIGHT = 40;
 
+  const baseId = useId();
+  const listboxId = `${baseId}-listbox`;
+  const optionId = (index: number) => `${baseId}-option-${index}`;
+
   const [searchQuery, setSearchQuery] = useState("");
 
   const filteredOptions = useMemo(() => {
@@ -83,6 +95,16 @@ export function CommandMenu(props: CommandMenuProps) {
           }
           return true;
         }
+        case "Home":
+          setFocusedIndex(0);
+          scrollToIndex(0);
+          return true;
+        case "End": {
+          const last = filteredOptions.length - 1;
+          setFocusedIndex(last);
+          scrollToIndex(last);
+          return true;
+        }
         case "Enter":
           if (focusedIndex >= 0 && focusedIndex < filteredOptions.length) {
             const opt = filteredOptions[focusedIndex];
@@ -111,6 +133,10 @@ export function CommandMenu(props: CommandMenuProps) {
     [handleKeyNavigation],
   );
 
+  const listLabel = accessibilityLabel ?? "Options";
+  const activeOptionId =
+    focusedIndex >= 0 && focusedIndex < filteredOptions.length ? optionId(focusedIndex) : undefined;
+
   return (
     <View style={[styles.container, screenSize.small ? { flex: 1 } : { maxHeight: 480 }]}>
       {enableSearch && (
@@ -124,20 +150,40 @@ export function CommandMenu(props: CommandMenuProps) {
           autoCapitalize="none"
           autoCorrect={false}
           onKeyPress={handleSearchKeyPress}
+          accessibilityLabel={listLabel}
+          role="combobox"
+          aria-expanded
+          aria-controls={listboxId}
+          aria-activedescendant={activeOptionId}
+          aria-autocomplete="list"
         />
       )}
-      <ScrollView ref={scrollViewRef} style={styles.optionsList}>
+      <ScrollView
+        ref={scrollViewRef}
+        style={styles.optionsList}
+        nativeID={listboxId}
+        accessibilityLabel={listLabel}
+        // Boundary adapter: `listbox` is a valid ARIA role but missing from
+        // React Native's `Role` enum, so TypeScript cannot accept the literal
+        // here. `react-native-web` forwards the attribute verbatim, which is
+        // what assistive technology reads on web.
+        role={"listbox" as "list"}
+      >
         {filteredOptions.map((item, index) => (
           <MenuButton
             key={item.value}
+            nativeID={optionId(index)}
             testID={`command-option-${item.value}`}
             title={
               <Text userSelect="none" numberOfLines={1}>
                 {item.label}
               </Text>
             }
+            accessibilityLabel={item.label}
+            role="option"
             right={undefined}
             focused={index === focusedIndex}
+            selected={index === focusedIndex}
             disabled={item.disabled}
             onPress={() => handleSelect(item.value)}
             onHoverIn={() => setFocusedIndex(index)}

package/src/dialog.tsx

@@ -163,7 +163,7 @@ export function Dialog(props: DialogProps) {
                   <PortalHost>
                     <View testID={testID} style={[styles.dialogContainer, { borderRadius }]}>
                       <View style={[styles.closeButtonContainer, { paddingHorizontal: screenSize.small ? 16 : 24 }]}>
-                        <Button icon="x" onPress={handleClose} />
+                        <Button icon="x" accessibilityLabel="Close" onPress={handleClose} />
                       </View>
                       <View style={styles.container}>{children}</View>
                     </View>