@lotics/ui 42.3.0 → 42.4.0

package/MIGRATION.md

@@ -4,6 +4,47 @@ Breaking changes, newest first — normally per major, plus the rare minor that
 anyway (recorded under its exact version). The current contract lives in `AGENTS.md` + `docs/`;
 this file exists only to move an app from one release to the next.
 
+## 42.4.0 — `Picker` is named by its `FormField`, and its way back to empty has a name
+
+Two fixes to the same control, both about a thing on screen that the control did
+not actually say.
+
+### A `FormPicker` rendered a label the select was never associated with
+
+`Picker` never consumed `useFormField()`, so the label above it was decoration
+for sighted readers: the select announced its current value and no name.
+`NumberInput` and `TextInputField` had always consumed the binding;
+`FormDatePicker` and `FormSwitch` work around it by passing
+`accessibilityLabel={label}` down. `FormPicker` passed nothing, so it was the one
+wrapper whose control was anonymous.
+
+`Picker` now takes `id` / `aria-labelledby` / `aria-describedby` / `aria-invalid`
+from the enclosing field, exactly as the other two inputs do — so a `FormField`'s
+description, warning and error are announced with it as well. An explicit
+`accessibilityLabel` still applies OUTSIDE a field and is ignored inside one,
+because an aria-label diverging from the visible text is what breaks
+label-in-name. Nothing to change at a call site; a bare `Picker` is unaffected.
+
+### The way back to empty has a name
+
+Not a type break, but it changes text you will see: every `Picker` with
+`includeEmptyOption` used to render its empty row **unlabelled once a value was selected**,
+and that row is the only way to clear the field. So the control offered a blank line as its
+escape, at precisely the moment the reader needed it — and every select cell editor, form
+select and filter condition in an app inherited that.
+
+The row is now named. `includeEmptyOption` declares empty a **choice**, and a choice the
+reader picks the way they pick any other row has to read like one: it takes the locale pack's
+word (`picker.emptyOption` — "None" / "Không có") and keeps it whether or not something is
+selected. Override per instance with the new **`emptyOptionLabel`** when the field has a
+truer word ("No skill", "Unassigned").
+
+`placeholder` is unchanged and stays a different job: the hint shown while nothing is chosen,
+which disappears on selection. It is no longer consulted when the row is a choice, so a call
+site passing `placeholder` **as** the empty option's name should move that string to
+`emptyOptionLabel`. Nothing else has to change — no existing caller in this repo passed one,
+which is why they were all rendering blanks.
+
 ## 42.0.0 — `DateFilter`'s presets are a listbox, and "Custom" is not one of them
 
 Three defects with one root: the preset row used EMPHASIS to mean "current state", inside a

package/docs/catalog.md

@@ -765,7 +765,17 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 ### Pickers & selection controls
 
 - **`picker`** — `Picker`: native `<select>`, plain label-only single, native typeahead;
-  also home of the shared `PickerOption` type.
+  also home of the shared `PickerOption` type. Its empty row does one of two jobs and they
+  are not interchangeable: `includeEmptyOption` makes empty a **choice** the reader picks to
+  clear the field, so it is NAMED ("None", from the locale pack; override per instance with
+  `emptyOptionLabel`) and keeps that name after a selection — a name that disappears once
+  something is chosen is missing exactly when it is the only route back to empty. Without
+  that flag the row is a **placeholder**: it carries `placeholder` and leaves on selection.
+  Don't reach for `placeholder` to name a choice — a hint and a value read differently.
+  Inside a `FormField` (so inside `FormPicker`) it takes its NAME from the visible label
+  via the field's binding, along with the description/warning/error — pass `accessibilityLabel`
+  only for a bare `Picker` with no label beside it, since inside a field an aria-label that
+  differs from the visible text is what breaks label-in-name.
 - **`select`** — `Select`: rich/custom-rendered, single/multi, select-all, chips via
   `renderSelected(item, { remove })` + `searchable` + `allowCustom` — the tag field is just
   a multi Select; opens `OptionList`. Its trigger is `role="combobox"` (a `<div>`), never

package/package.json

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

package/src/locale.tsx

@@ -47,6 +47,11 @@ export interface LoticsLocale {
    *  in-cell editors): the select-all/deselect-all links, the empty state, the
    *  internal search-field placeholder, and the `Combobox` recents header. */
   optionList: { selectAll: string; deselectAll: string; clear: string; noResults: string; recent: string; searchPlaceholder: string };
