@geomak/ui 7.17.0 → 7.18.0

package/README.md

@@ -4,7 +4,7 @@
 
 # @geomak/ui · Oxygen Design System
 
-**60+ production-grade React components for enterprise apps** — dashboards, CRMs, internal tools, and landing pages. Token-driven, accessible, light/dark first-class, and properly tree-shakeable.
+**100+ production-grade React components for enterprise apps** — dashboards, CRMs, internal tools, and landing pages. Token-driven, accessible, light/dark first-class, and properly tree-shakeable.
 
 [![npm version](https://img.shields.io/npm/v/@geomak/ui?color=0466c8&label=npm)](https://www.npmjs.com/package/@geomak/ui)
 [![types](https://img.shields.io/npm/types/@geomak/ui?color=0466c8)](https://www.npmjs.com/package/@geomak/ui)
@@ -64,7 +64,7 @@ import { ChevronDown, Search, createIcon } from '@geomak/ui/icons'
 
 ## Components
 
-60+ components across these groups — all with **live controls and a written guide** in [Storybook](https://oxygenui.com).
+100+ components across these groups — all with **live controls and a written guide** in [Storybook](https://oxygenui.com).
 
 | Group | Components |
 |---|---|
@@ -135,6 +135,71 @@ The standard **gray / slate / zinc** ramps and **black** stay available alongsid
 
 ---
 
+## AI toolchain (Claude Code)
+
+OxygenUI ships a built-in MCP server and a set of Claude Code skills and commands that let AI assistants look up component APIs, search by use-case, and scaffold new components — all grounded in the real MDX documentation.
+
+### MCP server
+
+The server is deployed alongside Storybook on Netlify as a Netlify Function at `/mcp`. It exposes four tools:
+
+| Tool | What it does |
+|---|---|
+| `list_components` | Browse all 100+ components with slug, category, and description |
+| `get_component` | Fetch the full props API and usage examples for one component by slug |
+| `find_component` | Keyword search across names, categories, and descriptions |
+| `get_token` | Look up CSS custom properties by name or category prefix |
+
+**Connect it:**
+
+```jsonc
+// .mcp.json (already in the repo — update the URL after first deploy)
+{
+  "mcpServers": {
+    "oxygen-ui": {
+      "type": "http",
+      "url": "https://your-site.netlify.app/mcp"
+    },
+    "oxygen-ui-local": {
+      "type": "http",
+      "url": "http://localhost:8888/mcp"
+    }
+  }
+}
+```
+
+Or add it from the CLI: `claude mcp add oxygen-ui --transport http https://your-site.netlify.app/mcp`
+
+### Claude Code commands
+
+Four slash commands are registered in `.claude/commands/`:
+
+| Command | Usage |
+|---|---|
+| `/ui-lookup <name>` | Fetch the full docs for a component — e.g. `/ui-lookup wizard` |
+| `/ui-find <query>` | Search by use-case — e.g. `/ui-find virtualized table` |
+| `/ui-scaffold <name>` | Scaffold a new component with source + story + MDX guide |
+| `/ui-story <name>` | Add story coverage for an existing component |
+
+### Context skill
+
+The `/oxygen-ui` skill loads the full design system context into any Claude Code session — import patterns, token usage, Tailwind utilities, form API, and repository conventions. Invoke it at the start of any session where you plan to build against `@geomak/ui`.
+
+### Local development with the MCP server
+
+```bash
+npm install -g netlify-cli          # one-time global install
+yarn mcp:dev                        # generates manifest + starts netlify dev on port 8888
+```
+
+The function is then available at `http://localhost:8888/mcp`. Claude Code picks up the `oxygen-ui-local` entry from `.mcp.json` automatically when you open the project.
+
+### How the manifest is built
+
+At build time, `scripts/generate-ai-manifest.mjs` scans all 101 MDX guide files in `src/docs/` and the co-located MDX files in `src/components/`, strips Storybook boilerplate, and emits `netlify/functions/ai-manifest.json`. The Netlify Function bundles this JSON via esbuild — no database, no runtime file I/O, no cold-start penalty.
+
+---
+
 ## Development
 
 ```bash

package/dist/index.cjs

@@ -5092,12 +5092,52 @@ function useTargetBbox(ref) {
 }
 var TOOLTIP_WIDTH = 280;
 var TOOLTIP_GAP = 12;
-function tooltipStyleFor(bbox, placement) {
-  const pl = placement ?? "right";
-  if (pl === "right") return { left: bbox.right + TOOLTIP_GAP, top: bbox.top + bbox.height / 2, transform: "translateY(-50%)", width: TOOLTIP_WIDTH };
-  if (pl === "left") return { left: bbox.left - TOOLTIP_WIDTH - TOOLTIP_GAP, top: bbox.top + bbox.height / 2, transform: "translateY(-50%)", width: TOOLTIP_WIDTH };
-  if (pl === "bottom") return { left: bbox.left + bbox.width / 2, top: bbox.bottom + TOOLTIP_GAP, transform: "translateX(-50%)", width: TOOLTIP_WIDTH };
-  return { left: bbox.left + bbox.width / 2, top: bbox.top - TOOLTIP_GAP, transform: "translate(-50%, -100%)", width: TOOLTIP_WIDTH };
+function tooltipStyleFor(bbox, placement, tooltipHeight) {
+  const GAP2 = TOOLTIP_GAP;
+  const W = TOOLTIP_WIDTH;
+  const H = tooltipHeight;
+  const vw = window.innerWidth;
+  const vh = window.innerHeight;
+  let side = placement ?? "right";
+  if (side === "right" && bbox.right + GAP2 + W > vw) side = "left";
+  if (side === "left" && bbox.left - W - GAP2 < 0) side = "right";
+  if (side === "bottom" && bbox.bottom + GAP2 + H > vh) side = "top";
+  if (side === "top" && bbox.top - GAP2 - H < 0) side = "bottom";
+  let left;
+  let top;
+  let transform;
+  if (side === "right") {
+    left = bbox.right + GAP2;
+    top = bbox.top + bbox.height / 2;
+    transform = "translateY(-50%)";
+  } else if (side === "left") {
+    left = bbox.left - W - GAP2;
+    top = bbox.top + bbox.height / 2;
+    transform = "translateY(-50%)";
+  } else if (side === "bottom") {
+    left = bbox.left + bbox.width / 2;
+    top = bbox.bottom + GAP2;
+    transform = "translateX(-50%)";
+  } else {
+    left = bbox.left + bbox.width / 2;
+    top = bbox.top - GAP2;
+    transform = "translate(-50%, -100%)";
+  }
+  if (side === "top" || side === "bottom") {
+    left = Math.max(GAP2 + W / 2, Math.min(left, vw - W / 2 - GAP2));
+  } else {
+    left = Math.max(GAP2, Math.min(left, vw - W - GAP2));
+  }
+  if (H > 0) {
+    if (side === "right" || side === "left") {
+      top = Math.max(GAP2 + H / 2, Math.min(top, vh - GAP2 - H / 2));
+    } else if (side === "bottom") {
+      top = Math.max(GAP2, Math.min(top, vh - GAP2 - H));
+    } else {
+      top = Math.max(GAP2 + H, Math.min(top, vh - GAP2));
+    }
+  }
+  return { left, top, transform, width: W };
 }
 function useFocusTrap(containerRef, active) {
   React36.useEffect(() => {
@@ -5145,6 +5185,11 @@ function Wizard({
   const reduced = framerMotion.useReducedMotion();
   const [open, setOpen] = React36.useState(() => steps.length > 0 && !readDismissed(storageKey));
   const [activeIndex, setActiveIndex] = React36.useState(0);
+  const [tooltipHeight, setTooltipHeight] = React36.useState(0);
+  React36.useLayoutEffect(() => {
+    const h = tooltipRef.current?.offsetHeight ?? 0;
+    if (h > 0) setTooltipHeight((prev) => prev === h ? prev : h);
+  }, [activeIndex, open]);
   const step = steps[activeIndex];
   const bbox = useTargetBbox(step?.stepRef);
   useFocusTrap(tooltipRef, open);
@@ -5197,7 +5242,7 @@ function Wizard({
     right: 0,
     height: bbox.height + SPOT_PAD * 2
   } : { display: "none" };
-  const tooltipStyle = bbox ? tooltipStyleFor(bbox, step?.placement) : { display: "none" };
+  const tooltipStyle = bbox ? tooltipStyleFor(bbox, step?.placement, tooltipHeight) : { display: "none" };
   const isLast = activeIndex === steps.length - 1;
   return /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
     children,