@lotics/ui 27.10.0 → 27.12.0

package/AGENTS.md

@@ -14,7 +14,7 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 
 | Doc | Read it for |
 |---|---|
-| [docs/catalog.md](./docs/catalog.md) | **The complete inventory** — Reach-by-role (each data role → the ONE canonical component) + every `@lotics/ui/<module>` entry point (incl. `@lotics/ui/vite`'s `loticsOptimizeDeps` for a custom-code app's `vite.config.ts`). Read before building any screen; reuse first. |
+| [docs/catalog.md](./docs/catalog.md) | **The complete inventory** — Reach-by-role (each data role → the ONE canonical component) + every `@lotics/ui/<module>` entry point (incl. `@lotics/ui/vite`'s `loticsOptimizeDeps` + `loticsResolve()` — the pre-bundle list and the whole `resolve` block a custom-code app's `vite.config.ts` imports rather than hand-carries, dev-link included). Read before building any screen; reuse first. |
 | [docs/data_entry.md](./docs/data_entry.md) | Which editing pattern for which job — inline edit, fieldset forms, browser-autofill suppression (search controls only), find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments (the `FilesEditor` COMPOUND — root owns selection/gallery/confirm, you compose the bar, a HOST verb reads `useFilesEditorSelection` — plus the three-way file INTAKE: CTA + `FileDropTarget` + `usePasteFiles`), stage gates, the commit-on-blur vs action-press ordering law (the kit gates the press — `pending_commits`). |
 | [docs/ai_patterns.md](./docs/ai_patterns.md) | AI acts, the human stays in charge — composer, live run feed (`AgentRun`), the one law's split (modify → review-before-apply; create → save-direct + the `ResultHeader` receipt), findings, provenance, confidence; the UI half of the SDK's [ai doc](../app-sdk/docs/ai.md)., the whole run in a dialog (`AgentRunScope`/`AgentRunPane`/`AgentRunActions` — a parked question REPLACES the feed, actions in the footer) |
 | [docs/composition.md](./docs/composition.md) | The design-language contract — canvas + content column, heading altitude (incl. eyebrow vs group lead — a label is one or the other), banded cards, register vs inset rows, master-detail `Drawer` on a LIST screen vs a child collection's row EXPANDING inside a record, view controls, RECORD EXTENT (one page, sections scrolled to and never routed to), color discipline, typography, whitespace, and how to TEST an overlay component (a `Popover`-backed surface never mounts under jsdom). |

package/docs/catalog.md