+  /** `Picker`'s empty option, when the caller declares empty a CHOICE
+   *  (`includeEmptyOption`). A value, not an action — hence "None" rather than
+   *  the option list's "Clear": in a native `<select>` the reader picks it the
+   *  same way they pick any other row, so it has to read like one. */
+  picker: { emptyOption: string };
   datePicker: DatePickerLabels;
   calendar: CalendarLabels;
   /** `FilterChip` (and `ColumnFilter`): the generic clear affordance, used when
@@ -266,6 +271,7 @@ export const en: LoticsLocale = {
   },
   referenceField: { open: "Open", change: "Change", clear: "Clear", edit: "Edit", save: "Save", saving: "Saving…", cancel: "Cancel" },
   optionList: { selectAll: "Select all", deselectAll: "Deselect all", clear: "Clear", noResults: "No results", recent: "Recent", searchPlaceholder: "Search…" },
+  picker: { emptyOption: "None" },
   datePicker: { today: "Today", now: "Now", clear: "Clear", done: "Done", openCalendar: "Open calendar", time: "Time", startTime: "Start time", endTime: "End time", startDate: "Start date", endDate: "End date", addTime: "Add time", removeTime: "Remove time", year: "Year", month: "Month", day: "Day", hour: "Hour", minute: "Minute", dayPeriod: "AM/PM", invalidDate: "Enter a complete date", invalidTime: "Enter a complete time" },
   calendar: { previousMonth: "Previous month", nextMonth: "Next month" },
   filterChip: { clear: "Clear" },
@@ -437,6 +443,7 @@ export const vi: LoticsLocale = {
   },
   referenceField: { open: "Mở", change: "Đổi", clear: "Bỏ chọn", edit: "Sửa", save: "Lưu", saving: "Đang lưu…", cancel: "Huỷ" },
   optionList: { selectAll: "Chọn tất cả", deselectAll: "Bỏ chọn tất cả", clear: "Xóa", noResults: "Không có kết quả", recent: "Gần đây", searchPlaceholder: "Tìm…" },
+  picker: { emptyOption: "Không có" },
   datePicker: { today: "Hôm nay", now: "Bây giờ", clear: "Xóa", done: "Xong", openCalendar: "Mở lịch", time: "Giờ", startTime: "Giờ bắt đầu", endTime: "Giờ kết thúc", startDate: "Ngày bắt đầu", endDate: "Ngày kết thúc", addTime: "Thêm giờ", removeTime: "Bỏ giờ", year: "Năm", month: "Tháng", day: "Ngày", hour: "Giờ", minute: "Phút", dayPeriod: "SA/CH", invalidDate: "Nhập ngày đầy đủ", invalidTime: "Nhập giờ đầy đủ" },
   calendar: { previousMonth: "Tháng trước", nextMonth: "Tháng sau" },
   filterChip: { clear: "Xóa" },

package/src/picker.tsx

@@ -7,6 +7,9 @@ import { useFocusRing } from "./use_focus_ring";
 import { useHover } from "./use_hover";
 import { fontFamilyRegular, getInputTextStyle } from "./text_utils";
 import { Icon } from "./icon";
+import { useLoticsLocale } from "./locale";
+import { useFormField } from "./form_field";
+import { pickerEmptyOptionLabel } from "./picker_empty_option";
 
 export interface PickerOption<T extends string = string, D = unknown> {
   label?: string;
@@ -41,7 +44,15 @@ export interface PickerProps<T extends string = string> {
   testID?: string;
   disabled?: boolean;
   autoFocus?: boolean;
+  /** Declares empty a CHOICE: the reader may pick it to clear the field, so the
+   *  option stays in the list after something is selected. Because it is a value
+   *  they pick, it is NAMED — see `emptyOptionLabel`. */
   includeEmptyOption?: boolean;
+  /** Overrides the name of that empty choice (locale default: "None"). Distinct
+   *  from `placeholder`, which is the hint shown while nothing is chosen: a hint
+   *  and a value are different jobs, and one string cannot do both — read as a
+   *  prompt it invites input, read as a row it looks selectable. */
+  emptyOptionLabel?: string;
   value?: T | null;
   onValueChange?: (value: T) => void;
 }
