@nqlib/nqui 0.4.0 → 0.4.2

package/scripts/examples/vite-main.tsx

@@ -0,0 +1,17 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { ThemeProvider } from "next-themes";
+import { BrowserRouter } from "react-router-dom";
+import "./index.css";
+import App from "./App";
+// Required dependencies: npm install @nqlib/nqui tw-animate-css next-themes hugeicons-core-free-icons hugeicons-react react-router-dom
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <ThemeProvider attribute="class" defaultTheme="system" enableSystem disableTransitionOnChange>
+      <BrowserRouter>
+        <App />
+      </BrowserRouter>
+    </ThemeProvider>
+  </StrictMode>
+);

package/scripts/examples.js

@@ -7,7 +7,7 @@ import { askQuestion } from './wizard.js';
 /**
  * Copy Next.js example files to user's project
  */
-export async function copyNextJsExamples(framework, { force }) {
+export async function copyNextJsExamples(framework, { force, sidebar }) {
   if (framework !== 'nextjs') {
     return;
   }
@@ -21,9 +21,95 @@ export async function copyNextJsExamples(framework, { force }) {
     ? join(cwd, 'src', 'app')
     : join(cwd, 'app');
 
+  // Choose examples based on sidebar flag
+  const examples = sidebar
+    ? [
+        { src: 'nextjs-page-sidebar.tsx', dest: join(appDir, 'page.tsx'), name: 'page.tsx' },
+        { src: 'nextjs-layout-sidebar.tsx', dest: join(appDir, 'layout.tsx'), name: 'layout.tsx' },
+      ]
+    : [
+        { src: 'nextjs-page.tsx', dest: join(appDir, 'page.tsx'), name: 'page.tsx' },
+        { src: 'nextjs-layout.tsx', dest: join(appDir, 'layout.tsx'), name: 'layout.tsx' },
+      ];
+
+  const copied = [];
+  const existing = [];
+
+  // Check which files exist
+  for (const { dest, name } of examples) {
+    if (existsSync(dest)) {
+      existing.push({ dest, name });
+    }
+  }
+
+  // Ask about overwriting if files exist and force is not set
+  let shouldOverwrite = force;
+  if (existing.length > 0 && !force) {
+    const fileList = existing.map(e => e.name).join(' and ');
+    const answer = await askQuestion(
+      `\n⚠️  ${fileList} already exist(s). Overwrite? (y/n): `
+    );
+    shouldOverwrite = answer === 'y';
+  }
+
+  for (const { src, dest, name } of examples) {
+    const srcPath = join(examplesDir, src);
+
+    if (!existsSync(srcPath)) {
+      console.warn(`⚠️  Example file not found: ${srcPath}`);
+      continue;
+    }
+
+    if (existsSync(dest) && !shouldOverwrite) {
+      console.log(`⏭️  Skipped: ${dest} (already exists)`);
+      continue;
+    }
+
+    const content = readFileSync(srcPath, 'utf8');
+    writeFileSync(dest, content, 'utf8');
+    copied.push(dest);
+    console.log(`✅ ${existsSync(dest) && shouldOverwrite ? 'Overwritten' : 'Created'}: ${dest}`);
+  }
+
+  if (copied.length > 0) {
+    const deps = sidebar
+      ? 'npm install @nqlib/nqui @hugeicons/react @hugeicons/core-free-icons tw-animate-css next-themes react-router-dom'
+      : 'npm install @nqlib/nqui tw-animate-css next-themes';
+    console.log(`\n📝 Required dependencies for example files:`);
+    console.log(`   ${deps}\n`);
+    if (sidebar) {
+      console.log(`   Note: 3-column layout uses Sidebar, TableOfContents; main.tsx includes ThemeProvider + BrowserRouter for Vite.\n`);
+    }
+  }
+
+  return copied;
+}
+
+/**
+ * Copy Vite example files to user's project
+ */
+export async function copyViteExamples(framework, { force, sidebar }) {
+  if (framework !== 'vite') {
+    return;
+  }
+
+  const root = getPackageRoot();
+  const examplesDir = join(root, 'scripts', 'examples');
+  const cwd = process.cwd();
+
+  // Determine src directory
+  const srcDir = existsSync(join(cwd, 'src')) ? join(cwd, 'src') : join(cwd, 'src');
+  
+  // Ensure src directory exists
+  if (!existsSync(srcDir)) {
+    console.warn('⚠️  src directory not found');
+    return;
+  }
+
+  // Choose examples based on sidebar flag (3-column with TOC when sidebar; same files + main for ThemeProvider)
   const examples = [
-    { src: 'nextjs-page.tsx', dest: join(appDir, 'page.tsx'), name: 'page.tsx' },
-    { src: 'nextjs-layout.tsx', dest: join(appDir, 'layout.tsx'), name: 'layout.tsx' },
+    { src: 'vite-app.tsx', dest: join(srcDir, 'App.tsx'), name: 'App.tsx' },
+    { src: 'vite-main.tsx', dest: join(srcDir, 'main.tsx'), name: 'main.tsx' },
   ];
 
   const copied = [];
@@ -66,11 +152,11 @@ export async function copyNextJsExamples(framework, { force }) {
   }
 
   if (copied.length > 0) {
+    const deps = 'npm install @nqlib/nqui tw-animate-css next-themes @hugeicons/react @hugeicons/core-free-icons react-router-dom';
     console.log(`\n📝 Required dependencies for example files:`);
-    console.log(`   npm install @nqlib/nqui tw-animate-css next-themes\n`);
-    console.log(`   Make sure your globals.css includes the setup from nqui/nqui-setup.css\n`);
+    console.log(`   ${deps}`);
+    console.log(`   Note: For Vite, wrap your app with ThemeProvider and BrowserRouter in main.tsx\n`);
   }
 
   return copied;
 }
-

package/scripts/generate-docs.js

@@ -0,0 +1,169 @@
+/**
+ * Generates downloadable documentation files for nqui.
+ * 
+ * Outputs:
+ * - INSTALL.md: Installation instructions
+ * - COMPONENTS.md: All component documentation bundled
+ * 
+ * Usage:
+ *   node scripts/generate-docs.js
+ *   node scripts/generate-docs.js --install
+ *   node scripts/generate-docs.js --components
+ */
+
+import { readFileSync, writeFileSync, readdirSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DOCS_DIR = join(__dirname, '../docs');
+const OUTPUT_DIR = join(__dirname, '../dist/docs');
+
+// Ensure output directory exists
+import { mkdirSync, rmSync } from 'fs';
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+function readDoc(filePath) {
+  try {
+    return readFileSync(filePath, 'utf-8');
+  } catch (e) {
+    return null;
+  }
+}
+
+function generateInstallDoc() {
+  const installPath = join(DOCS_DIR, 'internal-notes/INSTALLATION.md');
+  let content = readDoc(installPath);
+  
+  if (!content) {
+    console.error('Could not find INSTALLATION.md');
+    return null;
+  }
+  
+  // Add header
+  const header = `# @nqlib/nqui Installation Guide
+
+> Generated for LLM consumption. Use this file to understand how to install and set up nqui.
+
+`;
+  
+  return header + content;
+}
+
+function generateComponentsDoc() {
+  // Read the main README for shared conventions
+  const readmePath = join(DOCS_DIR, 'components/README.md');
+  let readmeContent = readDoc(readmePath);
+  
+  if (!readmeContent) {
+    console.error('Could not find README.md');
+    return null;
+  }
+  
+  // Extract sections from README that are useful for implementation
+  // (Prerequisites, Shared Conventions, When to Use tables)
+  const sectionsToKeep = [
+    '# nqui Component Instructions',
+    '## Prerequisites',
+    '## Shared Conventions',
+    '## When to Use',
+    '## AI Implementation Checklist'
+  ];
+  
+  // Build the content
+  let content = `# @nqlib/nqui Component Reference
+
+> Generated for LLM consumption. Use this file when implementing nqui components.
+
+**Import:** \`import { X } from "@nqlib/nqui"\`  
+**CSS:** \`@import "@nqlib/nqui/styles"\` (via \`npx @nqlib/nqui init-css\`)
+
+---
+
+`;
+  
+  // Add the main sections from README
+  let currentSection = '';
+  const lines = readmeContent.split('\n');
+  
+  for (const line of lines) {
+    // Track current section
+    if (line.startsWith('##')) {
+      currentSection = line;
+    }
+    
+    // Keep specific sections
+    if (sectionsToKeep.some(s => line.includes(s) || currentSection.includes(s.replace('## ', '').replace('# ', '')))) {
+      content += line + '\n';
+    }
+  }
+  
+  // Add component docs
+  content += '\n---\n\n## Component Documentation\n\n';
+  
+  const componentsDir = join(DOCS_DIR, 'components');
+  const files = readdirSync(componentsDir)
+    .filter(f => f.startsWith('nqui-') && f.endsWith('.md'))
+    .sort();
+  
+  for (const file of files) {
+    const componentPath = join(componentsDir, file);
+    const componentContent = readDoc(componentPath);
+    
+    if (componentContent) {
+      // Extract the relevant part (without frontmatter if present)
+      let docContent = componentContent;
+      
+      // Remove frontmatter
+      if (docContent.startsWith('---')) {
+        const endOfFm = docContent.indexOf('---', 3);
+        if (endOfFm !== -1) {
+          docContent = docContent.substring(endOfFm + 3);
+        }
+      }
+      
+      // Clean up and add
+      docContent = docContent.trim();
+      content += docContent + '\n\n---\n\n';
+    }
+  }
+  
+  return content;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const generateInstall = args.includes('--install') || args.length === 0;
+  const generateComponents = args.includes('--components') || args.length === 0;
+  
+  ensureDir(OUTPUT_DIR);
+  
+  console.log('Generating nqui documentation...\n');
+  
+  if (generateInstall) {
+    const installDoc = generateInstallDoc();
+    if (installDoc) {
+      const outputPath = join(OUTPUT_DIR, 'INSTALL.md');
+      writeFileSync(outputPath, installDoc);
+      console.log(`Generated: ${outputPath}`);
+    }
+  }
+  
+  if (generateComponents) {
+    const componentsDoc = generateComponentsDoc();
+    if (componentsDoc) {
+      const outputPath = join(OUTPUT_DIR, 'COMPONENTS.md');
+      writeFileSync(outputPath, componentsDoc);
+      console.log(`Generated: ${outputPath}`);
+    }
+  }
+  
+  console.log('\nDone!');
+}
+
+main();

package/scripts/init-css.js

@@ -16,12 +16,12 @@ import { runPipeline } from './pipeline/index.js';
 import { wizard, askAboutExamples } from './wizard.js';
 import { detectFramework, findMainCssFile } from './framework.js';
 import { generateSetupContent } from './setup-helper.js';
-import { copyNextJsExamples } from './examples.js';
+import { copyNextJsExamples, copyViteExamples } from './examples.js';
 import { emit } from './pipeline/emit.js';
 
 // Guard: if first arg is a subcommand, user has old package (main bin was init-css). Redirect.
 const firstArg = process.argv[2];
-const subcommands = ['init-cursor', 'install-peers', 'init-debug', 'init-debug-css', 'setup'];
+const subcommands = ['init-cursor', 'init-skills', 'install-peers', 'init-debug', 'init-debug-css', 'setup'];
 if (subcommands.includes(firstArg)) {
   console.error(`
 ❌ Outdated @nqlib/nqui — "npx @nqlib/nqui ${firstArg}" routed to init-css.
@@ -29,17 +29,17 @@ if (subcommands.includes(firstArg)) {
    Fix: npm install @nqlib/nqui@latest
    Then: npx @nqlib/nqui ${firstArg}
 
-   Or run the binary directly: npm exec nqui-init-cursor
+   Or run the binary directly: npm exec nqui-init-skills (for init-skills), etc.
 `);
   process.exit(1);
 }
 
-// Filter out command names from argv
-const commandNames = ['init-css', 'nqui', 'nqui-init-css'];
+// Filter out command names from argv (so they are never used as output path)
+const commandNames = ['init-css', 'init-skills', 'nqui', 'nqui-init-css'];
 const filteredArgs = process.argv.slice(2).filter(arg => !commandNames.includes(arg));
 
 const args = minimist(filteredArgs, {
-  boolean: ['js', 'tokens-only', 'force', 'dry-run', 'wizard', 'setup', 'help', 'version', 'local-copy'],
+  boolean: ['js', 'tokens-only', 'force', 'dry-run', 'wizard', 'setup', 'help', 'version', 'local-copy', 'sidebar'],
   alias: { h: 'help', v: 'version' },
 });
 
@@ -55,7 +55,11 @@ if (args.version) {
   process.exit(0);
 }
 
-const output = args._[0] || 'nqui/index.css';
+// Prevent subcommand names or bare filenames from becoming output path (would e.g. create init-skills or root nqui-setup.css)
+const rawOutput = args._[0] || 'nqui/index.css';
+const output = !rawOutput || rawOutput === 'init-skills' || rawOutput === 'init-cursor' || !dirname(rawOutput)
+  ? 'nqui/index.css'
+  : rawOutput;
 
 /**
  * Generate index.css that imports from library package
@@ -101,29 +105,45 @@ function generateIndexCssContent() {
       });
     }
 
-    // Generate setup helper file (always, unless dry-run)
+    // Generate setup helper file (always, unless dry-run). Always under nqui/ to avoid writing to project root.
     if (!args['dry-run'] && (args.setup || !args['tokens-only'])) {
       const setupContent = generateSetupContent(framework, output, useLibraryImport);
-      const setupPath = resolve(process.cwd(), dirname(output), 'nqui-setup.css');
+      const setupDir = dirname(output) || 'nqui';
+      const setupPath = resolve(process.cwd(), setupDir, 'nqui-setup.css');
       emit(setupPath, setupContent, { force: args.force, dryRun: false });
 
       const mainCssFile = findMainCssFile(framework);
 
       console.log(`\n📝 Next steps:`);
-      console.log(`   1. Copy the contents of ${dirname(output)}/nqui-setup.css`);
+      console.log(`   1. Copy the contents of ${setupDir}/nqui-setup.css`);
       console.log(`   2. Paste them at the VERY TOP of your main CSS file`);
       console.log(`      (e.g. ${mainCssFile})\n`);
     }
 
-    // Ask about copying examples (if not in wizard mode, ask for Next.js projects)
+    // Copy examples: when --sidebar and --force, auto-enable so nqui:init is non-interactive
     let shouldCopyExamples = wiz.copyExamples;
-    if (!args['dry-run'] && !shouldCopyExamples && framework === 'nextjs' && !args.wizard) {
-      shouldCopyExamples = await askAboutExamples(framework);
+    let useSidebar = wiz.sidebarLayout || args.sidebar;
+    if (!args.wizard && (framework === 'nextjs' || framework === 'vite')) {
+      if (args.sidebar && args.force) {
+        shouldCopyExamples = true;
+        useSidebar = true;
+      } else if (!args['dry-run'] && !shouldCopyExamples) {
+        shouldCopyExamples = await askAboutExamples(framework, useSidebar);
+        if (shouldCopyExamples) {
+          const sidebarAnswer = await askQuestion('\n🎨 Use sidebar layout (recommended for apps)? (y/n): ');
+          useSidebar = sidebarAnswer === 'y' || sidebarAnswer === 'yes';
+        }
+      }
     }
 
     // Copy example files if requested
     if (!args['dry-run'] && shouldCopyExamples) {
-      const copied = await copyNextJsExamples(framework, { force: args.force });
+      let copied;
+      if (framework === 'nextjs') {
+        copied = await copyNextJsExamples(framework, { force: args.force, sidebar: useSidebar });
+      } else if (framework === 'vite') {
+        copied = await copyViteExamples(framework, { force: args.force, sidebar: useSidebar });
+      }
       if (copied && copied.length === 0) {
         // Files were skipped (user said no to overwrite)
         console.log('\n⏭️  Example files skipped. Run with --force to overwrite existing files.\n');

package/scripts/init-cursor.js

@@ -13,6 +13,7 @@ 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';
+import { downloadSkills } from './download-skills.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const cwd = process.cwd();
@@ -153,12 +154,19 @@ function main() {
   }
 
   writeCursorRule(targetDir);
+  
+  // Also download nqui-skills to user's .cursor folder
+  console.log('\n📚 Downloading nqui-skills...');
+  downloadSkills({ force: false });
+
   console.log(`
 ✅ Cursor rules + skills installed
 
    ${displayPath}/.cursor/rules/nqui-components.mdc
    ${displayPath}/.cursor/skills/nqui-install/
    ${displayPath}/.cursor/skills/nqui-components/
+   ${displayPath}/.cursor/nqui-skills/
+   ${displayPath}/AGENTS.md
 
    Open this folder in Cursor for skills to work. Docs: node_modules/@nqlib/nqui/docs/components/
 `);

package/scripts/post-install.js

@@ -7,7 +7,7 @@
  * Auto-injects Cursor rules so consumers don't need to remember init-cursor.
  */
 
-import { existsSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { resolve } from 'path';
 
 // Skip in CI to reduce noise
@@ -36,6 +36,31 @@ function getInstallCmd(pkgs) {
   }
 }
 
+function addNquiInitScript() {
+  const cwd = process.cwd();
+  const packageJsonPath = resolve(cwd, 'package.json');
+  
+  if (!existsSync(packageJsonPath)) return false;
+  
+  try {
+    const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    
+    // Check if script already exists
+    if (pkg.scripts?.['nqui:init']) {
+      return false; // Already exists
+    }
+    
+    // Add the script
+    pkg.scripts = pkg.scripts || {};
+    pkg.scripts['nqui:init'] = 'npx @nqlib/nqui install-peers && npx @nqlib/nqui init-cursor && npx @nqlib/nqui init-skills && npx @nqlib/nqui init-css --sidebar --force';
+    
+    writeFileSync(packageJsonPath, JSON.stringify(pkg, null, 2) + '\n');
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
 import { FULL_PEER_LIST } from './peer-deps.js';
 import { writeCursorRule } from './init-cursor.js';
 import { resolveTargetDir } from './resolve-target-dir.js';
@@ -47,21 +72,28 @@ const installRequired = getInstallCmd(requiredPeers);
 const installFull = getInstallCmd(['@nqlib/nqui', ...FULL_PEER_LIST]);
 const installRecommended = getInstallCmd(recommended);
 
+// Auto-add nqui:init script to package.json
+const scriptAdded = addNquiInitScript();
+
 const msg = `
 ╔══════════════════════════════════════════════════════════════════╗
-║  nqui – Next steps                                               ║
+║  nqui – Next steps                                           ║
 ╚══════════════════════════════════════════════════════════════════╝
 
-1. Set up CSS (required)
-   npx @nqlib/nqui init-css
+${scriptAdded ? '✅ Added "nqui:init" script to package.json\n' : ''}Run the full setup:
+
+   npm run nqui:init
 
-2. Install peers: ${installRequired}
-   Full: npx @nqlib/nqui install-peers
+Or step by step:
 
-3. Optional: tw-animate-css, next-themes
+   npx @nqlib/nqui init-css --sidebar      # CSS + sidebar layout
+   npx @nqlib/nqui install-peers          # Install dependencies
+   npx @nqlib/nqui init-cursor            # Setup Cursor skills
 
-4. Cursor skills: auto-injected. Open this folder in Cursor.
-   Refresh: npx @nqlib/nqui init-cursor
+Manual commands:
+   - Install peers: ${installRequired}
+   - Full peers: npx @nqlib/nqui install-peers
+   - Refresh skills: npx @nqlib/nqui init-skills
 
 → Run "npx nqui-setup" anytime to see this again.
 `;

package/scripts/resolve-target-dir.js

@@ -59,11 +59,24 @@ function getWorkspacePackageDirs(workspaceRoot) {
 }
 
 function isNquiSourceDir(dir) {
+  // Must NOT be inside node_modules (that means we're installed as a dep, not dev source)
+  if (resolve(dir).includes('node_modules')) return false;
   return existsSync(resolve(dir, 'docs/components/README.md')) &&
     existsSync(resolve(dir, 'package.json')) &&
     readFileSync(resolve(dir, 'package.json'), 'utf8').includes('"name": "@nqlib/nqui"');
 }
 
+function findProjectRootFromNodeModules(startDir) {
+  let dir = resolve(startDir);
+  for (let i = 0; i < 20; i++) {
+    if (existsSync(resolve(dir, 'node_modules/@nqlib/nqui'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
 /**
  * Returns the directory where .cursor/ should be written.
  * Prefers a dir with node_modules/@nqlib/nqui so docs path resolves.
@@ -72,7 +85,13 @@ function isNquiSourceDir(dir) {
  * @returns {string} Absolute path to target directory
  */
 export function resolveTargetDir(startDir) {
-  const cwd = resolve(startDir);
+  let cwd = resolve(startDir);
+
+  // 0. Running from node_modules (postinstall as dep) -> use host project root
+  if (cwd.includes('node_modules')) {
+    const projectRoot = findProjectRootFromNodeModules(cwd);
+    if (projectRoot) return projectRoot;
+  }
 
   // 1. Current dir has nqui in node_modules -> use it
   if (hasNquiInNodeModules(cwd)) return cwd;

package/scripts/wizard.js

@@ -35,23 +35,28 @@ export async function wizard() {
 
   const framework = detectFramework();
   let copyExamples = false;
+  let sidebarLayout = false;
 
-  if (framework === 'nextjs') {
-    copyExamples = (await ask('\nCopy Next.js example files (page.tsx, layout.tsx)? (y/n): ')) === 'y';
+  if (framework === 'nextjs' || framework === 'vite') {
+    copyExamples = (await ask(`\nCopy ${framework} example files? (y/n): `)) === 'y';
+    if (copyExamples) {
+      sidebarLayout = (await ask('\nUse sidebar layout (recommended for apps)? (y/n): ')) === 'y';
+    }
   }
 
-  return { tokensOnly, js, copyExamples };
+  return { tokensOnly, js, copyExamples, sidebarLayout };
 }
 
 /**
- * Ask about copying examples (used in default mode for Next.js)
+ * Ask about copying examples (used in default mode)
  */
-export async function askAboutExamples(framework) {
-  if (framework !== 'nextjs') {
+export async function askAboutExamples(framework, useSidebar = false) {
+  if (framework !== 'nextjs' && framework !== 'vite') {
     return false;
   }
 
-  const answer = await askQuestion('\n📦 Copy Next.js example files (page.tsx, layout.tsx)? (y/n): ');
+  const layoutType = useSidebar ? 'sidebar' : 'basic';
+  const answer = await askQuestion(`\n📦 Copy ${framework} example files (${layoutType} layout)? (y/n): `);
   return answer === 'y' || answer === 'yes';
 }