@lotics/ui 6.0.0 → 6.1.0

package/AGENTS.md

@@ -12,9 +12,17 @@ typeahead, async search, virtualization, and a11y the primitive already ships.
   `PortalHost` at the app root.
 - RN-Web only: `View`/`ScrollView` from `react-native`, the `Text` primitive (no raw
   `div`/`span`, no raw `fontSize`/`fontWeight`); styles are RN objects.
-- i18n: most components are string-free; the few that emit their own user-facing strings take
-  a `labels` prop (`DateRangeFilterField`, `Pagination`, `SortHeader`/`Table.sortLabels`,
-  `RemainderMeter`) — localize there.
+- i18n: most components are string-free. For the rest, set the language ONCE at the root with
+  **`LoticsLocaleProvider`** (`@lotics/ui/locale`, the sibling of `LoticsThemeProvider`) — wrap
+  `<LoticsLocaleProvider locale={vi}>` and every wired component picks up the pack, no per-instance
+  props. Shipped packs: `en` (default) and `vi` (one canonical Vietnamese translation, so apps don't
+  redefine — or drift on — strings). Resolution is **prop → provider locale → English default**, so a
+  per-instance `labels`/`clearLabel`/`selectAllLabel` still overrides for one-offs, and an un-wrapped
+  app stays English. Wired so far: `Pagination`, `SortHeader`/`Table.sortLabels`, `OptionList`
+  (+ `Select`/`Combobox` built on it), `FilterChip`, `Drawer`. Adding a string to a wired component's
+  `*Labels` forces both packs in `locale.tsx` to fill it (compile error) — that's how the kit avoids a
+  silent English leak. Not yet on the provider (pass `labels` for now): `DateRangeFilterField`,
+  `RemainderMeter`, `ChangeReview`, calendar/gantt.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -56,6 +56,7 @@
     "./status_grid": "./src/status_grid.tsx",
     "./heatmap": "./src/heatmap.tsx",
     "./trend_footer": "./src/trend_footer.tsx",
+    "./locale": "./src/locale.tsx",
     "./spacing": "./src/spacing.ts",
     "./theme": "./src/theme.tsx",
     "./progress_bar": "./src/progress_bar.tsx",

package/src/column_filter.tsx

@@ -92,7 +92,8 @@ export interface ColumnFilterProps {
   column: FilterableColumn;
   value: ColumnFilterValue | undefined;
   onChange: (value: ColumnFilterValue | undefined) => void;
-  /** Accessible name for the clear (X) control. Pass a translated string. Default "Clear". */
+  /** Accessible name for the clear (X) control. Omit to use the locale's
+   *  `filterChip.clear` (English "Clear" by default). */
   clearLabel?: string;
 }
 
