@nqlib/nqui 0.3.2 → 0.4.0

package/docs/internal-notes/FROSTED_GLASS_FIX.md

@@ -0,0 +1,50 @@
+# Frosted Glass Header Fix - Release Notes
+
+## Issue
+Content was not visible behind sticky headers with frosted glass effect. Headers appeared solid/opaque, preventing the backdrop-filter blur effect from showing content scrolling behind them.
+
+## Root Cause
+The scroll container structure prevented content from actually scrolling behind sticky headers. Content was positioned below headers rather than overlapping them, so backdrop-filter had nothing to blur.
+
+## Fix Applied
+
+### AppLayout Header (`packages/nqui/src/components/AppLayout.tsx`)
+1. **Scroll Container Structure**: Ensured scroll container uses `flex flex-col` to allow normal content flow
+2. **Header Positioning**: Header uses `sticky top-0 z-10` with `FrostedGlass` component as backdrop layer
+3. **Content Layer**: Added semi-transparent background (`bg-background/40`) to content div for visibility while maintaining transparency
+4. **Removed Aggressive Scroll Resets**: Removed setInterval-based scroll resets that were interfering with user scrolling
+
+### Card Header (`packages/nqui/src/components/ui/card.tsx`)
+1. **FrostedGlass Integration**: Added `FrostedGlass` component with `borderRadius={8}` for rounded corners
+2. **Transparent Content Layer**: Removed background from content wrapper to allow content behind to show through
+3. **ScrollArea Structure**: Simplified ScrollArea wrapper to use `flex-1 min-h-0` directly, allowing content to scroll behind sticky header
+4. **Same Root Cause**: Content wasn't positioned to scroll behind sticky header - fixed by ensuring ScrollArea allows normal content flow
+
+## Technical Details
+
+### FrostedGlass Component Features
+- Extended backdrop (`h-[200%]`) to capture reflections from nearby elements (Josh Comeau method)
+- SVG mask for rounded corners when `borderRadius > 0`
+- Linear gradient mask for square corners
+- Very light background (`bg-background/5`) to make blur effect visible
+- `pointer-events: none` to allow interactions
+
+### Key CSS Properties
+- `backdrop-filter: blur(16px)` - Main blur effect
+- `-webkit-backdrop-filter: blur(16px)` - Safari support
+- `position: sticky` - Keeps header at top while scrolling
+- `z-index` layering - FrostedGlass at `z-0`, content at `z-10`
+
+## Files Modified
+- `packages/nqui/src/components/AppLayout.tsx`
+- `packages/nqui/src/components/ui/card.tsx`
+- `packages/nqui/src/components/ui/frosted-glass.tsx`
+- `packages/nqui/src/components/custom/table-of-contents.tsx` (TOC scroll container fix)
+
+## Testing
+- ✅ Content visible and blurred behind AppLayout header when scrolling
+- ✅ Content visible and blurred behind Card sticky header when scrolling
+- ✅ Reflections from nearby elements visible (extended backdrop technique)
+- ✅ TOC navigation works with custom scroll container
+- ✅ No scroll shaking or reset issues
+- ✅ Smooth scrolling behavior maintained

package/docs/internal-notes/INSTALLATION.md

