@nqlib/nqui 0.3.3 → 0.4.0

package/docs/internal-notes/INSTALLATION.md

@@ -1,99 +1,142 @@
 # nqui Installation Guide
 
-## Quick Start
+## Requirements
 
-### 1. Install nqui
+- **React 18 or 19**: nqui supports both via flexible peer dependencies (`^18.0.0 || ^19.0.0`).
+- **Tailwind CSS v4**: Required for component styling.
+- **Node.js**: See your framework requirements.
+
+---
+
+## Installation Sequence (Quick Reference)
+
+Run these commands in order:
 
 ```bash
-npm install nqui
-# or
-pnpm add nqui
+# 1. Install nqui + peers (choose one)
+pnpm add @nqlib/nqui @hugeicons/react @hugeicons/core-free-icons   # Minimal (icons only)
+npx @nqlib/nqui install-peers                                      # Full (all optional peers)
+
+# 2. Setup CSS
+npx @nqlib/nqui init-css
+
+# 3. Add the nqui import to your main CSS file (see Step 2 details)
+#    Copy contents of nqui/nqui-setup.css to the TOP of app/globals.css (Next.js) or src/index.css (Vite)
+
+# 4. Optional: Debug tools
+npx @nqlib/nqui init-debug-css
+
+# 5. Optional: Refresh Cursor rules (auto-injected on install)
+npx @nqlib/nqui init-cursor
+```
+
+**Run `npx nqui-setup` anytime** to see this checklist again (with nqui installed).
+
+**Monorepo:** Skills are written to the package that has `@nqlib/nqui` (e.g. `apps/frontend/`). Open that folder in Cursor as your workspace.
+
+---
+
+## Step 1: Install nqui + Peers
+
+### Minimal (icons only)
+
+Required for Button, Accordion, Select, and most components with icons:
+
+```bash
+npm install @nqlib/nqui @hugeicons/react @hugeicons/core-free-icons
 # or
-yarn add nqui
+pnpm add @nqlib/nqui @hugeicons/react @hugeicons/core-free-icons
 ```
 
-### 2. Setup CSS (Required)
+### Full (all optional peers)
 
-nqui components require CSS variables and design tokens. Install them using the CLI:
+For Sortable, Carousel, DataTable, Calendar, Command, Drawer, etc.:
 
 ```bash
-npx nqui init-css
+npx @nqlib/nqui install-peers
 ```
 
-This will automatically:
-- Detect your project type (Next.js, Vite, etc.)
-- Copy the CSS file with all design tokens to the appropriate location
-- Provide next steps
+This installs nqui + all optional peer dependencies. See [PEER_DEPENDENCIES.md](./PEER_DEPENDENCIES.md) for the component-to-peer mapping.
+
+---
+
+## Step 2: Setup CSS (Required)
+
+### 2a. Run init-css
 
-**Custom path:**
 ```bash
-npx nqui init-css app/styles/nqui.css
+npx @nqlib/nqui init-css
 ```
 
-The generated CSS includes:
-- All CSS variables (colors, spacing, radius, etc.)
-- Color scales (primary, success, warning, destructive, info)
-- Light and dark mode support
-- Base layer styles
+This creates:
+- `nqui/index.css` — imports from `@nqlib/nqui/styles`
+- `nqui/nqui-setup.css` — full Tailwind + nqui setup (framework-specific)
 
-**Important:** This CSS does NOT include Tailwind CSS imports. You must have Tailwind CSS configured in your project separately.
+### 2b. Add import to main CSS (manual step)
 
-### 3. Import Components
+**You must manually add the nqui import to your main CSS file.** Main files by framework:
 
