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

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

package/dist/{chunk-OAHORW4N.cjs → chunk-3YDTZUI6.cjs}

@@ -682,97 +682,116 @@ var DateInput = React__namespace.forwardRef(
       const helperId = `${inputId}-helper`;
       const showError = hasError || !!localError;
       const errorMessage = error || localError;
-      return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: chunkS5RVSXDV_cjs.cn("flex flex-col gap-1.5", widthClasses[width]), children: [
-        label && /* @__PURE__ */ jsxRuntime.jsxs(
-          "label",
-          {
-            htmlFor: inputId,
-            className: chunkS5RVSXDV_cjs.cn(
-              "text-foreground text-sm font-medium",
-              hideLabel && "sr-only"
+      return /* @__PURE__ */ jsxRuntime.jsxs(
+        "div",
+        {
+          "data-slot": "input-wrapper",
+          className: chunkS5RVSXDV_cjs.cn("flex flex-col gap-1.5", widthClasses[width]),
+          children: [
+            label && /* @__PURE__ */ jsxRuntime.jsxs(
+              "label",
+              {
+                "data-slot": "input-label",
+                htmlFor: inputId,
+                className: chunkS5RVSXDV_cjs.cn(
+                  "text-foreground text-sm font-medium",
+                  hideLabel && "sr-only"
+                ),
+                children: [
+                  label,
+                  required && /* @__PURE__ */ jsxRuntime.jsx(
+                    "span",
+                    {
+                      className: "ml-1",
+                      style: { color: "#ef4444" },
+                      "aria-hidden": "true",
+                      children: "*"
+                    }
+                  )
+                ]
+              }
             ),
-            children: [
-              label,
-              required && /* @__PURE__ */ jsxRuntime.jsx(
-                "span",
+            /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "relative", children: [
+              /* @__PURE__ */ jsxRuntime.jsx(
+                "input",
                 {
-                  className: "ml-1",
-                  style: { color: "#ef4444" },
-                  "aria-hidden": "true",
-                  children: "*"
+                  "data-slot": "input",
+                  ref,
+                  id: inputId,
+                  type: "text",
+                  inputMode: inputType === "date" ? "numeric" : void 0,
+                  autoComplete,
+                  placeholder: inputType === "month" ? "Select month" : inputType === "time" ? "Select time" : inputType === "datetime-local" ? "Select date and time" : placeholder,
+                  value: formatPickerValue(displayValue, inputType, timeFormat),
+                  onChange: handleChange,
+                  onBlur: inputType === "date" ? handleBlur : onBlur,
+                  onClick: (event) => {
+                    onClick?.(event);
+                    setIsCalendarOpen(true);
+                  },
+                  readOnly: !isFormattedDate,
+                  "aria-invalid": showError,
+                  "aria-describedby": [errorMessage ? errorId : null, helperText ? helperId : null].filter(Boolean).join(" ") || void 0,
+                  className: chunkS5RVSXDV_cjs.cn(
+                    "w-full px-3 py-2",
+                    "rounded-lg border",
+                    "bg-background text-foreground",
+                    "placeholder:text-muted-foreground",
+                    "transition-colors duration-200",
+                    "focus:ring-ring focus:border-transparent focus:ring-2 focus:outline-none",
+                    "disabled:cursor-not-allowed disabled:opacity-50",
+                    sizeClasses[resolvedSize],
+                    showError ? "border-destructive focus:ring-destructive" : "border-input",
+                    "pr-10",
+                    className
+                  ),
+                  ...inputProps
                 }
-              )
-            ]
-          }
-        ),
-        /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "relative", children: [
-          /* @__PURE__ */ jsxRuntime.jsx(
-            "input",
-            {
-              ref,
-              id: inputId,
-              type: "text",
-              inputMode: inputType === "date" ? "numeric" : void 0,
-              autoComplete,
-              placeholder: inputType === "month" ? "Select month" : inputType === "time" ? "Select time" : inputType === "datetime-local" ? "Select date and time" : placeholder,
-              value: formatPickerValue(displayValue, inputType, timeFormat),
-              onChange: handleChange,
-              onBlur: inputType === "date" ? handleBlur : onBlur,
-              onClick: (event) => {
-                onClick?.(event);
-                setIsCalendarOpen(true);
-              },
-              readOnly: !isFormattedDate,
-              "aria-invalid": showError,
-              "aria-describedby": [errorMessage ? errorId : null, helperText ? helperId : null].filter(Boolean).join(" ") || void 0,
-              className: chunkS5RVSXDV_cjs.cn(
-                "w-full px-3 py-2",
-                "rounded-lg border",
-                "bg-background text-foreground",
-                "placeholder:text-muted-foreground",
-                "transition-colors duration-200",
-                "focus:ring-ring focus:border-transparent focus:ring-2 focus:outline-none",
-                "disabled:cursor-not-allowed disabled:opacity-50",
-                sizeClasses[resolvedSize],
-                showError ? "border-destructive focus:ring-destructive" : "border-input",
-                "pr-10",
-                className
               ),
-              ...inputProps
-            }
-          ),
-          /* @__PURE__ */ jsxRuntime.jsx(
-            "button",
-            {
-              ref: buttonRef,
-              type: "button",
-              onClick: () => setIsCalendarOpen(!isCalendarOpen),
-              className: chunkS5RVSXDV_cjs.cn(
-                "absolute top-1/2 right-3 -translate-y-1/2",
-                "text-muted-foreground hover:text-foreground",
-                "focus:text-foreground focus:outline-none",
-                "transition-colors"
-              ),
-              "aria-label": inputType === "time" ? "Open time picker" : "Open calendar",
-              "aria-expanded": isCalendarOpen,
-              "aria-haspopup": "dialog",
-              children: inputType === "time" ? /* @__PURE__ */ jsxRuntime.jsx(lucideReact.Clock, { size: 18 }) : /* @__PURE__ */ jsxRuntime.jsx(lucideReact.Calendar, { size: 18 })
-            }
-          )
-        ] }),
-        isCalendarOpen && reactDom.createPortal(renderCalendar(), document.body),
-        errorMessage && /* @__PURE__ */ jsxRuntime.jsx(
-          "p",
-          {
-            id: errorId,
-            className: "text-sm",
-            style: { color: "#ef4444" },
-            role: "alert",
-            children: errorMessage
-          }
-        ),
-        helperText && !errorMessage && /* @__PURE__ */ jsxRuntime.jsx("p", { id: helperId, className: "text-muted-foreground text-sm", children: helperText })
-      ] });
+              /* @__PURE__ */ jsxRuntime.jsx(
+                "button",
+                {
+                  "data-slot": "date-input-trigger",
+                  ref: buttonRef,
+                  type: "button",
+                  onClick: () => setIsCalendarOpen(!isCalendarOpen),
+                  className: chunkS5RVSXDV_cjs.cn(
+                    "absolute top-1/2 right-3 -translate-y-1/2",
+                    "text-muted-foreground hover:text-foreground",
+                    "focus:text-foreground focus:outline-none",
+                    "transition-colors"
+                  ),
+                  "aria-label": inputType === "time" ? "Open time picker" : "Open calendar",
+                  "aria-expanded": isCalendarOpen,
+                  "aria-haspopup": "dialog",
+                  children: inputType === "time" ? /* @__PURE__ */ jsxRuntime.jsx(lucideReact.Clock, { size: 18 }) : /* @__PURE__ */ jsxRuntime.jsx(lucideReact.Calendar, { size: 18 })
+                }
+              )
+            ] }),
+            isCalendarOpen && reactDom.createPortal(renderCalendar(), document.body),
+            errorMessage && /* @__PURE__ */ jsxRuntime.jsx(
+              "p",
+              {
+                id: errorId,
+                "data-slot": "input-error",
+                className: "text-sm",
+                style: { color: "#ef4444" },
+                role: "alert",
+                children: errorMessage
+              }
+            ),
+            helperText && !errorMessage && /* @__PURE__ */ jsxRuntime.jsx(
+              "p",
+              {
+                id: helperId,
+                "data-slot": "input-helper",
+                className: "text-muted-foreground text-sm",
+                children: helperText
+              }
+            )
+          ]
+        }
+      );
     }
     return /* @__PURE__ */ jsxRuntime.jsx(
       chunk6ECKH4DJ_cjs.Input,
@@ -830,5 +849,5 @@ function ChevronRightIcon() {
 }
 
 exports.DateInput = DateInput;
-//# sourceMappingURL=chunk-OAHORW4N.cjs.map
-//# sourceMappingURL=chunk-OAHORW4N.cjs.map
+//# sourceMappingURL=chunk-3YDTZUI6.cjs.map
+//# sourceMappingURL=chunk-3YDTZUI6.cjs.map