@mieweb/ui 0.7.3-dev.7 → 0.7.3-dev.8

package/README.md

@@ -60,6 +60,20 @@ Heavy or specialized dependencies are kept in separate entry points so they don'
 > tables. The `@mieweb/ui/ag-grid` entry remains available for existing
 > consumers but will be removed in a future major release.
 
+### AI Agent Rules
+
+Working with AI coding agents (Copilot, Claude Code, Cursor, …)? Install
+@mieweb/ui's agent rules into your repo so agents use library components
+(DataVis NITRO for tables, `Button`/`Badge`/`Modal`/… instead of raw HTML):
+
+```bash
+npx @mieweb/ui init-agent
+```
+
+This writes `.github/instructions/mieweb-ui.instructions.md` (auto-applied by
+VS Code Copilot) and a marked block in `AGENTS.md` (the cross-tool convention).
+Idempotent — rerun after upgrading to refresh the rules. See [agent/](agent/).
+
 ## Quick Start
 
 ### Option 1: With Tailwind CSS (Recommended)

package/agent/README.md

@@ -0,0 +1,20 @@
+# agent/ — AI Agent Rules Shipped with @mieweb/ui
+
+Rules that teach AI coding agents (Copilot, Claude Code, Cursor, Codex, …) to
+use `@mieweb/ui` components — most importantly, **DataVis NITRO for all
+tables** — instead of inventing their own UI.
+
+Agents don't read files inside `node_modules`, so consumers install the rules
+into their repo with:
+
+```bash
+npx @mieweb/ui init-agent
+```
+
+| 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 both targets.                                                                                                                                                               |
+
+Rule content is sourced from [lessons/component-policy.md](../lessons/component-policy.md);
+keep the two in sync when policy changes.

package/agent/init-agent.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * `npx @mieweb/ui init-agent`
+ *
+ * Installs @mieweb/ui's AI-agent rules into the consuming repository:
+ *  1. `.github/instructions/mieweb-ui.instructions.md` — auto-applied by
+ *     VS Code Copilot (and compatible tools) to matching files.
+ *  2. A marked block in `AGENTS.md` — read by Claude Code, Cursor, Codex,
+ *     and other agents that follow the AGENTS.md convention.
+ *
+ * Idempotent: rerun after upgrading @mieweb/ui to refresh both targets.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const command = process.argv[2];
+if (command !== 'init-agent') {
+  console.log('Usage: npx @mieweb/ui init-agent');
+  process.exit(command ? 1 : 0);
+}
+
+const here = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8'));
+const template = readFileSync(join(here, 'mieweb-ui.instructions.md'), 'utf8');
+const targetRoot = resolve(process.cwd());
+
+// --- 1. VS Code instructions file --------------------------------------
+const instructionsDir = join(targetRoot, '.github', 'instructions');
+const instructionsPath = join(instructionsDir, 'mieweb-ui.instructions.md');
+mkdirSync(instructionsDir, { recursive: true });
+writeFileSync(instructionsPath, template);
+console.log(`✔ wrote .github/instructions/mieweb-ui.instructions.md`);
+
+// --- 2. AGENTS.md marked block ------------------------------------------
+const BEGIN = '<!-- mieweb-ui:begin -->';
+const END = '<!-- mieweb-ui:end -->';
+// Same rules, minus the VS Code-specific frontmatter.
+const body = template.replace(/^---\n[\s\S]*?\n---\n+/, '');
+const block = `${BEGIN}\n${body.trimEnd()}\n${END}`;
+
+const agentsPath = join(targetRoot, 'AGENTS.md');
+if (!existsSync(agentsPath)) {
+  writeFileSync(agentsPath, `${block}\n`);
+  console.log('✔ created AGENTS.md');
+} else {
+  const current = readFileSync(agentsPath, 'utf8');
+  const start = current.indexOf(BEGIN);
+  const end = start === -1 ? -1 : current.indexOf(END, start + BEGIN.length);
+  let updated;
+  if (start !== -1 && end !== -1) {
+    updated = current.slice(0, start) + block + current.slice(end + END.length);
+    console.log('✔ refreshed @mieweb/ui block in AGENTS.md');
+  } else {
+    updated = `${current.trimEnd()}\n\n${block}\n`;
+    console.log('✔ appended @mieweb/ui block to AGENTS.md');
+  }
+  writeFileSync(agentsPath, updated);
+}
+
+console.log(`\n@mieweb/ui@${pkg.version} agent rules installed.`);

package/agent/mieweb-ui.instructions.md

