@lotics/ui 42.4.0 → 43.0.0

package/src/time_columns.tsx

@@ -0,0 +1,225 @@
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import { ScrollView, StyleSheet, View } from "react-native";
+import { colors } from "./colors";
+import { CONTROL_RADIUS } from "./control_surface";
+import { MenuButton } from "./menu_button";
+import { Text } from "./text";
+import { useLoticsLocale, useLocaleTag } from "./locale";
+import {
+  composeTime,
+  dayPeriodOptions,
+  decomposeTime,
+  hourOptions,
+  minuteOptions,
+} from "./time_options";
+import type { PickerOption } from "./picker";
+
+/** Row height, and the unit the seat scroll counts in. */
+const ROW_HEIGHT = 36;
+/** How many rows a column shows before it scrolls. Odd, so the seated row can
+ *  sit near the middle with context above and below it rather than at an edge. */
+const VISIBLE_ROWS = 7;
+
+export interface TimeColumnsProps {
+  /** Canonical 24-hour `"HH:mm"`, `""` when empty (the columns then sit on midnight). */
+  value: string;
+  /** Fires on every pick, with a complete canonical time — one column at a time,
+   *  so the value is live rather than staged behind a confirm. */
+  onValueChange: (value: string) => void;
+  /** BCP-47 locale deciding 12- vs 24-hour, and whether there is a period column
+   *  at all. Defaults to the active `LoticsLocaleProvider` locale. */
+  locale?: string;
+  /** Accessible names for the three columns. Defaults to the `datePicker` slice. */
+  labels?: { hour: string; minute: string; dayPeriod: string };
+}
+
+/**
+ * The picking face of a time: an hour column, a minute column, and — only where
+ * the locale uses one — a day period.
+ *
+ * Split by UNIT rather than offered as composed times, which is what a native
+ * picker does and what makes every time reachable: a list of whole times has to
+ * choose a step, and any step makes the times between its rungs pickable only by
+ * typing. It also puts AM/PM where it belongs. A period is a choice between two
+ * named things and never a thing to spell — leaving it on a keyboard was the
+ * clearest sign the composed list was the wrong model.
+ *
+ * Each column commits on its own, so the value is always a real time and the
+ * face can be read back from it. There is no draft to confirm and nothing
+ * half-entered to guard against.
+ */
+export function TimeColumns(props: TimeColumnsProps) {
+  const { value, onValueChange } = props;
+  const localeTag = useLocaleTag(props.locale);
+  const loc = useLoticsLocale().datePicker;
+  const labels = props.labels ?? loc;
+
+  const parts = useMemo(() => decomposeTime(value, localeTag), [value, localeTag]);
+  const hours = useMemo(() => hourOptions(localeTag), [localeTag]);
+  const minutes = useMemo(() => minuteOptions(), []);
+  const periods = useMemo(() => dayPeriodOptions(localeTag), [localeTag]);
+
+  const pad = (n: number) => String(n).padStart(2, "0");
+
+  return (
+    <View style={styles.columns}>
+      <TimeColumn
+        accessibilityLabel={labels.hour}
+        options={hours}
+        value={pad(parts.displayHour)}
+        onValueChange={(next) => onValueChange(composeTime({ ...parts, displayHour: Number(next) }))}
+      />
+      <TimeColumn
+        accessibilityLabel={labels.minute}
+        options={minutes}
+        value={pad(parts.minute)}
+        onValueChange={(next) => onValueChange(composeTime({ ...parts, minute: Number(next) }))}
+      />
+      {periods.length > 0 && (
+        <TimeColumn
+          accessibilityLabel={labels.dayPeriod}
+          options={periods}
+          value={parts.pm ? "pm" : "am"}
+          onValueChange={(next) => onValueChange(composeTime({ ...parts, pm: next === "pm" }))}
+        />
+      )}
+    </View>
+  );
+}
+
+interface TimeColumnProps {
+  options: PickerOption<string>[];
+  value: string;
+  onValueChange: (value: string) => void;
+  accessibilityLabel: string;
+}
+
+/**
+ * One unit's column: a listbox that scrolls to its selection on open and moves
+ * on arrows.
+ *
+ * Roving tabindex, per the composite-widget rule — the selected row is the one
+ * tab stop and the rest are reached with arrows, so Tab crosses the three
+ * columns in three stops instead of sixty. Not `OptionList`: that body owns a
+ * hidden autofocus input for its typeahead, and three of them side by side would
+ * fight over focus the moment the popover opened.
+ */
+function TimeColumn(props: TimeColumnProps) {
+  const { options, value, onValueChange, accessibilityLabel } = props;
+  const scrollRef = useRef<ScrollView>(null);
+  const rowRefs = useRef<(View | null)[]>([]);
+
+  const selectedIndex = options.findIndex((option) => option.value === value);
+  // A value the column does not offer still needs a tab stop, or the column
+  // becomes unreachable by keyboard.
+  const tabStopIndex = selectedIndex === -1 ? 0 : selectedIndex;
+
+  const scrollToIndex = useCallback((index: number) => {
+    if (index < 0) return;
+    // Centre the row: subtract half the visible window, floored at the top.
+    const offset = index * ROW_HEIGHT - ((VISIBLE_ROWS - 1) / 2) * ROW_HEIGHT;
+    scrollRef.current?.scrollTo({ y: Math.max(0, offset), animated: false });
+  }, []);
+
+  // Seat on OPEN only. The column mounts with the popover, so this runs once per
+  // opening; re-running it on every pick would yank the list back under the
+  // pointer while someone is scanning it.
+  const seatedRef = useRef(false);
+  useEffect(() => {
+    if (seatedRef.current) return;
+    seatedRef.current = true;
+    scrollToIndex(tabStopIndex);
+  }, [tabStopIndex, scrollToIndex]);
+
+  const handleKeyDown = useCallback(
+    (event: { key: string; preventDefault?: () => void }, index: number) => {
+      const last = options.length - 1;
+      let next = index;
+      switch (event.key) {
+        case "ArrowDown":
+          next = index === last ? 0 : index + 1;
+          break;
+        case "ArrowUp":
+          next = index === 0 ? last : index - 1;
+          break;
+        case "Home":
+          next = 0;
+          break;
+        case "End":
+          next = last;
+          break;
+        case "Enter":
+        case " ":
+          event.preventDefault?.();
+          onValueChange(options[index].value);
+          return;
+        default:
+          return;
+      }
+      event.preventDefault?.();
+      // Selection follows focus, the listbox pattern for a single-select column:
+      // arrowing IS choosing, so the value under the cursor is always the value.
+      onValueChange(options[next].value);
+      scrollToIndex(next);
+      rowRefs.current[next]?.focus();
+    },
+    [options, onValueChange, scrollToIndex],
+  );
+
+  return (
+    <ScrollView
+      ref={scrollRef}
+      style={styles.column}
+      contentContainerStyle={styles.columnContent}
+      showsVerticalScrollIndicator={false}
+      accessibilityLabel={accessibilityLabel}
+      // `listbox` is valid ARIA but absent from RN's Role enum; rn-web forwards it.
+      role={"listbox" as "list"}
+    >
+      {options.map((option, index) => (
+        <MenuButton
+          key={option.value}
+          ref={(node: View | null) => {
+            rowRefs.current[index] = node;
+          }}
+          role="option"
+          selected={index === selectedIndex}
+          title={
+            <Text size="sm" userSelect="none">
+              {option.label}
+            </Text>
+          }
+          accessibilityLabel={option.label}
+          onPress={() => onValueChange(option.value)}
+          onKeyDown={(event) => handleKeyDown(event, index)}
+          // Exactly one stop per column; the rest are reached with arrows.
+          // tabIndex, NOT focusable — RN-Web's Pressable ignores `focusable`.
+          tabIndex={index === tabStopIndex ? 0 : -1}
+          style={styles.row}
+        />
+      ))}
+    </ScrollView>
+  );
+}
+
+const styles = StyleSheet.create({
+  columns: {
+    flexDirection: "row",
+    gap: 4,
+  },
+  column: {
+    maxHeight: ROW_HEIGHT * VISIBLE_ROWS,
+    borderRadius: CONTROL_RADIUS,
+    backgroundColor: colors.white,
+  },
+  columnContent: {
+    // Padding rather than a spacer row, so the first and last values can still
+    // reach the middle of the window when the column is scrolled to an end.
+    paddingVertical: 2,
+  },
+  row: {
+    height: ROW_HEIGHT,
+    minWidth: 56,
+    justifyContent: "center",
+  },
+});

