@lotics/ui 7.4.0 → 7.6.0

package/AGENTS.md

@@ -20,8 +20,8 @@ typeahead, async search, virtualization, and a11y the primitive already ships.
   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`, `Confidence`, `RemainderMeter`,
-  `ChangeReview`/`ChangeReviewActions`, and `DateRangeFilterField`/`DateFilter` (presets + footer +
-  time-segment a11y, one `dateRange` slice). Adding a string to a wired component's `*Labels` forces
+  `ChangeReview`/`ChangeReviewActions`, `DateRangeFilterField`/`DateFilter` (presets + footer +
+  time-segment a11y, one `dateRange` slice), and `FormField` (the `optional` marker). 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): calendar/gantt, the file/preview/comment labels.
 
@@ -115,9 +115,10 @@ Pick by capability, not by name. (→ the source file for the API.)
   (bulk-select bar).
 - **Filters & view controls** — `SearchInput`, `ChipGroup`, `FilterChip` (+ `RangeSlider`,
   `Counter`), `Chip`.
-- **Overlays** — `Dialog`, `Drawer` (+ `DrawerFooter`), `Popover`, `Tooltip`, `OptionList`
-  (the searchable list body — host it in a `Popover`/`Dialog` for a command palette),
-  `Alert` (the blocking confirm).
+- **Overlays** — `Dialog` (centered card over a scrim), `Modal` (+ `ModalHeader`/`ModalBody`/
+  `ModalFooter` — a full-bleed, edge-to-edge takeover with NO scrim), `Drawer` (+ `DrawerFooter`),
+  `Popover`, `Tooltip`, `OptionList` (the searchable list body — host it in a `Popover`/`Dialog` for
+  a command palette), `Alert` (the blocking confirm).
 - **Status / feedback** — `Badge` / `StatusBadge`, `Callout` (inline status), `EmptyState`,
   `CompletionState`, `ActivityIndicator` / `Loading`, `Skeleton`.
 - **Files** — `FilesEditor` (THE all-in-one attachment field: an upload-aware grid + a toolbar below
@@ -804,7 +805,7 @@ check_circle (CheckCircle — the completion ring: an empty ring that springs to
 floating_action_bar · filter_chip · column_filter (ColumnFilter — the typed per-column filter pill +
 columnFilterToConditions; for a register filtering on several columns) · chip_group · search_input ·
 sort_header · table · data_grid (DataGrid — the inline-managed grouped table: a grouped, sortable grid of LIVE inline-editor cells (`columns[].cell` → ANY field) + optional per-row `leading` (a CheckCircle) + `renderGroupFooter` (per-group add, align with the exported `gridRowStyle`) + `labels` (localize the sort-header a11y via `SortHeaderLabels`). Owns header/sections/rows; consumer owns data + sort/group/filter/collapse state + toolbar. Renders ALL rows — MODERATE data; 10k+ → the paginated `Table` register. Examples: `tpl_task_board`, `tpl_pipeline`) · pagination · accordion · stepper (Stepper + Step — done/current/upcoming/warning/complete progress on a track (horizontal) or spine (vertical); compound `<Step status>children` OR data `steps[]`+`current`; **navigable** via `Step.onPress` (both orientations — the whole step is the tap target) + `active` to wash the selected one, so it doubles as a section/phase switcher; the guided-run / agent-feed primitive — subsumes the old StepList) ·
-step_progress · timeline (heterogeneous event LOG — per-row icon + expandable details, models the past; NOT progress) · drawer (+ DrawerFooter) · dialog · popover · tooltip ·
+step_progress · timeline (heterogeneous event LOG — per-row icon + expandable details, models the past; NOT progress) · drawer (+ DrawerFooter) · dialog · modal (Modal + ModalHeader + ModalBody + ModalFooter — the full-bleed, edge-to-edge takeover: an OPAQUE surface that COVERS THE WHOLE SCREEN, so unlike Dialog (centered card WITH scrim) and Drawer (docked panel WITH scrim) there is nothing behind it to dim — NO scrim, NO backdrop. Lays children as a flex column: a pinned ModalHeader (eyebrow/title + an actions slot + close), a flex:1 scrolling ModalBody, a pinned ModalFooter (the commit bar, same chrome as DialogFooter/DrawerFooter). Reach for it for a focused capture / multi-step wizard / a console the user steps INTO, where surrounding chrome is a distraction; pick Dialog when the surface is a card the user can see context around) · popover · tooltip ·
 alert · peek · empty_state · completion_state · callout (Callout · CalloutTitle ·
 CalloutText · CalloutActions) · kpi_card · kpi_strip · metric · trend_chip · sparkline ·
 bar_chart · line_chart · pie_chart · ring_gauge · progress_bar · stacked_progress_bar · breakdown ·

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "7.4.0",
+  "version": "7.6.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -193,6 +193,7 @@
     "./date_calendar": "./src/date_calendar.tsx",
     "./dialog": "./src/dialog.tsx",
     "./drawer": "./src/drawer.tsx",
+    "./modal": "./src/modal.tsx",
     "./screen_router": "./src/screen_router.tsx",
     "./route_matching": "./src/route_matching.ts",
     "./menu_title": "./src/menu_title.tsx",

package/src/form_field.tsx

@@ -2,6 +2,7 @@ import { createContext, useContext, useId } from "react";
 import { StyleProp, View, ViewStyle } from "react-native";
 import { Text } from "./text";
 import { Spacer } from "./spacer";
+import { useLoticsLocale } from "./locale";
 
 export interface FormFieldProps {
   label: string;
@@ -9,7 +10,8 @@ export interface FormFieldProps {
   description?: string;
   error?: string;
   style?: StyleProp<ViewStyle>;
-  /** Label shown next to `label` when `optional` is true. Default: "Optional". Pass a translated string from the consumer. */
+  /** Label shown next to `label` when `optional` is true. Defaults to the locale
+   *  pack's `formField.optional` ("Optional"); pass to override for one instance. */
   optionalLabel?: string;
 }
 
@@ -40,7 +42,8 @@ export function useFormField(): FormFieldBinding | null {
 }
 
 export function FormField(props: FormFieldProps & { children: React.ReactNode }) {
-  const { label, description, error, optional, style, children, optionalLabel = "Optional" } = props;
+  const { label, description, error, optional, style, children, optionalLabel } = props;
+  const resolvedOptionalLabel = optionalLabel ?? useLoticsLocale().formField.optional;
 
   const inputId = useId();
   const labelId = `${inputId}-label`;
@@ -72,7 +75,7 @@ export function FormField(props: FormFieldProps & { children: React.ReactNode })
           )}
           {!!optional && (
             <Text numberOfLines={1} size="sm" color="zinc-500">
-              {optionalLabel}
+              {resolvedOptionalLabel}
             </Text>
           )}
         </View>

package/src/locale.tsx

@@ -24,12 +24,14 @@ export interface LoticsLocale {
   /** `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 };
