@nqlib/nqui 0.5.2 → 0.5.4

package/dist/styles.css

@@ -792,14 +792,11 @@
    nqui Additional System Variables
    ============================================ */
 
-/*
- * Non-dark surfaces: /* ============================================
+/* Default light theme variables (.mid / .dark blocks follow) */
+/* ============================================
    nqui Color System & Design Tokens
    ============================================ */
 
-:root + html.light = warm paper; html.mid = separate token block (showcase / comparison).
- * Dark = .dark. Showcase app uses next-themes classes light | mid | dark.
- */
 :root {
     /* ============================================
        Z-Index Elevation Scale
@@ -1205,9 +1202,4 @@
     --sidebar-accent-foreground: oklch(0.92 0 0);
     --sidebar-border: oklch(1 0 0 / 10%);
     --sidebar-ring: oklch(0.556 0 0);
-}
-
-/*
- * html.light — next-themes; surface tokens match :root (warm paper).
- * html.mid — next-themes; surfaces use .mid block above (distinct from light).
- */
+}

package/docs/nqui-skills/SKILL.md

@@ -1,8 +1,7 @@
 ---
-
-## name: nqui
-
+name: nqui
 description: Hub for nqui component library skills and impeccable design skills. Use /nqui-components, /nqui-design-system, /impeccable, /audit, or specific skill names to invoke them.
+---
 
 # nqui Skills (Hub)
 
@@ -14,7 +13,6 @@ Installed into `.cursor/nqui-skills/` via `npx @nqlib/nqui init-skills`.
 
 ## nqui Component Library
 
-
 | Skill                           | When to use                                                        |
 | ------------------------------- | ------------------------------------------------------------------ |
 | **nqui-components**             | Implementing UI, choosing components, component props and examples |
@@ -24,14 +22,12 @@ Installed into `.cursor/nqui-skills/` via `npx @nqlib/nqui init-skills`.
 | **nqui-bundle-size**            | Bundle size best practices when adding deps or creating packages   |
 | **nqui-local-published-toggle** | Switching between local and published @nqlib/nqui                  |
 
-
 ---
 
 ## Impeccable Design Skills
 
 Design quality and anti-pattern detection. Run `/impeccable teach` first to establish design context.
 
-
 | Skill          | When to use                                                                   |
 | -------------- | ----------------------------------------------------------------------------- |
 | **impeccable** | Build distinctive, production-grade UI; avoid AI slop aesthetics              |
@@ -52,7 +48,6 @@ Design quality and anti-pattern detection. Run `/impeccable teach` first to esta
 | **/critique**  | Heuristic-based UI review                                                     |
 | **/overdrive** | Push good UI to excellent                                                     |
 
-
 ---
 
 ## Usage
@@ -62,4 +57,4 @@ Skills are invoked by name — e.g. `/nqui-components`, `/impeccable`, `/audit i
 For component questions, always read the relevant doc first:
 
 - `.cursor/nqui-skills/components/nqui-<name>.md` (after init-skills)
-- `node_modules/@nqlib/nqui/docs/components/nqui-<name>.md` (npm install)
+- `node_modules/@nqlib/nqui/docs/components/nqui-<name>.md` (npm install)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nqlib/nqui",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "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/publish-npmjs.js

@@ -6,7 +6,7 @@
  */
 
 import { readFileSync, writeFileSync, existsSync } from 'fs';
-import { execSync } from 'child_process';
+import { execSync, spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 
@@ -16,116 +16,164 @@ const rootDir = join(__dirname, '..');
 const packageJsonPath = join(rootDir, 'package.json');
 const npmrcPath = join(rootDir, '.npmrc');
 
-// Read package.json
-const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+function printSslTroubleshooting() {
+  console.error(`
+💡 TLS / network (e.g. ERR_SSL_SSL\\TLS_ALERT_BAD_RECORD_MAC) is usually environmental:
+   • Run publish again; transient failures often work on a second attempt
+   • Disable VPN or try another network; corporate proxies and inspection break TLS
+   • Update Node LTS; ensure no antivirus is MITM’ing npm traffic
+   • Retry later if registry.npmjs.com is flaking
+   • Set NPM_PUBLISH_RETRIES=5 for more attempts (default 3)
+`);
+}
 
-// Save originals for restore
-const originalPublishConfig = packageJson.publishConfig;
-const originalDependencies = { ...packageJson.dependencies };
+async function main() {
+  // Read package.json
+  const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
 
-// 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)`);
-  }
-}
+  // Save originals for restore
+  const originalPublishConfig = packageJson.publishConfig;
+  const originalDependencies = { ...packageJson.dependencies };
 