@@ -105,7 +106,7 @@ export interface ColumnFilterProps {
  * `columnFilterToConditions`. Pure UI; no data layer.
  */
 export function ColumnFilter(props: ColumnFilterProps) {
-  const { column, value, onChange, clearLabel = "Clear" } = props;
+  const { column, value, onChange, clearLabel } = props;
   const active = isColumnFilterActive(value);
 
   return (

package/src/combobox.tsx

@@ -9,6 +9,7 @@ import {
 import { useCallback, useRef, useState, type ReactNode } from "react";
 import { colors } from "./colors";
 import { FOCUS_RING } from "./control_surface";
+import { useLoticsLocale } from "./locale";
 import { Text } from "./text";
 import { Icon, type IconName } from "./icon";
 import { TextInputField } from "./text_input_field";
@@ -110,8 +111,6 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
     searchDebounceMs = 200,
     icon,
     placeholder,
-    recentsLabel = "Recent",
-    emptyText = "No results",
     accessibilityLabel = "Results",
     disabled = false,
     clearable = false,
@@ -121,6 +120,9 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
     testID,
     style,
   } = props;
+  const loc = useLoticsLocale().optionList;
+  const emptyText = props.emptyText ?? loc.noResults;
+  const recentsLabel = props.recentsLabel ?? loc.recent;
 
   const single = value ?? null;
   const reflectedText = single ? (single.label ?? single.value) : "";

package/src/drawer.tsx

@@ -6,6 +6,7 @@ import { colors } from "@lotics/ui/colors";
 import { IconButton } from "@lotics/ui/icon_button";
 import { Text } from "@lotics/ui/text";
 import { useOverlayScope } from "@lotics/ui/overlay_scope";
+import { useLoticsLocale } from "@lotics/ui/locale";
 
 export interface DrawerProps {
   open: boolean;
@@ -44,6 +45,7 @@ export interface DrawerProps {
  */
 export function Drawer(props: DrawerProps) {
   const { open, onOpenChange, title, width = 420, onPrev, onNext, position, children, testID } = props;
+  const loc = useLoticsLocale().drawer;
   const screenSize = useScreenSize();
   useOverlayScope(open);
   const handleClose = () => onOpenChange(false);
@@ -79,7 +81,7 @@ export function Drawer(props: DrawerProps) {
     <Modal visible={open} onRequestClose={handleClose} transparent>
       <View style={styles.base}>
         {/* Scrim is a sibling of the panel, so tapping the panel never closes. */}
-        <Pressable style={styles.scrim} onPress={handleClose} accessibilityLabel="Close" tabIndex={-1} />
+        <Pressable style={styles.scrim} onPress={handleClose} accessibilityLabel={loc.close} tabIndex={-1} />
         <View style={[styles.panel, { width: screenSize.small ? "100%" : width }]}>
           <PortalHost>
             <View style={styles.header}>
@@ -94,7 +96,7 @@ export function Drawer(props: DrawerProps) {
                 <View style={styles.nav}>
                   <IconButton
                     icon="chevron-left"
-                    accessibilityLabel="Previous record"
+                    accessibilityLabel={loc.previous}
                     onPress={onPrev ?? (() => {})}
                     disabled={!onPrev}
                   />
@@ -105,13 +107,13 @@ export function Drawer(props: DrawerProps) {
                   ) : null}
                   <IconButton
                     icon="chevron-right"
-                    accessibilityLabel="Next record"
+                    accessibilityLabel={loc.next}
                     onPress={onNext ?? (() => {})}
                     disabled={!onNext}
                   />
                 </View>
               ) : null}
-              <IconButton icon="x" size="lg" accessibilityLabel="Close" onPress={handleClose} />
+              <IconButton icon="x" size="lg" accessibilityLabel={loc.close} onPress={handleClose} />
             </View>
             <View testID={testID} style={styles.body}>
               {children}

package/src/filter_chip.tsx

@@ -7,6 +7,7 @@ import { TextLink } from "./text_link";
 import { Chip } from "./chip";
 import { Popover, PopoverTrigger, PopoverContent, PopoverFooter } from "./popover";
 import type { PopoverSide, PopoverAlign } from "./popover";
+import { useLoticsLocale } from "./locale";
 
 export interface FilterChipProps {
   /** The dimension name — shown alone when inactive ("Owner"), prefixed when
@@ -69,7 +70,8 @@ export function selectSummary(
  * toolbar's `ColumnFilter` is this pill plus its query-condition mapping.
  */
 export function FilterChip(props: FilterChipProps) {
-  const { label, summary, onClear, clearLabel = "Clear", children, side = "bottom", align = "start", open, onOpenChange, footer } = props;
+  const { label, summary, onClear, children, side = "bottom", align = "start", open, onOpenChange, footer } = props;
+  const clearLabel = props.clearLabel ?? useLoticsLocale().filterChip.clear;
   const active = summary != null && (typeof summary !== "string" || summary.length > 0);
   // The clear × / Clear footer only when there's a clearable selection AND no
   // custom footer — a valued, non-clearable pill ("Target: 20") keeps its chevron.

package/src/locale.tsx

@@ -0,0 +1,107 @@
+import { createContext, useContext, type ReactNode } from "react";
+import { type PaginationLabels } from "./pagination";
+import { type SortHeaderLabels } from "./sort_header";
+
+/**
+ * The kit's localizable strings, one slice per string-bearing component. A
+ * `LoticsLocale` is plain DATA (like a date-fns locale) — it carries no i18n
+ * LOGIC, so the kit stays translation-agnostic while an app supplies the pack
+ * once at its root. Each slice REUSES the component's own `*Labels` type, so
+ * adding a localizable string to a component (a new key on its `Labels`) forces
+ * BOTH packs below to fill it — a missing translation is a compile error here,
+ * never a silent English leak at a call site.
+ *
+ * Resolution order in every wired component: an explicit per-instance prop wins,
+ * else this locale (from `LoticsLocaleProvider`, default `en`), else nothing —
+ * the locale is always complete, so there is no third fallback to forget.
+ */
+export interface LoticsLocale {
+  /** `Pagination` range + page summaries and the prev/next tooltips. */
+  pagination: Required<PaginationLabels>;
+  /** `SortHeader` a11y prefix + asc/desc suffixes. */
+  sortHeader: Required<SortHeaderLabels>;
+  /** `OptionList` (and everything built on it — `Select`, `Combobox`, the
+   *  in-cell editors): the select-all/deselect-all links, the empty state, and
+   *  the `Combobox` recents header. */
+  optionList: { selectAll: string; deselectAll: string; noResults: string; recent: string };
+  /** `FilterChip` (and `ColumnFilter`): the generic clear affordance, used when
+   *  a call site doesn't pass a dimension-specific `clearLabel`. */
+  filterChip: { clear: string };
+  /** `Drawer`: the record prev/next + close controls (screen-reader names). */
+  drawer: { previous: string; next: string; close: string };
+}
+
+/** The platform default — English. Every component's hardcoded default lives
+ *  HERE now, so the strings are documented in one place and overridable. */
+export const en: LoticsLocale = {
+  pagination: {
+    rangeWithTotal: (start, end, total) => `${start}–${end} of ${total.toLocaleString()}`,
+    range: (start, end) => `${start}–${end}`,
+    pageWithTotal: (page, pageCount) => `Page ${page} of ${pageCount}`,
+    page: (page) => `Page ${page}`,
+    previous: "Previous",
+    next: "Next",
+  },
+  sortHeader: {
+    sortBy: (label) => `Sort by ${label}`,
+    ascending: ", ascending",
+    descending: ", descending",
+  },
+  optionList: { selectAll: "Select all", deselectAll: "Deselect all", noResults: "No results", recent: "Recent" },
+  filterChip: { clear: "Clear" },
+  drawer: { previous: "Previous record", next: "Next record", close: "Close" },
+};
+
+/** Vietnamese. Maintained once here so every app (and the frontend) shares one
+ *  canonical translation — no per-app drift ("Chọn tất cả" vs "Chọn hết"). */
+export const vi: LoticsLocale = {
+  pagination: {
+    rangeWithTotal: (start, end, total) => `${start}–${end} trên ${total.toLocaleString("vi-VN")}`,
+    range: (start, end) => `${start}–${end}`,
+    pageWithTotal: (page, pageCount) => `Trang ${page} / ${pageCount}`,
+    page: (page) => `Trang ${page}`,
+    previous: "Trang trước",
+    next: "Trang sau",
+  },
+  sortHeader: {
+    sortBy: (label) => `Sắp xếp theo ${label}`,
+    ascending: " (tăng dần)",
+    descending: " (giảm dần)",
+  },
+  optionList: { selectAll: "Chọn tất cả", deselectAll: "Bỏ chọn tất cả", noResults: "Không có kết quả", recent: "Gần đây" },
+  filterChip: { clear: "Xóa" },
+  drawer: { previous: "Bản ghi trước", next: "Bản ghi sau", close: "Đóng" },
+};
+
+const LoticsLocaleContext = createContext<LoticsLocale>(en);
+
+interface LoticsLocaleProviderProps {
+  /** The locale pack supplying every kit string. Import a shipped pack
+   *  (`import { vi } from "@lotics/ui/locale"`) or pass your own `LoticsLocale`. */
+  locale: LoticsLocale;
+  children: ReactNode;
+}
+
+/**
+ * App-root provider that supplies localized strings to @lotics/ui primitives —
+ * the sibling of `LoticsThemeProvider`. Wrap your top-level element once and
+ * every wired component picks up the pack; no per-instance label props:
+ *
+ *     // src/main.tsx
+ *     import { vi } from "@lotics/ui/locale";
+ *     <LoticsLocaleProvider locale={vi}>
+ *       <App />
+ *     </LoticsLocaleProvider>
+ *
+ * Components read the locale via `useLoticsLocale()`. A per-instance label prop
+ * still overrides for one-offs; without a provider the English default applies,
+ * so an un-wrapped app behaves exactly as before.
+ */
+export function LoticsLocaleProvider(props: LoticsLocaleProviderProps) {
+  return <LoticsLocaleContext.Provider value={props.locale}>{props.children}</LoticsLocaleContext.Provider>;
+}
+
+/** Read the current locale. Wired primitives call this; apps use the provider. */
+export function useLoticsLocale(): LoticsLocale {
+  return useContext(LoticsLocaleContext);
+}

package/src/option_list.tsx

@@ -10,6 +10,7 @@ import { ActivityIndicator } from "./activity_indicator";
 import { TextInputField } from "./text_input_field";
 import { useScreenSize } from "./use_screen_size";
 import { useOptionList, type UseOptionListParams } from "./use_option_list";
+import { useLoticsLocale } from "./locale";
 import type { PickerOption } from "./picker";
 
 export interface OptionListProps<T extends string = string, MULTI extends boolean = false, D = unknown>
@@ -38,17 +39,11 @@ export interface OptionListProps<T extends string = string, MULTI extends boolea
 export function OptionList<T extends string, MULTI extends boolean = false, D = unknown>(
   props: OptionListProps<T, MULTI, D>,
 ) {
-  const {
-    testID,
-    renderOptionContent,
-    getOptionDescription,
-    loading = false,
-    emptyText = "No results",
-    accessibilityLabel,
-    selectAllLabel = "Select all",
-    deselectAllLabel = "Deselect all",
-    search,
-  } = props;
+  const { testID, renderOptionContent, getOptionDescription, loading = false, accessibilityLabel, search } = props;
+  const loc = useLoticsLocale().optionList;
+  const emptyText = props.emptyText ?? loc.noResults;
+  const selectAllLabel = props.selectAllLabel ?? loc.selectAll;
+  const deselectAllLabel = props.deselectAllLabel ?? loc.deselectAll;
   const list = useOptionList(props);
   const { small } = useScreenSize();
 

package/src/pagination.tsx

@@ -2,6 +2,7 @@ import * as React from "react";
 import { View, StyleSheet } from "react-native";
 import { IconButton } from "./icon_button";
 import { Text } from "./text";
+import { useLoticsLocale } from "./locale";
 
 /**
  * Localizable strings for `Pagination`. Every field is optional; an omitted
@@ -25,12 +26,6 @@ export interface PaginationLabels {
   next?: string;
 }
 
-const defaultRangeWithTotal = (start: number, end: number, total: number): string =>
-  `${start}–${end} of ${total.toLocaleString()}`;
-const defaultRange = (start: number, end: number): string => `${start}–${end}`;
-const defaultPageWithTotal = (page: number, pageCount: number): string => `Page ${page} of ${pageCount}`;
-const defaultPage = (page: number): string => `Page ${page}`;
-
 export interface PaginationProps {
   /** 0-indexed. */
   page: number;
@@ -59,20 +54,21 @@ export interface PaginationProps {
  */
 export function Pagination(props: PaginationProps): React.ReactNode {
   const { page, pageSize, rowCount, hasMore, total, loading, onPageChange, labels } = props;
+  const loc = useLoticsLocale().pagination;
   const start = page * pageSize + 1;
   const end = page * pageSize + rowCount;
   const showRange = !loading && rowCount > 0;
 
   const summary = showRange
     ? total !== undefined
-      ? (labels?.rangeWithTotal ?? defaultRangeWithTotal)(start, end, total)
-      : (labels?.range ?? defaultRange)(start, end)
+      ? (labels?.rangeWithTotal ?? loc.rangeWithTotal)(start, end, total)
+      : (labels?.range ?? loc.range)(start, end)
     : "";
 
   const pageLabel =
     total !== undefined
-      ? (labels?.pageWithTotal ?? defaultPageWithTotal)(page + 1, Math.max(1, Math.ceil(total / pageSize)))
-      : (labels?.page ?? defaultPage)(page + 1);
+      ? (labels?.pageWithTotal ?? loc.pageWithTotal)(page + 1, Math.max(1, Math.ceil(total / pageSize)))
+      : (labels?.page ?? loc.page)(page + 1);
 
   return (
     <View style={styles.container}>
@@ -90,14 +86,14 @@ export function Pagination(props: PaginationProps): React.ReactNode {
           color="secondary"
           onPress={() => onPageChange(Math.max(0, page - 1))}
           disabled={page === 0 || !!loading}
-          tooltip={labels?.previous ?? "Previous"}
+          tooltip={labels?.previous ?? loc.previous}
         />
         <IconButton
           icon="chevron-right"
           color="secondary"
           onPress={() => onPageChange(page + 1)}
           disabled={!hasMore || !!loading}
-          tooltip={labels?.next ?? "Next"}
+          tooltip={labels?.next ?? loc.next}
         />
       </View>
     </View>

package/src/sort_header.tsx

@@ -3,6 +3,7 @@ import { Text } from "./text";
 import { Icon } from "./icon";
 import { colors } from "./colors";
 import { PressableHighlight } from "./pressable_highlight";
+import { useLoticsLocale } from "./locale";
 
 export type SortDir = "asc" | "desc";
 export interface SortState {
@@ -74,14 +75,11 @@ export interface SortHeaderProps {
  */
 export function SortHeader(props: SortHeaderProps) {
   const { label, sortKey, sort, onSort, align = "left", style, labels } = props;
+  const loc = useLoticsLocale().sortHeader;
   const active = sort?.key === sortKey;
   const arrow = active ? (sort.dir === "asc" ? "chevron-up" : "chevron-down") : undefined;
-  const dirText = active
-    ? sort.dir === "asc"
-      ? (labels?.ascending ?? ", ascending")
-      : (labels?.descending ?? ", descending")
-    : "";
-  const sortByLabel = (labels?.sortBy ?? ((l: string) => `Sort by ${l}`))(label);
+  const dirText = active ? (sort.dir === "asc" ? (labels?.ascending ?? loc.ascending) : (labels?.descending ?? loc.descending)) : "";
+  const sortByLabel = (labels?.sortBy ?? loc.sortBy)(label);
 
   return (
     <PressableHighlight