aural-ui 2.1.21 → 3.0.0

package/README.md

@@ -6,11 +6,11 @@
 [![npm downloads](https://img.shields.io/npm/dm/aural-ui.svg)](https://www.npmjs.com/package/aural-ui)
 [![bundle size](https://img.shields.io/bundlephobia/minzip/aural-ui)](https://bundlephobia.com/package/aural-ui)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Storybook](https://img.shields.io/badge/Storybook-FF4785?style=flat&logo=storybook&logoColor=white)](https://aural-ui.netlify.app)
+[![Storybook](https://img.shields.io/badge/Storybook-FF4785?style=flat&logo=storybook&logoColor=white)](https://aural-ui.pocketfm.com/)
 
 A modern CLI toolkit for seamlessly integrating customizable UI components into React projects. Quickly scaffold, add, and manage production-ready components with minimal configuration.
 
-[📚 Documentation](https://aural-ui.netlify.app) • [🎨 Storybook](https://aural-ui.netlify.app) • [📦 NPM](https://www.npmjs.com/package/aural-ui) • [🐛 Issues](https://github.com/Pocket-Fm/fm-ui/issues)
+[📚 Documentation](https://aural-ui.pocketfm.com/) • [🎨 Storybook](https://aural-ui.pocketfm.com/) • [📦 NPM](https://www.npmjs.com/package/aural-ui) • [🐛 Issues](https://github.com/Pocket-Fm/aural-ui/issues)
 
 </div>
 
@@ -104,11 +104,62 @@ aural-ui update
 | Command | Description | Example |
 |---------|-------------|---------|
 | `init` | Initialize aural-ui in your project | `aural-ui init` |
+| `init --yes` | Non-interactive init with defaults | `aural-ui init --yes` |
 | `add <components>` | Add one or more components | `aural-ui add button card` |
 | `remove <components>` | Remove components from project | `aural-ui remove button` |
 | `update [components]` | Update components to latest version | `aural-ui update` |
 | `theme` | Configure theme and design tokens | `aural-ui theme` |
 
+## 🔌 MCP (Cursor / AI assistant)
+
+The **aural-ui MCP server** exposes the design system by reading from aural-ui source (components, icons, source and story files). No Storybook process is required.
+
+### Setup in Cursor
+
+Add **aural-ui** in `.cursor/mcp.json` (or Cursor Settings → MCP). Start the MCP server first (e.g. `npx tsx mcp/src/index.ts` from the aural-ui repo root, or run the Docker image), then point Cursor at the streamable HTTP endpoint:
+
+```json
+{
+  "mcpServers": {
+    "aural-ui-mcp": {
+      "type": "streamableHttp",
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}
+```
+
+Use the same URL when the server runs in Docker or elsewhere (e.g. `http://your-host:3000/mcp`).
+
+- **Config:** All MCP server settings are in `mcp/src/lib/env.ts` (no .env). You can set `AURAL_UI_SRC` there to the aural-ui repo `src` path if the workspace is not the aural-ui repo.
+
+**HTTP / Docker:** When running the MCP server over HTTP (e.g. in Docker):
+- **GET /health** — Returns `200` and `{ "ok": true, "server": "aural-ui" }` for load balancers and orchestrators (no MCP session required).
+- **GET /metrics** — Returns Prometheus-format metrics: `mcp_sessions_active`, `mcp_sessions_max`, `mcp_tool_calls_total{tool="..."}` (no MCP session required).
+- **Settings** (in `mcp/src/lib/env.ts`): `PORT` (default `3000`), `MCP_MAX_SESSIONS` (default `100`; 0 = unlimited), `MCP_SESSION_IDLE_TIMEOUT_MS` (default 15 min), `MCP_ALLOWED_PROJECT_ROOTS`, `MCP_LIST_CACHE_TTL_MS` (list cache TTL).
+
+To have Cursor install Aural UI components in your project (instead of writing code manually), ask it to use **`add_aural_components`** with the component names (e.g. `["button", "card", "dialog"]`). The tool will run `npx aural-ui init --yes` if needed, then `npx aural-ui add ...`.
+
+### MCP tools
+
+| Tool | Description |
+|------|-------------|
+| `add_aural_components` | **Runs the CLI:** init if needed, then `npx aural-ui add <components>`. Only use component names that exist; if the user's request is unclear or doesn't match, call `list_components` first and show available names—do not guess and add a different component. |
+| `init_aural_ui` | **Runs the CLI:** runs `npx aural-ui init --yes` in the workspace. Use when the project has no aural-ui.json yet. |
+| `get_aural_ui_status` | Where aural-ui source is resolved (env, repo, node_modules). |
+| `get_aural_ui_version` | Returns the aural-ui design system version from the resolved source (package.json). |
+| `list_components` / `list_icons` / `list_hooks` | **Call first when unsure:** returns available component, icon, or hook names. Use when the user asks for a component/hook that might not exist so you can show the list instead of guessing. |
+| `get_component_source` / `get_component_story` / `get_component_docs` | Component source and story file content (read from repo). `get_component_docs` includes metadata (tokens, internal deps) when available. |
+| `get_component_meta` | Component metadata: dependencies, internalDependencies, and design tokens. |
+| `get_icon_source` | Icon component source. |
+| `get_theme_source` | Theme CSS (design tokens) from aural-theme.css. Use for correct token names when implementing UI. |
+| `get_hook_source` | Hook source code. Use list_hooks for available hook names. |
+| `search_components` | Search components, icons, and hooks by name (substring). Use when the user describes something vaguely (e.g. "dropdown"). |
+
+**Prompts:** The server exposes guided-flow prompts: "Add aural-ui components" and "Implement UI from Figma". **When the user pastes a Figma link, frame, or URL,** use "Implement UI from Figma" (or the aural-ui MCP tools): get design via Figma MCP, add missing components with `ensure_aural_components`, then build the UI with aural-ui only. In Cursor you can invoke these via the prompts UI for step-by-step instructions.
+
+Design system docs and Storybook: [aural-ui.pocketfm.com](https://aural-ui.pocketfm.com/) (built on **Radix UI**).
+
 ## 🧩 Available Components
 
 ### Layout & Structure
@@ -181,7 +232,7 @@ aural-ui theme
 
 ## 📖 Storybook
 
-Interactive component documentation is available at: **[https://aural-ui.netlify.app](https://aural-ui.netlify.app)**
+Interactive component documentation is available at: **[https://aural-ui.pocketfm.com/](https://aural-ui.pocketfm.com/)**
 
 ### Local Development
 ```bash
@@ -228,8 +279,22 @@ aural-ui/
 │   │   ├── 📁 icons/         # Icon components
 │   │   └── 📁 fonts/         # Font assets
 │   └── 📁 stories/           # Storybook stories
+├── 📁 mcp/                   # MCP server (Cursor / HTTP)
+│   ├── 📁 docs/              # MCP docs (guidelines, figma-workflow, etc.)
+│   └── 📁 src/
+│       ├── 📁 lib/           # env, logger, constants
+│       ├── 📁 transport/     # HTTP transport (sessions, /mcp, /health, /metrics)
+│       ├── 📁 tools/         # MCP tool handlers
+│       ├── 📁 resources/     # MCP resource providers
+│       ├── 📁 prompts/        # MCP prompts
+│       ├── design-system.ts  # Resolve aural-ui source, list/get components
+│       ├── consumer-project.ts # Consumer detection, get_consumer_setup
+│       └── index.ts          # Entry (runHttp)
+├── 📁 .storybook/            # Storybook config and manager
 ├── 📁 aural-ui-example/      # Example implementation
-├── 📁 storybook-static/      # Built Storybook output
+├── 📁 .github/               # CI/CD (e.g. deploy-storybook)
+├── 📄 Dockerfile             # Build MCP HTTP server image (port 3000)
+├── 📄 .dockerignore          # Docker build exclusions
 ├── 📄 package.json           # Package configuration
 ├── 📄 tsconfig.json          # TypeScript configuration
 ├── 📄 vite.config.mts        # Vite configuration
@@ -243,7 +308,7 @@ The component documentation is automatically deployed to Netlify:
 
 1. **Build**: `npm run build-storybook`
 2. **Deploy**: `npm run deploy-storybook`
-3. **Live URL**: [https://aural-ui.netlify.app](https://aural-ui.netlify.app)
+3. **Live URL**: [https://aural-ui.pocketfm.com/](https://aural-ui.pocketfm.com/)
 
 ### NPM Package
 ```bash
@@ -283,7 +348,7 @@ We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) f
 ### Development Setup
 ```bash
 # Clone the repository
-git clone https://github.com/Pocket-Fm/fm-ui.git
+git clone https://github.com/Pocket-Fm/aural-ui.git
 cd aural-ui
 
 # Install dependencies

package/dist/components/drawer/index.tsx

@@ -126,7 +126,7 @@ const DrawerContent = React.forwardRef<
             "data-[vaul-drawer-direction=top]:inset-x-0 data-[vaul-drawer-direction=top]:top-0 data-[vaul-drawer-direction=top]:mb-24 data-[vaul-drawer-direction=top]:max-h-[80vh] data-[vaul-drawer-direction=top]:rounded-b-lg",
             "data-[vaul-drawer-direction=bottom]:inset-x-0 data-[vaul-drawer-direction=bottom]:bottom-0 data-[vaul-drawer-direction=bottom]:mt-24 data-[vaul-drawer-direction=bottom]:max-h-[80vh] data-[vaul-drawer-direction=bottom]:rounded-t-lg",
             "data-[vaul-drawer-direction=right]:inset-y-0 data-[vaul-drawer-direction=right]:right-0 data-[vaul-drawer-direction=right]:w-3/4 data-[vaul-drawer-direction=right]:rounded-l-lg data-[vaul-drawer-direction=right]:sm:max-w-sm",
-            "overflow-auto [scrollbar-width:none] data-[vaul-drawer-direction=left]:inset-y-0 data-[vaul-drawer-direction=left]:left-0 data-[vaul-drawer-direction=left]:w-3/4 data-[vaul-drawer-direction=left]:rounded-r-lg data-[vaul-drawer-direction=left]:sm:max-w-sm",
+            "overflow-hidden data-[vaul-drawer-direction=left]:inset-y-0 data-[vaul-drawer-direction=left]:left-0 data-[vaul-drawer-direction=left]:w-3/4 data-[vaul-drawer-direction=left]:rounded-r-lg data-[vaul-drawer-direction=left]:sm:max-w-sm",
             className,
             classes?.content
           )}
@@ -135,7 +135,9 @@ const DrawerContent = React.forwardRef<
           {showSwipeButton && (
             <div className="bg-fm-surface-primary mx-auto mt-4 hidden h-2 w-[100px] shrink-0 rounded-full group-data-[vaul-drawer-direction=bottom]/drawer-content:block" />
           )}
-          {children}
+          <div className="scrollbar-hide flex min-h-0 flex-1 flex-col overflow-auto">
+            {children}
+          </div>
         </DrawerPrimitive.Content>
       </DrawerPortal>
     )

package/dist/components/textarea/index.tsx

@@ -5,6 +5,7 @@ import React, {
   RefAttributes,
   useCallback,
   useEffect,
+  useId,
   useRef,
   useState,
 } from "react"
@@ -30,7 +31,7 @@ interface TextAreaBaseProps {
   onChange?: (e: React.ChangeEvent<HTMLTextAreaElement>) => void
   onBlur?: (e: React.FocusEvent<HTMLTextAreaElement>) => void
   onFocus?: (e: React.FocusEvent<HTMLTextAreaElement>) => void
-  onInput?: (e: React.FocusEvent<HTMLTextAreaElement>) => void
+  onInput?: (e: React.InputEvent<HTMLTextAreaElement>) => void
   onKeyDown?: (e: React.KeyboardEvent<HTMLTextAreaElement>) => void
   id?: string
   name?: string
@@ -361,8 +362,8 @@ const TextArea = forwardRef<HTMLTextAreaElement, TextAreaProps>(
     const [textareaValue, setTextareaValue] = useState(value || "")
 
     // Generate unique IDs for accessibility
-    const textareaId =
-      id || `textarea-${Math.random().toString(36).substr(2, 9)}`
+    const reactId = useId()
+    const textareaId = id || `textarea-${reactId}`
     const helperTextId = helperText ? `${textareaId}-helper` : undefined
     const charCountId = showCharCount ? `${textareaId}-char-count` : undefined
 
@@ -410,7 +411,7 @@ const TextArea = forwardRef<HTMLTextAreaElement, TextAreaProps>(
               currentLength={currentLength}
               maxLength={maxLength}
               id={charCountId}
-              className={cn("ml-auto", classes?.charCount)}
+              className="ml-auto"
             />
           )}
         </div>