@nqlib/nqui 0.4.1 → 0.4.2

package/docs/nqui-skills/rules/styling.md

@@ -0,0 +1,192 @@
+# Styling & Customization
+
+nqui uses Tailwind CSS v4 with semantic CSS variables. See customization docs for theming and CSS variables.
+
+## Contents
+
+- Semantic colors
+- Built-in variants first
+- className for layout only
+- No space-x-* / space-y-*
+- Prefer size-* over w-* h-* when equal
+- Prefer truncate shorthand
+- No manual dark: color overrides
+- Use cn() for conditional classes
+- No manual z-index on overlay components (use elevation.css)
+
+---
+
+## Semantic colors
+
+**Incorrect:**
+
+```tsx
+<div className="bg-blue-500 text-white">
+  <p className="text-gray-600">Secondary text</p>
+</div>
+```
+
+**Correct:**
+
+```tsx
+<div className="bg-primary text-primary-foreground">
+  <p className="text-muted-foreground">Secondary text</p>
+</div>
+```
+
+---
+
+## No raw color values for status/state indicators
+
+For positive, negative, or status indicators, use Badge variants, semantic tokens like `text-destructive`, or define custom CSS variables — don't reach for raw Tailwind colors.
+
+**Incorrect:**
+
+```tsx
+<span className="text-emerald-600">+20.1%</span>
+<span className="text-green-500">Active</span>
+<span className="text-red-600">-3.2%</span>
+```
+
+**Correct:**
+
+```tsx
+<Badge variant="secondary">+20.1%</Badge>
+<Badge>Active</Badge>
+<span className="text-destructive">-3.2%</span>
+```
+
+---
+
+## Built-in variants first
+
+**Incorrect:**
+
+```tsx
+<Button className="border border-input bg-transparent hover:bg-accent">
+  Click me
+</Button>
+```
+
+**Correct:**
+
+```tsx
+<Button variant="outline">Click me</Button>
+```
+
+---
+
+## className for layout only
+
+Use `className` for layout (e.g. `max-w-md`, `mx-auto`, `mt-4`), **not** for overriding component colors or typography. To change colors, use semantic tokens, built-in variants, or CSS variables.
+
+**Incorrect:**
+
+```tsx
+<Card className="bg-blue-100 text-blue-900 font-bold">
+  <CardContent>Dashboard</CardContent>
+</Card>
+```
+
+**Correct:**
+
+```tsx
+<Card className="max-w-md mx-auto">
+  <CardContent>Dashboard</CardContent>
+</Card>
+```
+
+To customize a component's appearance, prefer these approaches in order:
+1. **Built-in variants** — `variant="outline"`, `variant="destructive"`, etc.
+2. **Semantic color tokens** — `bg-primary`, `text-muted-foreground`.
+3. **CSS variables** — define custom colors in the global CSS file.
+
+---
+
+## No space-x-* / space-y-*
+
+Use `gap-*` instead. `space-y-4` → `flex flex-col gap-4`. `space-x-2` → `flex gap-2`.
+
+```tsx
+<div className="flex flex-col gap-4">
+  <Input />
+  <Input />
+  <Button>Submit</Button>
+</div>
+```
+
+---
+
+## Prefer size-* over w-* h-* when equal
+
+`size-10` not `w-10 h-10`. Applies to icons, avatars, skeletons, etc.
+
+---
+
+## Prefer truncate shorthand
+
+`truncate` not `overflow-hidden text-ellipsis whitespace-nowrap`.
+
+---
+
+## No manual dark: color overrides
+
+Use semantic tokens — they handle light/dark via CSS variables. `bg-background text-foreground` not `bg-white dark:bg-gray-950`.
+
+---
+
+## Use cn() for conditional classes
+
+Use the `cn()` utility from nqui for conditional or merged class names. Don't write manual ternaries in className strings.
+
+**Incorrect:**
+
+```tsx
+<div className={`flex items-center ${isActive ? "bg-primary text-primary-foreground" : "bg-muted"}`}>
+```
+
+**Correct:**
+
+```tsx
+import { cn } from "@/lib/utils"
+
+<div className={cn("flex items-center", isActive ? "bg-primary text-primary-foreground" : "bg-muted")}>
+```
+
+---
+
+## No manual z-index on overlay components (use elevation.css)
+
+`Dialog`, `Sheet`, `Drawer`, `AlertDialog`, `DropdownMenu`, `Popover`, `Tooltip`, `HoverCard` handle their own stacking. Use the centralized z-index system from `elevation.css`.
+
+**Incorrect:**
+
+```tsx
+<div className="z-50">
+<Dialog>...</Dialog>
+</div>
+```
+
+**Correct:**
+
+```tsx
+import { cn } from "@/lib/utils"
+
+<div className={cn("z-[var(--z-modal)]")}>
+  <Dialog>...</Dialog>
+</div>
+```
+
+Reference: [elevation.css](../src/styles/elevation.css)
+
+| Variable | Value | Use Case |
+|----------|-------|----------|
+| `--z-base` | 0 | Base layer |
+| `--z-content` | 10 | Standard content |
+| `--z-sticky-content` | 15 | Sticky content within containers |
+| `--z-sticky-page` | 20 | Page-level sticky elements |
+| `--z-floating` | 30 | Floating panels, sidebars |
+| `--z-modal-backdrop` | 40 | Modal backdrops |
+| `--z-modal` | 50 | Modal content |
+| `--z-popover` | 60 | Dropdowns, select menus |
+| `--z-tooltip` | 70 | Tooltips |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nqlib/nqui",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "A React component library with enhanced UI components and developer tools",
   "type": "module",
   "main": "./dist/nqui.cjs.js",
