@dreamtree-org/twreact-ui 1.1.49 → 1.1.51

package/dist/index.esm.js

@@ -17228,6 +17228,14 @@ var _excluded$8 = ["isOpen", "onClose", "title", "children", "size", "dismissibl
   _excluded4$1 = ["children", "className"];
 function ownKeys$c(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
 function _objectSpread$c(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys$c(Object(t), true).forEach(function (r) { _defineProperty$4(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys$c(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+// Elements that can receive keyboard focus. Used to drive the focus trap and to
+// pick the first element to focus when the dialog opens (WAI-ARIA APG dialog).
+var FOCUSABLE_SELECTOR = ['a[href]', 'button:not([disabled])', 'textarea:not([disabled])', 'input:not([disabled])', 'select:not([disabled])', '[tabindex]:not([tabindex="-1"])'].join(',');
+var getFocusable = function getFocusable(root) {
+  return root ? Array.from(root.querySelectorAll(FOCUSABLE_SELECTOR)).filter(function (el) {
+    return el.getAttribute('aria-hidden') !== 'true';
+  }) : [];
+};
 var Dialog = function Dialog(_ref) {
   var isOpen = _ref.isOpen,
     onClose = _ref.onClose,
@@ -17244,33 +17252,63 @@ var Dialog = function Dialog(_ref) {
     onOpen = _ref.onOpen,
     props = _objectWithoutProperties$1(_ref, _excluded$8);
   var dialogRef = useRef(null);
+  // The element that had focus when the dialog opened, so we can restore it on close.
+  var lastFocusedRef = useRef(null);
   useEffect(function () {
-    if (isOpen) {
-      var _dialogRef$current;
-      document.body.style.overflow = 'hidden';
-      (_dialogRef$current = dialogRef.current) === null || _dialogRef$current === void 0 || _dialogRef$current.focus();
-      onOpen === null || onOpen === void 0 || onOpen({
-        dialogRef: dialogRef.current
-      });
-    } else {
-      document.body.style.overflow = 'unset';
-    }
+    var _ref2, _focusables$;
+    if (!isOpen) return undefined;
+    // Remember the opener so focus can return to it when the dialog closes.
+    lastFocusedRef.current = document.activeElement;
+    document.body.style.overflow = 'hidden';
+    // Move focus into the panel: first focusable descendant, else the panel itself.
+    var panel = dialogRef.current;
+    var focusables = getFocusable(panel);
+    (_ref2 = (_focusables$ = focusables[0]) !== null && _focusables$ !== void 0 ? _focusables$ : panel) === null || _ref2 === void 0 || _ref2.focus();
+    onOpen === null || onOpen === void 0 || onOpen({
+      dialogRef: panel
+    });
     return function () {
+      var _lastFocusedRef$curre, _lastFocusedRef$curre2;
       document.body.style.overflow = 'unset';
+      // Restore focus to whatever opened the dialog (APG focus-restore requirement).
+      (_lastFocusedRef$curre = lastFocusedRef.current) === null || _lastFocusedRef$curre === void 0 || (_lastFocusedRef$curre2 = _lastFocusedRef$curre.focus) === null || _lastFocusedRef$curre2 === void 0 || _lastFocusedRef$curre2.call(_lastFocusedRef$curre);
     };
   }, [isOpen]);
+  // Escape-to-close + Tab focus trap. An aria-modal element must keep keyboard
+  // focus inside the panel; without this, Tab walks into the page behind it.
   useEffect(function () {
-    var handleEscape = function handleEscape(e) {
-      if (e.key === 'Escape' && dismissible) {
-        onClose === null || onClose === void 0 || onClose();
+    if (!isOpen) return undefined;
+    var handleKeyDown = function handleKeyDown(e) {
+      if (e.key === 'Escape') {
+        if (dismissible) onClose === null || onClose === void 0 || onClose();
+        return;
+      }
+      if (e.key !== 'Tab') return;
+      var panel = dialogRef.current;
+      if (!panel) return;
+      var focusables = getFocusable(panel);
+      if (focusables.length === 0) {
+        // Nothing focusable inside — pin focus to the panel.
+        e.preventDefault();
+        panel.focus();
+        return;
+      }
+      var first = focusables[0];
+      var last = focusables[focusables.length - 1];
+      var active = document.activeElement;
+      var outside = !panel.contains(active) || active === panel;
+      if (e.shiftKey && (active === first || outside)) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && (active === last || outside)) {
+        e.preventDefault();
+        first.focus();
       }
     };
-    if (isOpen) {
-      document.addEventListener('keydown', handleEscape);
-      return function () {
-        return document.removeEventListener('keydown', handleEscape);
-      };
-    }
+    document.addEventListener('keydown', handleKeyDown);
+    return function () {
+      return document.removeEventListener('keydown', handleKeyDown);
+    };
   }, [isOpen, dismissible, onClose]);
   if (!isOpen) return null;
   var sizeClasses = {
@@ -17290,7 +17328,7 @@ var Dialog = function Dialog(_ref) {
     onClick: handleBackdropClick,
     children: jsxs("div", _objectSpread$c(_objectSpread$c({
       ref: dialogRef,
-      className: cn$1('w-full rounded-lg bg-white shadow-xl animate-scale-in', sizeClasses[size], className),
+      className: cn$1('w-full rounded-lg bg-white shadow-xl animate-scale-in motion-reduce:animate-none', sizeClasses[size], className),
       tabIndex: -1,
       role: "dialog",
       "aria-modal": "true",
@@ -17322,30 +17360,30 @@ var Dialog = function Dialog(_ref) {
   }), document.body);
 };
 // Dialog components for composition
-Dialog.Header = function (_ref2) {
-  var children = _ref2.children,
-    className = _ref2.className,
-    props = _objectWithoutProperties$1(_ref2, _excluded2$1);
+Dialog.Header = function (_ref3) {
+  var children = _ref3.children,
+    className = _ref3.className,
+    props = _objectWithoutProperties$1(_ref3, _excluded2$1);
   return jsx("div", _objectSpread$c(_objectSpread$c({
     className: cn$1('border-b border-gray-200 px-6 py-4', className)
   }, props), {}, {
     children: children
   }));
 };
-Dialog.Body = function (_ref3) {
-  var children = _ref3.children,
-    className = _ref3.className,
-    props = _objectWithoutProperties$1(_ref3, _excluded3$1);
+Dialog.Body = function (_ref4) {
+  var children = _ref4.children,
+    className = _ref4.className,
+    props = _objectWithoutProperties$1(_ref4, _excluded3$1);
   return jsx("div", _objectSpread$c(_objectSpread$c({
     className: cn$1('px-6 py-4', className)
   }, props), {}, {
     children: children
   }));
 };
-Dialog.Footer = function (_ref4) {
-  var children = _ref4.children,
-    className = _ref4.className,
-    props = _objectWithoutProperties$1(_ref4, _excluded4$1);
+Dialog.Footer = function (_ref5) {
+  var children = _ref5.children,
+    className = _ref5.className,
+    props = _objectWithoutProperties$1(_ref5, _excluded4$1);
   return jsx("div", _objectSpread$c(_objectSpread$c({
     className: cn$1('flex items-center justify-end gap-3 border-t border-gray-200 px-6 py-4', className)
   }, props), {}, {

package/dist/index.js

@@ -17248,6 +17248,14 @@ var _excluded$8 = ["isOpen", "onClose", "title", "children", "size", "dismissibl
   _excluded4$1 = ["children", "className"];
 function ownKeys$c(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
 function _objectSpread$c(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys$c(Object(t), true).forEach(function (r) { _defineProperty$4(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys$c(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+// Elements that can receive keyboard focus. Used to drive the focus trap and to
+// pick the first element to focus when the dialog opens (WAI-ARIA APG dialog).
+var FOCUSABLE_SELECTOR = ['a[href]', 'button:not([disabled])', 'textarea:not([disabled])', 'input:not([disabled])', 'select:not([disabled])', '[tabindex]:not([tabindex="-1"])'].join(',');
+var getFocusable = function getFocusable(root) {
+  return root ? Array.from(root.querySelectorAll(FOCUSABLE_SELECTOR)).filter(function (el) {
+    return el.getAttribute('aria-hidden') !== 'true';
+  }) : [];
+};
 var Dialog = function Dialog(_ref) {
   var isOpen = _ref.isOpen,
     onClose = _ref.onClose,
@@ -17264,33 +17272,63 @@ var Dialog = function Dialog(_ref) {
     onOpen = _ref.onOpen,
     props = _objectWithoutProperties$1(_ref, _excluded$8);
   var dialogRef = React.useRef(null);
+  // The element that had focus when the dialog opened, so we can restore it on close.
+  var lastFocusedRef = React.useRef(null);
   React.useEffect(function () {
-    if (isOpen) {
-      var _dialogRef$current;
-      document.body.style.overflow = 'hidden';
-      (_dialogRef$current = dialogRef.current) === null || _dialogRef$current === void 0 || _dialogRef$current.focus();
-      onOpen === null || onOpen === void 0 || onOpen({
-        dialogRef: dialogRef.current
-      });
-    } else {
-      document.body.style.overflow = 'unset';
-    }
+    var _ref2, _focusables$;
+    if (!isOpen) return undefined;
+    // Remember the opener so focus can return to it when the dialog closes.
+    lastFocusedRef.current = document.activeElement;
+    document.body.style.overflow = 'hidden';
+    // Move focus into the panel: first focusable descendant, else the panel itself.
+    var panel = dialogRef.current;
+    var focusables = getFocusable(panel);
+    (_ref2 = (_focusables$ = focusables[0]) !== null && _focusables$ !== void 0 ? _focusables$ : panel) === null || _ref2 === void 0 || _ref2.focus();
+    onOpen === null || onOpen === void 0 || onOpen({
+      dialogRef: panel
+    });
     return function () {
+      var _lastFocusedRef$curre, _lastFocusedRef$curre2;
       document.body.style.overflow = 'unset';
+      // Restore focus to whatever opened the dialog (APG focus-restore requirement).
+      (_lastFocusedRef$curre = lastFocusedRef.current) === null || _lastFocusedRef$curre === void 0 || (_lastFocusedRef$curre2 = _lastFocusedRef$curre.focus) === null || _lastFocusedRef$curre2 === void 0 || _lastFocusedRef$curre2.call(_lastFocusedRef$curre);
     };
   }, [isOpen]);
+  // Escape-to-close + Tab focus trap. An aria-modal element must keep keyboard
+  // focus inside the panel; without this, Tab walks into the page behind it.
   React.useEffect(function () {
-    var handleEscape = function handleEscape(e) {
-      if (e.key === 'Escape' && dismissible) {
-        onClose === null || onClose === void 0 || onClose();
+    if (!isOpen) return undefined;
+    var handleKeyDown = function handleKeyDown(e) {
+      if (e.key === 'Escape') {
+        if (dismissible) onClose === null || onClose === void 0 || onClose();
+        return;
+      }
+      if (e.key !== 'Tab') return;
+      var panel = dialogRef.current;
+      if (!panel) return;
+      var focusables = getFocusable(panel);
+      if (focusables.length === 0) {
+        // Nothing focusable inside — pin focus to the panel.
+        e.preventDefault();
+        panel.focus();
+        return;
+      }
+      var first = focusables[0];
+      var last = focusables[focusables.length - 1];
+      var active = document.activeElement;
+      var outside = !panel.contains(active) || active === panel;
+      if (e.shiftKey && (active === first || outside)) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && (active === last || outside)) {
+        e.preventDefault();
+        first.focus();
       }
     };
-    if (isOpen) {
-      document.addEventListener('keydown', handleEscape);
-      return function () {
-        return document.removeEventListener('keydown', handleEscape);
-      };
-    }
+    document.addEventListener('keydown', handleKeyDown);
+    return function () {
+      return document.removeEventListener('keydown', handleKeyDown);
+    };
   }, [isOpen, dismissible, onClose]);
   if (!isOpen) return null;
   var sizeClasses = {
@@ -17310,7 +17348,7 @@ var Dialog = function Dialog(_ref) {
     onClick: handleBackdropClick,
     children: jsxRuntime.jsxs("div", _objectSpread$c(_objectSpread$c({
       ref: dialogRef,
-      className: cn$1('w-full rounded-lg bg-white shadow-xl animate-scale-in', sizeClasses[size], className),
+      className: cn$1('w-full rounded-lg bg-white shadow-xl animate-scale-in motion-reduce:animate-none', sizeClasses[size], className),
       tabIndex: -1,
       role: "dialog",
       "aria-modal": "true",
@@ -17342,30 +17380,30 @@ var Dialog = function Dialog(_ref) {
   }), document.body);
 };
 // Dialog components for composition
-Dialog.Header = function (_ref2) {
-  var children = _ref2.children,
-    className = _ref2.className,
-    props = _objectWithoutProperties$1(_ref2, _excluded2$1);
+Dialog.Header = function (_ref3) {
+  var children = _ref3.children,
+    className = _ref3.className,
+    props = _objectWithoutProperties$1(_ref3, _excluded2$1);
   return jsxRuntime.jsx("div", _objectSpread$c(_objectSpread$c({
     className: cn$1('border-b border-gray-200 px-6 py-4', className)
   }, props), {}, {
     children: children
   }));
 };
-Dialog.Body = function (_ref3) {
-  var children = _ref3.children,
-    className = _ref3.className,
-    props = _objectWithoutProperties$1(_ref3, _excluded3$1);
+Dialog.Body = function (_ref4) {
+  var children = _ref4.children,
+    className = _ref4.className,
+    props = _objectWithoutProperties$1(_ref4, _excluded3$1);
   return jsxRuntime.jsx("div", _objectSpread$c(_objectSpread$c({
     className: cn$1('px-6 py-4', className)
   }, props), {}, {
     children: children
   }));
 };
-Dialog.Footer = function (_ref4) {
-  var children = _ref4.children,
-    className = _ref4.className,
-    props = _objectWithoutProperties$1(_ref4, _excluded4$1);
+Dialog.Footer = function (_ref5) {
+  var children = _ref5.children,
+    className = _ref5.className,
+    props = _objectWithoutProperties$1(_ref5, _excluded4$1);
   return jsxRuntime.jsx("div", _objectSpread$c(_objectSpread$c({
     className: cn$1('flex items-center justify-end gap-3 border-t border-gray-200 px-6 py-4', className)
   }, props), {}, {

package/mcp/README.md

@@ -0,0 +1,83 @@
+# dreamtree-ui MCP server
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes
+`@dreamtree-org/twreact-ui` to AI agents: a coding agent can **discover the
+catalog, fetch authoritative prop contracts, search by capability, and read the
+docs — live**, instead of guessing prop names or copy-pasting from memory.
+
+This is the concrete delivery of the project's **AI-native moat** (roadmap issue
+[#61](https://github.com/DreamtreeTech/dreamtree-ui/issues/61)): something a
+copy-paste generator like shadcn/ui structurally cannot offer.
+
+## What it serves
+
+**Tools**
+| Tool | Args | Returns |
+| --- | --- | --- |
+| `list_components` | — | The full grouped catalog (core / feedback / navigation / utility + hooks + utils) with descriptions. |
+| `get_component` | `name` | One component's spec: import line, props (name/type/default/description), variants, sizes, examples, family exports, a11y + convention notes. Accepts a family-export name (`useToast` → `Toast`). |
+| `search_components` | `query` | Ranked matches across names, family exports, descriptions, prop names, and examples. |
+
+**Resources**
+- `dreamtree://skill` — the consumer AI usage guide (`ai-skills/dreamtree-ui.md`).
+- `dreamtree://docs/<Component>` — the per-component manual (`doc/<Component>.md`), one per documented component.
+
+**Prompt**
+- `compose_ui` (optional `task` arg) — primes an agent to build UI with the library correctly (vocabulary, providers, the get_component-before-use rule).
+
+## Single source of truth
+
+The catalog (`catalog.mjs`) is **derived, not hand-maintained**: it reads the
+public exports from `src/index.js` (names + group via import path) and the
+props/examples from `doc/<Component>.md`. Keep those accurate and the MCP server
+stays truthful automatically. There is no duplicate component list to drift.
+
+## Run it
+
+```bash
+# from the repo root
+npm run mcp          # node mcp/server.mjs  (stdio transport)
+npm run mcp:smoke    # end-to-end check: boots the server, exercises every tool/resource/prompt
+```
+
+It speaks MCP over **stdio** — logs go to stderr, the protocol uses stdout.
+
+## Use it from Claude Code (this repo)
+
+Already wired in [`.mcp.json`](../.mcp.json):
+
+```json
+{
+  "mcpServers": {
+    "dreamtree-ui": { "command": "node", "args": ["mcp/server.mjs"] }
+  }
+}
+```
+
+Open this repo in Claude Code and the `dreamtree-ui` tools/resources are
+available. The companion Claude Code skill at
+`.claude/skills/dreamtree-ui/SKILL.md` tells the agent to query these tools
+before composing UI.
+
+## Use it from another MCP client
+
+Point any MCP client at `node /path/to/dreamtree-ui/mcp/server.mjs`. It needs
+this repo present (the catalog reads `src/index.js` + `doc/`).
+
+## Repo-local vs shipped — both in this package
+
+- **Live server (`mcp/server.mjs`)** — reads `src/index.js` + `doc/*.md` live
+  via `mcp/catalog.mjs`. It's what `.mcp.json` and `npm run mcp` run.
+- **Shipped server** — consumers run `npx -y @dreamtree-org/twreact-ui mcp`
+  (the `mcp` subcommand of the library's bin, `bin/cli.mjs`). Since `src/` and
+  `doc/` aren't in the published tarball, it reads a frozen build-time
+  **snapshot** (`mcp/catalog.snapshot.json`) via `mcp/catalog-snapshot.mjs`.
+
+Both import the same handlers (`server-core.mjs`) and pure queries
+(`catalog-core.mjs`) — single source of truth, nothing copied.
+`npm run mcp:snapshot` regenerates the one generated artifact,
+`mcp/catalog.snapshot.json`. The MCP SDK is a runtime `dependency` of the
+library, lazy-imported only by the `mcp` subcommand (never in a consumer's app
+bundle). See
+[`docs/agents/11-mcp-sync.md §7`](../docs/agents/11-mcp-sync.md#7-consumer-distribution--bundled-in-the-main-package)
+(delivered under #74 / the moat in #61).

package/mcp/catalog-core.mjs

@@ -0,0 +1,44 @@
+// Pure catalog queries — no filesystem, no data source.
+// ---------------------------------------------------------------------------
+// These operate on an already-built catalog object (the shape returned by
+// buildCatalog()), so they are identical whether the catalog came from the
+// live source (mcp/catalog.mjs, reads src/ + doc/) or the frozen snapshot
+// (mcp/catalog-snapshot.mjs, reads mcp/catalog.snapshot.json). Both servers
+// import this file directly — no copying — which is what lets the repo-local
+// `mcp/server.mjs` and the shipped `twreact-ui mcp` subcommand share one
+// implementation.
+
+function allEntries(catalog) {
+  return [...catalog.components, ...catalog.hooks, ...catalog.utils, ...catalog.store];
+}
+
+// Resolve a name to a single catalog entry: exact match, then family-export
+// (e.g. "useToast" → "Toast"), then case-insensitive. Returns null if none.
+export function findComponentIn(catalog, name) {
+  const all = allEntries(catalog);
+  const lower = String(name || "").toLowerCase();
+  return (
+    all.find((x) => x.name === name) ||
+    all.find((x) => x.familyExports.includes(name)) ||
+    all.find((x) => x.name.toLowerCase() === lower) ||
+    null
+  );
+}
+
+// Ranked keyword search across names, family exports, descriptions, prop
+// names, and examples. Returns entries with a `_score`, highest first.
+export function searchCatalogIn(catalog, query) {
+  const q = String(query || "").toLowerCase().trim();
+  if (!q) return [];
+  const scored = [];
+  for (const x of allEntries(catalog)) {
+    let score = 0;
+    if (x.name.toLowerCase().includes(q)) score += 10;
+    if (x.familyExports.some((f) => f.toLowerCase().includes(q))) score += 6;
+    if (x.description.toLowerCase().includes(q)) score += 3;
+    if (x.props.some((p) => p.prop.toLowerCase().includes(q))) score += 2;
+    if (x.examples.toLowerCase().includes(q)) score += 1;
+    if (score > 0) scored.push({ ...x, _score: score });
+  }
+  return scored.sort((a, b) => b._score - a._score);
+}

package/mcp/catalog-snapshot.mjs

@@ -0,0 +1,42 @@
+// Snapshot-backed catalog — what the SHIPPED `twreact-ui mcp` server reads.
+// ---------------------------------------------------------------------------
+// Exposes the SAME surface as the live mcp/catalog.mjs
+//   buildCatalog, findComponent, searchCatalog, listDocNames, readDoc, readSkill
+// so the shared server core (mcp/server-core.mjs) is agnostic to the source.
+// Here the data is a frozen snapshot (mcp/catalog.snapshot.json, generated by
+// scripts/gen-mcp-snapshot.mjs) — no src/ or doc/ needed at runtime, so it
+// works after a plain `npm install @dreamtree-org/twreact-ui`. The pure query
+// helpers are shared verbatim with the live server (./catalog-core.mjs); no
+// copying — both the live and shipped servers import the same files in this
+// package.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { findComponentIn, searchCatalogIn } from "./catalog-core.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const snapshot = JSON.parse(readFileSync(join(__dirname, "catalog.snapshot.json"), "utf8"));
+
+export function buildCatalog() {
+  return snapshot.catalog;
+}
+
+export function findComponent(name) {
+  return findComponentIn(snapshot.catalog, name);
+}
+
+export function searchCatalog(query) {
+  return searchCatalogIn(snapshot.catalog, query);
+}
+
+export function listDocNames() {
+  return Object.keys(snapshot.docs);
+}
+
+export function readDoc(name) {
+  return snapshot.docs[name] ?? null;
+}
+
+export function readSkill() {
+  return snapshot.skill ?? null;
+}