-// Override publishConfig for npmjs.com
-packageJson.publishConfig = {
-  registry: 'https://registry.npmjs.com',
-  access: 'public'
-};
-
-// Write modified package.json
-writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n');
-
-// Handle .npmrc file if it exists
-let originalNpmrc = null;
-let npmrcExists = false;
-
-if (existsSync(npmrcPath)) {
-  npmrcExists = true;
-  originalNpmrc = readFileSync(npmrcPath, 'utf-8');
-
-  // Remove or comment out scoped registry line that points to GitHub Packages
-  const lines = originalNpmrc.split('\n');
-  const modifiedLines = lines.map(line => {
-    // Comment out scoped registry lines for @nqlib
-    if (line.trim().startsWith('@nqlib:registry=')) {
-      return `# ${line} # Temporarily disabled for npmjs.com publish`;
+  // Remove workspace:* deps (npm doesn't support workspace: protocol).
+  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)`);
     }
-    return line;
-  });
+  }
 
-  writeFileSync(npmrcPath, modifiedLines.join('\n'));
-  console.log('📝 Temporarily modified .npmrc');
-}
+  packageJson.publishConfig = {
+    registry: 'https://registry.npmjs.com',
+    access: 'public',
+  };
 
-try {
-  // Check if user is logged in to npm
-  console.log('🔐 Checking npm authentication...');
-  try {
-    const whoami = execSync('npm whoami --registry=https://registry.npmjs.com', {
-      encoding: 'utf-8',
-      cwd: rootDir,
-      env: {
-        ...process.env,
-        npm_config_registry: 'https://registry.npmjs.com'
+  writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n');
+
+  let originalNpmrc = null;
+  let npmrcExists = false;
+
+  if (existsSync(npmrcPath)) {
+    npmrcExists = true;
+    originalNpmrc = readFileSync(npmrcPath, 'utf-8');
+    const lines = originalNpmrc.split('\n');
+    const modifiedLines = lines.map((line) => {
+      if (line.trim().startsWith('@nqlib:registry=')) {
+        return `# ${line} # Temporarily disabled for npmjs.com publish`;
       }
-    }).trim();
-    console.log(`✅ Logged in as: ${whoami}`);
-  } catch (authError) {
-    console.error('❌ Not logged in to npmjs.com');
-    console.error('💡 Please run: npm login --registry=https://registry.npmjs.com');
-    console.error('💡 Or create an access token at: https://www.npmjs.com/settings/YOUR_USERNAME/tokens');
-    throw new Error('Authentication required. Please login to npmjs.com first.');
+      return line;
+    });
+    writeFileSync(npmrcPath, modifiedLines.join('\n'));
+    console.log('📝 Temporarily modified .npmrc');
   }
 