@@ -47,6 +47,11 @@
       "require": "./dist/styles.css",
       "default": "./dist/styles.css"
     },
+    "./debug": {
+      "types": "./dist/entries/debug.d.ts",
+      "import": "./dist/debug.es.js",
+      "require": "./dist/debug.cjs.js"
+    },
     "./debug.css": "./dist/nqui.css"
   },
   "files": [
@@ -65,7 +70,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/nqlib/nqui.git"
+    "url": "git+https://github.com/nqlib/nqui.git"
   },
   "keywords": [
     "ui",
@@ -103,15 +108,19 @@
     "build-storybook": "storybook build",
     "test-storybook": "test-storybook",
     "test-storybook:ci": "test-storybook --ci",
-    "test-storybook:coverage": "test-storybook --coverage"
+    "test-storybook:coverage": "test-storybook --coverage",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "nqui:init": "npx @nqlib/nqui install-peers && npx @nqlib/nqui init-cursor && npx @nqlib/nqui init-skills && npx @nqlib/nqui init-css --sidebar --force"
   },
   "bin": {
-    "nqui": "./scripts/cli.js",
-    "nqui-init-css": "./scripts/init-css.js",
-    "nqui-init-cursor": "./scripts/init-cursor.js",
-    "nqui-install-peers": "./scripts/install-peers.js",
-    "nqui-init-debug": "./scripts/init-debug-css.js",
-    "nqui-setup": "./scripts/post-install.js"
+    "nqui": "scripts/cli.js",
+    "nqui-init-css": "scripts/init-css.js",
+    "nqui-init-cursor": "scripts/init-cursor.js",
+    "nqui-init-skills": "scripts/download-skills.js",
+    "nqui-install-peers": "scripts/install-peers.js",
+    "nqui-init-debug": "scripts/init-debug-css.js",
+    "nqui-setup": "scripts/post-install.js"
   },
   "dependencies": {
     "@codesandbox/sandpack-react": "^2.20.0",
@@ -238,6 +247,8 @@
     "@storybook/react-vite": "^10.1.11",
     "@storybook/test-runner": "^0.24.2",
     "@storybook/testing-library": "^0.2.2",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.1.0",
     "@types/lodash.throttle": "^4.1.9",
     "@types/node": "^24.10.1",
     "@types/react": "^19.0.0",
@@ -253,6 +264,8 @@
     "storybook": "^10.1.11",
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.46.4",
-    "vite": "^7.2.4"
+    "vite": "^7.2.4",
+    "vitest": "^3.1.4",
+    "jsdom": "^26.1.0"
   }
 }

package/scripts/cli.js