-```tsx
-import { Button, DebugPanel } from 'nqui';
+| Framework   | Main CSS file       |
+|-------------|---------------------|
+| Next.js     | `app/globals.css`   |
+| Vite        | `src/index.css`     |
+| Remix       | `app/root.css`      |
+
+**Option A (recommended):** Add at the top (after `@import "tailwindcss"`):
+
+```css
+@import "@nqlib/nqui/styles";
 ```
 
-### 4. Setup Debug Tools CSS (Optional)
+**Option B:** Copy the **entire contents** of `nqui/nqui-setup.css` and paste at the **very top** of your main CSS file.
 
-The debug tools require CSS to be imported. You have **three options**:
+### 2c. Next.js + Tailwind v4 — @source directives
 
-#### Option A: Use CLI Tool (Recommended) ✨
+If using Next.js, ensure these are in your main CSS:
 
-```bash
-npx nqui init-debug-css
+```css
+@source "./**/*.{js,ts,jsx,tsx,mdx}";
+@source "../components/**/*.{js,ts,jsx,tsx,mdx}";
+@source "../node_modules/@nqlib/nqui/dist/**/*.js";
 ```
 
-This will automatically:
-- Detect your project type (Next.js, Vite, etc.)
-- Copy the CSS file to the appropriate location
-- Provide next steps
+### 2d. Custom path
 
-**Custom path:**
 ```bash
-npx nqui init-debug-css app/styles/debug.css
+npx @nqlib/nqui init-css app/styles/nqui.css
 ```
 
-#### Option B: Import from Package (If Supported)
+The generated CSS includes: design tokens, color scales, light/dark support. **It does not include Tailwind** — configure Tailwind separately.
 
-Some bundlers support importing CSS from package exports:
+---
+
+## Step 3: Import Components
 
 ```tsx
-// In your app entry point (e.g., app/layout.tsx, src/main.tsx)
-import 'nqui/debug.css';
+import { Button, Input, Card } from "@nqlib/nqui";
 ```
 
-**Note:** This may not work in all frameworks (e.g., Next.js). If you get a "Module not found" error, use Option A or C.
+**Note:** Next.js App Router pages using nqui need `"use client"`.
+
+---
 
-#### Option C: Manual Copy
+## Step 4: Debug Tools (Optional)
 
-1. Copy `node_modules/nqui/dist/nqui.css` to your project:
-   ```bash
-   cp node_modules/nqui/dist/nqui.css src/nqui-debug.css
-   ```
+### 4a. Run init-debug-css
+
+```bash
+npx @nqlib/nqui init-debug-css
+```
 
-2. Import it in your app:
-   ```tsx
-   import './nqui-debug.css';
-   ```
+Custom path: `npx @nqlib/nqui init-debug-css app/styles/debug.css`
 
-### 4. Use DebugPanel
+### 4b. Use DebugPanel
 
 ```tsx
 'use client'; // Required for Next.js App Router
 
-import { DebugPanel } from 'nqui';
-import './nqui-debug.css'; // If using manual copy
+import { DebugPanel } from "@nqlib/nqui";
+import "./nqui-debug.css"; // Path from init-debug-css
 
 export function App() {
   return (
@@ -105,28 +148,59 @@ export function App() {
 }
 ```
 
+**Alternatives:** Import `@nqlib/nqui/debug.css` if your bundler supports it, or manually copy `node_modules/@nqlib/nqui/dist/nqui.css` into your project.
+
+---
+
+## Step 5: Cursor/IDE Rules (Auto-injected)
+
+On install, component guidelines are written to `.cursor/rules/nqui-components.mdc`. To refresh:
+
+```bash
+npx @nqlib/nqui init-cursor
+```
+
+Full per-component docs: `node_modules/@nqlib/nqui/docs/components/README.md`
+
+---
+
+## Step 6: Optional Peer Dependencies
+
+Install only when you use these components:
+
+| Component(s)      | Install |
+|-------------------|---------|
+| Sortable          | `pnpm add @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities` |
+| CommandPalette    | `pnpm add cmdk` |
+| Carousel          | `pnpm add embla-carousel-react` |
+| DataTable         | `pnpm add @tanstack/react-table` |
+| Calendar          | `pnpm add react-day-picker date-fns` |
+| Toaster / Sonner  | `pnpm add sonner` |
+| Drawer            | `pnpm add vaul` |
+| ResizablePanel    | `pnpm add react-resizable-panels` |
+| Combobox          | `pnpm add @base-ui/react` |
+| CodeBlock/Snippet | `pnpm add @nqlib/nqcode shiki @shikijs/transformers` |
+
+See [PEER_DEPENDENCIES.md](./PEER_DEPENDENCIES.md) for the full mapping.
+
+---
+
 ## Framework-Specific Setup
 
 ### Next.js App Router
 
 ```tsx
-// app/layout.tsx or components/debug/debug-panel-client.tsx
+// app/layout.tsx
 'use client';
 
-import { DebugPanel } from 'nqui';
-import '../../node_modules/nqui/dist/nqui.css'; // Direct path import
+import { DebugPanel } from "@nqlib/nqui";
+import "../../node_modules/@nqlib/nqui/dist/nqui.css"; // Direct path if package import fails
 
 export function DebugPanelClient() {
   const [mounted, setMounted] = useState(false);
+  useEffect(() => { setMounted(true); }, []);
 
-  useEffect(() => {
-    setMounted(true);
-  }, []);
-
-  if (process.env.NODE_ENV !== 'development' || !mounted) {
-    return null;
-  }
-
+  if (process.env.NODE_ENV !== 'development' || !mounted) return null;
   return <DebugPanel />;
 }
 ```