@@ -61,12 +72,25 @@ export function Picker<T extends string>(props: PickerProps<T>) {
     includeEmptyOption,
     onValueChange,
     placeholder,
+    emptyOptionLabel,
     accessibilityLabel,
     style,
     disabled = false,
     autoFocus = false,
   } = props;
 
+  const binding = useFormField();
+  const describedBy =
+    [binding?.descriptionId, binding?.warningId, binding?.errorId].filter(Boolean).join(" ") ||
+    undefined;
+  const locale = useLoticsLocale();
+  const emptyLabel = pickerEmptyOptionLabel({
+    includeEmptyOption,
+    emptyOptionLabel,
+    placeholder,
+    localeEmptyOption: locale.picker.emptyOption,
+  });
+
   const pickerRef = useRef<RNPicker<string>>(null);
   // The native <select> is a text-like control — ring on any focus (like the inputs).
   const { focusVisible, focusProps } = useFocusRing({ always: true });
@@ -100,7 +124,18 @@ export function Picker<T extends string>(props: PickerProps<T>) {
       <RNPicker
         ref={pickerRef}
         testID={testID}
-        accessibilityLabel={accessibilityLabel}
+        // Inside a `FormField` the VISIBLE label names the control, the same way
+        // it does for `NumberInput` / `TextInputField`. Without this a
+        // `FormPicker` rendered a label the select was never associated with, so
+        // it announced its current value and no name at all — the label was
+        // there for sighted readers only. An explicit `accessibilityLabel` is
+        // used only OUTSIDE a field: inside one, an aria-label that differs from
+        // the visible text is what breaks label-in-name.
+        id={binding?.inputId}
+        aria-labelledby={binding?.labelId}
+        aria-label={!binding ? accessibilityLabel : undefined}
+        aria-describedby={describedBy}
+        aria-invalid={binding?.invalid || undefined}
         onFocus={focusProps.onFocus}
         onBlur={focusProps.onBlur}
         // Empty selection maps to "" (the placeholder option's value), never
@@ -113,10 +148,20 @@ export function Picker<T extends string>(props: PickerProps<T>) {
         enabled={!disabled}
       >
         {(!value || includeEmptyOption) && (
-          // Show the placeholder as the empty option (the standard
-          // `<option value="" selected>Placeholder</option>` pattern) so a
-          // native select hints what to choose.
-          <RNPicker.Item label={!value ? (placeholder ?? "") : ""} value="" />
+          // Two different jobs share this one row, and which one it is doing
+          // depends on `includeEmptyOption`:
+          //
+          // A CHOICE (`includeEmptyOption`) — the reader picks it to clear the
+          // field, so it is named, and named the SAME whether or not something
+          // is currently selected. It previously went blank the moment a value
+          // existed, which is exactly when the reader needs it: every select in
+          // the product offered an unlabelled row as its only way back to empty.
+          //
+          // A PLACEHOLDER (otherwise) — it exists only because nothing is
+          // chosen yet, so it carries the caller's hint and disappears on
+          // selection. Naming it "None" here would turn a prompt into an
+          // apparent value.
+          <RNPicker.Item label={emptyLabel} value="" />
         )}
         {options.map((option) =>
           option ? (

package/src/picker_empty_option.ts

@@ -0,0 +1,30 @@
+/**
+ * What `Picker`'s empty row is called — and it depends on which of two jobs that
+ * row is doing.
+ *
+ * A CHOICE (`includeEmptyOption`) is how the reader gets back to no value. They
+ * pick it the way they pick any other row, so it is NAMED, and named the same
+ * whether or not something is currently selected — a name that vanishes on
+ * selection vanishes exactly when it is needed.
+ *
+ * A PLACEHOLDER exists only because nothing is chosen yet. It carries the
+ * caller's hint and leaves on selection; naming it "None" would turn a prompt
+ * into an apparent value.
+ *
+ * RN-free so the rule is testable as the rule, rather than through a native
+ * `<select>` and its untranspiled dependency.
+ */
+export function pickerEmptyOptionLabel(opts: {
+  includeEmptyOption?: boolean;
+  /** Per-instance override for the choice's name. */
+  emptyOptionLabel?: string;
+  /** The caller's hint, used only when the row is a placeholder. */
+  placeholder?: string;
+  /** The locale pack's word for "no value". */
+  localeEmptyOption: string;
+}): string {
+  if (opts.includeEmptyOption) {
+    return opts.emptyOptionLabel ?? opts.localeEmptyOption;
+  }
+  return opts.placeholder ?? "";
+}