package/src/time_options.ts

@@ -0,0 +1,138 @@
+import { TIME_FORMAT_OPTIONS, getTimeLayout, to12h } from "./date_segments";
+import type { PickerOption } from "./picker";
+
+/**
+ * A time of day split into the parts a person PICKS.
+ *
+ * `displayHour` is what the locale shows on the hour column — 0–23 where the
+ * locale uses a 24-hour clock, 12/1–11 where it uses a 12-hour one. It is not
+ * the canonical hour: in a 12-hour locale the same displayed hour means two
+ * different times and only `pm` says which, which is why composing takes both.
+ */
+export interface TimeParts {
+  displayHour: number;
+  minute: number;
+  /** `null` in a 24-hour locale — there is no period to choose. */
+  pm: boolean | null;
+}
+
+const MINUTES_PER_HOUR = 60;
+
+/** Whether `locale` puts a day period on the clock, and what it calls one. */
+export function dayPeriodLabels(locale: string): { am: string; pm: string } | null {
+  const layout = getTimeLayout(locale);
+  return layout.hour12 ? { am: layout.amText, pm: layout.pmText } : null;
+}
+
+/** Minute-of-day for a canonical `"HH:mm"`, or `null` when it is not one. */
+export function timeToMinuteOfDay(value: string): number | null {
+  const match = /^(\d{2}):(\d{2})$/.exec(value);
+  if (!match) return null;
+  const hour = Number(match[1]);
+  const minute = Number(match[2]);
+  if (hour > 23 || minute > 59) return null;
+  return hour * MINUTES_PER_HOUR + minute;
+}
+
+/**
+ * Split a canonical `"HH:mm"` into the parts the columns show.
+ *
+ * TOTAL: a missing or unreadable value decomposes to midnight rather than
+ * returning null, because the columns must always have a row to sit on. An empty
+ * field therefore opens at 12:00 AM / 00:00 and the first pick composes a real
+ * time from it — there is no partial state to represent, which is the whole
+ * reason a picked time needs no "incomplete" signal.
+ */
+export function decomposeTime(value: string, locale: string): TimeParts {
+  const minuteOfDay = timeToMinuteOfDay(value) ?? 0;
+  const hour24 = Math.floor(minuteOfDay / MINUTES_PER_HOUR);
+  const minute = minuteOfDay % MINUTES_PER_HOUR;
+  if (!dayPeriodLabels(locale)) return { displayHour: hour24, minute, pm: null };
+  const { h12, pm } = to12h(hour24);
+  return { displayHour: h12, minute, pm };
+}
+
+/** Build a canonical 24-hour `"HH:mm"` back out of the parts. */
+export function composeTime(parts: TimeParts): string {
+  const { displayHour, minute, pm } = parts;
+  let hour24 = displayHour;
+  if (pm !== null) {
+    // 12 AM is 00 and 12 PM is 12 — the one place the 12-hour clock is not
+    // simply "add twelve".
+    const base = displayHour % 12;
+    hour24 = pm ? base + 12 : base;
+  }
+  return `${String(hour24).padStart(2, "0")}:${String(minute).padStart(2, "0")}`;
+}
+
+const formatters = new Map<string, Intl.DateTimeFormat>();
+
+function formatter(locale: string): Intl.DateTimeFormat {
+  const cached = formatters.get(locale);
+  if (cached) return cached;
+  const next = new Intl.DateTimeFormat(locale, TIME_FORMAT_OPTIONS);
+  formatters.set(locale, next);
+  return next;
+}
+
+/**
+ * How a time of day READS in `locale` — 12- or 24-hour, in that locale's own
+ * digits and separator.
+ *
+ * Formats under the same {@link TIME_FORMAT_OPTIONS} the date field's segments
+ * lay themselves out from, so a time shown on a picker's face and the same time
+ * shown in a datetime field can never disagree. A value that is not a time comes
+ * back unchanged rather than as "Invalid Date".
+ */
+export function formatTimeOfDay(value: string, locale: string): string {
+  const minuteOfDay = timeToMinuteOfDay(value);
+  if (minuteOfDay === null) return value;
+  // Any date works — only the time fields are formatted. Fixed rather than
+  // `new Date()` so the function is pure and testable.
+  const at = new Date(2023, 0, 2, Math.floor(minuteOfDay / MINUTES_PER_HOUR), minuteOfDay % MINUTES_PER_HOUR);
+  return formatter(locale).format(at);
+}
+
+const pad = (n: number) => String(n).padStart(2, "0");
+
+/**
+ * The hours a locale offers, in clock order.
+ *
+ * A 12-hour locale leads with 12 rather than 1 — that is the order on a clock
+ * face and on every native picker, and starting at 1 puts midnight and noon at
+ * the bottom of a list you scroll from the top.
+ */
+export function hourOptions(locale: string): PickerOption<string>[] {
+  if (!dayPeriodLabels(locale)) {
+    return Array.from({ length: 24 }, (_, hour) => ({ value: pad(hour), label: pad(hour) }));
+  }
+  return [12, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11].map((hour) => ({
+    value: pad(hour),
+    label: pad(hour),
+  }));
+}
+
+/**
+ * Every minute of the hour.
+ *
+ * Not a coarser step: a step turns the picker into a list of ALLOWED times, and
+ * a gate cut-off at 13:07 is then unreachable by picking — which is what forced
+ * the old flat list to splice odd values back in. Sixty rows scroll and seat
+ * exactly like the hours beside them.
+ */
+export function minuteOptions(): PickerOption<string>[] {
+  return Array.from({ length: MINUTES_PER_HOUR }, (_, minute) => ({
+    value: pad(minute),
+    label: pad(minute),
+  }));
+}
+
+/** The two periods, named as `locale` names them. Empty where it has none. */
+export function dayPeriodOptions(locale: string): PickerOption<string>[] {
+  const labels = dayPeriodLabels(locale);
+  if (!labels) return [];
+  return [
+    { value: "am", label: labels.am },
+    { value: "pm", label: labels.pm },
+  ];
+}

