@lotics/ui 7.5.0 → 7.6.0

package/AGENTS.md

@@ -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.5.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/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,
+  },
+});