@mieweb/ui 0.11.0-dev.18 → 0.11.0-dev.19

package/agent/README.md

@@ -18,13 +18,13 @@ governing spec: later tickets cite it instead of re-deciding.
 
 ## Files
 
-| File                                                   | Purpose                                                                                                                                                                                                                                                     |
-| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [mieweb-ui.instructions.md](mieweb-ui.instructions.md) | The rules template. Copied verbatim to the consumer's `.github/instructions/` (VS Code Copilot auto-applies it via the `applyTo` frontmatter) and embedded, minus frontmatter, in a marked block in the consumer's `AGENTS.md` (the cross-tool convention). |
-| [init-agent.mjs](init-agent.mjs)                       | The `mieweb-ui` bin. Idempotent — rerun after upgrading `@mieweb/ui` to refresh all targets. `--experimental-agents` additionally installs the agent team below.                                                                                            |
-| [agents/](agents/)                                     | Agent templates: `mieweb-ui-design` (orchestrator) + `mieweb-ui-styling`. Installed to the consumer's `.github/agents/` behind `--experimental-agents`.                                                                                                     |
-| [skills/](skills/)                                     | Skill templates: `mieweb-ui-catalog`, `mieweb-ui-tokens`, `mieweb-ui-icons` (generated — `pnpm agent:skills`, never hand-edit) + `mieweb-ui-brands` (hand-written). Installed to `.github/skills/` behind `--experimental-agents`.                          |
-| `evals/` _(Phase 2+)_                                  | Golden-question eval sets per specialist; the regression harness for agent knowledge.                                                                                                                                                                       |
+| File                                                   | Purpose                                                                                                                                                                                                                                                                            |
+| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [mieweb-ui.instructions.md](mieweb-ui.instructions.md) | The rules template. Copied verbatim to the consumer's `.github/instructions/` (VS Code Copilot auto-applies it via the `applyTo` frontmatter) and embedded, minus frontmatter, in a marked block in the consumer's `AGENTS.md` (the cross-tool convention).                        |
+| [init-agent.mjs](init-agent.mjs)                       | The `mieweb-ui` bin. Idempotent — rerun after upgrading `@mieweb/ui` to refresh all targets. `--experimental-agents` additionally installs the agent team below.                                                                                                                   |
+| [agents/](agents/)                                     | Agent templates: `mieweb-ui-design` (orchestrator) + `mieweb-ui-styling` + `mieweb-ui-install`. Installed to the consumer's `.github/agents/` behind `--experimental-agents`.                                                                                                      |
+| [skills/](skills/)                                     | Skill templates: `mieweb-ui-catalog`, `mieweb-ui-tokens`, `mieweb-ui-icons` (generated — `pnpm agent:skills`, never hand-edit) + `mieweb-ui-brands`, `mieweb-ui-tailwind4` (hand-written, sourced from `lessons/`). Installed to `.github/skills/` behind `--experimental-agents`. |
+| `evals/` _(Phase 2+)_                                  | Golden-question eval sets per specialist; the regression harness for agent knowledge.                                                                                                                                                                                              |
 
 Rule content is sourced from [lessons/component-policy.md](../lessons/component-policy.md);
 keep the two in sync when policy changes.

package/agent/agents/mieweb-ui-design.agent.md

@@ -7,6 +7,10 @@ handoffs:
     agent: MIE UI Styling Agent
     prompt: Handle the styling/theming question above (tokens, Tailwind classes, brands, dark mode) and apply fixes where asked.
     send: false
+  - label: Install & setup
+    agent: MIE UI Install Agent
+    prompt: Diagnose the installation/setup problem above (peer deps, Tailwind wiring, CSS entry, dark-mode plumbing) and report the minimal fix.
+    send: false
 ---
 
 # MIE UI Design Agent (orchestrator)
@@ -36,11 +40,12 @@ comparison tables) and `mieweb-ui-icons` (icon aliases and conventions):
 
 ## Route to specialists
 
-| Question is about…                               | Delegate to          |
-| ------------------------------------------------ | -------------------- |
-| tokens, CSS vars, Tailwind classes, brands, dark | MIE UI Styling Agent |
+| Question is about…                                  | Delegate to          |
+| --------------------------------------------------- | -------------------- |
+| install / peer deps / preset / safelist / `@source` | MIE UI Install Agent |
+| tokens, CSS vars, Tailwind classes, brands, dark    | MIE UI Styling Agent |
 
