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

package/README.md

@@ -51,10 +51,28 @@ npm install react react-dom
 
 Heavy or specialized dependencies are kept in separate entry points so they don't bloat the core bundle. Install the peer dependencies for the add-ons you need:
 
-| Entry point              | Install                                              | Import path              |
-| ------------------------ | ---------------------------------------------------- | ------------------------ |
-| **AG Grid**              | `npm install ag-grid-community ag-grid-react`        | `@mieweb/ui/ag-grid`    |
-| **DataVis**              | `npm install @mieweb/datavis datavis-ace`            | `@mieweb/ui/datavis`    |
+| Entry point              | Install                                       | Import path          |
+| ------------------------ | --------------------------------------------- | -------------------- |
+| **AG Grid** (deprecated) | `npm install ag-grid-community ag-grid-react` | `@mieweb/ui/ag-grid` |
+| **DataVis**              | `npm install @mieweb/datavis datavis-ace`     | `@mieweb/ui/datavis` |
+
+> ⚠️ **AGGrid is deprecated.** Use DataVis NITRO (`@mieweb/ui/datavis`) for all
+> 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
 
@@ -173,20 +191,20 @@ This watches for source changes and rebuilds automatically. It does **not** star
 
 ### Available Scripts
 
-| Script                    | Description                                               |
-| ------------------------- | --------------------------------------------------------- |
-| `npm run dev`             | Watch & rebuild the library (for local consumers, not Storybook) |
+| Script                    | Description                                                                                       |
+| ------------------------- | ------------------------------------------------------------------------------------------------- |
+| `npm run dev`             | Watch & rebuild the library (for local consumers, not Storybook)                                  |
 | `npm run build:esheet`    | Build eSheet submodule packages (auto-run by `prestorybook`/`prebuild`; skips when already built) |
-| `npm run build`           | Build the library for production                          |
-| `npm run storybook`       | Start Storybook development server                        |
-| `npm run build-storybook` | Build Storybook for static hosting                        |
-| `npm run typecheck`       | Run TypeScript type checking        |
-| `npm run lint`            | Run ESLint                          |
-| `npm run lint:fix`        | Run ESLint with auto-fix            |
-| `npm run format`          | Check code formatting with Prettier |
-| `npm run format:fix`      | Fix code formatting with Prettier   |
-| `npm run test`            | Run tests                           |
-| `npm run test:watch`      | Run tests in watch mode             |
+| `npm run build`           | Build the library for production                                                                  |
+| `npm run storybook`       | Start Storybook development server                                                                |
+| `npm run build-storybook` | Build Storybook for static hosting                                                                |
+| `npm run typecheck`       | Run TypeScript type checking                                                                      |
+| `npm run lint`            | Run ESLint                                                                                        |
+| `npm run lint:fix`        | Run ESLint with auto-fix                                                                          |
+| `npm run format`          | Check code formatting with Prettier                                                               |
+| `npm run format:fix`      | Fix code formatting with Prettier                                                                 |
+| `npm run test`            | Run tests                                                                                         |
+| `npm run test:watch`      | Run tests in watch mode                                                                           |
 
 ## Date & Time Standard
 
@@ -211,7 +229,8 @@ const inProviderZone = DateTime.fromISO(timestamp, {
   zone: 'America/New_York',
 });
 
-const isOpen = DateTime.now().setZone('America/New_York') <
+const isOpen =
+  DateTime.now().setZone('America/New_York') <
   inProviderZone.plus({ hours: 1 });
 ```
 
@@ -692,10 +711,10 @@ This package uses automated releases via GitHub Actions. There are two release c
 
 ### Release Channels
 
-| Channel | npm Tag | Install Command | Description |
-| ------- | ------- | --------------- | ----------- |
-| **Stable** | `latest` | `npm install @mieweb/ui` | Production-ready releases |
-| **Prerelease** | `next` | `npm install @mieweb/ui@next` | Latest from `main` branch |
+| Channel        | npm Tag  | Install Command               | Description               |
+| -------------- | -------- | ----------------------------- | ------------------------- |
+| **Stable**     | `latest` | `npm install @mieweb/ui`      | Production-ready releases |
+| **Prerelease** | `next`   | `npm install @mieweb/ui@next` | Latest from `main` branch |
 
 ### Prerelease (Automatic)
 
@@ -721,6 +740,7 @@ To create a stable release:
 5. Click **Run workflow**
 
 The workflow will:
+
 1. Bump the version in `package.json`
 2. Commit and push the change
 3. Create a git tag (e.g., `v0.2.0`)
@@ -737,6 +757,7 @@ git push origin v1.0.0
 ```
 
 The release workflow will automatically:
+
 - Run tests and build
 - Publish to npm with the appropriate tag (`latest` for stable, `next` for prereleases like `v1.0.0-beta.1`)
 - Create a GitHub Release with auto-generated release notes
@@ -752,8 +773,8 @@ We follow [Semantic Versioning](https://semver.org/):
 ## Contributing
 
 We welcome contributions! This README and the [Storybook](https://ui.mieweb.org)
-are the **consumer** docs (how to *use* the library). If you want to *build or
-change* the library itself, the **provider / maintainer** guide is
+are the **consumer** docs (how to _use_ the library). If you want to _build or
+change_ the library itself, the **provider / maintainer** guide is
 **[CONTRIBUTING.md](CONTRIBUTING.md)** — it covers repo layout, the component
 anatomy and conventions, the autodocs story pattern, exports & tree-shaking,
 build, testing (unit + visual baselines), submodules, brands, and the release

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`.

package/dist/ag-grid.cjs

@@ -86,6 +86,14 @@ var getDefaultColDef = (sortable, filterable, resizable) => ({
   headerClass: "ag-header-cell-custom",
   cellClass: "ag-cell-custom"
 });
+var didWarnDeprecated = false;
+function warnDeprecatedOnce() {
+  if (process.env.NODE_ENV === "production" || didWarnDeprecated) return;
+  didWarnDeprecated = true;
+  console.warn(
+    "[@mieweb/ui] AGGrid is deprecated. Use DataVis NITRO (@mieweb/ui/datavis) for all tables."
+  );
+}
 function AGGridInner({
   className,
   variant,
@@ -111,6 +119,9 @@ function AGGridInner({
 }, ref) {
   const internalRef = React__namespace.useRef(null);
   const gridApiRef = React__namespace.useRef(null);
+  React__namespace.useEffect(() => {
+    warnDeprecatedOnce();
+  }, []);
   const resolvedRef = gridRef || ref || internalRef;
   const handleGridReady = React__namespace.useCallback(
     (event) => {