@@ -134,9 +208,9 @@ export function DebugPanelClient() {
 ### Vite / Create React App
 
 ```tsx
-// src/main.tsx or src/index.tsx
-import { DebugPanel } from 'nqui';
-import './nqui-debug.css'; // After running init script
+// src/main.tsx
+import { DebugPanel } from "@nqlib/nqui";
+import "./nqui-debug.css";
 
 function App() {
   return (
@@ -152,15 +226,12 @@ function App() {
 
 ```tsx
 // app/root.tsx
-import { DebugPanel } from 'nqui';
-import './nqui-debug.css'; // After running init script
+import { DebugPanel } from "@nqlib/nqui";
+import "./nqui-debug.css";
 
 export default function Root() {
   return (
     <html>
-      <head>
-        {/* ... */}
-      </head>
       <body>
         <Outlet />
         {process.env.NODE_ENV === 'development' && <DebugPanel />}
@@ -170,52 +241,34 @@ export default function Root() {
 }
 ```
 
-## Troubleshooting
-
-### "Module not found: Can't resolve 'nqui/debug.css'"
-
-This error occurs in some frameworks (especially Next.js). **Solution:**
-
-1. Use the CLI tool: `npx nqui init-debug-css`
-2. Or use a direct path import: `import '../../node_modules/nqui/dist/nqui.css'`
-
-### CSS Not Loading
+---
 
-1. Ensure the CSS file exists in `node_modules/nqui/dist/nqui.css`
-2. Check that you've imported it in your app entry point
-3. Verify the import path is correct
+## Troubleshooting
 
-### Debug Panel Not Appearing
+### "Module not found: Can't resolve '@nqlib/nqui/styles'" or CSS not loading
 
-1. Ensure you're in development mode (`NODE_ENV !== 'production'`)
-2. Check that the component is rendered in your app
-3. Verify CSS is imported correctly
+1. Run `npx @nqlib/nqui init-css`
+2. Add `@import "@nqlib/nqui/styles";` to the **top** of your main CSS file (app/globals.css or src/index.css)
+3. Ensure the import is **before** your other styles
 
-## Advanced: Custom CSS Location
+### nqui components render without styles
 
-If you want to customize the CSS or integrate it with your existing styles:
+The main CSS file is missing the nqui import. Add `@import "@nqlib/nqui/styles";` near the top. Or copy contents of `nqui/nqui-setup.css` into your main CSS.
 
-1. Run the init script to get the base CSS
-2. Copy it to your preferred location
-3. Modify as needed
-4. Import in your app
+### Debug Panel not appearing
 
-```bash
-npx nqui init-debug-css src/styles/nqui-debug.css
-```
+1. Ensure `NODE_ENV !== 'production'`
+2. Import the debug CSS
+3. Verify `DebugPanel` is rendered in your app tree
 
-## Package Exports
+### Package import (nqui vs @nqlib/nqui)
 
-The package exports CSS via:
+Use `@nqlib/nqui` — the package name. Old docs may reference `nqui`.
 
-```json
-{
-  "exports": {
-    ".": "./dist/nqui.es.js",
-    "./debug.css": "./dist/nqui.css"
-  }
-}
-```
+---
 
-This allows importing via `import 'nqui/debug.css'` in frameworks that support it.
+## Advanced: Custom CSS Location
 
+1. Run `npx @nqlib/nqui init-css your/path/nqui.css`
+2. Add the import from that path to your main CSS
+3. Or copy `nqui/nqui-setup.css` contents into your existing setup

package/docs/internal-notes/PEER_DEPENDENCIES.md

@@ -0,0 +1,105 @@
+# nqui Optional Peer Dependencies
+
+Heavy or feature-specific dependencies are externalized from the nqui bundle. Consumers using these components must install the corresponding packages.
+
+## Component-to-Peer Mapping
+
+| Component(s) | Peer Dependency |
+|--------------|-----------------|
+| Icons (HugeiconsIcon, most components with icons) | `@hugeicons/react`, `@hugeicons/core-free-icons` |
+| Sortable | `@dnd-kit/core`, `@dnd-kit/modifiers`, `@dnd-kit/sortable`, `@dnd-kit/utilities` |
+| Command, CommandPalette | `cmdk` |
+| Carousel | `embla-carousel-react` |
+| DataTable | `@tanstack/react-table` |
+| Calendar, EnhancedCalendar | `react-day-picker`, `date-fns` |
+| Toaster, Sonner | `sonner` |
+| Drawer | `vaul` |
+| ResizablePanelGroup, ResizablePanel, ResizableHandle | `react-resizable-panels` |
+| Combobox, EnhancedCombobox | `@base-ui/react` |
+
+## Code Display Components (@nqlib/nqcode)
+
+CodeBlock, CodeEditor, Snippet, and Sandbox are in a separate package. Install: `pnpm add @nqlib/nqcode shiki @shikijs/transformers`
+
+| Package | Components | Peer Dependencies |
+|---------|------------|-------------------|
+| `@nqlib/nqcode` | CodeBlock, CodeEditor, Snippet, Sandbox | @nqlib/nqui, shiki, @shikijs/transformers |
+| `@nqlib/nqcode/server` | CodeBlockContentServer (RSC) | shiki, @shikijs/transformers |
+
+## Subpath Exports (Smaller Bundles)
+
+Use subpath imports when you only need specific component groups. This keeps consumer bundles smaller by avoiding the full nqui bundle.
+
+| Subpath | Components | Peer Dependencies |
+|---------|------------|--------------------|
+| `@nqlib/nqui/carousel` | Carousel | embla-carousel-react |
+| `@nqlib/nqui/command` | Command, CommandPalette | cmdk |
+| `@nqlib/nqui/sortable` | Sortable | @dnd-kit/* |
+| `@nqlib/nqui/calendar` | Calendar | react-day-picker, date-fns |
+| `@nqlib/nqui/sonner` | Toaster, Sonner | sonner |
+| `@nqlib/nqui/drawer` | Drawer | vaul |
+
+Example:
+
+```ts
+// Full import (larger bundle)
+import { Carousel } from "@nqlib/nqui";
+
+// Subpath imports (smaller - only loads what you need)
+import { Carousel } from "@nqlib/nqui/carousel";
+
+// Code display (separate package)
+import { CodeBlock, Snippet } from "@nqlib/nqcode";
+```
+
+## Installation
+
+For a minimal setup (Button, Card, etc.), install nqui and the icon library:
+
+```bash
+pnpm add @nqlib/nqui @hugeicons/react @hugeicons/core-free-icons
+```
+
+For full library support (all components: Sortable, Carousel, DataTable, Calendar, etc.):
+
+```bash
+npx @nqlib/nqui install-peers
+```
+
+This installs nqui + all required and optional peer dependencies.
+
+To use Sortable:
+
+```bash
+pnpm add @nqlib/nqui @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities
+```
+
+To use Command/CommandPalette:
+
+```bash
+pnpm add @nqlib/nqui cmdk
+```
+
+To use Resizable panels:
+
+```bash
+pnpm add @nqlib/nqui react-resizable-panels
+```
+
+To use Combobox/EnhancedCombobox:
+
+```bash
+pnpm add @nqlib/nqui @base-ui/react
+```
+
+To use CodeBlock, CodeEditor, Snippet, or Sandbox:
+
+```bash
+pnpm add @nqlib/nqui @nqlib/nqcode shiki @shikijs/transformers
+```
+
+And so on for each component group above.
+
+## Rationale
+
+Externalizing these dependencies keeps the core nqui bundle smaller. Users who only need basic components (Button, Input, Card) do not pay for Sortable, Carousel, or CodeBlock dependencies.

package/docs/internal-notes/PUBLISHING.md

@@ -209,6 +209,78 @@ npm run publish:github
 
 ---
 
+### Republishing After a Bad Release
+
+If a version had bugs (e.g. init-cursor routed to wrong script, skills not working):
+
+1. **Bump version** and fix the code:
+   ```bash
+   cd packages/nqui
+   npm version patch   # 0.4.1 → 0.4.2
+   ```
+
+2. **Publish the fixed version** (same as normal):
+   ```bash
+   npm run publish:both
+   # or npm run publish:npm / publish:github
+   ```
+
+3. **Optional: Deprecate the bad version** (npm only):
+   ```bash
+   npm deprecate @nqlib/nqui@0.4.1 "Use 0.4.2 instead. See changelog."
+   ```
+
+4. **Unpublish** (rare, npm restrictions apply): See [Unpublishing](#unpublishing) below.
+
+**Recommendation:** Usually deprecate + publish patch. Unpublish only for security issues.
+
+---
+
+## Unpublishing
+
+### npmjs.com
+
+**Rules:**
+- **Within 72 hours of publish**: You can unpublish. The version is then available for re-publish.
+- **After 72 hours**: Unpublish is disallowed. Versions are permanently locked. Use deprecation instead.
+
+**Unpublish a specific version** (within 72 hours):
+```bash
+cd packages/nqui
+npm unpublish @nqlib/nqui@0.4.1 --force --registry=https://registry.npmjs.com
+```
+
+**Unpublish entire package** (within 72 hours, removes all versions):
+```bash
+npm unpublish @nqlib/nqui --force --registry=https://registry.npmjs.com
+```
+
+**After 72 hours – deprecate instead:**
+```bash
+npm deprecate @nqlib/nqui@0.4.1 "Superseded by 0.4.2. Use npm install @nqlib/nqui@0.4.2"
+```
+
+### GitHub Packages
+
+**Rules:**
+- You can delete any version at any time.
+- Deleted versions can be re-published (unlike npm).
+
+**Delete via GitHub UI:**
+1. Go to your repo → **Packages** (right sidebar) or `https://github.com/ORG/REPO/packages`
+2. Click the package `nqui`
+3. **Manage package** → **Delete package** (entire package) or **Manage versions** → delete specific versions
+
+**Delete via GitHub API** (for automation):
+```bash
+# Requires GITHUB_TOKEN with delete:packages
+curl -X DELETE -H "Authorization: token $GITHUB_TOKEN" \
+  "https://api.github.com/orgs/nqlib/packages/npm/nqui/versions/VERSION_ID"
+```
+(Get `VERSION_ID` from the package page or API.)
+
+---
+
 ## Version Management
 
 The `npm version` command automatically:

package/docs/internal-notes/SKILLS-ARCHITECTURE.md

@@ -0,0 +1,105 @@
+# nqui Skills Architecture (LLM-Native Documentation)
+
+nqui uses **Cursor/IDE skills** instead of a documentation website. The AI learns from skills and executes install commands and component docs directly.
+
+## Philosophy
+
+- **LLM-native:** Skills teach the AI; the AI teaches the user.
+- **Docs in package:** `docs/components/` ships with the npm package. Consumers get `node_modules/@nqlib/nqui/docs/components/`.
+- **No doc site:** No need to build or host a docs website. The AI reads markdown from the package.
+
+---
+
+## Skill Package (Injected by `npx @nqlib/nqui init-cursor`)
+
+```
+.cursor/
+├── rules/
+│   └── nqui-components.mdc    # Entry rule (globs: **/*.{ts,tsx})
+└── skills/
+    ├── nqui-install/
+    │   └── SKILL.md           # Install commands, execute in terminal
+    └── nqui-components/
+        └── SKILL.md           # Points to docs path, file resolution table
+```
+
+### 1. nqui-install Skill
+
+**When to load:** User asks to install nqui, set up project, fix missing deps, or run setup commands.
+
+**What it does:**
+- Lists install commands in sequence (full, minimal, CSS, peers)
+- Tells the AI to **execute** these commands (run in terminal)
+- Points to init-css, init-cursor, install-peers with exact usage
+
+**File:** `.cursor/skills/nqui-install/SKILL.md`
+
+### 2. nqui-components Skill
+
+**When to load:** User asks about components, which component to use, how to implement X, or builds UI with nqui.
+
+**What it does:**
+- **Always** points the AI to: `node_modules/@nqlib/nqui/docs/components/`
+- For "which component": read `README.md` (has use-case tables)
+- For "how to use X": read `nqui-<name>.md` (e.g. `nqui-button.md`, `nqui-toggle-group.md`)
+- Enforces rules: ToggleGroup for toolbar, RadioGroup for forms only, context-first design
+
+**File resolution:**
+| Question | File to read |
+|----------|--------------|
+| Component index, use cases | `node_modules/@nqlib/nqui/docs/components/README.md` |
+| Specific component (Button, Toggle, etc.) | `node_modules/@nqlib/nqui/docs/components/nqui-<name>.md` |
+
+**Path for consumers:** `node_modules/@nqlib/nqui/docs/components/`  
+**Path for nqui dev (monorepo):** `packages/nqui/docs/components/`
+
+---
+
+## Flow
+
+1. **User:** "Install nqui in my project"
+   - AI loads nqui-install skill → runs `npx @nqlib/nqui install-peers`, then `npx @nqlib/nqui init-css`, etc.
+
+2. **User:** "Which component for a view mode toggle?"
+   - AI loads nqui-components skill → reads `README.md` → finds ToggleGroup in tables → implements
+
+3. **User:** "How do I use the ToggleGroup?"
+   - AI loads nqui-components → reads `nqui-toggle-group.md` → implements from doc
+
+4. **User:** "nqui styles not loading"
+   - AI has CSS Setup in rule → adds `@import "@nqlib/nqui/styles"` to main CSS
+
+---
+
+## File Map (docs/components)
+
+All component docs follow `nqui-<name>.md`. The README has the full index with links.
+
+| Category | Components |
+|----------|------------|
+| Buttons & Actions | Button, ButtonGroup, Toggle, ToggleGroup |
+| Forms | Input, Select, Checkbox, RadioGroup, Switch, Slider, etc. |
+| Display | Badge, Avatar, Card, Alert, Skeleton, etc. |
+| Overlay | Dialog, Sheet, Drawer, Popover, Tooltip |
+| Layout | Sidebar, Tabs, Accordion, Resizable |
+| Data | DataTable, Sortable, Pagination |
+| Code | CodeBlock, Snippet, CodeEditor (via @nqlib/nqcode) |
+
+---
+
+## Injection
+
+`npx @nqlib/nqui init-cursor` creates:
+- `.cursor/rules/nqui-components.mdc` — Entry rule with globs, install snippet, component rules, skill pointers
+- `.cursor/skills/nqui-install/SKILL.md` — Install commands (execute in terminal)
+- `.cursor/skills/nqui-components/SKILL.md` — Component docs path and file resolution
+
+Post-install also runs `writeCursorRule()` so skills are auto-injected on install.
+
+---
+
+## Extending
+
+- **New component:** Add `nqui-<name>.md` to `docs/components/`, add row to README tables.
+- **New install step:** Update `install.md` template in init-cursor.js, update peer-deps.js.
+- **New skill:** Add to `.cursor/skills/nqui/` template, update init-cursor to emit it.