@@ -325,6 +325,18 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `import { loticsOptimizeDeps } from "@lotics/ui/vite"` → `optimizeDeps: { include: loticsOptimizeDeps }`.
   To add app-specific entries, spread: `include: [...loticsOptimizeDeps, "my-dep"]`. A Node-loadable
   `.mjs` leaf (a Vite config can't import a `.ts` from `node_modules`), zero-import by contract.
+- **`vite`** — `loticsResolve()`: the whole `resolve` block, for the same reason and on the same
+  terms — `resolve: loticsResolve()`. Every entry is dictated by the kit's internals, so the kit
+  owns them: the `react-native` → `react-native-web` alias (**load-bearing** — without it the RN
+  primitives have no web implementation and the app does not build), `.web.tsx`-first `extensions`
+  (per-target variants win; `.mjs`/`.mts` kept for parity with Vite's default resolver), `dedupe`
+  for React + RN-Web (the kit is consumed across many subpaths, and a second React copy in one
+  chunk nulls the hooks dispatcher — "Invalid hook call"), and the `LOTICS_UI_SRC` **dev-link**,
+  read at call time so it lasts exactly one command. To add your own alias, spread:
+  `const base = loticsResolve(); resolve: { ...base, alias: [...base.alias, entry] }`.
+  `lotics app codegen` writes the matching `paths` into the app's `.lotics/tsconfig.link.json`,
+  so `tsc`, vitest, eslint and the editor resolve the same kit Vite does — the dev-link is not a
+  Vite-only trick that leaves every other tool checking the published package.
 
 ### Text & formatting
 
@@ -370,7 +382,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`control_surface`** — `CONTROL_HEIGHT` (40), `CONTROL_RADIUS` (10), `CONTROL_TEXT_INSET`
   (9 — how far a control insets its OWN text: 1px border + 8px padding; anything that must line
   up with a control's WORDS rather than its box carries it, and `TASK_TEXT_INSET` IS it),
-  `FOCUS_RING`, `HOVER_BORDER`, `CONTROL_TRANSITION`, `chipSurfaceStyle` — the shared
+  `FOCUS_RING` (a 2px OUTSET ring, so a container that CLIPS — any `ScrollView` — has to
+  keep padding on an edge a focusable child sits against, or the ring shears off on the
+  one interaction it signals; the padding still comes off the 8-grid, the ring is only
+  the floor), `HOVER_BORDER`, `CONTROL_TRANSITION`, `chipSurfaceStyle` — the shared
   control-surface tokens.
 - **`fonts.css`** — the Inter sheet (400/500/600, served by absolute URL so it resolves on
   every origin an app runs from); the app entry imports it ONCE or every `Text` falls back
@@ -1166,6 +1181,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   stack (a Drawer drilling into a LINKED record swaps its header to a BACK `IconButton`
   while `canGoBack`). Key the router by record id so stepping between records resets the
   stack. Worked example: [`tpl_item_list`](../examples/tpl_item_list.tsx) drawer.
+  **`useScreenActive()` says whether the surrounding `Screen` is the one on top** —
+  because "stays mounted" means its effects keep running, so anything a screen claims
+  GLOBALLY (a keyboard shortcut) must stand down while it is buried, or the covered
+  screen answers input aimed at the one in front of it. `true` outside any `Screen`.
 - **`route_matching`** — pure `:param` route-pattern utilities — `routeMatches` /
   `parseRouteParams` / `findBestPattern` (exact beats parameterized) / `shouldRouteMatch`;
   the matching core under `ScreenRouter`/`Dialog`.

package/docs/composition.md

@@ -493,8 +493,8 @@ All view controls are 40px tall (`CONTROL_HEIGHT`), `sm` labels, in ONE wrapping
   "success"/green button. Decision UIs put positive/negative color on the STATUS (dot) and verdict
   (colored `Text`), not the buttons.
 - **Create buttons carry NO `+` icon** — "Add fee", not "+ Add fee". A create is `primary` and
-  sits BELOW the list it extends, never in the section heading — see the verb-placement law for
-  why, and for the one-verb-one-weight rule that keeps it primary in the `EmptyState` too. (The
+  rides its section's HEADING row at the right edge — see § The add-placement law for why, and
+  for the one-verb-one-weight rule that keeps it primary in the `EmptyState` too. (The
   icon-only `+` `IconButton` — a composer's attach — is a different thing and keeps its glyph.)
 
 ## The action-gating law — disabled + the reason as a co-located Callout
@@ -594,15 +594,13 @@ gate's SCOPE, once** — never prose beside the button, never revealed only on p
   |---|---|
   | a VALUE (copy it, open what it points at) | ON the value — `InlineButton` in the editor's `actions` |
   | a ROW (remove it, move it) | ON the row — an `ActionMenu`, or the row's own controls |
-  | the LIST (one more of them) | BELOW the list, left-aligned, `primary` |
+  | the LIST (one more of them) | its section's HEADING row, right edge, `primary` — see [the add-placement law](#the-add-placement-law--a-sections-add-rides-its-heading-row-right-edge) |
   | the RECORD (issue, print, hand off) | its own action row at the section's END |
   | the record's EXISTENCE | the `DangerZone`, last on the page |
 
-  The heading row is therefore identity + meta + view controls, and holds no content verb. An
-  **Add in the heading sits above the thing it extends**, at a different altitude from the rows
-  it affects, competing with the title for the one line that names the section — while the row it
-  creates appears at the BOTTOM, nowhere near the button that made it. Put it under the last row,
-  on the list's own left edge, and the button is where its result will be.
+  The ADD is the one verb this law does NOT place next to its effect, and the add-placement law
+  says why: a position that never moves beats a position that is adjacent, because "below the
+  last row" is a different place on every list and no place at all on an empty one.
   **An add is `primary`, in the `EmptyState` too.** It is the act its section offers, so it
   carries that section's weight; a lone `secondary` button reads as though the real action were
   somewhere else. The rule that matters is that ONE VERB KEEPS ONE WEIGHT — the same add must

package/docs/templates.md

@@ -92,11 +92,11 @@ Laws for any screen where a record's data is edited and a primary action produce
 7. **Header = identity + provenance.** Id, the key identifier, created-at. No metrics or badges
    duplicating data a section already owns.
 8. **Action placement — a verb goes where its effect lands.** Value verbs on the value
-   (`InlineButton`), row verbs on the row, an ADD below the list it extends (primary, left —
-   where the new row will appear, and primary in the `EmptyState` too: one verb, one weight),
+   (`InlineButton`), row verbs on the row, an ADD on its section's HEADING row at the right edge
+   (primary — the one spot that does not move with the row count, and primary in the
+   `EmptyState` too: one verb, one weight),
    a committing act in its own row at the section's end,
-   deletion in the `DangerZone`. Section headings carry identity and view controls only; an Add
-   in the heading sits above what it extends and competes with the title. A committing act rides
+   deletion in the `DangerZone`. A committing act rides
    an empty-label `DetailRow` so it lands on the CONTROL column — never right-floated, which
    aligns to nothing (only overlay footers right-align).
 9. **Destructive placement.** Solid `danger`, bottom-left after the entity's fields, ONE

package/package.json

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

package/src/control_surface.ts

@@ -23,6 +23,13 @@ export const MIN_CONTROL_WIDTH = 160;
  *  (avatars, dots, switches, sliders, progress, icon buttons) stay full. */
 export const CONTROL_RADIUS = 10;
 
+/** How far {@link FOCUS_RING} extends BEYOND the control's border box. Module-local
+ *  on purpose: it is a FLOOR for anyone who clips (a container reserving less than
+ *  this on an edge a focusable child sits against shears that child's ring), never a
+ *  spacing value — padding comes off the 8-grid in `spacing.ts`, which clears this
+ *  several times over without coupling a layout number to a decoration one. */
+const FOCUS_RING_WIDTH = 2;
+
 /** THE focus ring — a 2px zinc-900 box-shadow flush against the box (offset 0),
  *  layout-neutral (never reflows). The kit no longer ships a global `:focus-visible`
  *  CSS rule, so every interactive control paints THIS inline when keyboard-focused
@@ -30,7 +37,7 @@ export const CONTROL_RADIUS = 10;
  *  trigger (Picker / Combobox / InlineSelect / InlineDatePicker) wears it on its open
  *  state so an open trigger reads identically to a keyboard-focused one — one token,
  *  one look. Apps building their own controls reuse it. */
-export const FOCUS_RING = `0 0 0 2px ${colors.zinc[900]}`;
+export const FOCUS_RING = `0 0 0 ${FOCUS_RING_WIDTH}px ${colors.zinc[900]}`;
 
 /**
  * How far a control surface insets its OWN text: 1px of border (transparent on an

package/src/dialog.tsx

@@ -313,6 +313,16 @@ const styles = StyleSheet.create({
     minHeight: 56,
   },
   scrollAreaContent: {
+    // A ScrollView clips, so the FIRST child sat flush against the boundary and lost
+    // the outer half of its focus ring — an input at the top of a dialog showed a
+    // sheared ring on the one interaction the ring exists to signal. 8 clears that
+    // several times over, but the ring is only the FLOOR here, not the reason: this
+    // is separation from the header, so it comes off the 8-grid like every other gap.
+    // `DialogHeader` already pays 8 below itself, making the visible gap a clean 16.
+    //
+    // Asymmetric with the bottom on purpose — 24 there is scroll RUNOUT, so the last
+    // row isn't jammed against the edge at the end of a scroll. Different job.
+    paddingTop: 8,
     paddingBottom: 24,
   },
   footer: {

package/src/react_native.d.ts

@@ -4,11 +4,14 @@ import "react-native";
 // Pressable's `hovered` callback state, plus web-only ViewStyle / TextStyle
 // properties (cursor, outline, boxShadow, etc.) used by its primitives.
 //
-// Each consumer (frontend, container-invoices, future iframe
-// apps) ships its own copy of this file in its `src/`. TypeScript doesn't
-// auto-pick-up `.d.ts` files inside node_modules dependencies; the augmentation
-// has to be visible in the consumer's `include`. The CLI starter template
-// (`lotics app create`) generates this file as part of every new app.
+// TypeScript does not auto-load a `.d.ts` from inside a dependency — the
+// augmentation has to be visible in the consumer's own `include`. In-repo
+// consumers (frontend) keep a copy in `src/`; a custom-code app does NOT, because
+// `lotics app codegen` copies THIS file into its `.lotics/` on every run. That
+// direction matters: a scaffolded snapshot silently falls behind whatever the kit
+// adds here — the starter's copy was already missing `TextStyle`'s `boxShadow`,
+// `transitionDuration` and `transitionProperty`, so an app author writing one got
+// a type error the kit itself does not have.
 declare module "react-native" {
   interface PressableStateCallbackType {
     hovered: boolean;

package/src/screen_router.tsx

@@ -159,6 +159,24 @@ export function useNavigationStack(
 // Screen
 // ============================================================================
 
+/**
+ * Whether the surrounding {@link Screen} is the one on top.
+ *
+ * A screen stacked BEHIND another stays mounted (`display: none`) so its scroll
+ * position survives, which means its effects keep running — including any
+ * keyboard shortcut it registered. Anything that claims a global key must read
+ * this and stand down while hidden, or the buried screen answers a keystroke the
+ * user aimed at the screen in front of it.
+ *
+ * Defaults to `true`, so a subtree outside any `Screen` behaves as if visible.
+ */
+const ScreenActiveContext = createContext(true);
+
+/** @see ScreenActiveContext */
+export function useScreenActive(): boolean {
+  return useContext(ScreenActiveContext);
+}
+
 export interface ScreenProps {
   /** Route pattern to match. Use empty string "" for the default/initial screen. */
   route: string;
@@ -208,9 +226,11 @@ export function Screen(props: ScreenProps) {
   const params = parseRouteParams(route, matchingStackPath);
 
   return (
-    <View style={isActive ? screenStyles.active : screenStyles.hidden}>
-      {typeof children === "function" ? children(params) : children}
-    </View>
+    <ScreenActiveContext.Provider value={isActive}>
+      <View style={isActive ? screenStyles.active : screenStyles.hidden}>
+        {typeof children === "function" ? children(params) : children}
+      </View>
+    </ScreenActiveContext.Provider>
   );
 }
 

package/src/vite.d.mts

@@ -5,3 +5,13 @@
  * extend: `include: [...loticsOptimizeDeps, "my-extra-dep"]`.
  */
 export declare const loticsOptimizeDeps: readonly string[];
+
+/**
+ * The Vite `resolve` block for a Lotics custom-code app (runtime in `vite.mjs`).
+ * Reads `LOTICS_UI_SRC` at call time, so the dev-link is decided per command.
+ */
+export declare function loticsResolve(): {
+  alias: ({ find: RegExp; replacement: string } | { find: string; replacement: string })[];
+  extensions: string[];
+  dedupe: string[];
+};

package/src/vite.mjs

@@ -71,3 +71,45 @@ export const loticsOptimizeDeps = [
   "fast-formula-parser",
   "@formulajs/formulajs",
 ];
+
+/**
+ * The complete Vite `resolve` block a Lotics custom-code app needs — the second
+ * half of the same contract `loticsOptimizeDeps` carries, and shipped here for
+ * the same reason: it tracks the installed @lotics/ui and cannot drift.
+ *
+ * Everything in it exists because the kit ships RN-Web SOURCE:
+ *  - the `react-native` → `react-native-web` alias, so the kit's RN primitives
+ *    (View/Text/Pressable/StyleSheet) render on the web at all. This entry is
+ *    LOAD-BEARING: the deleted `lotics ui link` edited it by regex and twice
+ *    deleted it along with the array's closing bracket (GAP-133/142), which is
+ *    why the dev-link below is computed here rather than written into an app.
+ *  - `.web.tsx`-first `extensions`, so per-target variants (avatar.web.tsx) win,
+ *    plus `.mjs`/`.mts` to keep parity with Vite's default resolver — an override
+ *    otherwise drops them and a package shipping only `.mjs` (lucide-react/dynamic,
+ *    reached by DynamicIcon/AppIcon) fails to resolve under `lotics app dev` while
+ *    the prod build resolves it, so the gap is dev-only and silent.
+ *  - `dedupe`, because the kit is consumed across many subpath entries and Vite
+ *    can otherwise pre-bundle one into its own chunk with a second React copy —
+ *    a hook called from there hits a null dispatcher ("Invalid hook call").
+ *  - the `LOTICS_UI_SRC` dev-link, when set: kit edits go live under
+ *    `lotics app dev` (HMR) and bundle under `lotics app deploy`, with no publish
+ *    round-trip. `lotics app codegen` writes the matching `paths` into
+ *    `.lotics/tsconfig.link.json` from the same variable, so `tsc`, vitest, eslint
+ *    and the editor resolve the same copy Vite does — the dev-link is not a
+ *    Vite-only trick that lies to every other tool.
+ *
+ * An app that needs its own alias spreads the result:
+ *   const base = loticsResolve();
+ *   resolve: { ...base, alias: [...base.alias, { find: "x", replacement: "y" }] }
+ */
+export function loticsResolve() {
+  const uiSrc = process.env.LOTICS_UI_SRC;
+  return {
+    alias: [
+      ...(uiSrc ? [{ find: /^@lotics\/ui\/(.+)$/, replacement: `${uiSrc}/$1` }] : []),
+      { find: "react-native", replacement: "react-native-web" },
+    ],
+    extensions: [".web.tsx", ".web.ts", ".web.js", ".tsx", ".ts", ".jsx", ".js", ".mjs", ".mts"],
+    dedupe: ["react", "react-dom", "react-native-web"],
+  };
+}