@lotics/ui 13.7.1 → 13.8.0

package/docs/catalog.md

@@ -295,8 +295,12 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   brand accent (OKLCH blue by default) that chart fills, hero CTAs, and focus rings read.
 - **`locale`** — `LoticsLocaleProvider` / `useLoticsLocale` + the shipped `en` (default) and
   `vi` packs. Set the language ONCE at the root; wired components resolve **prop → provider
-  locale → English default**. **Limitation:** the calendar/gantt views and the comment
-  labels are not yet provider-wired — pass their `labels` props directly.
+  locale → English default**. Each pack also carries a **`bcp47`** tag (`en`→`en-US`,
+  `vi`→`vi-VN`); date/time controls read it via **`useLocaleTag`** (`resolveLocaleTag` is its
+  pure core) so the segmented field's part ORDER (dd/MM vs MM/dd), the picker calendar's
+  weekday/month names, and `formatDate` display all follow the provider with no per-instance
+  `locale` prop — an explicit `locale` still overrides. **Limitation:** the calendar/gantt
+  views and the comment labels are not yet provider-wired — pass their `labels` props directly.
 - **`colors`** — the palette + `withAlpha` · `solid` · `tint` · `ramp` · `ColorName` ·
   `isColorName` · `asColorName` (coerce a stored option/status token to a `ColorName`,
   neutral fallback).

package/docs/data_entry.md

@@ -65,8 +65,9 @@ restore is gated on modality via `shouldRestoreFocusOnClose`).
 
 **Typed dates.** `InlineDatePicker`'s keyboard mode is an internal segmented date field
 (`DateField` — not exported; reached only through `InlineDatePicker`): type
