@lotics/ui 42.0.0 → 42.4.0

package/src/colors.ts

@@ -1,386 +1,17 @@
-const palette = {
-  black: "rgba(0,0,0,1)",
-  white: "rgba(255,255,255,1)",
-
-  // We use RGBA so that we can use React Native Animations with colors
-  red: {
-    50: "rgba(254, 242, 242, 1)",
-    100: "rgba(254, 226, 226, 1)",
-    200: "rgba(254, 202, 202, 1)",
-    300: "rgba(252, 165, 165, 1)",
-    400: "rgba(248, 113, 113, 1)",
-    500: "rgba(239, 68, 68, 1)",
-    600: "rgba(220, 38, 38, 1)",
-    700: "rgba(185, 28, 28, 1)",
-    800: "rgba(153, 27, 27, 1)",
-    900: "rgba(127, 29, 29, 1)",
-    950: "rgba(69, 10, 10, 1)",
-  },
-  orange: {
-    50: "rgba(255, 247, 237, 1)",
-    100: "rgba(255, 237, 213, 1)",
-    200: "rgba(254, 215, 170, 1)",
-    300: "rgba(253, 186, 116, 1)",
-    400: "rgba(251, 146, 60, 1)",
-    500: "rgba(249, 115, 22, 1)",
-    600: "rgba(234, 88, 12, 1)",
-    700: "rgba(194, 65, 12, 1)",
-    800: "rgba(154, 52, 18, 1)",
-    900: "rgba(124, 45, 18, 1)",
-    950: "rgba(67, 20, 7, 1)",
-  },
-  amber: {
-    50: "rgba(255, 251, 235, 1)",
-    100: "rgba(254, 243, 199, 1)",
-    200: "rgba(253, 230, 138, 1)",
-    300: "rgba(252, 211, 77, 1)",
-    400: "rgba(251, 191, 36, 1)",
-    500: "rgba(245, 158, 11, 1)",
-    600: "rgba(217, 119, 6, 1)",
-    700: "rgba(180, 83, 9, 1)",
-    800: "rgba(146, 64, 14, 1)",
-    900: "rgba(120, 53, 15, 1)",
-    950: "rgba(69, 26, 3, 1)",
-  },
-  yellow: {
-    50: "rgba(254, 252, 232, 1)",
-    100: "rgba(254, 249, 195, 1)",
-    200: "rgba(254, 240, 138, 1)",
-    300: "rgba(253, 224, 71, 1)",
-    400: "rgba(250, 204, 21, 1)",
-    500: "rgba(234, 179, 8, 1)",
-    600: "rgba(202, 138, 4, 1)",
-    700: "rgba(161, 98, 7, 1)",
-    800: "rgba(133, 77, 14, 1)",
-    900: "rgba(113, 63, 18, 1)",
-    950: "rgba(66, 32, 6, 1)",
-  },
-  lime: {
-    50: "rgba(247, 254, 231, 1)",
-    100: "rgba(236, 252, 203, 1)",
-    200: "rgba(217, 249, 157, 1)",
-    300: "rgba(190, 242, 100, 1)",
-    400: "rgba(163, 230, 53, 1)",
-    500: "rgba(132, 204, 22, 1)",
-    600: "rgba(101, 163, 13, 1)",
-    700: "rgba(77, 124, 15, 1)",
-    800: "rgba(63, 98, 18, 1)",
-    900: "rgba(54, 83, 20, 1)",
-    950: "rgba(26, 46, 5, 1)",
-  },
-  green: {
-    50: "rgba(240, 253, 244, 1)",
-    100: "rgba(220, 252, 231, 1)",
-    200: "rgba(187, 247, 208, 1)",
-    300: "rgba(134, 239, 172, 1)",
-    400: "rgba(74, 222, 128, 1)",
-    500: "rgba(34, 197, 94, 1)",
-    600: "rgba(22, 163, 74, 1)",
-    700: "rgba(21, 128, 61, 1)",
-    800: "rgba(22, 101, 52, 1)",
-    900: "rgba(20, 83, 45, 1)",
-    950: "rgba(5, 46, 22, 1)",
-  },
-  emerald: {
-    50: "rgba(236, 253, 245, 1)",
-    100: "rgba(209, 250, 229, 1)",
-    200: "rgba(167, 243, 208, 1)",
-    300: "rgba(110, 231, 183, 1)",
-    400: "rgba(52, 211, 153, 1)",
-    500: "rgba(16, 185, 129, 1)",
-    600: "rgba(5, 150, 105, 1)",
-    700: "rgba(4, 120, 87, 1)",
-    800: "rgba(6, 95, 70, 1)",
-    900: "rgba(6, 78, 59, 1)",
-    950: "rgba(2, 44, 34, 1)",
-  },
-  teal: {
-    50: "rgba(240, 253, 250, 1)",
-    100: "rgba(204, 251, 241, 1)",
-    200: "rgba(153, 246, 228, 1)",
-    300: "rgba(94, 234, 212, 1)",
-    400: "rgba(45, 212, 191, 1)",
-    500: "rgba(20, 184, 166, 1)",
-    600: "rgba(13, 148, 136, 1)",
-    700: "rgba(15, 118, 110, 1)",
-    800: "rgba(17, 94, 89, 1)",
-    900: "rgba(19, 78, 74, 1)",
-    950: "rgba(4, 47, 46, 1)",
-  },
-  cyan: {
-    50: "rgba(236, 254, 255, 1)",
-    100: "rgba(207, 250, 254, 1)",
-    200: "rgba(165, 243, 252, 1)",
-    300: "rgba(103, 232, 249, 1)",
-    400: "rgba(34, 211, 238, 1)",
-    500: "rgba(6, 182, 212, 1)",
-    600: "rgba(8, 145, 178, 1)",
-    700: "rgba(14, 116, 144, 1)",
-    800: "rgba(21, 94, 117, 1)",
-    900: "rgba(22, 78, 99, 1)",
-    950: "rgba(8, 51, 68, 1)",
-  },
-  sky: {
-    50: "rgba(240, 249, 255, 1)",
-    100: "rgba(224, 242, 254, 1)",
-    200: "rgba(186, 230, 253, 1)",
-    300: "rgba(125, 211, 252, 1)",
-    400: "rgba(56, 189, 248, 1)",
-    500: "rgba(14, 165, 233, 1)",
-    600: "rgba(2, 132, 199, 1)",
-    700: "rgba(3, 105, 161, 1)",
-    800: "rgba(7, 89, 133, 1)",
-    900: "rgba(12, 74, 110, 1)",
-    950: "rgba(8, 47, 73, 1)",
-  },
-  blue: {
-    50: "rgba(239, 246, 255, 1)",
-    100: "rgba(219, 234, 254, 1)",
-    200: "rgba(191, 219, 254, 1)",
-    300: "rgba(147, 197, 253, 1)",
-    400: "rgba(96, 165, 250, 1)",
-    500: "rgba(59, 130, 246, 1)",
-    600: "rgba(37, 99, 235, 1)",
-    700: "rgba(29, 78, 216, 1)",
-    800: "rgba(30, 64, 175, 1)",
-    900: "rgba(30, 58, 138, 1)",
-    950: "rgba(23, 37, 84, 1)",
-  },
-  indigo: {
-    50: "rgba(238, 242, 255, 1)",
-    100: "rgba(224, 231, 255, 1)",
-    200: "rgba(199, 210, 254, 1)",
-    300: "rgba(165, 180, 252, 1)",
-    400: "rgba(129, 140, 248, 1)",
-    500: "rgba(99, 102, 241, 1)",
-    600: "rgba(79, 70, 229, 1)",
-    700: "rgba(67, 56, 202, 1)",
-    800: "rgba(55, 48, 163, 1)",
-    900: "rgba(49, 46, 129, 1)",
-    950: "rgba(30, 27, 75, 1)",
-  },
-  violet: {
-    50: "rgba(245, 243, 255, 1)",
-    100: "rgba(237, 233, 254, 1)",
-    200: "rgba(221, 214, 254, 1)",
-    300: "rgba(196, 181, 253, 1)",
-    400: "rgba(167, 139, 250, 1)",
-    500: "rgba(139, 92, 246, 1)",
-    600: "rgba(124, 58, 237, 1)",
-    700: "rgba(109, 40, 217, 1)",
-    800: "rgba(91, 33, 182, 1)",
-    900: "rgba(76, 29, 149, 1)",
-    950: "rgba(46, 16, 101, 1)",
-  },
-  purple: {
-    50: "rgba(250, 245, 255, 1)",
-    100: "rgba(243, 232, 255, 1)",
-    200: "rgba(233, 213, 255, 1)",
-    300: "rgba(216, 180, 254, 1)",
-    400: "rgba(192, 132, 252, 1)",
-    500: "rgba(168, 85, 247, 1)",
-    600: "rgba(147, 51, 234, 1)",
-    700: "rgba(126, 34, 206, 1)",
-    800: "rgba(107, 33, 168, 1)",
-    900: "rgba(88, 28, 135, 1)",
-    950: "rgba(59, 7, 100, 1)",
-  },
-  fuchsia: {
-    50: "rgba(253, 244, 255, 1)",
-    100: "rgba(250, 232, 255, 1)",
-    200: "rgba(245, 208, 254, 1)",
-    300: "rgba(240, 171, 252, 1)",
-    400: "rgba(232, 121, 249, 1)",
-    500: "rgba(217, 70, 239, 1)",
-    600: "rgba(192, 38, 211, 1)",
-    700: "rgba(162, 28, 175, 1)",
-    800: "rgba(134, 25, 143, 1)",
-    900: "rgba(112, 26, 117, 1)",
-    950: "rgba(74, 4, 78, 1)",
-  },
-  pink: {
-    50: "rgba(253, 242, 248, 1)",
-    100: "rgba(252, 231, 243, 1)",
-    200: "rgba(251, 207, 232, 1)",
-    300: "rgba(249, 168, 212, 1)",
-    400: "rgba(244, 114, 182, 1)",
-    500: "rgba(236, 72, 153, 1)",
-    600: "rgba(219, 39, 119, 1)",
-    700: "rgba(190, 24, 93, 1)",
-    800: "rgba(157, 23, 77, 1)",
-    900: "rgba(131, 24, 67, 1)",
-    950: "rgba(80, 7, 36, 1)",
-  },
-  rose: {
-    50: "rgba(255, 241, 242, 1)",
-    100: "rgba(255, 228, 230, 1)",
-    200: "rgba(254, 205, 211, 1)",
-    300: "rgba(253, 164, 175, 1)",
-    400: "rgba(251, 113, 133, 1)",
-    500: "rgba(244, 63, 94, 1)",
-    600: "rgba(225, 29, 72, 1)",
-    700: "rgba(190, 18, 60, 1)",
-    800: "rgba(159, 18, 57, 1)",
-    900: "rgba(136, 19, 55, 1)",
-    950: "rgba(76, 5, 25, 1)",
-  },
-  slate: {
-    50: "rgba(248, 250, 252, 1)",
-    100: "rgba(241, 245, 249, 1)",
-    200: "rgba(226, 232, 240, 1)",
-    300: "rgba(203, 213, 225, 1)",
-    400: "rgba(148, 163, 184, 1)",
-    500: "rgba(100, 116, 139, 1)",
-    600: "rgba(71, 85, 105, 1)",
-    700: "rgba(51, 65, 85, 1)",
-    800: "rgba(30, 41, 59, 1)",
-    900: "rgba(15, 23, 42, 1)",
-    950: "rgba(2, 6, 23, 1)",
-  },
-  gray: {
-    50: "rgba(249, 250, 251, 1)",
-    100: "rgba(243, 244, 246, 1)",
-    200: "rgba(229, 231, 235, 1)",
-    300: "rgba(209, 213, 219, 1)",
-    400: "rgba(156, 163, 175, 1)",
-    500: "rgba(107, 114, 128, 1)",
-    600: "rgba(75, 85, 99, 1)",
-    700: "rgba(55, 65, 81, 1)",
-    800: "rgba(31, 41, 55, 1)",
-    900: "rgba(17, 24, 39, 1)",
-    950: "rgba(3, 7, 18, 1)",
-  },
-  zinc: {
-    50: "rgba(250, 250, 250, 1)",
-    100: "rgba(244, 244, 245, 1)",
-    200: "rgba(228, 228, 231, 1)",
-    300: "rgba(212, 212, 216, 1)",
-    400: "rgba(161, 161, 170, 1)",
-    500: "rgba(113, 113, 122, 1)",
-    600: "rgba(82, 82, 91, 1)",
-    700: "rgba(63, 63, 70, 1)",
-    800: "rgba(39, 39, 42, 1)",
-    900: "rgba(24, 24, 27, 1)",
-    950: "rgba(9, 9, 11, 1)",
-  },
-  neutral: {
-    50: "rgba(250, 250, 250, 1)",
-    100: "rgba(245, 245, 245, 1)",
-    200: "rgba(229, 229, 229, 1)",
-    300: "rgba(212, 212, 212, 1)",
-    400: "rgba(163, 163, 163, 1)",
-    500: "rgba(115, 115, 115, 1)",
-    600: "rgba(82, 82, 82, 1)",
-    700: "rgba(64, 64, 64, 1)",
-    800: "rgba(38, 38, 38, 1)",
-    900: "rgba(23, 23, 23, 1)",
-    950: "rgba(10, 10, 10, 1)",
-  },
-  stone: {
-    50: "rgba(250, 250, 249, 1)",
-    100: "rgba(245, 245, 244, 1)",
-    200: "rgba(231, 229, 228, 1)",
-    300: "rgba(214, 211, 209, 1)",
-    400: "rgba(168, 162, 158, 1)",
-    500: "rgba(120, 113, 108, 1)",
-    600: "rgba(87, 83, 78, 1)",
-    700: "rgba(68, 64, 60, 1)",
-    800: "rgba(41, 37, 36, 1)",
-    900: "rgba(28, 25, 23, 1)",
-    950: "rgba(12, 10, 9, 1)",
-  },
-};
-
-export const colors = {
-  ...palette,
-  border: palette.zinc["200"],
-  border_shadow: `0px 1px 2px 0px ${palette.zinc["200"]}`,
-  background: palette.white,
-  shadow: `0px 0px 6px 1px ${palette.zinc["300"]}`,
-};
-
-/**
- * A low-alpha wash of a palette color (hover tints, dimmed chart segments,
- * icon discs). Handles the palette's rgba() strings plus rgb()/#RRGGBB.
- */
-export function withAlpha(color: string, alpha: number): string {
-  if (color.startsWith("rgba(")) return color.replace(/,\s*[\d.]+\s*\)\s*$/, `, ${alpha})`);
-  if (color.startsWith("rgb(")) return color.replace("rgb(", "rgba(").replace(/\)\s*$/, `, ${alpha})`);
-  if (color.startsWith("#") && color.length === 7) {
-    return `${color}${Math.round(alpha * 255)
-      .toString(16)
-      .padStart(2, "0")}`;
-  }
-  return color;
-}
-
-/**
- * A palette FAMILY name — the single, semantic way to reference a color across
- * the system (Badge, status indicators, chart series, breakdown segments).
- * Reference colors by NAME and let the component resolve the shade it needs;
- * never thread a raw hex through props — it drifts (one call site picks 500,
- * another 600, and the same "status" renders two greens). Excludes the
- * non-scale role keys (border/background/shadow/black/white).
- */
-export type ColorName = Exclude<keyof typeof colors, "border" | "border_shadow" | "background" | "shadow" | "black" | "white">;
-
-/**
- * The canonical SOLID shade of a family (500) — status dots, status-grid
- * cells, breakdown segments, chart series. Defined ONCE so every indicator of
- * the same color agrees on the shade.
- */
-export function solid(name: ColorName): string {
-  return colors[name][500];
-}
-
-/** A low-alpha wash of a family's solid shade — cell/segment tints, dimmed
- *  states. `tint("emerald", 0.2)` === `withAlpha(solid("emerald"), 0.2)`. */
-export function tint(name: ColorName, alpha: number): string {
-  return withAlpha(solid(name), alpha);
-}
-
-/** Dark → light stops a `ramp` spans (the usable mid range of a scale). */
-const RAMP_STOPS = [700, 600, 500, 400, 300, 200] as const;
-
-/**
- * `count` distinct shades of ONE family, strong → light — the monochrome
- * "one hue family per dimension" data ramp (a Breakdown's segments, an ordered
- * funnel, any multi-category breakdown of a single dimension). Use this for a
- * COHERENT dimension instead of hand-picking shades or scattering hues; the
- * segment LABEL carries identity, the shade only orders. (For semantic
- * categories whose color carries MEANING — status — give each its own
- * `ColorName` and `solid()` it, don't ramp.)
- */
-export function ramp(name: ColorName, count: number): string[] {
-  const scale = colors[name];
-  if (count <= 1) return [scale[600]];
-  return Array.from({ length: count }, (_, i) => {
-    const idx = Math.round((i / (count - 1)) * (RAMP_STOPS.length - 1));
-    return scale[RAMP_STOPS[idx]];
-  });
-}
-
-/**
- * Is `value` a usable {@link ColorName} — a palette FAMILY, not a role key
- * (`border`/`background`/…) and not `black`/`white`? A family resolves to a
- * shade object; the role/scalar keys resolve to a string, so "value is an
- * object" is the test (no name list to keep in sync).
- */
-export function isColorName(value: unknown): value is ColorName {
-  return (
-    typeof value === "string" &&
-    value in colors &&
-    typeof (colors as Record<string, unknown>)[value] === "object"
-  );
-}
+export * from "./color_tokens";
 
 /**
- * Coerce an arbitrary color token to a {@link ColorName}, falling back to a
- * neutral. The single graceful-degradation point for stored option/status
- * colors: a select option's `color` may be a token a newer table config
- * introduced that this UI build predates, or absent entirely — either way a
- * component renders a neutral badge instead of breaking. Used by `OptionBadge`.
+ * The NATIVE token surface — the literal table, unchanged.
+ *
+ * The values themselves live in `./color_tokens`, which both this file and
+ * `./colors.web.ts` re-export. That indirection exists for one concrete reason:
+ * a relative `./colors` resolves `.web.ts` FIRST on web, so a web variant that
+ * imported `./colors` would import itself, and esbuild reports it as
+ * "Detected cycle while resolving import". Neither variant may name the other;
+ * both name a third module instead.
+ *
+ * Importers never see this split — `@lotics/ui/colors` and the kit's own
+ * `./colors` both keep working, and which of the two files answers is decided by
+ * platform (the `react-native` export condition, and `.web.ts` extension order
+ * inside the kit).
  */