@@ -0,0 +1,169 @@
+---
+applyTo: '**/*.{ts,tsx,js,jsx}'
+---
+
+<!-- Generated by `npx @mieweb/ui init-agent`. Do not edit by hand — rerun the command after upgrading @mieweb/ui to refresh. -->
+
+# @mieweb/ui — Rules for AI Agents
+
+This project uses the `@mieweb/ui` component library. Follow these rules for ALL UI work. Browse the full catalog at https://ui.mieweb.org (Storybook).
+
+## Rule 1: Tables start with DataVis NITRO
+
+When asked to create a table, data grid, or any tabular data view:
+
+- **Always start with `DataVisNitroGrid` from `@mieweb/ui/datavis`.** It is the default for every table — propose it first, every time.
+- If the human **explicitly insists** on a plain, simple table after you propose DataVis NITRO, fall back to the `Table` component from `@mieweb/ui` (`Table` + `TableHeader`/`TableBody`/`TableRow`/`TableCell`). Do not choose `Table` on your own.
+- **`AGGrid` is deprecated.** Never import from `@mieweb/ui/ag-grid` in new code.
+- **Never hand-roll a data grid** from raw `<table>`, `<div>` grids, or a third-party grid library.
+
+```tsx
+import { DataVisNitroSource, DataVisNitroGrid } from '@mieweb/ui/datavis';
+// Peer deps: npm install @mieweb/datavis datavis-ace
+```
+
+## Rule 2: Buttons belong in a ButtonGroup
+
+- **Two or more adjacent buttons → always wrap them in `ButtonGroup`.** Never lay out sibling buttons with ad-hoc flex/gap divs.
+- **A single button with a long or unpredictable label** (sentence-like labels, translated text, user-provided data — e.g. "Permanently delete this record") **→ also wrap it in a `ButtonGroup`.** The default `orientation="auto"` measures labels and controls text ellipsis/stacking so long labels never truncate silently.
+- A single button with a short, fixed label ("Save", "OK") may stand alone.
+- **Icon-only buttons** → `<Button size="icon" aria-label="...">`. The `aria-label` is required.
+
+```tsx
+import { Button, ButtonGroup } from '@mieweb/ui';
+
+// Multiple buttons
+<ButtonGroup split>
+  <Button variant="ghost">Back</Button>
+  <Button variant="secondary">Cancel</Button>
+  <Button variant="danger">Permanently delete this record</Button>
+</ButtonGroup>
+
+// Single button, long/dynamic label
+<ButtonGroup>
+  <Button>{t('orders.submitForPriorAuthorization')}</Button>
+</ButtonGroup>
+```
+
+## Rule 3: Use an existing @mieweb/ui component before writing your own
+
+Before writing any UI element, check whether `@mieweb/ui` already provides it. It ships 126+ components, including:
+
+| Category   | Components                                                                                                    |
+| ---------- | ------------------------------------------------------------------------------------------------------------- |
+| Actions    | `Button`, `ButtonGroup` (see Rule 2), `Dropdown`, `CommandPalette`, `QuickAction`                             |
+| Forms      | `Input`, `Textarea`, `Select`, `Checkbox`, `Radio`, `Switch`, `Slider`, `PhoneInput`, `DateInput`             |
+| Display    | `Table` (only if the human insists — see Rule 1), `Badge`, `Avatar`, `Card`, `CountBadge`, `Text`, `Timeline` |
+| Feedback   | `Alert`, `Toast`, `Spinner`, `Skeleton`, `Progress`, `LoadingPage`, `ErrorPage`                               |
+| Navigation | `Tabs`, `Breadcrumb`, `Pagination`, `Sidebar`, `AppHeader`, `PageHeader`, `StepIndicator`                     |
+| Overlays   | `Modal`, `Tooltip`, `DropzoneOverlay`                                                                         |
+| Media      | `AudioPlayer`, `AudioRecorder`, `RecordButton`, `DocumentScanner`                                             |
+| Messaging  | `MessageBubble`, `MessageList`, `MessageComposer`                                                             |
+| Grids      | `DataVisNitroGrid` (default for all tables) — `AGGrid` is **deprecated**                                      |
+
+Raw HTML that duplicates a component is a violation, even if it looks right:
+
+```tsx
+// ❌ Violations
+<button onClick={save}>Save</button>
+<span className="rounded-full bg-blue-100 px-2 py-1 text-xs">Active</span>
+<div className="rounded-lg border p-4 shadow">...</div>
+<table>...</table>
+
+// ✅ Compliant
+<Button onClick={save}>Save</Button>
+<Badge>Active</Badge>
+<Card><CardContent>...</CardContent></Card>
+<DataVisNitroGrid ... />
+```
+
+## Rule 4: Use composition slots, not custom markup
+
+Components ship structural sub-components — use them instead of bespoke divs inside a component:
+
+- `Modal` → `ModalHeader` / `ModalBody` / `ModalFooter`
+- `Card` → `CardHeader` / `CardContent`
+- `Table` → `TableHeader` / `TableBody` / `TableRow` / `TableCell`
+
+```tsx
+// ❌ <Modal open={open}><div className="p-4 border-b font-bold">Title</div>...</Modal>
+// ✅
+<Modal open={open} onClose={close}>
+  <ModalHeader>Title</ModalHeader>
+  <ModalBody>...</ModalBody>
+  <ModalFooter>...</ModalFooter>
+</Modal>
+```
+
+## Rule 5: Use variants and sizes, not className hacks
+
+If a component has a prop for it, use the prop. Never restyle a component with utility classes to imitate an existing variant.
+
+```tsx
+// ❌ <Button className="bg-red-600 text-white hover:bg-red-700">Delete</Button>
+// ✅ <Button variant="danger">Delete</Button>
+// ❌ <Button className="text-xs px-2 py-1">Save</Button>
+// ✅ <Button size="sm">Save</Button>
+```
+
+Button variants: `primary`, `secondary`, `ghost`, `outline`, `danger`, `link`. Sizes: `sm`, `md`, `lg`, `icon`.
+
+## Rule 6: Never hardcode colors
+
+Use design tokens so multi-brand theming (mieweb, bluehive, webchart, enterprise-health, …) keeps working:
+
+- ❌ `bg-blue-500`, `text-[#1a73e8]`, `style={{ color: 'red' }}`
+- ✅ semantic tokens: `bg-primary-600`, `text-muted-foreground`, `border-border`, `bg-background`
+- ✅ charts: `var(--mieweb-chart-1)` … `var(--mieweb-chart-5)`
+
+## Rule 7: Theme through the brand system, never global CSS
+
+- Wrap the app in `ThemeProvider`; use `@mieweb/ui/brands` (`generateBrandCSS`, `brands`) for brand switching.
+- **No global resets or element-selector overrides** (`button { … }`, `* { … }`). Styles stay component-scoped and minimal.
+
+## Rule 8: Feedback states use library components
+
+- Loading: `Spinner` (inline), `Skeleton` (content placeholder), `LoadingPage` (full page). Never a hand-rolled CSS spinner.
+- Outcomes: `Alert` (inline), `Toast` (transient — announces via aria-live for free). Never a bespoke alert div.
+- Errors/empty pages: `ErrorPage`. Progress: `Progress`.
+
+## Rule 9: Accessibility is not optional
+
+- Every interactive element needs an accessible name (`aria-label`, `aria-labelledby`, or visible text).
+- Use semantic HTML (`nav`, `main`, `button`) — never a clickable `div`.
+- Dynamic updates (modals, alerts, notifications) must be announced — prefer `Toast`/`Alert`, which handle aria-live.
+- Preserve logical tab order and visible focus indicators; never remove focus outlines.
+
+## Rule 10: Internationalization and RTL
+
+- **Externalize all user-facing text** — no hardcoded English strings in JSX. Use the project's i18n function (`t('…')`).
+- **Use RTL-safe logical classes**: `ms-*`/`me-*`, `ps-*`/`pe-*`, `start-*`/`end-*`, `text-start`/`text-end` — never `ml-*`/`mr-*`, `pl-*`/`pr-*`, `left-*`/`right-*`, `text-left`/`text-right`.
+- Localize dates, numbers, and currency via `Intl` APIs, not string formatting.
+
+## Rule 11: Forms
+
+- Always use library fields (`Input`, `Textarea`, `Select`, `Checkbox`, `Radio`, `Switch`, `Slider`) with a properly associated `<label>`.
+- Dates → `DateInput` / `DateRangePicker`, never raw `type="date"`. Phones → `PhoneInput`. URLs → `WebsiteInput`.
+
+## Rule 12: Imports and Tailwind setup
+
+```tsx
+// Most components: named imports from the main barrel
+import { Button, Input, Card, Modal, Badge } from '@mieweb/ui';
+
+// Heavy add-ons live behind subpath entries (install their peer deps):
+import { DataVisNitroGrid } from '@mieweb/ui/datavis'; // tables/grids
+import { generateBrandCSS, brands } from '@mieweb/ui/brands'; // branding
+```
+
+Never import from `@mieweb/ui/ag-grid` (deprecated).
+
+Tailwind: on Tailwind 4, add an `@source` for `@mieweb/ui` so library classes are generated; on Tailwind 3, use the `@mieweb/ui/tailwind-preset` preset and `miewebUISafelist`. Do not invent purge/content configs.
+
+## Rule 13: Deprecations are law
+
+If JSDoc, the console, or the docs mark something deprecated (`AGGrid` today), do not use it in new code and do not suppress the warning. Use the documented replacement.
+
+## Rule 14: When no component exists
+
+First verify it truly doesn't exist — check https://ui.mieweb.org (Storybook) rather than guessing. Then build it locally, but in `@mieweb/ui` style: Tailwind utility classes with the library's design tokens, ARIA labels on interactive elements, and externalized user-facing text. Prefer composing existing primitives (`Card`, `Text`, `Badge`) over new bespoke markup. If the pattern is generic, propose contributing it upstream to `@mieweb/ui`.