@nqlib/nqui 0.4.3 → 0.4.4

package/INSTALLATION.md

@@ -0,0 +1,215 @@
+# nqui – Installation & CLI reference
+
+Developer guide: what runs on install, available commands, and the recommended setup sequence.
+
+---
+
+## What runs on `npm install`
+
+When you add `@nqlib/nqui` to a project and run `npm install` (or pnpm/yarn/bun):
+
+1. **Postinstall script** runs: `node scripts/post-install.js` (same as `npx @nqlib/nqui setup`).
+2. **Behavior:**
+   - If your project has a `package.json` and no `nqui:init` script, a **`nqui:init`** script is added to run the full setup in one command.
+   - **Cursor rules** are written into your project’s `.cursor/` directory:
+     - `.cursor/rules/nqui-components.mdc`
+     - `.cursor/skills/nqui-install/`
+     - `.cursor/skills/nqui-components/`
+   - A **next-steps message** is printed (run `npx nqui-setup` anytime to see it again).
+3. **Not done on install:** Peer packages are not installed, `.cursor/nqui-skills/` is not created, and CSS is not set up. Run the full setup (see below) for that.
+4. **CI:** Postinstall is skipped when `CI=true` or `CI=1`.
+
+---
+
+## CLI commands
+
+All commands are run from your **project root** (where `package.json` lives).
+
+| Command | Description |
+|--------|-------------|
+| `npx @nqlib/nqui setup` | Re-run postinstall: print next steps and write Cursor rules (no peers/skills/CSS). Same as `npx nqui-setup`. |
+| `npx @nqlib/nqui install-peers` | Install `@nqlib/nqui` and all required + optional peer dependencies (icons, cmdk, dnd-kit, etc.). |
+| `npx @nqlib/nqui init-cursor` | Write `.cursor/rules` and `.cursor/skills`, and **download nqui-skills** (copy `docs/nqui-skills` → `.cursor/nqui-skills`, create `AGENTS.md`). |
+| `npx @nqlib/nqui init-skills` | Only download skills: copy to `.cursor/nqui-skills`, (re)create `AGENTS.md`. Use `--force` to overwrite. |
+| `npx @nqlib/nqui init-css` | Detect framework, create `nqui/index.css` and `nqui/nqui-setup.css`, optionally copy example layouts. Options: `--sidebar`, `--force`, `--wizard`. |
+| `npx @nqlib/nqui` _(no args)_ | Runs **init-css** with default output `nqui/index.css`. |
+| `npx @nqlib/nqui init-debug` / `init-debug-css` | Initialize debug CSS for `DebugPanel`. |
+| `npm run nqui:init` | One-shot full setup (only after install added the script): install-peers → init-cursor → init-skills → init-css --sidebar --force. |
+
+**Monorepos:** Cursor rules and skills are written to the package that has `@nqlib/nqui` in `node_modules` or in its `package.json`. Open that package folder in Cursor for skills to resolve.
+
+---
+
+## Recommended sequence
+
+### Option A: One command (after install)
+
+If postinstall added the script:
+
+```bash
+npm run nqui:init
+```
+
+This runs: **install-peers** → **init-cursor** → **init-skills** → **init-css --sidebar --force**.
+
+Then **manually** add the nqui CSS import to your main CSS file (see [Step 2: Setup CSS](#step-2-setup-css-required) below).
+
+### Option B: Step by step
+
+```bash
+# 1. Install nqui + minimal deps (or use install-peers for full)
+npm install @nqlib/nqui @hugeicons/react @hugeicons/core-free-icons
+# or: npx @nqlib/nqui install-peers
+
+# 2. Cursor rules + nqui-skills
+npx @nqlib/nqui init-cursor
+
+# 3. (Optional) Refresh skills only
+npx @nqlib/nqui init-skills
+
+# 4. CSS setup
+npx @nqlib/nqui init-css --sidebar
+# Then add the import to your main CSS (see Step 2 below)
+```
+
+---
+
+## Requirements
+
+- **React 18 or 19** (peer: `^18.0.0 || ^19.0.0`)
+- **Tailwind CSS v4**
+- **Node.js** per your framework
+
+---
+
+## Step 1: Install nqui + peers
+
+**Minimal (icons required for most components):**
+
+```bash
+npm install @nqlib/nqui @hugeicons/react @hugeicons/core-free-icons
+```
+
+**Full (all optional peers for Sortable, Carousel, DataTable, Calendar, etc.):**
+
+```bash
+npx @nqlib/nqui install-peers
+```
+
+---
+
+## Step 2: Setup CSS (required)
+
+### 2a. Run init-css
+
+```bash
+npx @nqlib/nqui init-css
+```
+
+Creates:
+
+- `nqui/index.css` — imports `@nqlib/nqui/styles`
+- `nqui/nqui-setup.css` — framework-specific Tailwind + nqui snippet
+
+### 2b. Add import to main CSS (manual)
+
+Add the nqui import to your **main CSS file**:
+
+| Framework | Main CSS file |
+|-----------|----------------|
+| Next.js   | `app/globals.css` |
+| Vite      | `src/index.css` |
+| Remix     | `app/root.css` |
+
+**Option A (recommended):** After `@import "tailwindcss"`:
+
+```css
+@import "@nqlib/nqui/styles";
+```
+
+**Option B:** Copy the **entire contents** of `nqui/nqui-setup.css` to the **very top** of your main CSS file.
+
+### 2c. Next.js + Tailwind v4
+
+Include these in your main CSS:
+
+```css
+@source "./**/*.{js,ts,jsx,tsx,mdx}";
+@source "../components/**/*.{js,ts,jsx,tsx,mdx}";
+@source "../node_modules/@nqlib/nqui/dist/**/*.js";
+```
+
+### 2d. Custom path
+
+```bash
+npx @nqlib/nqui init-css app/styles/nqui.css
+```
+
+---
+
+## Step 3: Use components
+
+```tsx
+import { Button, Input, Card } from "@nqlib/nqui";
+```
+
+Next.js App Router pages that use nqui need `"use client"`.
+
+---
+
+## Step 4: Debug tools (optional)
+
+```bash
+npx @nqlib/nqui init-debug-css
+```
+
+Then in your app:
+
+```tsx
+import { DebugPanel } from "@nqlib/nqui";
+import "./nqui-debug.css"; // or path from init-debug-css
+
+// In your root/layout: render when NODE_ENV === 'development'
+<DebugPanel />
+```
+
+---
+
+## Step 5: Cursor / IDE rules
+
+On install, basic rules are written to `.cursor/rules/nqui-components.mdc`. For the full **nqui-skills** set (`.cursor/nqui-skills/` and `AGENTS.md`), run:
+
+```bash
+npx @nqlib/nqui init-cursor
+```
+
+Component docs index: `node_modules/@nqlib/nqui/docs/components/README.md`.
+
+---
+
+## Optional: Local vs published nqui
+
+To switch between a **local** (linked) build and the **published** npm package during development, you can add a `scripts/toggle-nqui.js` script to your app and wire it to your `dev` script. This is optional and not created by nqui. See the nqui skill **nqui-local-published-toggle** for the script and usage (e.g. `USE_LOCAL_NQUI=true node scripts/toggle-nqui.js && next dev`).
+
+---
+
+## Troubleshooting
+
+**"Module not found: '@nqlib/nqui/styles'" or CSS not loading**
+
+1. Run `npx @nqlib/nqui init-css`.
+2. Add `@import "@nqlib/nqui/styles";` near the **top** of your main CSS file.
+3. Ensure it appears **before** other app styles.
+
+**Components render without styles**
+
+Your main CSS is missing the nqui import. Add `@import "@nqlib/nqui/styles";` or paste the contents of `nqui/nqui-setup.css` at the top of your main CSS.
+
+**Debug Panel not showing**
+
+- Ensure `NODE_ENV !== 'production'`.
+- Import the debug CSS and render `<DebugPanel />` in your app tree.
+
+**Package name**
+
+Use `@nqlib/nqui` (the published package name).

package/README.md

@@ -10,42 +10,88 @@ A React component library with enhanced UI components and developer tools. Built
 
 ## Installation
 
-Install from npmjs.com (recommended - no authentication needed):
+### Install the package
+
+Install the published package from [npm](https://www.npmjs.com/package/@nqlib/nqui):
 
 ```bash
 npm install @nqlib/nqui @hugeicons/react @hugeicons/core-free-icons
 ```
 
-Hugeicons is required for icon display in components (Button, Accordion, Select, etc.).
+Hugeicons is required for icons in components (Button, Accordion, Select, etc.).
 
-**Full install** (all optional peers for Sortable, Carousel, DataTable, Calendar, etc.):
+**All optional peers** (Sortable, Carousel, DataTable, Calendar, etc.):
 
 ```bash
 npx @nqlib/nqui install-peers
 ```
 
-**After install:** A post-install message will show the next steps. Run `npx nqui-setup` anytime to see them again.
+**After `npm install`:** the post-install script may add a `nqui:init` script and write initial Cursor rules under `.cursor/`. It does **not** copy full **nqui-skills** or set up CSS — run the commands below. Run `npx nqui-setup` (same as `npx @nqlib/nqui setup`) anytime to see next steps again. Post-install is skipped when `CI=true` or `CI=1`.
+
+### IDE skills (Cursor and compatible agents)
+
+Copy the library’s **skills** into your app so your IDE can follow nqui patterns (components, design system, ToggleGroup rules, etc.):
+
+| Command | What it does |
+|--------|----------------|
+| `npx @nqlib/nqui init-cursor` | Writes `.cursor/rules` and `.cursor/skills`, copies **`docs/nqui-skills`** → **`.cursor/nqui-skills`**, and creates **`AGENTS.md`** at the project root pointing agents at `.cursor/nqui-skills/SKILL.md`. |
+| `npx @nqlib/nqui init-skills` | **Skills only:** copies nqui-skills to `.cursor/nqui-skills/` and (re)creates `AGENTS.md`. Use `--force` to overwrite existing files. |
+| `npm run nqui:init` | **One-shot** (if post-install added this script): `install-peers` → `init-cursor` → `init-skills` → `init-css --sidebar --force`. You still add the CSS import to your main stylesheet (see [INSTALLATION.md](./INSTALLATION.md)). |
+
+After copying skills, **restart the IDE** so rules and skills reload.
+
+**Monorepos:** rules and skills are written to the workspace package that depends on `@nqlib/nqui`. Open that folder in your IDE so paths resolve.
+
+---
 
-**Alternative:** Install from GitHub Packages (requires GitHub account + token):
+### CLI commands
+
+Run from your **app project root** (where `package.json` lives). Equivalent **global bins** (when the package is installed): `nqui`, `nqui-setup`, `nqui-install-peers`, `nqui-init-cursor`, `nqui-init-skills`, `nqui-init-css`, `nqui-init-debug`.
+
+| Command | Description |
+|--------|-------------|
+| `npx @nqlib/nqui setup` | Re-run post-install: next steps + Cursor rules (not full skills/CSS). Same as `npx nqui-setup`. |
+| `npx @nqlib/nqui install-peers` | Install `@nqlib/nqui` and required + optional peer dependencies. |
+| `npx @nqlib/nqui init-cursor` | Cursor rules + **nqui-skills** → `.cursor/nqui-skills/` + `AGENTS.md`. |
+| `npx @nqlib/nqui init-skills` | Copy nqui-skills only; `--force` to overwrite. |
+| `npx @nqlib/nqui init-css` | Detect framework; create `nqui/index.css` and `nqui/nqui-setup.css`. Flags: `--sidebar`, `--force`, `--wizard`. Optional output path, e.g. `npx @nqlib/nqui init-css app/styles/nqui.css`. |
+| `npx @nqlib/nqui` | No args → same as **init-css** (default `nqui/index.css`). |
+| `npx @nqlib/nqui init-debug` or `init-debug-css` | Scaffold CSS for `DebugPanel`. |
+
+---
+
+### Recommended setup order
+
+**Option A — one command** (if `nqui:init` exists in `package.json`):
 
 ```bash
-# Create .npmrc in your project
-echo "@nqlib:registry=https://npm.pkg.github.com" > .npmrc
+npm run nqui:init
+```
+
+Then add `@import "@nqlib/nqui/styles";` (or your framework’s full CSS snippet) to your main CSS — see [INSTALLATION.md](./INSTALLATION.md) Step 2.
 
-# Authenticate with GitHub
-npm login --registry=https://npm.pkg.github.com
+**Option B — step by step:**
 
-# Install
+```bash
 npm install @nqlib/nqui @hugeicons/react @hugeicons/core-free-icons
+# optional: npx @nqlib/nqui install-peers
+
+npx @nqlib/nqui init-cursor
+# optional refresh: npx @nqlib/nqui init-skills
+
+npx @nqlib/nqui init-css --sidebar
+# add CSS import to app/globals.css or src/index.css — see INSTALLATION.md
 ```
 
+**Detailed CSS paths, Next.js `@source` lines, and troubleshooting:** [INSTALLATION.md](./INSTALLATION.md).
+
 ## Quick Start
 
-### Option 1: Package Import (Recommended)
+### Option 1: Package import (recommended)
 
-#### For Next.js
+#### Next.js
 
-1. **Import CSS in your `app/layout.tsx` or `app/globals.css`:**
+1. **Import CSS** in `app/globals.css` (or equivalent):
 
 ```tsx
 // app/globals.css
@@ -71,9 +117,10 @@ export default function Page() {
 }
 ```
 
-**Note:** Pages using nqui components must include `"use client"` because nqui components use React hooks.
+Pages using nqui must use `"use client"` where required (hooks).
+
+**Local linking:** with `npm link` or `file:`, you may need Webpack instead of Turbopack:
 
-**For Local Development:** If you're using `npm link` or `file:` protocol, you may need to use Webpack instead of Turbopack:
 ```json
 {
   "scripts": {
@@ -81,22 +128,22 @@ export default function Page() {
   }
 }
 ```
-See [Troubleshooting](#troubleshooting) for more details.
 
-#### For Vite
+See [Troubleshooting](#troubleshooting).
+
+#### Vite
 
-1. **Import CSS in your `src/main.tsx` or `src/index.css`:**
+1. **CSS** in `src/index.css`:
 
 ```css
-/* src/index.css */
 @import "tailwindcss";
 @import "tw-animate-css";
 @import "@nqlib/nqui/styles";
 ```
 
-**Note:** Vite does NOT require `@source` directives. Tailwind CSS v4 automatically scans files when using the `@tailwindcss/vite` plugin. Only Next.js requires `@source` directives.
+Vite with `@tailwindcss/vite` does not need the same `@source` directives as Next.js.
 
-2. **Use components:**
+2. **Components:**
 
 ```tsx
 import { Button } from '@nqlib/nqui';
@@ -106,43 +153,30 @@ function App() {
 }
 ```
 
-### Option 2: Init Script (Alternative)
-
-The init script automatically detects your framework and sets up CSS with framework-specific Tailwind directives:
+### Option 2: `init-css` helper
 
 ```bash
 npx @nqlib/nqui init-css
 ```
 
-This will:
-- Detect your framework (Next.js, Vite, Remix, etc.)
-- Add framework-specific Tailwind setup
-- Copy nqui CSS variables to the appropriate location
-- Provide next steps
-
-**For Next.js:** Creates/updates `app/globals.css` with Next.js-specific directives  
-**For Vite:** Creates/updates `src/index.css` with Vite-specific directives
+Detects Next.js, Vite, Remix, etc., and scaffolds CSS entry files; see [INSTALLATION.md](./INSTALLATION.md) for wiring the import into your main stylesheet.
 
-## Setup Requirements
+## Setup requirements
 
-### Tailwind CSS Configuration
+### Tailwind CSS
 
-nqui requires Tailwind CSS v4. Ensure you have it installed:
+nqui expects Tailwind CSS v4:
 
 ```bash
 npm install tailwindcss@^4.1.0
 ```
 
-For **Next.js**, Tailwind CSS v4 works with the new `@import` syntax in CSS files.
-
-For **Vite**, install the Tailwind CSS Vite plugin:
+**Vite** — add the plugin:
 
 ```bash
 npm install @tailwindcss/vite
 ```
 
-Then add it to your `vite.config.ts`:
-
 ```ts
 import tailwindcss from '@tailwindcss/vite';
 import { defineConfig } from 'vite';
@@ -152,16 +186,12 @@ export default defineConfig({
 });
 ```
 
-### Optional: Debug Tools
-
-If you want to use the debug tools in development:
+### Optional: debug tools
 
 ```bash
 npx @nqlib/nqui init-debug-css
 ```
 
-Then import in your app:
-
 ```tsx
 import { DebugPanel } from '@nqlib/nqui';
 import '@nqlib/nqui/debug.css';
@@ -176,16 +206,11 @@ function App() {
 }
 ```
 
-## Component Instructions
-
-Per-component implementation guides (AI/LLM-optimized) are in `docs/components/`:
-- After install: `node_modules/@nqlib/nqui/docs/components/README.md` (index of all components)
-- Each file: `nqui-<component>.md` — import, variants, props, notes
-- Token-optimized for easy AI consumption and implementation
+## Component instructions
 
-**Cursor/IDE rules:** Component guidelines are auto-injected to `.cursor/rules/nqui-components.mdc` on install. Run `npx @nqlib/nqui init-cursor` to refresh.
+Guides for each component live under `docs/components/` in the package (after install: `node_modules/@nqlib/nqui/docs/components/`). Use **`npx @nqlib/nqui init-skills`** (or `init-cursor`) so your IDE loads `.cursor/nqui-skills` and `AGENTS.md`.
 
-### Basic Components
+### Examples
 
 ```tsx
 import { Button, Checkbox, Input } from '@nqlib/nqui';
@@ -198,13 +223,8 @@ function MyForm() {
       <Button variant="default">Submit</Button>
     </form>
   );
-}
 ```
 
-### Enhanced Components
-
-nqui includes enhanced versions of common components with additional variants:
-
 ```tsx
 import { Button, Separator } from '@nqlib/nqui';
 
@@ -220,8 +240,6 @@ function MyComponent() {
 }
 ```
 
-### Custom Components
-
 ```tsx
 import { ColorPicker, Rating, TableOfContents } from '@nqlib/nqui';
 
@@ -236,48 +254,26 @@ function MyApp() {
 }
 ```
 
-## Framework Support
+## Framework support
 
-- ✅ **Next.js** (App Router) - Fully tested and supported
-- ✅ **Vite** - Fully supported
-- ✅ **Remix** - Supported
-- ✅ **Create React App** - Supported
+- **Next.js** (App Router)
+- **Vite**
+- **Remix**
+- **Create React App**
 
-All components are framework-agnostic and work with any React setup.
+Components are framework-agnostic for any React setup.
 
 ## Troubleshooting
 
-### @source Directives: Next.js vs Vite
-
-**Problem:** Tailwind classes not working, or confusion about whether to use `@source` directives
-
-**Solution:**
-- **Next.js REQUIRES `@source` directives** in your CSS file:
-  ```css
-  @import "tailwindcss";
-  @source "./**/*.{js,ts,jsx,tsx,mdx}";
-  @source "../components/**/*.{js,ts,jsx,tsx,mdx}";
-  @source "../node_modules/@nqlib/nqui/dist/**/*.js";
-  @import "tw-animate-css";
-  @import "@nqlib/nqui/styles";
-  ```
-
-- **Vite does NOT need `@source` directives** - Tailwind automatically scans files:
-  ```css
-  @import "tailwindcss";
-  @import "tw-animate-css";
-  @import "@nqlib/nqui/styles";
-  ```
+### `@source`: Next.js vs Vite
 
-**Why the difference?** Next.js has a different file structure and build process, so Tailwind needs explicit paths. Vite's `@tailwindcss/vite` plugin automatically handles file scanning.
+- **Next.js** needs `@source` lines so Tailwind sees app and `node_modules/@nqlib/nqui` — see the Quick Start block above.
+- **Vite** typically does not need those `@source` lines when using `@tailwindcss/vite`.
 
-**Common mistake:** Adding `@source` directives to Vite projects (not needed and may cause issues) or missing them in Next.js projects (will cause Tailwind to not find classes).
+### Module resolution (Next.js 16+, local packages)
 
-### Module Resolution Issues (Next.js 16+)
+If `@nqlib/nqui` fails to resolve with `npm link` / `file:`:
 
-If you encounter `Module not found: Can't resolve '@nqlib/nqui'` when using `npm link` or `file:` protocol, switch to Webpack:
-
-**Quick Fix:**
 ```json
 {
   "scripts": {
@@ -286,79 +282,36 @@ If you encounter `Module not found: Can't resolve '@nqlib/nqui'` when using `npm
 }
 ```
 
-**Or in `next.config.ts`:**
-```typescript
-const nextConfig: NextConfig = {
-  experimental: {
-    turbo: undefined, // Disable Turbopack
-  },
-};
-```
-
-**Why?** Next.js 16 uses Turbopack by default, which has limited symlink support. Webpack handles symlinks better for local development. Production builds always use Webpack, so there's no production impact.
+Production builds use Webpack; this mainly affects local dev with symlinks.
 
-See [instructions.md](./instructions.md) for more troubleshooting tips.
+More tips: [instructions.md](./instructions.md).
 
 ## Features
 
-- ✨ **Enhanced UI Components** - Button, Checkbox, RadioGroup, Separator, ScrollArea with additional variants
-- 🎨 **Custom Components** - ColorPicker, Rating, TableOfContents
-- 🛠️ **Debug Tools** - Development tools for inspecting and testing components
-- 🎯 **TypeScript** - Full TypeScript support with exported types
-- ♿ **Accessible** - Built on Radix UI primitives for accessibility
-- 🎨 **Themable** - CSS variables for easy theming
-- 📦 **Tree-shakeable** - Import only what you need
+- **UI components** — Buttons, forms, layout, data display, overlays, with consistent variants
+- **Custom components** — e.g. ColorPicker, Rating, TableOfContents
+- **Debug tools** — optional `DebugPanel` in development
+- **TypeScript** — exported types
+- **Accessible** — Radix UI primitives
+- **Theming** — CSS variables
+- **Tree-shakeable** — import only what you use
 
 ## Documentation
 
-- [Installation Guide](./INSTALLATION.md) - Detailed setup instructions
-- [Debug Tools](./src/components/debug/README.md) - Debug panel documentation
-- [AGENTS.md](./AGENTS.md) - Development guidelines for contributors
-
-## Development
+- [INSTALLATION.md](./INSTALLATION.md) — CSS setup, CLI details, monorepos
+- [Debug tools](./src/components/debug/README.md) — debug panel
+- [CHANGELOG.md](./CHANGELOG.md) — release history
 
-For contributors:
+## Publishing (maintainers)
 
-```bash
-# Install dependencies
-npm install
-
-# Run dev server (showcase app)
-npm run dev
-
-# Build library
-npm run build:lib
-
-# Build showcase app
-npm run build:app
-
-# Lint
-npm run lint
-```
-
-## Publishing
-
-For maintainers:
-
-**Publish to npmjs.com (recommended):**
 ```bash
 npm version patch|minor|major
 npm run publish:npm
 ```
 
-**Publish to GitHub Packages:**
-```bash
-npm version patch|minor|major
-npm run publish:github
-```
-
-**Publish to both:**
-```bash
-npm version patch|minor|major
-npm run publish:both
-```
+GitHub Packages: `npm run publish:github`. Both: `npm run publish:both`.
 
-See [PUBLISHING.md](./PUBLISHING.md) for detailed instructions.
+Details: [docs/internal-notes/PUBLISHING.md](./docs/internal-notes/PUBLISHING.md).
 
 ## License