@lotics/ui 12.0.0 → 12.1.0

package/AGENTS.md

@@ -34,7 +34,7 @@ doc before building any screen, **never from memory**. Exact props are the shipp
 
 | 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. 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` for a custom-code app's `vite.config.ts`). 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, find-or-create (`Combobox`), line items, handoffs, phased records, billing, tags, dispositions, attachments, stage gates. |
 | [docs/ai_patterns.md](./docs/ai_patterns.md) | AI proposes, the human decides — composer, live run feed (`AgentRun`), review-before-apply, findings, provenance, confidence; the UI half of the SDK's [ai doc](../app-sdk/docs/ai.md). |
 | [docs/composition.md](./docs/composition.md) | The design-language contract — canvas + content column, heading altitude, banded cards, register vs inset rows, master-detail `Drawer`, view controls, color discipline, typography, whitespace. |

package/docs/catalog.md

@@ -263,6 +263,17 @@ verdict the host records; `finding` locale slice).
 Every published entry point, grouped by area. Import as `@lotics/ui/<module>`; the module's
 source (`src/<module>.tsx`/`.ts`) is the API reference.
 
+### Dev / build integration
+
+- **`vite`** — `loticsOptimizeDeps`: the canonical `optimizeDeps.include` list a custom-code
+  app's `vite.config.ts` must pre-bundle for `lotics app dev` to render (RN-ecosystem + markdown
+  CJS-interop; dev-only — the prod rollup build resolves the interop without it). Ships WITH the
+  kit so it can never drift from what @lotics/ui's transitive deps require across a major bump —
+  the scaffold's `vite.config.ts` imports it instead of hardcoding the list:
+  `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.
+
 ### Text & formatting
 
 - **`text`** — the `Text` primitive (never raw `div`/`span`/`fontSize`): `size` `xs`–`xxxl`

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@lotics/ui",
-  "version": "12.0.0",
+  "version": "12.1.0",
   "type": "module",
   "exports": {
+    "./vite": {
+      "types": "./src/vite.d.mts",
+      "default": "./src/vite.mjs"
+    },
     "./tokens": "./src/tokens.ts",
     "./colors": "./src/colors.ts",
     "./option_badge": "./src/option_badge.tsx",

package/src/vite.d.mts

@@ -0,0 +1,7 @@
+/**
+ * Types for the `@lotics/ui/vite` subpath (runtime lives in `vite.mjs`).
+ *
+ * `readonly` so a consumer can't mutate the shared canonical list; spread it to
+ * extend: `include: [...loticsOptimizeDeps, "my-extra-dep"]`.
+ */
+export declare const loticsOptimizeDeps: readonly string[];

package/src/vite.mjs

@@ -0,0 +1,67 @@
+/**
+ * Vite dev-optimizer config for Lotics custom-code apps — the `@lotics/ui/vite` subpath.
+ *
+ * ZERO-IMPORT LEAF. This module is loaded inside Vite's Node config context
+ * (a scaffolded app's `vite.config.ts` imports it), so it must pull in NOTHING —
+ * no react-native-web, no kit components, no other module. It exports only a
+ * plain array of strings. It ships as `.mjs` (not `.ts`) on purpose: a Vite
+ * config bundle externalizes its bare imports to their on-disk paths and hands
+ * them to Node's `import()`, and Node refuses to strip types for a `.ts` file
+ * under `node_modules` — a source `.ts` export would fail the config load.
+ *
+ * `loticsOptimizeDeps` is the set of module specifiers a scaffolded app's
+ * `vite.config.ts` `optimizeDeps.include` MUST carry for `lotics app dev` to
+ * render. Vite's dev dep-optimizer pre-bundles these to synthesize the
+ * CJS-interop (`default` / named) exports the RN-ecosystem + markdown subtree
+ * ship un-prebundled — otherwise one of them blanks the dev iframe with "does
+ * not provide an export named 'default'/'parse'". Dev-ONLY: the production
+ * rollup build resolves the interop without it (typecheck/lint/build stay green
+ * while the dev iframe goes blank), which is exactly why this list ships WITH
+ * the kit — so it can never drift from what @lotics/ui's transitive deps
+ * require across a major bump.
+ *
+ * Why each family is here:
+ *  - `react-native-svg` — @lotics/ui's svg charts (PieChart/LineChart/Sparkline/
+ *    RingGauge) reach a named-export entry the dev optimizer won't resolve
+ *    unbundled ("does not provide an export named 'parse'").
+ *  - `react-native-web` + `@react-native/normalize-colors` + the `inline-style-
+ *    prefixer` / `fbjs` / `styleq` / `postcss-value-parser` / `nullthrows` core —
+ *    RN-Web's CJS deps; force-prebundling folds them into interop'd chunks, and
+ *    the deep subpaths it reaches via *default* imports need an ESM shim.
+ *  - `react-markdown` — @lotics/ui's Markdown renderer (AgentRun + any markdown
+ *    surface) pulls a transitive CJS dep (`style-to-js`) whose default export the
+ *    dev optimizer won't synthesize unbundled.
+ *  - `react` / `react-dom` / `react-dom/client` — pinned into the pre-bundle so
+ *    every kit subpath shares one React instance (else "Invalid hook call").
+ *
+ * Usage — consumed by a scaffolded app's `vite.config.ts`:
+ *
+ *     import { loticsOptimizeDeps } from "@lotics/ui/vite";
+ *     export default defineConfig({ optimizeDeps: { include: loticsOptimizeDeps } });
+ *
+ * To add app-specific pre-bundle entries, spread the list:
+ *
+ *     optimizeDeps: { include: [...loticsOptimizeDeps, "my-extra-dep"] }
+ */
+export const loticsOptimizeDeps = [
+  "react-native-svg",
+  "react-markdown",
+  "react-native-web",
+  "@react-native/normalize-colors",
+  "inline-style-prefixer/lib/createPrefixer",
+  "inline-style-prefixer/lib/plugins/crossFade",
+  "inline-style-prefixer/lib/plugins/imageSet",
+  "inline-style-prefixer/lib/plugins/logical",
+  "inline-style-prefixer/lib/plugins/position",
+  "inline-style-prefixer/lib/plugins/sizing",
+  "inline-style-prefixer/lib/plugins/transition",
+  "postcss-value-parser",
+  "fbjs/lib/invariant",
+  "fbjs/lib/warning",
+  "styleq",
+  "styleq/transform-localize-style",
+  "react",
+  "react-dom",
+  "react-dom/client",
+  "nullthrows",
+];

package/src/vite.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect } from "vitest";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { loticsOptimizeDeps } from "./vite.mjs";
+
+describe("@lotics/ui/vite", () => {
+  it("exports a non-empty list of module-specifier strings", () => {
+    expect(Array.isArray(loticsOptimizeDeps)).toBe(true);
+    expect(loticsOptimizeDeps.length).toBeGreaterThan(0);
+    for (const entry of loticsOptimizeDeps) {
+      expect(typeof entry).toBe("string");
+      expect(entry.length).toBeGreaterThan(0);
+    }
+  });
+
+  it("is a zero-import leaf (it loads inside Vite's Node config context)", () => {
+    // The module is imported by an app's `vite.config.ts`, evaluated by Node
+    // before any resolve.alias or RN-Web shim exists. A single import would drag
+    // react-native-web (and its Metro globals) into the Node config load and
+    // crash it — so the runtime module must import nothing at all. Strip comments
+    // first so the usage example in the header (which shows an `import` line) is
+    // not mistaken for real code.
+    const raw = fs.readFileSync(path.join(__dirname, "vite.mjs"), "utf-8");
+    const code = raw
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      .replace(/(^|[^:])\/\/.*$/gm, "$1");
+    expect(code).not.toMatch(/^\s*import\b/m);
+    expect(code).not.toMatch(/\bfrom\s+["']/);
+    expect(code).not.toMatch(/\brequire\s*\(/);
+  });
+
+  test("carries the load-bearing RN-Web interop entries (a missing one blanks the dev iframe)", () => {
+    // RN-Web does `import normalizeColor from "@react-native/normalize-colors"`
+    // (nested CJS): un-prebundled, the dev server serves it as ESM with no
+    // default export and the iframe blanks the moment a colour-touching
+    // component mounts. These membership pins port the scaffold-era literal
+    // assertions to the list's owner.
+    expect(loticsOptimizeDeps).toContain("react-native-web");
+    expect(loticsOptimizeDeps).toContain("@react-native/normalize-colors");
+  });
+});