@nqlib/nqui 0.3.2 → 0.4.0

package/docs/internal-notes/progress.md

@@ -0,0 +1,348 @@
+# Progress Component
+
+The Progress component displays progress indicators with two distinct styles: a block-based segmented design (dash style) similar to GitHub's contribution graph, or a smooth continuous bar (solid style).
+
+## Installation
+
+```bash
+npm install @nqlib/nqui
+```
+
+## Import
+
+```tsx
+import { Progress } from '@nqlib/nqui';
+// Or import the base version:
+import { CoreProgress } from '@nqlib/nqui';
+```
+
+## Basic Usage
+
+### Dash Style (Default)
+
+The dash style displays progress as discrete colored blocks:
+
+```tsx
+import { Progress } from '@nqlib/nqui';
+
+export default function Example() {
+  return <Progress value={75} variant="success" />;
+}
+```
+
+### Solid Style
+
+The solid style displays progress as a smooth continuous bar:
+
+```tsx
+import { Progress } from '@nqlib/nqui';
+
+export default function Example() {
+  return (
+    <Progress 
+      value={75} 
+      variant="success" 
+      style="solid" 
+    />
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `number` | **required** | Progress value (0 to max) |
+| `max` | `number` | `100` | Maximum value |
+| `variant` | `'default' \| 'success' \| 'warning' \| 'error' \| 'neutral'` | `'default'` | Color variant |
+| `style` | `'dash' \| 'solid'` | `'dash'` | Progress style/appearance |
+| `blocks` | `number` | auto | Number of blocks to display (dash style only, 20-100) |
+| `showTooltip` | `boolean` | `false` | Show tooltip on hover showing progress percentage |
+| `hoverEffect` | `boolean` | `false` | Enable hover opacity effect on blocks (dash style only) |
+| `showAnimation` | `boolean` | `false` | Show animation transition when value changes |
+| `label` | `string` | - | Optional label text to display next to progress bar (solid style only) |
+| `height` | `string` | `'h-8'` (dash) or `'h-2'` (solid) | Height override (Tailwind class or CSS value) |
+| `className` | `string` | - | Additional CSS classes |
+
+## Variants
+
+Progress comes in five color variants:
+
+```tsx
+<Progress value={60} variant="default" />   // Primary color
+<Progress value={60} variant="success" />  // Green
+<Progress value={60} variant="warning" />  // Yellow
+<Progress value={60} variant="error" />    // Red
+<Progress value={60} variant="neutral" />  // Gray
+```
+
+## Styles
+
+### Dash Style
+
+The dash style displays progress as discrete blocks, similar to GitHub's contribution graph. Blocks are auto-calculated based on container width, or you can specify a custom count.
+
+```tsx
+// Auto-calculated blocks (default)
+<div className="w-96">
+  <Progress value={60} variant="success" />
+</div>
+
+// Custom block count
+<Progress value={60} blocks={50} variant="success" />
+
+// With hover effect
+<Progress 
+  value={60} 
+  variant="success" 
+  hoverEffect 
+/>
+
+// With tooltip
+<Progress 
+  value={60} 
+  variant="success" 
+  showTooltip 
+/>
+```
+
+### Solid Style
+
+The solid style displays progress as a smooth continuous bar with rounded corners.
+
+```tsx
+// Basic solid bar
+<Progress value={75} variant="success" style="solid" />
+
+// With label
+<Progress 
+  value={75} 
+  variant="success" 
+  style="solid" 
+  label="75% Complete" 
+/>
+
+// With animation
+<Progress 
+  value={progress} 
+  variant="success" 
+  style="solid" 
+  showAnimation 
+/>
+
+// Custom height
+<Progress 
+  value={75} 
+  variant="success" 
+  style="solid" 
+  height="h-4" 
+/>
+```
+
+## Examples
+
+### Dash Style Examples
+
+#### Auto-calculated Blocks
+
+The component automatically calculates the optimal number of blocks based on container width:
+
+```tsx
+<div className="w-64">
+  <Progress value={60} variant="default" />
+</div>
+
+<div className="w-96">
+  <Progress value={60} variant="success" />
+</div>
+
+<div className="w-full max-w-2xl">
+  <Progress value={60} variant="warning" />
+</div>
+```
+
+#### Custom Block Count
+
+Specify a custom number of blocks (between 20-100):
+
+```tsx
+// Sparse (20 blocks)
+<Progress value={60} blocks={20} variant="success" />
+
+// Default density (50 blocks)
+<Progress value={60} blocks={50} variant="success" />
+
+// Dense (100 blocks)
+<Progress value={60} blocks={100} variant="success" />
+```
+
+#### With Tooltip
+
+Show progress percentage on hover:
+
+```tsx
+import { TooltipProvider } from '@nqlib/nqui';
+
+<TooltipProvider>
+  <Progress 
+    value={65} 
+    variant="success" 
+    showTooltip 
+  />
+</TooltipProvider>
+```
+
+#### With Hover Effect
+
+Enable opacity effect on blocks when hovering:
+
+```tsx
+<Progress 
+  value={70} 
+  variant="default" 
+  hoverEffect 
+/>
+```
+
+#### Custom Heights
+
+```tsx
+<Progress value={60} height="h-4" variant="success" />   // Small
+<Progress value={60} height="h-6" variant="success" />   // Medium
+<Progress value={60} height="h-8" variant="success" />   // Default
+<Progress value={60} height="h-12" variant="success" />  // Large
+<Progress value={60} height="2rem" variant="success" />  // Custom CSS
+```
+
+### Solid Style Examples
+
+#### Basic Solid Bar
+
+```tsx
+<Progress value={75} variant="success" style="solid" />
+```
+
+#### With Label
+
+```tsx
+<Progress 
+  value={75} 
+  variant="success" 
+  style="solid" 
+  label="75%" 
+/>
+```
+
+#### With Animation
+
+Animate value changes smoothly:
+
+```tsx
+import { useState } from 'react';
+
+function AnimatedProgress() {
+  const [progress, setProgress] = useState(50);
+
+  return (
+    <Progress 
+      value={progress} 
+      variant="success" 
+      style="solid" 
+      showAnimation 
+    />
+  );
+}
+```
+
+#### Different Progress Values
+
+```tsx
+<Progress value={0} variant="default" style="solid" />    // 0%
+<Progress value={25} variant="success" style="solid" />   // 25%
+<Progress value={50} variant="warning" style="solid" />   // 50%
+<Progress value={75} variant="success" style="solid" />  // 75%
+<Progress value={100} variant="success" style="solid" />  // 100%
+```
+
+## Controlled Progress
+
+Use controlled state to update progress dynamically:
+
+```tsx
+import { useState } from 'react';
+import { Progress } from '@nqlib/nqui';
+
+function ControlledProgress() {
+  const [progress, setProgress] = useState(50);
+
+  return (
+    <div className="space-y-4">
+      <Progress 
+        value={progress} 
+        variant="success" 
+        showTooltip 
+      />
+      <input
+        type="range"
+        min="0"
+        max="100"
+        value={progress}
+        onChange={(e) => setProgress(Number(e.target.value))}
+        className="w-full"
+      />
+      <div className="text-sm text-muted-foreground">
+        Progress: {progress}%
+      </div>
+    </div>
+  );
+}
+```
+
+## Requirements
+
+### CSS Import
+
+Ensure the library CSS is imported in your application:
+
+```tsx
+import '@nqlib/nqui/dist/index.css';
+```
+
+### Tooltip Provider
+
+If using `showTooltip`, wrap your app with `TooltipProvider`:
+
+```tsx
+import { TooltipProvider } from '@nqlib/nqui';
+
+function App() {
+  return (
+    <TooltipProvider>
+      {/* Your app */}
+    </TooltipProvider>
+  );
+}
+```
+
+## Accessibility
+
+- Includes ARIA attributes (`role="progressbar"`, `aria-valuenow`, `aria-valuemin`, `aria-valuemax`)
+- Proper progress semantics for screen readers
+- Keyboard accessible (inherited from Radix UI primitives)
+
+## Notes
+
+- **Dash style**: Block-based design that auto-calculates block count based on container width if `blocks` prop is not provided
+- **Solid style**: Smooth continuous bar with rounded corners, supports labels and animations
+- **Responsive**: Dash style adapts block count to container width automatically
+- **Performance**: Uses ResizeObserver for efficient width calculations in dash style
+
+## Base Component
+
+If you need the base Radix UI Progress component without enhancements, import `CoreProgress`:
+
+```tsx
+import { CoreProgress } from '@nqlib/nqui';
+
+<CoreProgress value={33} />
+```

package/docs/internal-notes/stacked-avatar-implementation.md

@@ -0,0 +1,38 @@
+# Stacked Avatar (Assignees) Implementation
+
+Use this pattern to show multiple assignees/people in a project cell with limited space.
+
+## Pattern
+
+1. **Stack avatars** – Use `flex` + `-space-x-1.5` so avatars overlap.
+2. **Limit visible** – Show the first `maxVisible` avatars (e.g. 2–3).
+3. **Overflow indicator** – When there are more, append a "…" badge.
+4. **Hover for details** – Wrap the overflow case in `Tooltip` / `TooltipProvider`; show full list on hover.
+
+## Data Shape
+
+```ts
+type Person = { id: string; name: string; avatarUrl?: string }
+```
+
+## Key Props
+
+| Prop        | Description                         |
+|-------------|-------------------------------------|
+| `maxVisible`| How many avatars to show (2–3)      |
+| `people`    | Array of `Person` objects           |
+
+## Layout Classes
+
+- Container: `flex shrink-0 items-center -space-x-1.5`
+- Avatar: `h-5 w-5 border border-background`
+- Fallback: `text-[10px]` for initials
+- Overflow badge: Same size as avatar, `bg-muted text-muted-foreground`
+
+## Overflow Logic
+
+```ts
+const visible = people.slice(0, maxVisible)
+const overflow = people.length > maxVisible
+// Render visible + "…" badge when overflow; wrap in Tooltip for hover
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nqlib/nqui",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "A React component library with enhanced UI components and developer tools",
   "type": "module",
   "main": "./dist/nqui.cjs.js",