-  console.log('📦 Publishing to npmjs.com...');
-  execSync('npm publish --registry=https://registry.npmjs.com --access=public', {
-    stdio: 'inherit',
-    cwd: rootDir,
-    env: {
+  try {
+    console.log('🔐 Checking npm authentication...');
+    try {
+      const whoami = execSync('npm whoami --registry=https://registry.npmjs.com', {
+        encoding: 'utf-8',
+        cwd: rootDir,
+        env: {
+          ...process.env,
+          npm_config_registry: 'https://registry.npmjs.com',
+        },
+      }).trim();
+      console.log(`✅ Logged in as: ${whoami}`);
+    } catch {
+      console.error('❌ Not logged in to npmjs.com');
+      console.error('💡 Please run: npm login --registry=https://registry.npmjs.com');
+      console.error(
+        '💡 Or create an access token at: https://www.npmjs.com/settings/YOUR_USERNAME/tokens'
+      );
+      throw new Error('Authentication required. Please login to npmjs.com first.');
+    }
+
+    const publishEnv = {
       ...process.env,
-      // Force npm to use npmjs.com registry
-      npm_config_registry: 'https://registry.npmjs.com'
+      npm_config_registry: 'https://registry.npmjs.com',
+    };
+
+    const maxAttempts = Math.min(
+      5,
+      Math.max(1, parseInt(process.env.NPM_PUBLISH_RETRIES || '3', 10) || 3)
+    );
+
+    const runPublish = () =>
+      new Promise((resolve, reject) => {
+        const child = spawn(
+          'npm',
+          ['publish', '--registry=https://registry.npmjs.com', '--access', 'public'],
+          { stdio: 'inherit', cwd: rootDir, env: publishEnv, shell: false }
+        );
+        child.on('error', reject);
+        child.on('close', (code) => {
+          if (code === 0) resolve();
+          else {
+            const err = new Error(`npm publish exited with code ${code}`);
+            err.status = code;
+            reject(err);
+          }
+        });
+      });
+
+    console.log('📦 Publishing to npmjs.com...');
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        await runPublish();
+        lastError = null;
+        break;
+      } catch (e) {
+        lastError = e;
+        if (attempt < maxAttempts) {
+          const wait = attempt * 2000;
+          console.warn(
+            `⚠️  Publish failed (attempt ${attempt}/${maxAttempts}). Retrying in ${wait / 1000}s (transient TLS/network often succeeds on retry)…`
+          );
+          await new Promise((r) => setTimeout(r, wait));
+        }
+      }
     }
-  });
-  console.log('✅ Published to npmjs.com successfully!');
-} catch (error) {
-  console.error('❌ Failed to publish to npmjs.com');
-  if (error.message && error.message.includes('Authentication required')) {
+    if (lastError) throw lastError;
+    console.log('✅ Published to npmjs.com successfully!');
+  } catch (error) {
+    console.error('❌ Failed to publish to npmjs.com');
+    if (error.message && error.message.includes('Authentication required')) {
+      throw error;
+    }
+    const errText = `${error.message || ''} ${(error.output && error.output.toString()) || ''}`;
+    if (error.status === 404 || errText.includes('404')) {
+      console.error('💡 Package not found. This might be the first publish.');
+      console.error('💡 Make sure the @nqlib scope exists on npmjs.com');
+      console.error('💡 For scoped packages, you need to own the scope or be added to it');
+    }
+    if (error.status === 401 || errText.includes('401')) {
+      console.error(
+        '💡 Authentication failed. Please login: npm login --registry=https://registry.npmjs.com'
+      );
+    }
+    printSslTroubleshooting();
     throw error;
-  }
-  if (error.status === 404 || (error.output && error.output.toString().includes('404'))) {
-    console.error('💡 Package not found. This might be the first publish.');
-    console.error('💡 Make sure the @nqlib scope exists on npmjs.com');
-    console.error('💡 For scoped packages, you need to own the scope or be added to it');
-  }
-  if (error.status === 401 || (error.output && error.output.toString().includes('401'))) {
-    console.error('💡 Authentication failed. Please login: npm login --registry=https://registry.npmjs.com');
-  }
-  throw error;
-} finally {
-  // 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 package.json');
-
-  // Restore .npmrc if it existed
-  if (npmrcExists && originalNpmrc !== null) {
-    writeFileSync(npmrcPath, originalNpmrc);
-    console.log('🔄 Restored .npmrc');
+  } finally {
+    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 package.json');
+    if (npmrcExists && originalNpmrc !== null) {
+      writeFileSync(npmrcPath, originalNpmrc);
+      console.log('🔄 Restored .npmrc');
+    }
   }
 }
 
+main().catch((e) => {
+  if (e && e.message) console.error(e.message);
+  process.exit(1);
+});

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(' ')}`;