@nqlib/nqui 0.3.2 → 0.4.0

package/scripts/init-cursor.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+
+/**
+ * Injects nqui Cursor/IDE rules so AI assistants have instructions
+ * for building components correctly with @nqlib/nqui.
+ *
+ * Usage: npx nqui init-cursor
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { resolve, dirname, relative } from 'path';
+import { fileURLToPath } from 'url';
+import { FULL_PEER_LIST } from './peer-deps.js';
+import { buildInstallSkill, buildComponentsSkill } from './skill-templates.js';
+import { resolveTargetDir } from './resolve-target-dir.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cwd = process.cwd();
+const cursorDir = resolve(cwd, '.cursor');
+const rulesDir = resolve(cursorDir, 'rules');
+const rulePath = resolve(rulesDir, 'nqui-components.mdc');
+
+const fullInstallCmd = `pnpm add @nqlib/nqui ${FULL_PEER_LIST.join(' ')}`;
+const npmInstallCmd = `npm install @nqlib/nqui ${FULL_PEER_LIST.join(' ')}`;
+
+export function buildCursorRule() {
+  return `---
+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
+${fullInstallCmd}
+\`\`\`
+
+Alternative (npm): \`${npmInstallCmd}\`
+
+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\` — points to \`node_modules/@nqlib/nqui/docs/components/\`
+
+For any component question, read from \`node_modules/@nqlib/nqui/docs/components/README.md\` (index) then \`nqui-<name>.md\` (specific component).
+`;
+}
+
+export function writeCursorRule(targetCwd) {
+  const cursorDir = resolve(targetCwd, '.cursor');
+  const rulesDir = resolve(cursorDir, 'rules');
+  const skillsDir = resolve(cursorDir, 'skills');
+
+  if (!existsSync(cursorDir)) mkdirSync(cursorDir, { recursive: true });
+  if (!existsSync(rulesDir)) mkdirSync(rulesDir, { recursive: true });
+
+  writeFileSync(resolve(rulesDir, 'nqui-components.mdc'), buildCursorRule(), 'utf8');
+
+  // Inject skills for install + component docs
+  const installSkillDir = resolve(skillsDir, 'nqui-install');
+  const componentsSkillDir = resolve(skillsDir, 'nqui-components');
+  if (!existsSync(installSkillDir)) mkdirSync(installSkillDir, { recursive: true });
+  if (!existsSync(componentsSkillDir)) mkdirSync(componentsSkillDir, { recursive: true });
+
+  writeFileSync(resolve(installSkillDir, 'SKILL.md'), buildInstallSkill(), 'utf8');
+  writeFileSync(resolve(componentsSkillDir, 'SKILL.md'), buildComponentsSkill(), 'utf8');
+}
+
+function main() {
+  const targetDir = resolveTargetDir(cwd);
+  const nquiPath = resolve(targetDir, 'node_modules/@nqlib/nqui');
+  const inMonorepo = existsSync(resolve(__dirname, '../docs/components/README.md'));
+  if (!existsSync(nquiPath) && !inMonorepo) {
+    console.warn('⚠️  @nqlib/nqui not found in node_modules. Rule created; install nqui for full docs path.');
+  }
+
+  const displayPath = targetDir === cwd ? '.' : relative(cwd, targetDir) || '.';
+  if (targetDir !== cwd) {
+    console.log(`📁 Monorepo: writing to ${displayPath} (open this folder in Cursor)`);
+  }
+
+  writeCursorRule(targetDir);
+  console.log(`
+✅ Cursor rules + skills installed
+
+   ${displayPath}/.cursor/rules/nqui-components.mdc
+   ${displayPath}/.cursor/skills/nqui-install/
+   ${displayPath}/.cursor/skills/nqui-components/
+
+   Open this folder in Cursor for skills to work. Docs: node_modules/@nqlib/nqui/docs/components/
+`);
+}
+
+// Only run when executed directly (npx nqui init-cursor), not when imported
+const isMain = process.argv[1]?.includes('init-cursor');
+if (isMain) main();

package/scripts/install-peers.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+/**
+ * Installs @nqlib/nqui + all required and optional peer dependencies.
+ * Use when you want full library support (Sortable, Carousel, DataTable, etc.).
+ *
+ * Usage: npx @nqlib/nqui install-peers
+ */
+
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+import { execSync } from 'child_process';
+import { FULL_PEER_LIST } from './peer-deps.js';
+
+const cwd = process.cwd();
+
+function detectPackageManager() {
+  if (existsSync(resolve(cwd, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (existsSync(resolve(cwd, 'yarn.lock'))) return 'yarn';
+  if (existsSync(resolve(cwd, 'bun.lockb'))) return 'bun';
+  return 'npm';
+}
+
+function getInstallCmd(pkgs) {
+  const pm = detectPackageManager();
+  const list = pkgs.join(' ');
+  switch (pm) {
+    case 'pnpm':
+      return `pnpm add ${list}`;
+    case 'yarn':
+      return `yarn add ${list}`;
+    case 'bun':
+      return `bun add ${list}`;
+    default:
+      return `npm install ${list}`;
+  }
+}
+
+const pkgs = ['@nqlib/nqui', ...FULL_PEER_LIST];
+const cmd = getInstallCmd(pkgs);
+
+console.log(`\nInstalling nqui + all peer dependencies...\n  ${cmd}\n`);
+execSync(cmd, { stdio: 'inherit', cwd });

package/scripts/peer-deps.js

@@ -0,0 +1,27 @@
+/**
+ * nqui peer dependencies. Required + optional (for full library usage).
+ * Used by install-peers.js and init-cursor.js.
+ */
+
+export const REQUIRED_PEERS = [
+  '@hugeicons/react',
+  '@hugeicons/core-free-icons',
+];
+
+export const OPTIONAL_PEERS = [
+  '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',
+  '@base-ui/react',
+];
+
+export const FULL_PEER_LIST = [...REQUIRED_PEERS, ...OPTIONAL_PEERS];

package/scripts/post-install.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+/**
+ * Post-install: print next steps for nqui setup.
+ * Runs after npm/pnpm/yarn install. Also invokable via: npx nqui-setup
+ *
+ * Auto-injects Cursor rules so consumers don't need to remember init-cursor.
+ */
+
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+
+// Skip in CI to reduce noise
+if (process.env.CI === 'true' || process.env.CI === '1') process.exit(0);
+
+function detectPackageManager() {
+  const cwd = process.cwd();
+  if (existsSync(resolve(cwd, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (existsSync(resolve(cwd, 'yarn.lock'))) return 'yarn';
+  if (existsSync(resolve(cwd, 'bun.lockb'))) return 'bun';
+  return 'npm';
+}
+
+function getInstallCmd(pkgs) {
+  const pm = detectPackageManager();
+  const list = pkgs.join(' ');
+  switch (pm) {
+    case 'pnpm':
+      return `pnpm add ${list}`;
+    case 'yarn':
+      return `yarn add ${list}`;
+    case 'bun':
+      return `bun add ${list}`;
+    default:
+      return `npm install ${list}`;
+  }
+}
+
+import { FULL_PEER_LIST } from './peer-deps.js';
+import { writeCursorRule } from './init-cursor.js';
+import { resolveTargetDir } from './resolve-target-dir.js';
+
+const requiredPeers = ['@hugeicons/react', '@hugeicons/core-free-icons'];
+const recommended = ['tw-animate-css', 'next-themes'];
+
+const installRequired = getInstallCmd(requiredPeers);
+const installFull = getInstallCmd(['@nqlib/nqui', ...FULL_PEER_LIST]);
+const installRecommended = getInstallCmd(recommended);
+
+const msg = `
+╔══════════════════════════════════════════════════════════════════╗
+║  nqui – Next steps                                               ║
+╚══════════════════════════════════════════════════════════════════╝
+
+1. Set up CSS (required)
+   npx @nqlib/nqui init-css
+
+2. Install peers: ${installRequired}
+   Full: npx @nqlib/nqui install-peers
+
+3. Optional: tw-animate-css, next-themes
+
+4. Cursor skills: auto-injected. Open this folder in Cursor.
+   Refresh: npx @nqlib/nqui init-cursor
+
+→ Run "npx nqui-setup" anytime to see this again.
+`;
+console.log(msg);
+
+// Auto-inject Cursor rules (writes to package that has nqui in monorepos)
+const targetDir = resolveTargetDir(process.cwd());
+writeCursorRule(targetDir);
+console.log(`   Skills written to: ${targetDir}/.cursor/\n`);

package/scripts/publish-npmjs.js

@@ -19,8 +19,19 @@ const npmrcPath = join(rootDir, '.npmrc');
 // Read package.json
 const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
 
-// Save original publishConfig
+// Save originals for restore
 const originalPublishConfig = packageJson.publishConfig;
+const originalDependencies = { ...packageJson.dependencies };
+
+// Remove workspace:* deps (npm doesn't support workspace: protocol).
+// nqcode/nqappbuilder are dev/showcase-only and not bundled in the library.
+const workspaceDeps = ['@nqlib/nqcode', '@nqlib/nqappbuilder'];
+for (const name of workspaceDeps) {
+  if (packageJson.dependencies?.[name] === 'workspace:*') {
+    delete packageJson.dependencies[name];
+    console.log(`   Removed ${name} (workspace dep)`);
+  }
+}
 
 // Override publishConfig for npmjs.com
 packageJson.publishConfig = {
@@ -99,14 +110,17 @@ try {
   }
   throw error;
 } finally {
-  // Restore original publishConfig
+  // Restore original publishConfig and dependencies
   if (originalPublishConfig) {
     packageJson.publishConfig = originalPublishConfig;
   } else {
     delete packageJson.publishConfig;
   }
+  if (originalDependencies) {
+    packageJson.dependencies = originalDependencies;
+  }
   writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n');
-  console.log('🔄 Restored publishConfig');
+  console.log('🔄 Restored package.json');
 
   // Restore .npmrc if it existed
   if (npmrcExists && originalNpmrc !== null) {

package/scripts/resolve-target-dir.js

@@ -0,0 +1,99 @@
+/**
+ * Resolves the best directory to write .cursor/ into.
+ * Prefers a directory where node_modules/@nqlib/nqui exists (so docs path works).
+ *
+ * Used by init-cursor and post-install for monorepo support.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { resolve, dirname } from 'path';
+
+function hasNquiInNodeModules(dir) {
+  return existsSync(resolve(dir, 'node_modules/@nqlib/nqui'));
+}
+
+function hasNquiInPackageJson(dir) {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(dir, 'package.json'), 'utf8'));
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    return !!deps['@nqlib/nqui'];
+  } catch {
+    return false;
+  }
+}
+
+function findWorkspaceRoot(startDir) {
+  let dir = resolve(startDir);
+  for (let i = 0; i < 20; i++) {
+    if (existsSync(resolve(dir, 'pnpm-workspace.yaml'))) return dir;
+    const pkgPath = resolve(dir, 'package.json');
+    if (existsSync(pkgPath) && readFileSync(pkgPath, 'utf8').includes('"workspaces"')) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+function getWorkspacePackageDirs(workspaceRoot) {
+  const dirs = [];
+  const candidates = ['packages', 'apps', 'packages/*', 'apps/*'];
+  for (const base of ['packages', 'apps']) {
+    const basePath = resolve(workspaceRoot, base);
+    if (!existsSync(basePath)) continue;
+    try {
+      const entries = readdirSync(basePath, { withFileTypes: true });
+      for (const e of entries) {
+        if (e.isDirectory()) {
+          const pkgDir = resolve(basePath, e.name);
+          if (existsSync(resolve(pkgDir, 'package.json'))) {
+            dirs.push(pkgDir);
+          }
+        }
+      }
+    } catch {}
+  }
+  return dirs;
+}
+
+function isNquiSourceDir(dir) {
+  return existsSync(resolve(dir, 'docs/components/README.md')) &&
+    existsSync(resolve(dir, 'package.json')) &&
+    readFileSync(resolve(dir, 'package.json'), 'utf8').includes('"name": "@nqlib/nqui"');
+}
+
+/**
+ * Returns the directory where .cursor/ should be written.
+ * Prefers a dir with node_modules/@nqlib/nqui so docs path resolves.
+ *
+ * @param {string} startDir - Usually process.cwd()
+ * @returns {string} Absolute path to target directory
+ */
+export function resolveTargetDir(startDir) {
+  const cwd = resolve(startDir);
+
+  // 1. Current dir has nqui in node_modules -> use it
+  if (hasNquiInNodeModules(cwd)) return cwd;
+
+  // 2. Current dir is nqui source (developing the library) -> use it
+  if (isNquiSourceDir(cwd)) return cwd;
+
+  // 3. Current dir has nqui in package.json (might be hoisted) -> use it
+  if (hasNquiInPackageJson(cwd)) return cwd;
+
+  // 4. Monorepo: find a workspace package that has nqui
+  const workspaceRoot = findWorkspaceRoot(cwd);
+  if (workspaceRoot) {
+    const pkgDirs = getWorkspacePackageDirs(workspaceRoot);
+    for (const dir of pkgDirs) {
+      if (hasNquiInNodeModules(dir) || hasNquiInPackageJson(dir)) {
+        return dir;
+      }
+    }
+  }
+
+  // 5. Fallback: use cwd (rule created; docs path may need manual fix)
+  return cwd;
+}

package/scripts/skill-templates.js

@@ -0,0 +1,109 @@
+/**
+ * Skill templates injected by init-cursor into consumer projects.
+ * Paths use node_modules for consumers (package install location).
+ */
+
+import { FULL_PEER_LIST } from './peer-deps.js';
+
+const fullInstallCmd = `pnpm add @nqlib/nqui ${FULL_PEER_LIST.join(' ')}`;
+const npmInstallCmd = `npm install @nqlib/nqui ${FULL_PEER_LIST.join(' ')}`;
+
+const DOCS_PATH = 'node_modules/@nqlib/nqui/docs/components';
+
+export function buildInstallSkill() {
+  return `---
+name: nqui-install
+description: Install and setup nqui. Use when user wants to install nqui, set up project, fix missing peers, or run setup commands. Execute these commands in the project root.
+---
+
+# nqui Install & Setup
+
+**When to load:** User asks to install nqui, set up a new project, fix "module not found" or missing peer deps, or run setup.
+
+**Action:** Execute the relevant command(s) below in the project root. Run in sequence when doing full setup.
+
+## 1. Install nqui + peers
+
+**Minimal (icons only):**
+\`\`\`bash
+pnpm add @nqlib/nqui @hugeicons/react @hugeicons/core-free-icons
+\`\`\`
+(npm: \`npm install @nqlib/nqui @hugeicons/react @hugeicons/core-free-icons\`)
+
+**Full (all optional components):**
+\`\`\`bash
+npx @nqlib/nqui install-peers
+\`\`\`
+Or manually:
+\`\`\`bash
+${fullInstallCmd}
+\`\`\`
+(npm: \`${npmInstallCmd}\`)
+
+## 2. Setup CSS (required)
+
+\`\`\`bash
+npx @nqlib/nqui init-css
+\`\`\`
+
+Then add to main CSS (app/globals.css or src/index.css): \`@import "@nqlib/nqui/styles";\`
+Or copy contents of \`nqui/nqui-setup.css\` to top of main CSS.
+
+## 3. Refresh Cursor rules (optional)
+
+\`\`\`bash
+npx @nqlib/nqui init-cursor
+\`\`\`
+
+## File locations
+
+- Docs: \`${DOCS_PATH}/README.md\` (index) and \`${DOCS_PATH}/nqui-<name>.md\` (per component)
+- Check setup: \`npx nqui-setup\`
+`;
+}
+
+export function buildComponentsSkill() {
+  return `---
+name: nqui-components
+description: Component implementation for nqui. Use when building UI with @nqlib/nqui, choosing components, or implementing a specific component. Always read from docs path before implementing.
+---
+
+# nqui Components
+
+**When to load:** User asks about nqui components, which component to use, how to implement X, or builds UI with nqui.
+
+**Action:** Read from the docs path before implementing. Do not guess – the docs have exact import, props, and examples.
+
+## Documentation path (always use this)
+
+\`\`\`
+${DOCS_PATH}/
+\`\`\`
+
+## File resolution
+
+| User asks | File to read |
+|-----------|--------------|
+| Component index, use cases, which component for X | \`${DOCS_PATH}/README.md\` |
+| How to use Button | \`${DOCS_PATH}/nqui-button.md\` |
+| How to use ToggleGroup | \`${DOCS_PATH}/nqui-toggle-group.md\` |
+| Any component X | \`${DOCS_PATH}/nqui-<kebab-name>.md\` (e.g. nqui-data-table.md) |
+
+**Rule:** For any component question, read the doc first. The docs have import, variants, props, and examples.
+
+## Quick rules (details in README.md)
+
+- **Toolbar/inline selection** → ToggleGroup (never RadioGroup)
+- **Form context** → RadioGroup, Checkbox
+- **Actions** → Button, ButtonGroup
+- **Context-first:** Place controls in realistic layout (toolbar, chart settings), not floating alone
+
+## Import
+
+\`\`\`tsx
+import { Button, ToggleGroup, ToggleGroupItem } from "@nqlib/nqui"
+\`\`\`
+
+CSS: \`@import "@nqlib/nqui/styles"\` in main CSS (run \`npx @nqlib/nqui init-css\` first).
+`;
+}