-More specialists (Install, A11y, i18n, Migration, Grids, DataVis, Views,
+More specialists (A11y, i18n, Migration, Grids, DataVis, Views,
 SuperChat, Rich Text) land in later phases; until one ships, answer its domain
 from the skills and the component docs, or defer (below).
 
@@ -49,7 +54,8 @@ from the skills and the component docs, or defer (below).
 - _Delegation mechanics:_ for multi-domain answers, invoke the specialist as a
   subagent (the `agent` tool) and fold its result into your synthesis; use the
   handoff instead when the user should continue the conversation with the
-  specialist. Delegate only to installed MIE UI agents.- _Selection vs depth:_ "which component" is always yours, even for grid/chart
+  specialist. Delegate only to installed MIE UI agents.
+- _Selection vs depth:_ "which component" is always yours, even for grid/chart
   components; the specialist owns configuration, APIs, and debugging of the
   chosen component.
 - _Styling a specialist's component:_ generic token/Tailwind/brand questions go

package/agent/agents/mieweb-ui-install.agent.md

@@ -0,0 +1,78 @@
+---
+name: MIE UI Install Agent
+description: Installation & setup diagnostician for the @mieweb/ui design system — peer dependencies, Tailwind 4 `@source` vs the Tailwind 3 preset/safelist, PostCSS config, CSS entry wiring, dark-mode plumbing, pnpm resolution quirks, and headless module adapters. Invoke for broken/unstyled components after install, peer-dep errors, dark mode or brand CSS not applying, or wiring ViewSet/SuperChat-style modules to app data.
+tools: ['search', 'codebase', 'fetch', 'runInTerminal']
+handoffs:
+  - label: Apply Fixes
+    agent: agent
+    prompt: Apply the setup fixes identified above to the codebase.
+    send: false
+---
+
+# MIE UI Install Agent
+
+You are the installation and setup diagnostician for the **@mieweb/ui** design
+system. Consumers come to you when the library looks broken right after
+install, or when setup questions ("preset or `@source`?") block adoption. You
+diagnose from evidence, then report a minimal fix — you do not edit files
+(offer the **Apply Fixes** handoff instead).
+
+## Your sources of truth (never inline-duplicate them)
+
+- **`mieweb-ui-tailwind4` skill** — the full setup procedure: TW4 `@source` vs
+  TW3 preset/safelist decision, CSS entry order, PostCSS plugin, dark-mode
+  hooks, CSS-variable fallbacks, peer-dep model, headless-module adapter
+  rules, and the symptom→fix troubleshooting table. Start every diagnosis
+  here.
+- **`mieweb-ui-tokens` skill** — token/variable reference and the
+  TW3-safelist / TW4-`@source` mechanics.
+- **`mieweb-ui-brands` skill** — brand CSS loading order and the
+  brand-without-base-stylesheet pitfall.
+- **`mieweb-ui-catalog` skill** — entry points and which optional peer each
+  one requires.
+
+## Diagnostic workflow
+
+1. **Reproduce the symptom in the config, not the component.** Almost every
+   "component is broken" report after install is environment: read the CSS
+   entry, `postcss.config.*`, `tailwind.config.*`, and `package.json`
+   (dependencies + packageManager) before suspecting the library.
+2. **Match against the skill's troubleshooting table.** Unstyled components →
+   missing `@source`/safelist (Tailwind consumers; the precompiled
+   `styles.css` path needs neither); transparent dark mode → missing
+   fallbacks or base stylesheet; dead toggle → missing `@custom-variant`, or
+   the toggle sets a hook the configured variant doesn't match; silent
+   PostCSS → TW3 plugin.
+3. **Verify, don't assume.** Run the checks the skill prescribes (grep for
+   `@source`, `@custom-variant`, fallback commas in `@theme`; `npx tsc
+--noEmit`; `pnpm why <pkg>` for resolution questions) in the consumer repo.
+4. **Report, then hand off.** State root cause, evidence, and the smallest
+   fix. Offer **Apply Fixes** for the edit.
+
+## Peer-dependency triage
+
+`react`/`react-dom` are the only required peers. Everything else is optional
+and entry-scoped — before telling anyone to install a package, check whether
+they actually import the entry that needs it (catalog skill table). Under
+pnpm, remind consumers that peers are not hoisted; required peers belong in
+the app's own `package.json`.
+
+## Redirects
+
+- "Which component should I use?" → **MIE UI Design Agent** (selection is the
+  orchestrator's domain).
+- Token choices, hardcoded-color audits, creating/modifying brands →
+  **MIE UI Styling Agent**. You own getting brand CSS _loaded_; Styling owns
+  what's _in_ it.
+- Once the stack renders correctly, usage questions about specific components
+  go back to the Design Agent.
+
+## Rules
+
+1. Never invent config, package names, or versions — verify against the
+   skills or the consumer's lockfile.
+2. Prefer the smallest change that fixes the root cause; no stack rewrites.
+3. `@mieweb/ui/ag-grid` is deprecated — if a consumer is setting it up, steer
+   them to `/datavis` before optimizing its config.
+4. The installed `mieweb-ui.instructions.md` rules apply to any code you
+   recommend.

package/agent/skills/mieweb-ui-tailwind4/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: mieweb-ui-tailwind4
+description: Installing and wiring @mieweb/ui in a consumer app — Tailwind 4 `@source` setup vs the Tailwind 3 preset, PostCSS config, dark-mode variant and CSS-variable fallbacks, peer dependencies per entry point, and connecting headless modules to a data layer. USE WHEN setting up @mieweb/ui, components render unstyled/broken, dark mode or brand CSS misbehaves after install, peer-dep errors appear, or a ViewSet/SuperChat-style module needs wiring to app data.
+---
+
+# Installing @mieweb/ui (Tailwind 4 era)
+
+Sourced from `lessons/tailwind4-integration.md`, `lessons/adopting-mieweb-ui.md`, and `lessons/wiring-headless-modules.md` in the mieweb/ui repo. Token tables live in the `mieweb-ui-tokens` skill; brand procedures in `mieweb-ui-brands`; entry points and their peer deps in `mieweb-ui-catalog`.
+
+## Install
+
+```bash
+npm install @mieweb/ui react react-dom
+npm install -D tailwindcss@4 @tailwindcss/postcss autoprefixer
+```
+
+`react` / `react-dom` (>=18) are the only **required** peers. Every other peer is **optional** and only needed when you import the entry that uses it (`/maps` → leaflet, `/globe` → react-globe.gl + three, `/kerebron` → @kerebron/\*, `/motion` → motion, `/q` → @mieweb/q, …) — see the catalog skill's entry-point table. A peer-dep warning for an entry you never import is noise, not a problem. Under pnpm's strict node_modules there is no hoisting: required peers must be in the app's own `package.json`; diagnose resolution with `pnpm why <pkg>`.
+
+## Tailwind 4 vs Tailwind 3 vs no Tailwind — pick the right mechanism
+
+| Consumer | Mechanism |
+| --- | --- |
+| Tailwind 4 (CSS-first) | `@source "../node_modules/@mieweb/ui/dist";` in the CSS entry — TW4 does **not** scan `node_modules` on its own |
+| Tailwind 3 (config-first) | `presets: [miewebUIPreset]` from `@mieweb/ui/tailwind-preset` + the exported `miewebUISafelist` + `node_modules/@mieweb/ui/dist/**/*.js` in `content` |
+| No Tailwind | `import '@mieweb/ui/styles.css'` (+ a brand CSS after it) — precompiled, fully supported; no Tailwind, PostCSS, or `@source` needed |
+
+In a Tailwind consumer, missing `@source` (TW4) or content/safelist coverage (TW3) means the library's utility classes are tree-shaken away: **black borders, missing backgrounds, broken layout** on every component. The `@source`/safelist/PostCSS checks below apply **only** when the consumer runs its own Tailwind pipeline — don't prescribe Tailwind tooling to a precompiled-CSS app.
+
+## CSS entry — quick start vs manual
+
+**Option A (quick start)** — three lines, all in **your own** CSS entry (the first two resolve relative to your file, so they cannot live inside the package):
+
+```css
+@import 'tailwindcss';
+@source "../node_modules/@mieweb/ui/dist"; /* path relative to THIS file */
+@import '@mieweb/ui/init.css'; /* dark variant + @theme fallbacks + default brand + base styles */
+```
+
+**Option B (manual, full control)** — every line matters, in this order:
+
+```css
+/* 1. Base stylesheet THEN brand (both plain/unlayered — see brands skill) */
+@import '@mieweb/ui/styles.css';
+@import '@mieweb/ui/brands/bluehive.css';
+
+/* 2. Tailwind */
+@import 'tailwindcss';
+
+/* 3. Scan the library output for class names */
+@source "../node_modules/@mieweb/ui/dist";
+
+/* 4. Dark variant (TW4 doesn't reliably honor tailwind.config darkMode) */
+@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));
+
+/* 5. Map Tailwind color tokens to @mieweb/ui variables — WITH fallbacks */
+@theme {
+  --color-primary-500: var(--mieweb-primary-500);
+  --color-neutral-900: var(--mieweb-neutral-900, #171717);
+  /* … full block with fallback hex values: see init.css in the package */
+}
+```
+
+Primary needs no fallbacks (every brand defines it). **All other scales must carry hex fallbacks** — if the base stylesheet is missing, `var()` resolves to nothing and `dark:bg-neutral-900` renders transparent. This is the single most time-expensive gotcha.
+
+## PostCSS
+
+```js
+// postcss.config.cjs
+module.exports = {
+  plugins: {
+    '@tailwindcss/postcss': {}, // Tailwind 4 plugin
+    autoprefixer: {},
+  },
+};
+```
+
+`tailwindcss: {}` is the Tailwind **3** plugin — with Tailwind 4 installed it silently fails or produces wrong output.
+
+## Dark mode toggle — match the configured variant
+
+The variant selector decides which hook works: `init.css` accepts **either** `.dark` or `data-theme="dark"`, while the manual Option B variant above is attribute-only. A single-hook toggle against `init.css` is valid — diagnose by comparing the toggle to the `@custom-variant` actually in effect, not by demanding both hooks. Setting both is the compatibility-safe recommendation for new code:
+
+```ts
+function applyTheme(t: 'light' | 'dark') {
+  document.documentElement.classList.toggle('dark', t === 'dark');
+  document.documentElement.setAttribute('data-theme', t);
+}
+```
+
+"Dark mode toggles but half the page stays light" usually means the toggle sets a hook the configured `@custom-variant` doesn't match. Brand switching at runtime uses the `brands` barrel loader — see the `mieweb-ui-brands` skill.
+
+## Wiring headless modules
+
+Modules never fetch, subscribe, navigate, or write — you supply a small adapter. The recipe below is the **collection-view contract** (`ViewSet` and friends). `SuperChatInbox` follows the same principles (host-owned state, promise-returning callbacks) but has its own props — `conversations`, `onMessageSent`, `onConversationOpened` — see the catalog skill and component docs; don't hand it collection-view props.
+
+1. **Fetch with your stack** (Meteor `useSubscribe`/`useTracker`, TanStack `useQuery`, …) and pass `items` / `loading` / `error` straight through.
+2. **Describe records once** via `accessors` (`getId`, `getTitle`, `getStatus`, …) — defined at module scope or memoized; they sit in `useMemo` deps.
+3. **Return the promise from `on*` callbacks** (`onMove={(id, s) => update(id, s)}`). The view shows pending state and reverts on rejection. TanStack: `mutateAsync`, not `mutate`; Meteor: `Meteor.callAsync`, don't catch-and-swallow.
+4. **Pass both `onOpen` and `getHref`** — `getHref` makes rows real anchors (⌘-click, copy link); `onOpen` intercepts plain clicks for client routing.
+
+Filters/selection/pagination state is yours (usually the URL); `ViewSet` owns only which view is showing. The `table` slot takes a DataVis NITRO grid — `ViewSet` has no table of its own.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| Black/missing borders, unstyled components | TW4 tree-shaking (Tailwind consumers only) | Add the `@source` directive |
+| Dark mode toggle does nothing | Missing `@custom-variant dark`, or toggle sets a hook the variant doesn't match | Add the variant; align toggle with its selectors |
+| Dark toggles but surfaces stay light | Missing `var()` fallbacks / missing base stylesheet | Hex fallbacks in `@theme`; import `styles.css` or `init.css` |
+| Brand switch has no effect | Wrong import path | Barrel: `from '@mieweb/ui/brands'` |
+| Brand CSS loads but doesn't apply (TW4) | Brand import wrapped in `layer(theme)` | Keep base + brand imports plain/unlayered (brands skill) |
+| PostCSS does nothing | TW3 plugin configured | `@tailwindcss/postcss`, not `tailwindcss` |
+| `var()` renders transparent | Variable undefined | Fallback: `var(--token, #hex)` |
+| Peer-dep install errors | Required vs optional confusion | Only react/react-dom are required; match optional peers to imported entries |
+| Module shows failed action as success | `on*` promise swallowed | Return the real promise (`mutateAsync` / `callAsync`) |
+| Views regroup on every render | Unstable `accessors` | Module scope or `useMemo` |
+
+## Verification checklist
+
+- [ ] Tailwind consumer: `@source` (TW4) or preset + safelist + content (TW3) in place. No Tailwind: `styles.css` imported
+- [ ] `@custom-variant dark` defined (Tailwind consumers); toggle sets a hook the variant matches (both `.dark` and `data-theme` for maximum compatibility)
+- [ ] All non-primary `var()` mappings carry hex fallbacks (or `init.css` is used)
+- [ ] PostCSS uses `@tailwindcss/postcss`
+- [ ] Base stylesheet imported before brand CSS, both unlayered
+- [ ] Dark mode works with a non-default brand active
+- [ ] `npx tsc --noEmit` clean; no console errors on theme/brand switch

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mieweb/ui",
-  "version": "0.11.0-dev.18",
+  "version": "0.11.0-dev.19",
   "description": "A themeable, accessible React component library built with Tailwind CSS",
   "author": "Medical Informatics Engineering, Inc.",
   "license": "SEE LICENSE IN LICENSE",