@@ -0,0 +1,274 @@
+# nqui Installation Guide
+
+## Requirements
+
+- **React 18 or 19**: nqui supports both via flexible peer dependencies (`^18.0.0 || ^19.0.0`).
+- **Tailwind CSS v4**: Required for component styling.
+- **Node.js**: See your framework requirements.
+
+---
+
+## Installation Sequence (Quick Reference)
+
+Run these commands in order:
+
+```bash
+# 1. Install nqui + peers (choose one)
+pnpm add @nqlib/nqui @hugeicons/react @hugeicons/core-free-icons   # Minimal (icons only)
+npx @nqlib/nqui install-peers                                      # Full (all optional peers)
+
+# 2. Setup CSS
+npx @nqlib/nqui init-css
+
+# 3. Add the nqui import to your main CSS file (see Step 2 details)
+#    Copy contents of nqui/nqui-setup.css to the TOP of app/globals.css (Next.js) or src/index.css (Vite)
+
+# 4. Optional: Debug tools
+npx @nqlib/nqui init-debug-css
+
+# 5. Optional: Refresh Cursor rules (auto-injected on install)
+npx @nqlib/nqui init-cursor
+```
+
+**Run `npx nqui-setup` anytime** to see this checklist again (with nqui installed).
+
+**Monorepo:** Skills are written to the package that has `@nqlib/nqui` (e.g. `apps/frontend/`). Open that folder in Cursor as your workspace.
+
+---
+
+## Step 1: Install nqui + Peers
+
+### Minimal (icons only)
+
+Required for Button, Accordion, Select, and most components with icons:
+
+```bash
+npm install @nqlib/nqui @hugeicons/react @hugeicons/core-free-icons
+# or
+pnpm add @nqlib/nqui @hugeicons/react @hugeicons/core-free-icons
+```
+
+### Full (all optional peers)
+
+For Sortable, Carousel, DataTable, Calendar, Command, Drawer, etc.:
+
+```bash
+npx @nqlib/nqui install-peers
+```
+
+This installs nqui + all optional peer dependencies. See [PEER_DEPENDENCIES.md](./PEER_DEPENDENCIES.md) for the component-to-peer mapping.
+
+---
+
+## Step 2: Setup CSS (Required)
+
+### 2a. Run init-css
+
+```bash
+npx @nqlib/nqui init-css
+```
+
+This creates:
+- `nqui/index.css` — imports from `@nqlib/nqui/styles`
+- `nqui/nqui-setup.css` — full Tailwind + nqui setup (framework-specific)
+
+### 2b. Add import to main CSS (manual step)
+
+**You must manually add the nqui import to your main CSS file.** Main files by framework:
+
+| Framework   | Main CSS file       |
+|-------------|---------------------|
+| Next.js     | `app/globals.css`   |
+| Vite        | `src/index.css`     |
+| Remix       | `app/root.css`      |
+
+**Option A (recommended):** Add at the top (after `@import "tailwindcss"`):
+
+```css
+@import "@nqlib/nqui/styles";
+```
+
+**Option B:** Copy the **entire contents** of `nqui/nqui-setup.css` and paste at the **very top** of your main CSS file.
+
+### 2c. Next.js + Tailwind v4 — @source directives
+
+If using Next.js, ensure these are in your main CSS:
+
+```css
+@source "./**/*.{js,ts,jsx,tsx,mdx}";
+@source "../components/**/*.{js,ts,jsx,tsx,mdx}";
+@source "../node_modules/@nqlib/nqui/dist/**/*.js";
+```
+
+### 2d. Custom path
+
+```bash
+npx @nqlib/nqui init-css app/styles/nqui.css
+```
+
+The generated CSS includes: design tokens, color scales, light/dark support. **It does not include Tailwind** — configure Tailwind separately.
+
+---
+
+## Step 3: Import Components
+
+```tsx
+import { Button, Input, Card } from "@nqlib/nqui";
+```
+
+**Note:** Next.js App Router pages using nqui need `"use client"`.
+
+---
+
+## Step 4: Debug Tools (Optional)
+
+### 4a. Run init-debug-css
+
+```bash
+npx @nqlib/nqui init-debug-css
+```
+
+Custom path: `npx @nqlib/nqui init-debug-css app/styles/debug.css`
+
+### 4b. Use DebugPanel
+
+```tsx
+'use client'; // Required for Next.js App Router
+
+import { DebugPanel } from "@nqlib/nqui";
+import "./nqui-debug.css"; // Path from init-debug-css
+
+export function App() {
+  return (
+    <>
+      <YourApp />
+      {process.env.NODE_ENV === 'development' && <DebugPanel />}
+    </>
+  );
+}
+```
+
+**Alternatives:** Import `@nqlib/nqui/debug.css` if your bundler supports it, or manually copy `node_modules/@nqlib/nqui/dist/nqui.css` into your project.
+
+---
+
+## Step 5: Cursor/IDE Rules (Auto-injected)
+
+On install, component guidelines are written to `.cursor/rules/nqui-components.mdc`. To refresh:
+
+```bash
+npx @nqlib/nqui init-cursor
+```
+
+Full per-component docs: `node_modules/@nqlib/nqui/docs/components/README.md`
+
+---
+
+## Step 6: Optional Peer Dependencies
+
+Install only when you use these components:
+
+| Component(s)      | Install |
+|-------------------|---------|
+| Sortable          | `pnpm add @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities` |
+| CommandPalette    | `pnpm add cmdk` |
+| Carousel          | `pnpm add embla-carousel-react` |
+| DataTable         | `pnpm add @tanstack/react-table` |
+| Calendar          | `pnpm add react-day-picker date-fns` |
+| Toaster / Sonner  | `pnpm add sonner` |
+| Drawer            | `pnpm add vaul` |
+| ResizablePanel    | `pnpm add react-resizable-panels` |
+| Combobox          | `pnpm add @base-ui/react` |
+| CodeBlock/Snippet | `pnpm add @nqlib/nqcode shiki @shikijs/transformers` |
+
+See [PEER_DEPENDENCIES.md](./PEER_DEPENDENCIES.md) for the full mapping.
+
+---
+
+## Framework-Specific Setup
+
+### Next.js App Router
+
+```tsx
+// app/layout.tsx
+'use client';
+
+import { DebugPanel } from "@nqlib/nqui";
+import "../../node_modules/@nqlib/nqui/dist/nqui.css"; // Direct path if package import fails
+
+export function DebugPanelClient() {
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => { setMounted(true); }, []);
+
+  if (process.env.NODE_ENV !== 'development' || !mounted) return null;
+  return <DebugPanel />;
+}
+```
+
+### Vite / Create React App
+
+```tsx
+// src/main.tsx
+import { DebugPanel } from "@nqlib/nqui";
+import "./nqui-debug.css";
+
+function App() {
+  return (
+    <>
+      <YourApp />
+      {import.meta.env.DEV && <DebugPanel />}
+    </>
+  );
+}
+```
+
+### Remix
+
+```tsx
+// app/root.tsx
+import { DebugPanel } from "@nqlib/nqui";
+import "./nqui-debug.css";
+
+export default function Root() {
+  return (
+    <html>
+      <body>
+        <Outlet />
+        {process.env.NODE_ENV === 'development' && <DebugPanel />}
+      </body>
+    </html>
+  );
+}
+```
+
+---
+
+## Troubleshooting
+
+### "Module not found: Can't resolve '@nqlib/nqui/styles'" or CSS not loading
+
+1. Run `npx @nqlib/nqui init-css`
+2. Add `@import "@nqlib/nqui/styles";` to the **top** of your main CSS file (app/globals.css or src/index.css)
+3. Ensure the import is **before** your other styles
+
+### nqui components render without styles
+
+The main CSS file is missing the nqui import. Add `@import "@nqlib/nqui/styles";` near the top. Or copy contents of `nqui/nqui-setup.css` into your main CSS.
+
+### Debug Panel not appearing
+
+1. Ensure `NODE_ENV !== 'production'`
+2. Import the debug CSS
+3. Verify `DebugPanel` is rendered in your app tree
+
+### Package import (nqui vs @nqlib/nqui)
+
+Use `@nqlib/nqui` — the package name. Old docs may reference `nqui`.
+
+---
+
+## Advanced: Custom CSS Location
+
+1. Run `npx @nqlib/nqui init-css your/path/nqui.css`
+2. Add the import from that path to your main CSS
+3. Or copy `nqui/nqui-setup.css` contents into your existing setup