@@ -20,6 +20,7 @@ const subcommand = process.argv[2];
 
 const routes = {
   'init-cursor': './init-cursor.js',
+  'init-skills': './download-skills.js',
   'install-peers': './install-peers.js',
   'init-debug': './init-debug-css.js',
   'init-debug-css': './init-debug-css.js',

package/scripts/download-skills.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * Download nqui-skills to user's project
+ * 
+ * Usage: npx @nqlib/nqui init-skills
+ * 
+ * Copies docs/nqui-skills to user's .cursor/nqui-skills
+ * Creates AGENTS.md pointing to the skills
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, cpSync } from 'fs';
+import { join, resolve } from 'path';
+import { getPackageRoot } from './getPackageRoot.js';
+import { resolveTargetDir } from './resolve-target-dir.js';
+
+const root = getPackageRoot();
+const skillsSource = join(root, 'docs', 'nqui-skills');
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+
+export async function downloadSkills({ force = true }) {
+  const targetDir = resolveTargetDir(process.cwd());
+  const cursorDir = join(targetDir, '.cursor');
+  const skillsDest = join(cursorDir, 'nqui-skills');
+  const agentsFile = join(targetDir, 'AGENTS.md');
+
+  // Create .cursor directory if needed
+  ensureDir(cursorDir);
+
+  // Copy skills folder
+  if (existsSync(skillsSource)) {
+    if (existsSync(skillsDest) && !force) {
+      console.log('⏭️  nqui-skills already exists. Use --force to overwrite.');
+    } else {
+      cpSync(skillsSource, skillsDest, { recursive: true });
+      console.log('✅ Copied nqui-skills to:', skillsDest);
+    }
+  } else {
+    console.warn('⚠️  Source skills not found:', skillsSource);
+    return;
+  }
+
+  // Create or update AGENTS.md
+  const agentsContent = `# AGENTS.md
+
+This file points to nqui skills for AI assistants.
+
+## nqui Skills
+
+For component implementation and UI design with @nqlib/nqui, load skills from:
+
+\`\`\`
+.cursor/nqui-skills/SKILL.md
+\`\`\`
+
+The skills include:
+- Component implementation guide
+- Design system conventions (sizing, z-index)
+- ToggleGroup usage rules
+- App design patterns
+
+## How to Use
+
+When working with nqui components, AI assistants should load:
+- \`.cursor/nqui-skills/SKILL.md\` - main guide
+
+---
+
+Generated by nqui. Run \`npx @nqlib/nqui init-skills\` to update.
+`;
+
+  if (existsSync(agentsFile) && !force) {
+    console.log('⏭️  AGENTS.md already exists. Use --force to overwrite.');
+  } else {
+    writeFileSync(agentsFile, agentsContent);
+    console.log('✅ Created AGENTS.md at:', agentsFile);
+  }
+
+  console.log('\n📚 nqui-skills installed!');
+  console.log('   Restart Cursor to load the skills.');
+}
+
+// CLI execution
+const args = process.argv.slice(2);
+const force = args.includes('--force') || args.length === 0;
+
+downloadSkills({ force }).catch(console.error);

package/scripts/examples/nextjs-layout-sidebar.tsx

@@ -0,0 +1,100 @@
+import type { Metadata } from "next";
+import { ThemeProvider } from "next-themes";
+import "./globals.css";
+import {
+  SidebarProvider,
+  Sidebar,
+  SidebarContent,
+  SidebarHeader,
+  SidebarMenu,
+  SidebarMenuItem,
+  SidebarMenuButton,
+  SidebarInset,
+  SidebarTrigger,
+  Separator,
+} from "@nqlib/nqui";
+import { NquiLogo } from "@nqlib/nqui";
+import { HomeIcon, SettingsIcon, MailIcon, FileIcon } from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import Link from "next/link";
+
+export const metadata: Metadata = {
+  title: "nqui App",
+  description: "3-column app with sidebar, header, and content area (showcase-style)",
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <ThemeProvider
+          attribute="class"
+          defaultTheme="system"
+          enableSystem
+          disableTransitionOnChange
+        >
+          <SidebarProvider defaultOpen>
+            <Sidebar>
+              <SidebarHeader>
+                <div className="flex items-center gap-2 px-2 py-4">
+                  <NquiLogo className="w-8 h-8" />
+                  <span className="font-semibold">My App</span>
+                </div>
+              </SidebarHeader>
+              <SidebarContent>
+                <SidebarMenu>
+                  <SidebarMenuItem>
+                    <SidebarMenuButton asChild>
+                      <Link href="/">
+                        <HugeiconsIcon icon={HomeIcon} className="w-4 h-4" />
+                        <span>Home</span>
+                      </Link>
+                    </SidebarMenuButton>
+                  </SidebarMenuItem>
+                  <SidebarMenuItem>
+                    <SidebarMenuButton asChild>
+                      <Link href="/inbox">
+                        <HugeiconsIcon icon={MailIcon} className="w-4 h-4" />
+                        <span>Inbox</span>
+                      </Link>
+                    </SidebarMenuButton>
+                  </SidebarMenuItem>
+                  <SidebarMenuItem>
+                    <SidebarMenuButton asChild>
+                      <Link href="/files">
+                        <HugeiconsIcon icon={FileIcon} className="w-4 h-4" />
+                        <span>Files</span>
+                      </Link>
+                    </SidebarMenuButton>
+                  </SidebarMenuItem>
+                  <SidebarMenuItem>
+                    <SidebarMenuButton asChild>
+                      <Link href="/settings">
+                        <HugeiconsIcon icon={SettingsIcon} className="w-4 h-4" />
+                        <span>Settings</span>
+                      </Link>
+                    </SidebarMenuButton>
+                  </SidebarMenuItem>
+                </SidebarMenu>
+              </SidebarContent>
+            </Sidebar>
+            <SidebarInset className="flex flex-col min-h-screen">
+              <header className="flex h-12 items-center gap-2 border-b px-4 shrink-0 bg-background/95">
+                <SidebarTrigger className="-ml-1" />
+                <Separator orientation="vertical" className="h-4" />
+                <span className="text-sm font-medium">My App</span>
+              </header>
+              <main className="flex-1 min-h-0 flex">
+                {children}
+              </main>
+            </SidebarInset>
+          </SidebarProvider>
+        </ThemeProvider>
+      </body>
+    </html>
+  );
+}