+   *  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; noResults: string; recent: string; searchPlaceholder: string };
   /** `FilterChip` (and `ColumnFilter`): the generic clear affordance, used when
    *  a call site doesn't pass a dimension-specific `clearLabel`. */
   filterChip: { clear: string };
+  /** `FormField`: the "Optional" marker shown next to the label when `optional`. */
+  formField: { optional: string };
   /** `Drawer`: the record prev/next + close controls (screen-reader names). */
   drawer: { previous: string; next: string; close: string };
   /** `Confidence`: the full level phrase ("High confidence" …). */
@@ -74,8 +76,9 @@ export const en: LoticsLocale = {
     ascending: ", ascending",
     descending: ", descending",
   },
-  optionList: { selectAll: "Select all", deselectAll: "Deselect all", noResults: "No results", recent: "Recent" },
+  optionList: { selectAll: "Select all", deselectAll: "Deselect all", noResults: "No results", recent: "Recent", searchPlaceholder: "Search…" },
   filterChip: { clear: "Clear" },
+  formField: { optional: "Optional" },
   drawer: { previous: "Previous record", next: "Next record", close: "Close" },
   confidence: { high: "High confidence", medium: "Medium confidence", low: "Low confidence" },
   remainderMeter: {
@@ -123,8 +126,9 @@ export const vi: LoticsLocale = {
     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" },
+  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", searchPlaceholder: "Tìm…" },
   filterChip: { clear: "Xóa" },
+  formField: { optional: "Tùy chọn" },
   drawer: { previous: "Bản ghi trước", next: "Bản ghi sau", close: "Đóng" },
   confidence: { high: "Độ tin cậy cao", medium: "Độ tin cậy trung bình", low: "Độ tin cậy thấp" },
   remainderMeter: {

package/src/modal.tsx

@@ -0,0 +1,163 @@
+import { ReactNode } from "react";
+import { Modal as RNModal, StyleSheet, View, ScrollView, ViewStyle } from "react-native";
+import { colors } from "@lotics/ui/colors";
+import { IconButton } from "@lotics/ui/icon_button";
+import { Text } from "@lotics/ui/text";
+import { PortalHost } from "@lotics/ui/portal";
+import { useOverlayScope } from "@lotics/ui/overlay_scope";
+
+export interface ModalProps {
+  open: boolean;
+  onClose: () => void;
+  /**
+   * The modal body. Lay it out as a flex column — a fixed `ModalHeader` and
+   * `ModalFooter` pin while a `ModalBody` scrolls between them.
+   */
+  children: ReactNode;
+  testID?: string;
+}
+
+/**
+ * A full-bleed, edge-to-edge takeover: an OPAQUE surface that covers the entire
+ * screen. Unlike `Dialog` (a centered card over a scrim) or `Drawer` (a docked
+ * panel over a scrim), a `Modal` has nothing behind it to dim — it owns the whole
+ * viewport. Reach for it for a focused capture, a multi-step wizard, or a console
+ * the user steps INTO and out of, where the surrounding chrome is a distraction.
+ *
+ * Lays children as a flex column so a fixed `ModalHeader` + `ModalFooter` pin
+ * while a `ModalBody` scrolls between them. Controlled via `open`/`onClose`; the
+ * header close control dismisses it (Escape on web, the back gesture on Android).
+ */
+export function Modal(props: ModalProps) {
+  const { open, onClose, children, testID } = props;
+  useOverlayScope(open);
+
+  return (
+    <RNModal visible={open} onRequestClose={onClose} animationType="fade">
+      <View testID={testID} style={styles.surface}>
+        <PortalHost>{children}</PortalHost>
+      </View>
+    </RNModal>
+  );
+}
+
+export interface ModalHeaderProps {
+  /** Header title. A string renders as the standard title; a node renders as-is. */
+  title?: ReactNode;
+  /** A short caption above the title (a context label / category). */
+  eyebrow?: ReactNode;
+  /** Right-aligned controls placed before the close button (e.g. a save action). */
+  actions?: ReactNode;
+  onClose: () => void;
+  style?: ViewStyle;
+}
+
+/**
+ * The fixed top bar of a `Modal`: an optional eyebrow + title on the left, an
+ * optional `actions` slot, and a close control wired to `onClose` on the right.
+ * Render it as the FIRST child of the `Modal`; it never scrolls.
+ */
+export function ModalHeader(props: ModalHeaderProps) {
+  const { title, eyebrow, actions, onClose, style } = props;
+
+  return (
+    <View style={[styles.header, style]}>
+      <View style={styles.headerText}>
+        {eyebrow !== undefined ? (
+          typeof eyebrow === "string" ? (
+            <Text size="xs" weight="medium" color="muted">
+              {eyebrow}
+            </Text>
+          ) : (
+            eyebrow
+          )
+        ) : null}
+        {title !== undefined ? (
+          typeof title === "string" ? (
+            <Text size="lg" weight="semibold">
+              {title}
+            </Text>
+          ) : (
+            title
+          )
+        ) : null}
+      </View>
+      {actions !== undefined ? <View style={styles.headerActions}>{actions}</View> : null}
+      <IconButton icon="x" size="lg" accessibilityLabel="Close" onPress={onClose} />
+    </View>
+  );
+}
+
+export interface ModalBodyProps {
+  children: ReactNode;
+}
+
+/**
+ * The flex:1 scrolling content region between a `Modal`'s pinned header and
+ * footer. Fills the remaining height; its content scrolls.
+ */
+export function ModalBody(props: ModalBodyProps) {
+  const { children } = props;
+  return <ScrollView contentContainerStyle={styles.bodyContent}>{children}</ScrollView>;
+}
+
+export interface ModalFooterProps {
+  /** The action(s) — typically right-aligned `Button`s. Prepend a
+   *  `<Text style={{ flex: 1 }}>` hint to push them right with a summary on the left. */
+  children: ReactNode;
+  align?: "start" | "end" | "space-between";
+}
+
+/**
+ * The pinned bottom action bar of a `Modal` — a hairline-topped band (the same
+ * chrome as `DialogFooter` / `DrawerFooter`) that commits the modal's work.
+ * Render it as the LAST child of the `Modal`, after the `ModalBody`; the body's
+ * `flex:1` pins it to the surface bottom.
+ */
+export function ModalFooter(props: ModalFooterProps) {
+  const { children, align = "end" } = props;
+  const justifyContent =
+    align === "end" ? "flex-end" : align === "space-between" ? "space-between" : "flex-start";
+
+  return <View style={[styles.footer, { justifyContent }]}>{children}</View>;
+}
+
+const styles = StyleSheet.create({
+  surface: {
+    flex: 1,
+    backgroundColor: colors.white,
+    flexDirection: "column",
+  },
+  header: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 12,
+    paddingLeft: 24,
+    paddingRight: 16,
+    paddingVertical: 16,
+    minHeight: 64,
+    borderBottomWidth: 1,
+    borderBottomColor: colors.border,
+  },
+  headerText: {
+    flex: 1,
+    gap: 2,
+  },
+  headerActions: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 8,
+  },
+  bodyContent: {
+    padding: 24,
+  },
+  footer: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 12,
+    paddingHorizontal: 24,
+    paddingVertical: 16,
+    borderTopWidth: 1,
+    borderTopColor: colors.border,
+  },
+});

package/src/option_list.tsx

@@ -58,7 +58,7 @@ export function OptionList<T extends string, MULTI extends boolean = false, D =
           icon="search"
           value={list.query}
           onChangeText={list.setQuery}
-          placeholder={search.placeholder ?? "Search…"}
+          placeholder={search.placeholder ?? loc.searchPlaceholder}
           autoFocus={!small}
           autoCapitalize="none"
           autoCorrect={false}