package/src/time_picker.tsx

@@ -1,114 +1,152 @@
-import { useMemo, useState } from "react";
+import { useRef, useState } from "react";
 import { StyleSheet, View } from "react-native";
 import { colors } from "./colors";
-import { CONTROL_RADIUS, FOCUS_RING, HOVER_BORDER } from "./control_surface";
-import { useHover } from "./use_hover";
-import { DateSegments } from "./date_segments_field";
-import { SegmentLabels, timeSegmentsConfig } from "./date_segments";
+import {
+  CONTROL_HEIGHT,
+  CONTROL_PADDING_V,
+  CONTROL_RADIUS,
+  CONTROL_TRANSITION,
+  FOCUS_RING,
+  HOVER_BORDER,
+} from "./control_surface";
+import { Icon } from "./icon";
+import { Popover, PopoverContent } from "./popover";
+import { PressableHighlight } from "./pressable_highlight";
+import { Text } from "./text";
+import { TimeColumns } from "./time_columns";
+import { formatTimeOfDay } from "./time_options";
 import { useLoticsLocale, useLocaleTag } from "./locale";
 
 export interface TimePickerProps {
   /** Canonical 24-hour "HH:mm", `""` when empty — independent of how it displays. */
   value?: string;
   onValueChange: (value: string) => void;
-  onBlur?: () => void;
-  autoFocus?: boolean;
   disabled?: boolean;
   accessibilityLabel?: string;
   /**
-   * BCP-47 locale deciding 12- vs 24-hour DISPLAY. Defaults to the active
-   * `LoticsLocaleProvider` locale.
+   * BCP-47 locale deciding 12- vs 24-hour DISPLAY, and whether the picker offers
+   * a day-period column at all. Defaults to the active `LoticsLocaleProvider`
+   * locale.
    *
-   * This is the whole reason the field is segments and not `<input type="time">`:
-   * a native time input takes its 12/24-hour form from the BROWSER's UI locale
-   * and ignores `lang` entirely, so a Vietnamese screen on an en-US browser read
+   * This is the whole reason the face is ours and not `<input type="time">`: a
+   * native time input takes its 12/24-hour form from the BROWSER's UI locale and
+   * ignores `lang` entirely, so a Vietnamese screen on an en-US browser read
    * "01:45 PM" next to its own 24-hour "13:45 02/01/2023".
    */
   locale?: string;
-  /** Accessible names per segment. Defaults to the `datePicker` locale slice. */
-  segmentLabels?: SegmentLabels;
-  /** Escape pressed in a segment — an inline editor cancels its session. */
-  onEscape?: () => void;
-  /** True while the entry is non-empty but still half-typed (an hour, no minute).
-   *  An inline editor blocks its commit on this. */
-  onIncompleteChange?: (incomplete: boolean) => void;
+  /** Shown when no time is set. Defaults to the `datePicker` slice's `chooseTime`. */
+  placeholder?: string;
   testID?: string;
 }
 
 /**
- * A time of day. The value is always canonical 24-hour "HH:mm"; the locale only
- * decides what the user sees and types (an AM/PM segment appears only where the
- * locale uses one).
+ * A time of day: the value on a pressable field, and an hour / minute / period
+ * picker behind it.
+ *
+ * There is no text entry. A time used to be TYPED into segments here, with the
+ * picker bolted on as a small glyph inside the field, and both halves of that
+ * were wrong. The glyph sat exactly where `DateField` puts a display-only
+ * calendar icon — same slot, same size, same colour, one pressable and one not —
+ * so the only affordance for picking was one a reader had no way to identify.
+ * And typing is simply the wrong input for part of a time: a day period is a
+ * choice between two named things, and asking someone to spell "PM" is asking
+ * them to type an answer to a yes/no question.
+ *
+ * The trigger is the kit's "current value, opens a list" surface — the bordered
+ * control a `Select` uses — so a time field is recognisable as pickable by the
+ * same shape as every other field that opens something.
+ *
+ * The value stays canonical 24-hour "HH:mm" whatever the locale shows.
  */
 export function TimePicker(props: TimePickerProps) {
   const {
     value = "",
     onValueChange,
-    onBlur,
-    autoFocus,
     disabled,
     accessibilityLabel,
     locale,
-    onEscape,
-    onIncompleteChange,
     testID,
   } = props;
   const localeTag = useLocaleTag(locale);
   const loc = useLoticsLocale().datePicker;
-  const segmentLabels = props.segmentLabels ?? loc;
-  const config = useMemo(() => timeSegmentsConfig(localeTag), [localeTag]);
-  const { hovered, hoverProps } = useHover();
-  const [focused, setFocused] = useState(false);
+  const placeholder = props.placeholder ?? loc.chooseTime;
+  const [open, setOpen] = useState(false);
+  const triggerRef = useRef<View>(null);
 
   return (
-    <View
-      {...(hoverProps as object)}
-      style={[
-        styles.frame,
-        hovered && !disabled && styles.frameHovered,
-        focused && !disabled && styles.frameFocused,
-        disabled && styles.frameDisabled,
-      ]}
-      testID={testID}
-    >
-      <DateSegments
-        value={value}
-        onChange={onValueChange}
-        config={config}
-        segmentLabels={segmentLabels}
+    <>
+      <PressableHighlight
+        focusRing
+        ref={triggerRef}
+        testID={testID}
         disabled={disabled}
-        autoFocus={autoFocus}
-        accessibilityLabel={accessibilityLabel}
-        onFocus={() => setFocused(true)}
-        onBlur={() => {
-          setFocused(false);
-          onBlur?.();
-        }}
-        onEscape={onEscape}
-        onIncompleteChange={onIncompleteChange}
-      />
-    </View>
+        // A field whose value comes from a list it opens — the same role the
+        // kit's other "pick one" triggers carry.
+        accessibilityRole="combobox"
+        accessibilityLabel={accessibilityLabel ?? loc.chooseTime}
+        aria-expanded={open}
+        aria-disabled={disabled}
+        style={(state) => [
+          styles.trigger,
+          CONTROL_TRANSITION,
+          open && styles.opened,
+          disabled && styles.disabled,
+          state.hovered && !disabled && { borderColor: HOVER_BORDER },
+        ]}
+        onPress={disabled ? undefined : () => setOpen(true)}
+      >
+        <Icon
+          name="clock"
+          size={18}
+          color={disabled ? colors.zinc["300"] : colors.zinc["400"]}
+        />
+        {value ? (
+          <Text size="sm" userSelect="none">
+            {formatTimeOfDay(value, localeTag)}
+          </Text>
+        ) : (
+          <Text size="sm" color="zinc-500" userSelect="none">
+            {placeholder}
+          </Text>
+        )}
+      </PressableHighlight>
+      <Popover
+        open={open && !disabled}
+        onOpenChange={setOpen}
+        triggerRef={triggerRef}
+        side="bottom"
+        align="start"
+      >
+        <PopoverContent testID={testID ? `${testID}_time_columns` : undefined} disableBodyScroll>
+          <TimeColumns value={value} onValueChange={onValueChange} locale={locale} />
+        </PopoverContent>
+      </Popover>
+    </>
   );
 }
 
 const styles = StyleSheet.create({
-  frame: {
+  trigger: {
     flexDirection: "row",
     alignItems: "center",
-    height: 40,
+    gap: 6,
     paddingHorizontal: 8,
-    borderRadius: CONTROL_RADIUS,
+    // Shared with every other control trigger, so a time field seats at exactly
+    // `CONTROL_HEIGHT` beside the date field it usually sits under.
+    paddingVertical: CONTROL_PADDING_V,
+    minHeight: CONTROL_HEIGHT,
     borderWidth: 1,
     borderColor: colors.border,
+    borderRadius: CONTROL_RADIUS,
     backgroundColor: colors.background,
   },
-  frameHovered: {
-    borderColor: HOVER_BORDER,
-  },
-  frameFocused: {
+  opened: {
+    // Mouse-opened, so the trigger never takes keyboard focus — wear the same
+    // ring a focused control gets, over the unchanged 1px border.
     boxShadow: FOCUS_RING,
   },
-  frameDisabled: {
+  disabled: {
     backgroundColor: colors.zinc[50],
+    opacity: 0.5,
   },
 });

package/src/use_option_list.ts

@@ -252,6 +252,25 @@ export function useOptionList<T extends string, MULTI extends boolean = false, D
     if (index >= 0) scrollRef.current?.scrollTo({ y: index * OPTION_HEIGHT - 80, animated: false });
   }, []);
 
+  // Scroll the OPENING seat into view.
+  //
+  // `initialIndex` seats the highlight through `useState`, which fires no
+  // `onActiveChange` — so the row it lands on was highlighted and never scrolled
+  // to. On a list short enough to fit that is invisible; past a screenful the
+  // list opens at the top with the current value somewhere below the fold, which
+  // is the one row it was opened to show. A day of times at 15-minute steps is 96
+  // rows, so an afternoon value sat two thirds of the way down an unscrolled list.
+  //
+  // Gated on rows ARRIVING rather than on mount, so an async list (options still
+  // loading when the popover opens) seats on its real value instead of on the
+  // empty list's index 0. Once only: after that the member owns the scroll.
+  const scrollSeatedRef = useRef(false);
+  useEffect(() => {
+    if (scrollSeatedRef.current || rows.length === 0) return;
+    scrollSeatedRef.current = true;
+    scrollToIndex(initialActiveIndex);
+  }, [rows.length, initialActiveIndex, scrollToIndex]);
+
   const requestClose = useCallback(() => {
     onRequestClose?.();
     if (onClose) {