-the date in the locale's own field order (dd/MM/yyyy where the locale says so — pass
-`locale`), digits auto-advance, and a typed separator (`/` `.` `-`) advances a single-digit
+the date in the locale's own field order — dd/MM/yyyy under the `vi` provider, MM/dd/yyyy
+under `en`, derived from the active `LoticsLocaleProvider` (an explicit `locale` prop still
+overrides) — digits auto-advance, and a typed separator (`/` `.` `-`) advances a single-digit
 day/month; Enter or blur commits, Escape reverts, Alt+ArrowDown floats the calendar. The
 calendar popover stays the pointer path (click the resting value, as ever) — it is no longer
 the only path. A PARTIAL entry never commits and never clears the stored value: the field

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "13.7.1",
+  "version": "13.8.0",
   "type": "module",
   "exports": {
     "./vite": {

package/src/date_calendar.tsx

@@ -7,7 +7,7 @@ import { Picker, PickerOption } from "./picker";
 import { IconButton } from "./icon_button";
 import { FOCUS_RING } from "./control_surface";
 import { useFocusRing } from "./use_focus_ring";
-import { useLoticsLocale } from "./locale";
+import { useLoticsLocale, useLocaleTag } from "./locale";
 
 /** Accessible names for the calendar's month-navigation arrows. Backs the
  *  `calendar` locale slice. (The month/weekday NAMES come from `Intl` + the
@@ -76,7 +76,8 @@ export interface CalendarRef {
 interface CalendarBaseProps {
   /** First day of the week (0 = Sunday, 1 = Monday, ..., 6 = Saturday). Default: 1 (Monday) */
   firstDayOfWeek?: DayOfWeek;
-  /** BCP-47 locale for weekday/month names. Default: "en-US". */
+  /** BCP-47 locale for weekday/month names. Defaults to the active
+   *  `LoticsLocaleProvider` locale. */
   locale?: string;
   /** Ref to access calendar methods like navigateToMonth */
   ref?: React.Ref<CalendarRef>;
@@ -130,9 +131,6 @@ interface CalendarMonthProps {
 // Helper Functions
 // =============================================================================
 
-/** BCP-47 locale used when a caller does not supply one. */
-const DEFAULT_LOCALE = "en-US";
-
 interface LocalizedNames {
   /** Weekday short names, index 0 = Sunday. */
   weekdays: string[];
@@ -425,7 +423,7 @@ export function Calendar<TMode extends "single" | "range">(
 ): React.ReactElement {
   const screenSize = useScreenSize();
   const firstDayOfWeek = props.firstDayOfWeek ?? 1; // Default to Monday
-  const locale = props.locale ?? DEFAULT_LOCALE;
+  const locale = useLocaleTag(props.locale);
 
   if (props.mode === "single") {
     return (

package/src/date_field.tsx

@@ -6,6 +6,7 @@ import { useHover } from "./use_hover";
 import { Text } from "./text";
 import { DateSegments } from "./date_segments_field";
 import { SegmentLabels, dateSegmentsConfig } from "./date_segments";
+import { useLocaleTag } from "./locale";
 
 export interface DateFieldProps {
   /** Canonical ISO value parts: one (single) or two (range, "start"/"end"). */
@@ -13,7 +14,8 @@ export interface DateFieldProps {
   onPartChange: (index: number, value: string) => void;
   hasTime: boolean;
   segmentLabels: SegmentLabels;
-  /** BCP-47 locale driving segment order + 12/24h. Defaults to "en-US". */
+  /** BCP-47 locale driving segment order + 12/24h. Defaults to the active
+   *  `LoticsLocaleProvider` locale (`vi` → dd/MM/yyyy, `en` → MM/dd/yyyy). */
   locale?: string;
   disabled?: boolean;
   /** Shown when every part is empty and the field is unfocused. */
@@ -111,7 +113,8 @@ export function DateField(props: DateFieldProps) {
     [onIncompleteChange],
   );
 
-  const config = useMemo(() => dateSegmentsConfig(locale ?? "en-US", hasTime), [locale, hasTime]);
+  const localeTag = useLocaleTag(locale);
+  const config = useMemo(() => dateSegmentsConfig(localeTag, hasTime), [localeTag, hasTime]);
 
   const isEmpty = parts.every((part) => !part);
   const showPlaceholder = !!placeholder && isEmpty && !focused;

package/src/date_filter.tsx

@@ -11,7 +11,7 @@ import { useScreenSize } from "./use_screen_size";
 import { SegmentLabels } from "./date_segments";
 import { PresetId, PRESET_IDS, getPresetValue } from "./date_filter_presets";
 import { formatDate } from "./format_date";
-import { useLoticsLocale } from "./locale";
+import { useLoticsLocale, useLocaleTag } from "./locale";
 
 type SelectionMode = "single" | "range";
 
@@ -50,7 +50,8 @@ export interface DateFilterProps {
   includeTime?: boolean;
   /** Translated labels. Defaults to English. */
   labels?: Partial<DateFilterLabels>;
-  /** BCP-47 locale for the calendar and date display. Defaults to "en-US". */
+  /** BCP-47 locale for the calendar and date display. Defaults to the active
+   *  `LoticsLocaleProvider` locale. */
   locale?: string;
 }
 
@@ -88,6 +89,7 @@ function formatDateDisplay(date: Date | null, locale: string | undefined): strin
 
 export function DateFilter(props: DateFilterProps) {
   const { value, onValueChange, includeTime = false, locale } = props;
+  const localeTag = useLocaleTag(locale);
   const loc = useLoticsLocale().dateRange;
   const labels = useMemo<DateFilterLabels>(
     () => ({ ...loc, ...props.labels }),
@@ -238,7 +240,7 @@ export function DateFilter(props: DateFilterProps) {
           mode="range"
           value={calendarValue}
           onValueChange={handleCalendarChange}
-          locale={locale}
+          locale={localeTag}
         />
 
         {selectionMode === "range" ? (
@@ -249,7 +251,7 @@ export function DateFilter(props: DateFilterProps) {
                   {labels.from}
                 </Text>
                 <Text size="sm" weight="medium">
-                  {formatDateDisplay(value.start.date, locale) || labels.selectDate}
+                  {formatDateDisplay(value.start.date, localeTag) || labels.selectDate}
                 </Text>
                 {includeTime && (
                   <View style={{ marginTop: 4 }}>
@@ -269,7 +271,7 @@ export function DateFilter(props: DateFilterProps) {
                   {labels.to}
                 </Text>
                 <Text size="sm" weight="medium">
-                  {formatDateDisplay(value.end.date, locale) || labels.selectDate}
+                  {formatDateDisplay(value.end.date, localeTag) || labels.selectDate}
                 </Text>
                 {includeTime && value.end.date && (
                   <View style={{ marginTop: 4 }}>

package/src/date_picker.tsx

@@ -74,7 +74,8 @@ export interface DatePickerProps {
    *  omitted resolves from the `datePicker` locale slice — English by default, or
    *  the active `LoticsLocaleProvider` pack. */
   labels?: Partial<DatePickerLabels>;
-  /** BCP-47 locale for the calendar's weekday/month names. Defaults to "en-US". */
+  /** BCP-47 locale for the segment order + the calendar's weekday/month names.
+   *  Defaults to the active `LoticsLocaleProvider` locale. */
   locale?: string;
   /** Shown in the field when nothing is selected yet. */
   placeholder?: string;
@@ -94,7 +95,8 @@ export interface DatePickerPanelProps {
   /** Single `date` formats only: time is optional and driven by the value's shape. */
   optionalTime?: boolean;
   labels?: Partial<DatePickerLabels>;
-  /** BCP-47 locale for the calendar's weekday/month names. Defaults to "en-US". */
+  /** BCP-47 locale for the segment order + the calendar's weekday/month names.
+   *  Defaults to the active `LoticsLocaleProvider` locale. */
   locale?: string;
   /** Called when a selection completes and the surrounding surface should dismiss. */
   onRequestClose?: () => void;

package/src/date_range_filter_field.tsx

@@ -9,7 +9,7 @@ import { FocusRingPressable } from "./focus_ring_pressable";
 import { Popover, PopoverTrigger, PopoverContent, PopoverFooter } from "./popover";
 import { DateFilter, DateFilterValue, DateFilterLabels } from "./date_filter";
 import { formatDate } from "./format_date";
-import { useLoticsLocale } from "./locale";
+import { useLoticsLocale, useLocaleTag } from "./locale";
 
 // =============================================================================
 // DateRangeFilterField — the common filter composition over DateFilter:
@@ -35,8 +35,8 @@ export interface DateRangeFilterFieldProps {
   includeTime?: boolean;
   /** Translated labels (presets + footer + placeholder). Defaults to English. */
   labels?: Partial<DateRangeFilterFieldLabels>;
-  /** BCP-47 locale for the calendar + trigger date display. Date display defaults to
-   *  the kit's home market (vi-VN, via `formatDate`) when unset. */
+  /** BCP-47 locale for the calendar + trigger date display. Defaults to the active
+   *  `LoticsLocaleProvider` locale. */
   locale?: string;
   testID?: string;
 }
@@ -110,12 +110,13 @@ function formatTrigger(value: DateFilterValue, includeTime: boolean, locale: str
 
 export function DateRangeFilterField(props: DateRangeFilterFieldProps) {
   const { value, onValueChange, includeTime, locale, testID } = props;
+  const localeTag = useLocaleTag(locale);
   const loc = useLoticsLocale().dateRange;
   const labels = useMemo(() => ({ ...loc, ...props.labels }), [loc, props.labels]);
   const [open, setOpen] = useState(false);
 
   const hasValue = Boolean(value.start.date || value.end.date);
-  const display = formatTrigger(value, Boolean(includeTime), locale) || labels.placeholder;
+  const display = formatTrigger(value, Boolean(includeTime), localeTag) || labels.placeholder;
 
   return (
     <Popover open={open} onOpenChange={setOpen} side="bottom" align="start">
@@ -150,7 +151,7 @@ export function DateRangeFilterField(props: DateRangeFilterFieldProps) {
           onValueChange={onValueChange}
           includeTime={includeTime}
           labels={props.labels}
-          locale={locale}
+          locale={localeTag}
         />
         <PopoverFooter align="space-between">
           {hasValue ? <Button title={labels.clear} onPress={() => onValueChange(EMPTY_VALUE)} /> : <View />}

package/src/date_segments.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect } from "vitest";
+import { resolveLocaleTag, en as enLocale, vi as viLocale } from "./locale";
 import {
   getDateLayout,
   getTimeLayout,
@@ -241,6 +242,41 @@ describe("placeholderFor", () => {
   });
 });
 
+describe("locale-driven default segment order (LoticsLocaleProvider)", () => {
+  // The provider pack carries a BCP-47 tag; a wired date field defaults its
+  // segment order to that tag when no explicit `locale` prop is given. These
+  // assert the end-to-end contract — provider pack → rendered part ORDER —
+  // through the same resolveLocaleTag + getDateLayout the components compose.
+  // Before this, the field hardcoded "en-US", so a vi-wrapped app showed
+  // MM/DD/YYYY unless every call site threaded a `locale` prop.
+  it("a vi provider yields dd/MM/yyyy by default (no explicit locale)", () => {
+    const tag = resolveLocaleTag(viLocale);
+    expect(tag).toBe("vi-VN");
+    expect(fieldOrder(getDateLayout(tag, false))).toEqual(["day", "month", "year"]);
+  });
+
+  it("an en provider yields MM/dd/yyyy by default", () => {
+    const tag = resolveLocaleTag(enLocale);
+    expect(tag).toBe("en-US");
+    expect(fieldOrder(getDateLayout(tag, false))).toEqual(["month", "day", "year"]);
+  });
+
+  it("an explicit locale prop overrides the provider pack, both directions", () => {
+    // Under a vi provider, an author passing en-US still gets MM/dd/yyyy…
+    expect(fieldOrder(getDateLayout(resolveLocaleTag(viLocale, "en-US"), false))).toEqual([
+      "month",
+      "day",
+      "year",
+    ]);
+    // …and an en provider with an explicit vi-VN gets dd/MM/yyyy.
+    expect(fieldOrder(getDateLayout(resolveLocaleTag(enLocale, "vi-VN"), false))).toEqual([
+      "day",
+      "month",
+      "year",
+    ]);
+  });
+});
+
 describe("getTimeLayout", () => {
   it("is hour/minute(+AM/PM) only, locale-driven", () => {
     expect(fieldOrder(getTimeLayout("en-US"))).toEqual(["hour", "minute", "dayPeriod"]);

package/src/inline_date_picker.tsx

@@ -11,7 +11,7 @@ import { formatDate } from "./format_date";
 import { ActivityIndicator } from "./activity_indicator";
 import { type InlineEditVariant, InlineEditView } from "./inline_edit";
 import { type TextColor } from "./text_utils";
-import { useLoticsLocale } from "./locale";
+import { useLoticsLocale, useLocaleTag } from "./locale";
 import { getInteractionModality } from "./interaction_modality";
 import { shouldOpenOnFocus, shouldRestoreFocusOnClose } from "./inline_focus";
 
@@ -31,7 +31,8 @@ export interface InlineDatePickerProps {
    *  until a time is added). Ignored when `format` is "datetime" (time always on). */
   optionalTime?: boolean;
   placeholder?: string;
-  /** BCP-47 locale for the calendar, the displayed date, and the typed segment order. */
+  /** BCP-47 locale for the calendar, the displayed date, and the typed segment
+   *  order. Defaults to the active `LoticsLocaleProvider` locale. */
   locale?: string;
   disabled?: boolean;
   accessibilityLabel?: string;
@@ -62,6 +63,9 @@ export function InlineDatePicker(props: InlineDatePickerProps) {
   const locales = useLoticsLocale();
   const inlineLabels = locales.inline;
   const dateLabels = locales.datePicker;
+  // The calendar, the resting display, and the typed segments must all agree —
+  // resolve one tag (explicit prop, else the provider) and thread it to all three.
+  const localeTag = useLocaleTag(locale);
 
   const [editing, setEditing] = useState(false);
   const [open, setOpen] = useState(false);
@@ -224,7 +228,7 @@ export function InlineDatePicker(props: InlineDatePickerProps) {
   // resting view follows the stored value, the segments follow the session draft
   // (the panel's "Add time" grows the segments live).
   const showTime = optionalTime ? isoHasTime(value) : format === "datetime";
-  const display = formatDate(value, { time: showTime, locale, emptyLabel: "" });
+  const display = formatDate(value, { time: showTime, locale: localeTag, emptyLabel: "" });
   const fieldHasTime = optionalTime ? isoHasTime(draft) : format === "datetime";
 
   const trailing = saving ? (
@@ -248,7 +252,7 @@ export function InlineDatePicker(props: InlineDatePickerProps) {
             onPartChange={(_, next) => updateDraft(next)}
             hasTime={fieldHasTime}
             segmentLabels={dateLabels}
-            locale={locale}
+            locale={localeTag}
             disabled={disabled}
             placeholder={placeholder}
             partLabels={accessibilityLabel ? [accessibilityLabel] : undefined}
@@ -284,7 +288,7 @@ export function InlineDatePicker(props: InlineDatePickerProps) {
             onValueChange={updateDraft}
             format={format}
             optionalTime={optionalTime}
-            locale={locale}
+            locale={localeTag}
             // Commit on panel close. A single-date pick and the "Today" button
             // auto-close through here — a bare setOpen(false) would be a
             // controlled close the Popover never reports, silently dropping it.

package/src/locale.tsx

@@ -20,9 +20,18 @@ import { type FindingLabels } from "./finding";
  *
  * 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.
+ * the locale is always complete, so there is no third fallback to forget. The
+ * same order governs the {@link LoticsLocale.bcp47} tag via {@link useLocaleTag}.
  */
 export interface LoticsLocale {
+  /** The BCP-47 language tag this pack renders in (`en` → `"en-US"`, `vi` →
+   *  `"vi-VN"`). This is what makes a date control follow the active locale
+   *  WITHOUT the author threading a `locale` prop: it drives every `Intl`-derived
+   *  rendering the kit does — the segmented date field's part ORDER (dd/MM/yyyy
+   *  vs MM/dd/yyyy) and 12/24h, the calendar's weekday/month names, and
+   *  `formatDate` display. A per-instance `locale` prop still overrides it
+   *  (resolved through {@link useLocaleTag} / {@link resolveLocaleTag}). */
+  bcp47: string;
   /** `Pagination` range + page summaries and the prev/next tooltips. */
   pagination: Required<PaginationLabels>;
   /** `SortHeader` a11y prefix + asc/desc suffixes. */
@@ -127,6 +136,7 @@ export interface LoticsLocale {
 /** 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 = {
+  bcp47: "en-US",
   pagination: {
     rangeWithTotal: (start, end, total) => `${start}–${end} of ${total.toLocaleString()}`,
     range: (start, end) => `${start}–${end}`,
@@ -221,6 +231,7 @@ export const en: LoticsLocale = {
 /** 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 = {
+  bcp47: "vi-VN",
   pagination: {
     rangeWithTotal: (start, end, total) => `${start}–${end} trên ${total.toLocaleString("vi-VN")}`,
     range: (start, end) => `${start}–${end}`,
@@ -344,3 +355,24 @@ export function LoticsLocaleProvider(props: LoticsLocaleProviderProps) {
 export function useLoticsLocale(): LoticsLocale {
   return useContext(LoticsLocaleContext);
 }
+
+/**
+ * Resolve the effective BCP-47 tag for a locale-aware control: an explicit
+ * per-instance `locale` wins, else the pack's own {@link LoticsLocale.bcp47}.
+ * The pure core of {@link useLocaleTag}, kept RN-free so the resolution — and
+ * the segment ORDER it drives — is unit-testable without rendering a component.
+ */
+export function resolveLocaleTag(locale: LoticsLocale, explicit?: string): string {
+  return explicit ?? locale.bcp47;
+}
+
+/**
+ * The BCP-47 tag a date / time control should render in: the explicit `locale`
+ * prop when given, else the active `LoticsLocaleProvider` pack's tag. Wired date
+ * controls default their `locale` through this, so wrapping an app in the `vi`
+ * pack yields dd/MM/yyyy segment order, Vietnamese calendar names, and Vietnamese
+ * display with no per-instance prop — while an explicit `locale` still wins.
+ */
+export function useLocaleTag(explicit?: string): string {
+  return resolveLocaleTag(useContext(LoticsLocaleContext), explicit);
+}

package/src/vite.mjs

@@ -64,4 +64,10 @@ export const loticsOptimizeDeps = [
   "react-dom",
   "react-dom/client",
   "nullthrows",
+  // FilePreview's Excel/CSV engine (@lotics/xlsx) lazy-imports these CJS formula
+  // libraries; without pre-bundling, the dev optimizer can't resolve their CJS→ESM
+  // default export and the in-app spreadsheet preview fails (dev-server only — the
+  // rollup prod build handles the CJS interop).
+  "fast-formula-parser",
+  "@formulajs/formulajs",
 ];