package/scripts/examples/nextjs-page-sidebar.tsx

@@ -0,0 +1,81 @@
+"use client";
+
+import { Button } from "@nqlib/nqui";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+  TableOfContents,
+  Input,
+  Label,
+  Checkbox,
+  Separator,
+} from "@nqlib/nqui";
+
+export default function Home() {
+  return (
+    <div className="flex flex-1 min-h-0">
+      <div className="flex-1 min-w-0 overflow-y-auto p-6">
+        <div className="max-w-3xl space-y-8">
+          <div className="space-y-2">
+            <h1 className="text-3xl font-bold">Welcome to My App</h1>
+            <p className="text-muted-foreground">
+              Sample 3-column layout: sidebar, main content, and table of contents (showcase-style).
+            </p>
+          </div>
+
+          <section className="space-y-4">
+            <h2 id="getting-started" className="text-xl font-semibold scroll-mt-6">
+              Getting Started
+            </h2>
+            <Card>
+              <CardHeader>
+                <CardTitle>Quick start</CardTitle>
+                <CardDescription>
+                  Edit this page to start building your app
+                </CardDescription>
+              </CardHeader>
+              <CardContent className="space-y-4">
+                <div className="grid gap-2">
+                  <Label htmlFor="name">Name</Label>
+                  <Input id="name" placeholder="Enter your name" />
+                </div>
+                <div className="grid gap-2">
+                  <Label htmlFor="email">Email</Label>
+                  <Input id="email" type="email" placeholder="Enter your email" />
+                </div>
+                <Checkbox id="terms">Accept terms and conditions</Checkbox>
+                <Separator />
+                <div className="flex gap-2">
+                  <Button variant="default">Submit</Button>
+                  <Button variant="outline">Cancel</Button>
+                </div>
+              </CardContent>
+            </Card>
+          </section>
+
+          <section className="space-y-4">
+            <h2 id="next-steps" className="text-xl font-semibold scroll-mt-6">
+              Next steps
+            </h2>
+            <p className="text-muted-foreground text-sm">
+              Edit <code className="rounded bg-muted px-1 py-0.5">app/page.tsx</code> to get started.
+            </p>
+          </section>
+        </div>
+      </div>
+      <aside className="w-56 shrink-0 border-l bg-muted/30 p-4 hidden lg:block overflow-y-auto">
+        <TableOfContents
+          autoDetect
+          headingSelector="h2"
+          variant="clerk"
+          enableScrollSpy
+          title="Contents"
+          scrollOffset={80}
+        />
+      </aside>
+    </div>
+  );
+}

package/scripts/examples/vite-app.tsx