@@ -12,6 +12,36 @@
       "import": "./dist/nqui.es.js",
       "require": "./dist/nqui.cjs.js"
     },
+    "./carousel": {
+      "types": "./dist/entries/carousel.d.ts",
+      "import": "./dist/carousel.es.js",
+      "require": "./dist/carousel.cjs.js"
+    },
+    "./command": {
+      "types": "./dist/entries/command.d.ts",
+      "import": "./dist/command.es.js",
+      "require": "./dist/command.cjs.js"
+    },
+    "./sortable": {
+      "types": "./dist/entries/sortable.d.ts",
+      "import": "./dist/sortable.es.js",
+      "require": "./dist/sortable.cjs.js"
+    },
+    "./calendar": {
+      "types": "./dist/entries/calendar.d.ts",
+      "import": "./dist/calendar.es.js",
+      "require": "./dist/calendar.cjs.js"
+    },
+    "./sonner": {
+      "types": "./dist/entries/sonner.d.ts",
+      "import": "./dist/sonner.es.js",
+      "require": "./dist/sonner.cjs.js"
+    },
+    "./drawer": {
+      "types": "./dist/entries/drawer.d.ts",
+      "import": "./dist/drawer.es.js",
+      "require": "./dist/drawer.cjs.js"
+    },
     "./styles": {
       "import": "./dist/styles.css",
       "require": "./dist/styles.css",
@@ -22,6 +52,7 @@
   "files": [
     "dist",
     "scripts",
+    "docs",
     "README.md",
     "INSTALLATION.md"
   ],
@@ -50,6 +81,7 @@
   "author": "",
   "license": "MIT",
   "scripts": {
+    "postinstall": "node scripts/post-install.js",
     "dev": "vite",
     "build": "npm run build:lib",
     "build:lib": "vite build --mode library && npm run build:types && npm run build:styles && npm run copy:css",
@@ -74,12 +106,14 @@
     "test-storybook:coverage": "test-storybook --coverage"
   },
   "bin": {
-    "nqui": "./scripts/init-css.js",
+    "nqui": "./scripts/cli.js",
     "nqui-init-css": "./scripts/init-css.js",
-    "nqui-init-debug": "./scripts/init-debug-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"
   },
   "dependencies": {
-    "@base-ui/react": "^1.0.0",
     "@codesandbox/sandpack-react": "^2.20.0",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/modifiers": "^9.0.0",
@@ -88,7 +122,6 @@
     "@fontsource-variable/inter": "^5.2.8",
     "@hugeicons/core-free-icons": "^3.1.1",
     "@hugeicons/react": "^1.1.4",
-    "@icons-pack/react-simple-icons": "^13.8.0",
     "@radix-ui/react-avatar": "^1.1.11",
     "@radix-ui/react-checkbox": "^1.3.3",
     "@radix-ui/react-collapsible": "^1.1.12",
@@ -105,36 +138,28 @@
     "@radix-ui/react-tabs": "^1.1.13",
     "@radix-ui/react-tooltip": "^1.2.8",
     "@radix-ui/react-use-controllable-state": "^1.2.2",
-    "@remixicon/react": "^4.8.0",
     "@shikijs/transformers": "^3.21.0",
     "@tailwindcss/vite": "^4.1.17",
     "@tanstack/react-table": "^8.21.3",
-    "@tanstack/react-virtual": "^3.13.18",
     "@uidotdev/usehooks": "^2.4.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
     "date-fns": "^4.1.0",
     "embla-carousel-react": "^8.6.0",
-    "html2canvas-pro": "^1.6.3",
     "input-otp": "^1.4.2",
-    "jotai": "^2.17.0",
     "lodash.throttle": "^4.1.1",
-    "lucide-react": "^0.562.0",
     "minimist": "^1.2.8",
-    "motion": "^12.24.10",
     "next-themes": "^0.4.6",
     "package": "^1.0.1",
     "postcss": "^8.4.0",
     "postcss-discard-comments": "^7.0.0",
     "postcss-import": "^16.0.0",
     "radix-ui": "^1.4.3",
-    "react": "^18.2.0",
+    "react": "^19.0.0",
     "react-day-picker": "^9.13.0",
-    "react-dom": "^18.2.0",
-    "react-resizable-panels": "^4.2.1",
+    "react-dom": "^19.0.0",
     "react-router-dom": "^7.11.0",
-    "recharts": "^2.15.4",
     "shiki": "^3.21.0",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.4.0",
@@ -143,7 +168,68 @@
     "tw-animate-css": "^1.4.0",
     "vaul": "^1.1.2"
   },
+  "peerDependencies": {
+    "@base-ui/react": "^1.0.0",
+    "@hugeicons/core-free-icons": "^3.0.0",
+    "@hugeicons/react": "^1.0.0",
+    "@dnd-kit/core": "^6.0.0",
+    "@dnd-kit/modifiers": "^9.0.0",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.0.0",
+    "@tanstack/react-table": "^8.0.0",
+    "cmdk": "^1.0.0",
+    "date-fns": "^4.0.0",
+    "embla-carousel-react": "^8.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-day-picker": "^9.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "react-resizable-panels": "^4.0.0",
+    "sonner": "^2.0.0",
+    "vaul": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "cmdk": {
+      "optional": true
+    },
+    "@dnd-kit/core": {
+      "optional": true
+    },
+    "@dnd-kit/modifiers": {
+      "optional": true
+    },
+    "@dnd-kit/sortable": {
+      "optional": true
+    },
+    "@dnd-kit/utilities": {
+      "optional": true
+    },
+    "embla-carousel-react": {
+      "optional": true
+    },
+    "@tanstack/react-table": {
+      "optional": true
+    },
+    "react-day-picker": {
+      "optional": true
+    },
+    "date-fns": {
+      "optional": true
+    },
+    "sonner": {
+      "optional": true
+    },
+    "vaul": {
+      "optional": true
+    },
+    "react-resizable-panels": {
+      "optional": true
+    },
+    "@base-ui/react": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@base-ui/react": "^1.0.0",
     "@eslint/js": "^9.39.1",
     "@storybook/addon-docs": "^10.1.11",
     "@storybook/addon-links": "^10.1.11",
@@ -154,14 +240,15 @@
     "@storybook/testing-library": "^0.2.2",
     "@types/lodash.throttle": "^4.1.9",
     "@types/node": "^24.10.1",
-    "@types/react": "^18.2.0",
-    "@types/react-dom": "^18.2.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
     "@vitejs/plugin-react": "^5.1.1",
     "eslint": "^9.39.1",
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.4.24",
     "eslint-plugin-storybook": "10.1.11",
     "globals": "^16.5.0",
+    "react-resizable-panels": "^4.2.1",
     "shadcn": "^3.6.2",
     "storybook": "^10.1.11",
     "typescript": "~5.9.3",

package/scripts/cli.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+/**
+ * nqui CLI dispatcher. Routes subcommands to the correct script.
+ *
+ * Usage:
+ *   npx @nqlib/nqui init-css [output.css]
+ *   npx @nqlib/nqui init-cursor
+ *   npx @nqlib/nqui install-peers
+ *   npx @nqlib/nqui init-debug
+ *   npx @nqlib/nqui setup
+ */
+
+import { spawnSync } from 'child_process';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const subcommand = process.argv[2];
+
+const routes = {
+  'init-cursor': './init-cursor.js',
+  'install-peers': './install-peers.js',
+  'init-debug': './init-debug-css.js',
+  'init-debug-css': './init-debug-css.js',
+  setup: './post-install.js',
+};
+
+if (routes[subcommand]) {
+  const script = resolve(__dirname, routes[subcommand]);
+  const result = spawnSync(process.execPath, [script, ...process.argv.slice(3)], {
+    stdio: 'inherit',
+    cwd: process.cwd(),
+  });
+  process.exit(result.status ?? 1);
+}
+
+// Default: init-css (pass all args through)
+const initCss = resolve(__dirname, 'init-css.js');
+const result = spawnSync(process.execPath, [initCss, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+  cwd: process.cwd(),
+});
+process.exit(result.status ?? 1);

package/scripts/help.js

@@ -11,6 +11,7 @@ ${pkg.name} v${pkg.version}
 
 Usage:
   npx nqui init-css [output.css] [options]
+  npx nqui-setup              Show post-install next steps
 
 Options:
   --js            Generate JS token file

package/scripts/init-css.js

@@ -19,6 +19,21 @@ import { generateSetupContent } from './setup-helper.js';
 import { copyNextJsExamples } 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'];
+if (subcommands.includes(firstArg)) {
+  console.error(`
+❌ Outdated @nqlib/nqui — "npx @nqlib/nqui ${firstArg}" routed to init-css.
+
+   Fix: npm install @nqlib/nqui@latest
+   Then: npx @nqlib/nqui ${firstArg}
+
+   Or run the binary directly: npm exec nqui-init-cursor
+`);
+  process.exit(1);
+}
+
 // Filter out command names from argv
 const commandNames = ['init-css', 'nqui', 'nqui-init-css'];
 const filteredArgs = process.argv.slice(2).filter(arg => !commandNames.includes(arg));