@nqlib/nqui 0.5.2 → 0.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nqlib/nqui",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "A React component library with enhanced UI components and developer tools",
   "type": "module",
   "main": "./dist/nqui.cjs.js",

package/scripts/cursor-rule-nqui-components.mdc

@@ -0,0 +1,93 @@
+---
+description: nqui component implementation guide. Use when building UI with @nqlib/nqui.
+globs: "**/*.{ts,tsx}"
+alwaysApply: false
+---
+
+# nqui Component Guidelines
+
+When building UI with @nqlib/nqui, follow these rules so the AI builds components correctly.
+
+## Install (full: nqui + all optional peers)
+
+Run this when setting up a new project or when components fail due to missing peers:
+
+```bash
+pnpm add @nqlib/nqui @hugeicons/react @hugeicons/core-free-icons cmdk @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities embla-carousel-react @tanstack/react-table react-day-picker date-fns sonner vaul react-resizable-panels
+```
+
+Alternative (npm): `npm install @nqlib/nqui @hugeicons/react @hugeicons/core-free-icons cmdk @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities embla-carousel-react @tanstack/react-table react-day-picker date-fns sonner vaul react-resizable-panels`
+
+Or use `npx @nqlib/nqui install-peers` to auto-detect package manager.
+
+## Import
+
+```tsx
+import { Button, ToggleGroup, ToggleGroupItem, Select } from "@nqlib/nqui"
+```
+
+**CSS:** `@import "@nqlib/nqui/styles"` (run `npx @nqlib/nqui init-css` first)
+
+## CSS Setup (First-Run Fix)
+
+`init-css` creates `nqui/index.css` and `nqui/nqui-setup.css` in the project root. **User must manually add the import** to their main CSS file. If nqui components render without styles or user reports "CSS import issue":
+
+1. **Check** if the main CSS file has the nqui import. Main files: `app/globals.css` (Next.js), `src/index.css` (Vite), `app/root.css` (Remix).
+
+2. **Fix options:**
+   - **Option A (recommended):** Add `@import "@nqlib/nqui/styles";` near the top of the main CSS file (after `@import "tailwindcss"`).
+   - **Option B:** If `nqui/nqui-setup.css` exists, copy its contents to the very top of the main CSS file.
+
+3. **Next.js only:** Ensure `@source` directives exist for Tailwind v4:
+   ```css
+   @source "./**/*.{js,ts,jsx,tsx,mdx}";
+   @source "../components/**/*.{js,ts,jsx,tsx,mdx}";
+   @source "../node_modules/@nqlib/nqui/dist/**/*.js";
+   ```
+
+4. **Vite:** Simpler – just `@import "tailwindcss";` + `@import "tw-animate-css";` + `@import "@nqlib/nqui/styles";`
+
+If user hasn't run init-css, suggest: `npx @nqlib/nqui init-css` then add the import as above.
+
+## Component Selection Rules
+
+### Inline/Toolbar Selection → ToggleGroup (never RadioGroup)
+
+| Context | Use | NOT |
+|---------|-----|-----|
+| View mode (List/Grid), scale (Linear/Log), size (S/M/L) | **ToggleGroup** `type="single" variant="segmented"` | RadioGroup |
+| Format toolbar (Bold/Italic/Underline) | **ToggleGroup** `type="multiple"` | Multiple Checkboxes |
+| Toolbar actions (Undo/Redo) | **ButtonGroup** | — |
+| Single on/off (Bold, Mute) | **Toggle** | — |
+
+**Rule:** Inline/toolbar = ToggleGroup. RadioGroup only for form context (settings modal, stacked list).
+
+### Quick Decision
+
+- **ToggleGroup segmented** → 1 of N, 2–4 options, primary fill on selected
+- **ToggleGroup single** → 1 of N, neutral styling
+- **ToggleGroup multiple** → 0+ of N (bold/italic)
+- **Select** → 1 of N, 5+ options or dropdown
+- **ButtonGroup** → Actions (each click = action)
+- **RadioGroup** → Form context only
+
+## Context-First Design
+
+**Rule:** Never show Toggle/ToggleGroup/ButtonGroup floating alone. Place in realistic context:
+- Document editor: toolbar above content, `bg-muted/30`, `Separator` between groups
+- Chart/settings: label + inline controls, `rounded-lg border bg-muted/30 p-3`
+
+## Shared Conventions
+
+- **Control sizes:** sm=h-6, default=h-7, lg=h-8
+- **Enhanced vs Core:** Default is enhanced. Use `CoreButton`, `CoreBadge` for plain shadcn.
+- **Z-index:** Use CSS vars only, e.g. `z-[var(--z-modal)]`. Never hardcode `z-10`, `z-50`.
+- **Grouped controls:** ButtonGroup, ToggleGroup share container border; ToggleGroup uses item dividers.
+
+## Skills (load for install or component questions)
+
+- **Install/setup:** Load `.cursor/skills/nqui-install/SKILL.md` — commands to execute
+- **Components:** Load `.cursor/skills/nqui-components/SKILL.md` — routing for per-component docs
+- **After `init-skills`:** `.cursor/nqui-skills/COMPONENTS_INDEX.md` then **one** file under `.cursor/nqui-skills/components/nqui-<name>.md`
+
+Fallback (no init-skills): `node_modules/@nqlib/nqui/docs/components/README.md` (index, skim sections) then `nqui-<name>.md`.

package/scripts/skill-templates.js

@@ -6,8 +6,30 @@
  * The skill content itself is read from the SSOT by download-skills.
  */
 
+import { readFileSync, existsSync } from 'fs';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
 import { FULL_PEER_LIST } from './peer-deps.js';
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Full body for `.cursor/rules/nqui-components.mdc` (shipped next to this file in the npm package).
+ */
+export function buildCursorRule() {
+  const shipped = resolve(__dirname, 'cursor-rule-nqui-components.mdc');
+  if (existsSync(shipped)) {
+    return readFileSync(shipped, 'utf8');
+  }
+  const monorepo = resolve(__dirname, '../.cursor/rules/nqui-components.mdc');
+  if (existsSync(monorepo)) {
+    return readFileSync(monorepo, 'utf8');
+  }
+  throw new Error(
+    'nqui: missing cursor rule template. Expected cursor-rule-nqui-components.mdc next to skill-templates.js'
+  );
+}
+
 const fullInstallCmd = `pnpm add @nqlib/nqui ${FULL_PEER_LIST.join(' ')}`;
 const npmInstallCmd = `npm install @nqlib/nqui ${FULL_PEER_LIST.join(' ')}`;