-export function asColorName(value: unknown, fallback: ColorName = "zinc"): ColorName {
-  return isColorName(value) ? value : fallback;
-}

package/src/colors.web.ts

@@ -0,0 +1,43 @@
+import { colors as contract } from "./color_tokens";
+
+export { withAlpha, solid, tint, ramp, isColorName, asColorName } from "./color_tokens";
+export type { ColorName } from "./color_tokens";
+
+/**
+ * The token contract, with its FOUR themeable roles indirected through CSS
+ * variables so an app can carry its own visual identity.
+ *
+ * Why this file exists at all, rather than a React context: 136 of the kit's 320
+ * modules import `colors` directly, at module scope, into `StyleSheet.create`.
+ * A context would have to reach every one of them, turning static stylesheets
+ * into per-render inline styles — the kit's whole performance model — for a
+ * feature that changes four values. A variable costs nothing at runtime and
+ * touches no component: `colors.background` still reads `colors.background`.
+ *
+ * It is safe because react-native-web's `isWebColor` allowlists `var(` ahead of
+ * its own colour normalization, so a variable reaches CSS untouched on every
+ * colour property. That is a web-only guarantee, which is exactly why this is a
+ * `.web.ts` sibling: the `react-native` export condition and `.web.ts` extension
+ * order pick it for the browser; native keeps the literals it can parse.
+ *
+ * It reads its literals from `./color_tokens`, NEVER from `./colors` — on web a
+ * relative `./colors` resolves back to this very file, which esbuild reports as
+ * "Detected cycle while resolving import".
+ *
+ * Each variable carries its literal DEFAULT inline, so the theme is opt-in in
+ * the strictest sense — an app that sets nothing has no `--lotics-*` defined,
+ * every `var()` falls back, and the pixels are identical to before this file.
+ *
+ * ONLY these three. The palette families stay literal, and must: `withAlpha`,
+ * `tint` and `ramp` do string surgery on an `rgba()` to derive a wash, and a
+ * `var()` handed to them would produce garbage no type would catch. Keeping the
+ * themeable set to chrome keeps those functions total — the maintainability
+ * argument and the "colour must keep meaning status" argument turn out to be the
+ * same argument.
+ */
+export const colors = {
+  ...contract,
+  background: `var(--lotics-background, ${contract.background})`,
+  border: `var(--lotics-border, ${contract.border})`,
+  accent: `var(--lotics-accent, ${contract.accent})`,
+};

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 ?? "";
+}