@@ -0,0 +1,135 @@
+import { Routes, Route } from "react-router-dom";
+import {
+  SidebarProvider,
+  Sidebar,
+  SidebarContent,
+  SidebarHeader,
+  SidebarMenu,
+  SidebarMenuItem,
+  SidebarMenuButton,
+  SidebarInset,
+  SidebarTrigger,
+  Separator,
+  TableOfContents,
+  NquiLogo,
+} from "@nqlib/nqui";
+import { HomeIcon, SettingsIcon, MailIcon, FileIcon } from "@hugeicons/core-free-icons";
+import { HugeiconsIcon } from "@hugeicons/react";
+import { Link } from "react-router-dom";
+
+function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <SidebarProvider defaultOpen>
+      <Sidebar>
+        <SidebarHeader>
+          <div className="flex items-center gap-2 px-2 py-4">
+            <NquiLogo className="w-8 h-8" />
+            <span className="font-semibold">My App</span>
+          </div>
+        </SidebarHeader>
+        <SidebarContent>
+          <SidebarMenu>
+            <SidebarMenuItem>
+              <SidebarMenuButton asChild>
+                <Link to="/">
+                  <HugeiconsIcon icon={HomeIcon} className="w-4 h-4" />
+                  <span>Home</span>
+                </Link>
+              </SidebarMenuButton>
+            </SidebarMenuItem>
+            <SidebarMenuItem>
+              <SidebarMenuButton asChild>
+                <Link to="/inbox">
+                  <HugeiconsIcon icon={MailIcon} className="w-4 h-4" />
+                  <span>Inbox</span>
+                </Link>
+              </SidebarMenuButton>
+            </SidebarMenuItem>
+            <SidebarMenuItem>
+              <SidebarMenuButton asChild>
+                <Link to="/files">
+                  <HugeiconsIcon icon={FileIcon} className="w-4 h-4" />
+                  <span>Files</span>
+                </Link>
+              </SidebarMenuButton>
+            </SidebarMenuItem>
+            <SidebarMenuItem>
+              <SidebarMenuButton asChild>
+                <Link to="/settings">
+                  <HugeiconsIcon icon={SettingsIcon} className="w-4 h-4" />
+                  <span>Settings</span>
+                </Link>
+              </SidebarMenuButton>
+            </SidebarMenuItem>
+          </SidebarMenu>
+        </SidebarContent>
+      </Sidebar>
+      <SidebarInset className="flex flex-col min-h-screen">
+        <header className="flex h-12 items-center gap-2 border-b px-4 shrink-0 bg-background/95">
+          <SidebarTrigger className="-ml-1" />
+          <Separator orientation="vertical" className="h-4" />
+          <span className="text-sm font-medium">My App</span>
+        </header>
+        <main className="flex-1 min-h-0 flex">
+          {children}
+        </main>
+      </SidebarInset>
+    </SidebarProvider>
+  );
+}
+
+function HomePage() {
+  return (
+    <div className="flex flex-1 min-h-0">
+      <div className="flex-1 min-w-0 overflow-y-auto p-6">
+        <div className="max-w-3xl space-y-8">
+          <div className="space-y-2">
+            <h1 className="text-3xl font-bold">Welcome to My App</h1>
+            <p className="text-muted-foreground">
+              Sample 3-column layout: sidebar, main content, and table of contents (showcase-style).
+            </p>
+          </div>
+          <section className="space-y-4">
+            <h2 id="getting-started" className="text-xl font-semibold scroll-mt-6">
+              Getting Started
+            </h2>
+            <p className="text-muted-foreground text-sm">
+              Edit <code className="rounded bg-muted px-1 py-0.5">App.tsx</code> to get started.
+            </p>
+          </section>
+          <section className="space-y-4">
+            <h2 id="next-steps" className="text-xl font-semibold scroll-mt-6">
+              Next steps
+            </h2>
+            <p className="text-muted-foreground text-sm">
+              Add routes and pages. The right column shows a table of contents from headings on this page.
+            </p>
+          </section>
+        </div>
+      </div>
+      <aside className="w-56 shrink-0 border-l bg-muted/30 p-4 hidden lg:block overflow-y-auto">
+        <TableOfContents
+          autoDetect
+          headingSelector="h2"
+          variant="clerk"
+          enableScrollSpy
+          title="Contents"
+          scrollOffset={80}
+        />
+      </aside>
+    </div>
+  );
+}
+
+export default function App() {
+  return (
+    <Layout>
+      <Routes>
+        <Route path="/" element={<HomePage />} />
+        <Route path="/inbox" element={<div className="p-6">Inbox – Coming soon</div>} />
+        <Route path="/files" element={<div className="p-6">Files – Coming soon</div>} />
+        <Route path="/settings" element={<div className="p-6">Settings – Coming soon</div>} />
+      </Routes>
+    </Layout>
+  );
+}