package/docs/internal-notes/PEER_DEPENDENCIES.md

@@ -0,0 +1,105 @@
+# nqui Optional Peer Dependencies
+
+Heavy or feature-specific dependencies are externalized from the nqui bundle. Consumers using these components must install the corresponding packages.
+
+## Component-to-Peer Mapping
+
+| Component(s) | Peer Dependency |
+|--------------|-----------------|
+| Icons (HugeiconsIcon, most components with icons) | `@hugeicons/react`, `@hugeicons/core-free-icons` |
+| Sortable | `@dnd-kit/core`, `@dnd-kit/modifiers`, `@dnd-kit/sortable`, `@dnd-kit/utilities` |
+| Command, CommandPalette | `cmdk` |
+| Carousel | `embla-carousel-react` |
+| DataTable | `@tanstack/react-table` |
+| Calendar, EnhancedCalendar | `react-day-picker`, `date-fns` |
+| Toaster, Sonner | `sonner` |
+| Drawer | `vaul` |
+| ResizablePanelGroup, ResizablePanel, ResizableHandle | `react-resizable-panels` |
+| Combobox, EnhancedCombobox | `@base-ui/react` |
+
+## Code Display Components (@nqlib/nqcode)
+
+CodeBlock, CodeEditor, Snippet, and Sandbox are in a separate package. Install: `pnpm add @nqlib/nqcode shiki @shikijs/transformers`
+
+| Package | Components | Peer Dependencies |
+|---------|------------|-------------------|
+| `@nqlib/nqcode` | CodeBlock, CodeEditor, Snippet, Sandbox | @nqlib/nqui, shiki, @shikijs/transformers |
+| `@nqlib/nqcode/server` | CodeBlockContentServer (RSC) | shiki, @shikijs/transformers |
+
+## Subpath Exports (Smaller Bundles)
+
+Use subpath imports when you only need specific component groups. This keeps consumer bundles smaller by avoiding the full nqui bundle.
+
+| Subpath | Components | Peer Dependencies |
+|---------|------------|--------------------|
+| `@nqlib/nqui/carousel` | Carousel | embla-carousel-react |
+| `@nqlib/nqui/command` | Command, CommandPalette | cmdk |
+| `@nqlib/nqui/sortable` | Sortable | @dnd-kit/* |
+| `@nqlib/nqui/calendar` | Calendar | react-day-picker, date-fns |
+| `@nqlib/nqui/sonner` | Toaster, Sonner | sonner |
+| `@nqlib/nqui/drawer` | Drawer | vaul |
+
+Example:
+
+```ts
+// Full import (larger bundle)
+import { Carousel } from "@nqlib/nqui";
+
+// Subpath imports (smaller - only loads what you need)
+import { Carousel } from "@nqlib/nqui/carousel";
+
+// Code display (separate package)
+import { CodeBlock, Snippet } from "@nqlib/nqcode";
+```
+
+## Installation
+
+For a minimal setup (Button, Card, etc.), install nqui and the icon library:
+
+```bash
+pnpm add @nqlib/nqui @hugeicons/react @hugeicons/core-free-icons
+```
+
+For full library support (all components: Sortable, Carousel, DataTable, Calendar, etc.):
+
+```bash
+npx @nqlib/nqui install-peers
+```
+
+This installs nqui + all required and optional peer dependencies.
+
+To use Sortable:
+
+```bash
+pnpm add @nqlib/nqui @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities
+```
+
+To use Command/CommandPalette:
+
+```bash
+pnpm add @nqlib/nqui cmdk
+```
+
+To use Resizable panels:
+
+```bash
+pnpm add @nqlib/nqui react-resizable-panels
+```
+
+To use Combobox/EnhancedCombobox:
+
+```bash
+pnpm add @nqlib/nqui @base-ui/react
+```
+
+To use CodeBlock, CodeEditor, Snippet, or Sandbox:
+
+```bash
+pnpm add @nqlib/nqui @nqlib/nqcode shiki @shikijs/transformers
+```
+
+And so on for each component group above.
+
+## Rationale
+
+Externalizing these dependencies keeps the core nqui bundle smaller. Users who only need basic components (Button, Input, Card) do not pay for Sortable, Carousel, or CodeBlock dependencies.