@nqlib/nqui 0.4.5 → 0.4.7

package/dist/styles.css

@@ -1185,8 +1185,9 @@
     --secondary-foreground: oklch(0.3067 0.0309 56.81);
     --muted: oklch(0.9111 0.0082 73.15);
     --muted-foreground: oklch(0.5576 0.0222 57.81);
-    --accent: oklch(0.4789 0.0623 56.16);
-    --accent-foreground: oklch(0.9792 0.0042 78.3);
+    /* Hover/focus wash (menus, ghost buttons) — high L like :root accent, not a filled control */
+    --accent: oklch(0.935 0.011 73.15);
+    --accent-foreground: oklch(0.2416 0.0219 57);
     --border: oklch(0.89 0.0137 73.1);
     --input: oklch(0.89 0.0137 73.1);
 

package/docs/components/nqui-card.md

@@ -35,5 +35,5 @@ import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter }
 - **Layout / bounds:** Root **Card**, **CardHeader**, **CardContent**, and **CardFooter** include **`min-w-0`** so nested flex/grid layouts can shrink and children are less likely to spill horizontally. **Card** stays **`overflow-visible`** on purpose so popovers, menus, and focus rings are not clipped—pair with bounded components (buttons, carousel insets, `truncate`, etc.) instead of `overflow-hidden` on the card by default.
 - **stickyHeader:** Use `stickyHeader` prop on Card for scrollable content with sticky header. The header uses `--z-sticky-content` (z-index: 15).
 - **Z-index layering:** Card sticky headers (15) are below page headers (20). If using in a page with sticky header, ensure proper z-index layering.
-- **Height required:** Card needs a defined height (e.g., `h-[400px]` or `h-full`) for sticky behavior to work.
+- **Height required:** Card needs a bounded height (e.g., `h-[400px]`, `h-80`, or `h-full` inside a fixed-height parent). **`max-h-*` alone is not enough**—the card still grows with content, so the scroll body will not overflow. Clip frosted glass with an outer `overflow-hidden rounded-*` wrapper if needed; avoid `overflow-hidden` on the Card root with `stickyHeader` (it can break Radix ScrollArea).
 - **Content scroll:** The CardContent becomes scrollable when Card has `stickyHeader` and a defined height.

package/docs/components/nqui-combobox.md

@@ -1,12 +1,13 @@
 # nqui Combobox
 
-> **Searchable** select (Base UI). User types to filter options. Single or multiple selection.
+> **Searchable** select (Radix Popover + cmdk). Type in `**ComboboxInput`** to filter; a hidden cmdk input stays in sync. Single or multiple selection.
 
 ## When to Use
 
-- **Selection:** Single (default) or multiple (`multiple` on root)
-- **Key feature:** Filter list by typing in the input
-- **Options:** Many rows; use **`items`** on `Combobox` + render prop on `ComboboxList` for built-in filtering
+- **Selection:** Single (default) or multiple (`multiple` on root — items toggle; popover stays open until dismissed)
+- **Filter:** Type in the **trigger field** while the list is open (same `search` state as cmdk)
+- **Icons:** Put icons (or other nodes) inside `**ComboboxItem`**; use `**keywords**` if the visible label text is not enough for matching
+- **Options:** Many rows; use `**items`** on `Combobox` + render prop on `ComboboxList` for built-in filtering
 
 **Choose Combobox when:** Users need search. Use **Select** when a plain dropdown is enough.
 
@@ -16,6 +17,7 @@
 import {
   Combobox,
   ComboboxInput,
+  ComboboxBadgeTrigger,
   ComboboxContent,
   ComboboxList,
   ComboboxItem,
@@ -36,16 +38,16 @@ import {
 
 ## Single selection + type-to-filter (recommended)
 
-Pass **`items`** to `Combobox` and use a **render function** as the only child of `ComboboxList`. Place **`ComboboxEmpty`** next to `ComboboxList` (both under `ComboboxContent`), not inside `ComboboxList` alongside the function.
+Pass `**items**` to `Combobox` and use a **render function** on `ComboboxList`. Put `**ComboboxEmpty`** first inside `**ComboboxList**` (cmdk empty state).
 
 ```tsx
 const fruits = ["Apple", "Banana", "Cherry", "Date", "Elderberry"]
 
-<Combobox items={fruits}>
-  <ComboboxInput placeholder="Search..." />
+<Combobox items={fruits} searchPlaceholder="Filter…">
+  <ComboboxInput placeholder="Pick a fruit…" />
   <ComboboxContent>
-    <ComboboxEmpty>No results found.</ComboboxEmpty>
     <ComboboxList>
+      <ComboboxEmpty>No results found.</ComboboxEmpty>
       {(item) => (
         <ComboboxItem key={item} value={item}>
           {item}
@@ -78,17 +80,79 @@ You can still render `ComboboxItem` children manually when you control filtering
 <ComboboxInput showClear placeholder="Search..." />
 ```
 
-## Multiple selection
+## Multiple selection (badge trigger)
+
+Use `**ComboboxBadgeTrigger**` as the anchor (outline button, badges, **maxShownItems** truncation, **+N more** / **Show less**). Pair with `**ComboboxContent showPanelSearch`** so users type in the **panel** search field (matches typical multi-select combobox UX).
+
+```tsx
+<Combobox multiple items={ids} value={value} onValueChange={setValue} searchPlaceholder="Search…">
+  <ComboboxBadgeTrigger placeholder="Select…" maxShownItems={2} />
+  <ComboboxContent showPanelSearch>
+    <ComboboxList>
+      <ComboboxEmpty>No results.</ComboboxEmpty>
+      {(id) => (
+        <ComboboxItem key={id} value={id}>
+          {resolveLabel(id)}
+        </ComboboxItem>
+      )}
+    </ComboboxList>
+  </ComboboxContent>
+</Combobox>
+```
+
+For a custom chip row, you can still use `**ComboboxChips**`, `**ComboboxChip**`, and `**ComboboxChipsInput**` inside `**ComboboxContent**`.
+
+## Development-only diagnostics
+
+Pass `**debug**` on `**Combobox**` to log open state, value, search, and list id (only when `**import.meta.env.DEV**` is true, e.g. Vite dev). No logging in production builds.
+
+```tsx
+<Combobox debug defaultValue="us">
+  ...
+</Combobox>
+```
+
+## Architecture (internal)
+
+The public API is unchanged; the implementation composes:
+
+
+| Layer                              | Role                                                                                                                       |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `**radix-ui` Popover**             | Same primitives as `popover.tsx` (`Root`, `Anchor`, `Portal`, `Content`) — one Radix entrypoint for positioning and focus. |
+| `**Command` (cmdk)**               | Panel search + list; order matches the command palette: `**CommandInput`** then list children.                             |
+| `**ComboboxList` → `CommandList**` | Ref reads the **real** list node id after mount for `**aria-controls`** on the trigger (see cmdk constraints below).       |
+| `**ComboboxItem` → `CommandItem**` | Shared row styles and checkmark behavior with `**CommandPalette**` / cmdk.                                                 |
+
+
+When `**showPanelSearch**` is false, the panel `**CommandInput**` is wrapped in `**sr-only**` (not `hidden` / `display: none`) so cmdk filtering stays consistent.
+
+## cmdk constraints
+
+- **List `id`:** cmdk **overwrites** the `id` on `Command.List`. Do not assume `useId()` matches the DOM — the combobox mirrors the mounted list element’s id into context for `**aria-controls`**.
+- **Selection styling:** Prefer `**aria-selected`** / `**data-selected**` (boolean) utilities. Patterns like `**data-[selected=true]:**` can fail because the attribute is not always the string `"true"`.
+- **Panel input:** Keep the cmdk input **mounted** when filtering (see `**sr-only`** branch above).
+
+## Troubleshooting
+
+
+| Symptom                                                      | What to check                                                                                                                                                                                                                                                                                                                                                      |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Trigger `**aria-controls**` missing or wrong                 | `**ComboboxList**` must mount while the popover is open so the list ref can read `**id**`.                                                                                                                                                                                                                                                                         |
+| Row highlight / keyboard selection looks wrong               | Styles targeting only `**data-[selected=true]**`; use `**aria-selected:**` or boolean `**data-selected**` variants.                                                                                                                                                                                                                                                |
+| **Mouse hover / click on rows does nothing; keyboard works** | Row styles must not use a broad `**data-[disabled]:pointer-events-none`** (can match any `data-disabled` value). Use `**aria-disabled:**` (or `**data-[disabled=true]:**`) so only disabled items drop pointer events. Hidden panel search is wrapped with `**sr-only**` + `**pointer-events-none**`; the cmdk `**CommandInput**` keeps `**pointer-events-auto**`. |
+| Filter feels out of sync                                     | Avoid hiding the panel `**CommandInput**` with `**display: none**`.                                                                                                                                                                                                                                                                                                |
 
-Use **`multiple`** on `Combobox` (see [Base UI Combobox](https://base-ui.com/react/components/combobox)). Combine with **`ComboboxChips`**, **`ComboboxChip`**, **`ComboboxChipsInput`** as needed for chip UI.
 
 ## Implementation
 
 - **Source:** `packages/nqui/src/components/ui/combobox.tsx`
 - **Public API:** exported from `@nqlib/nqui` (same as `CoreCombobox*` aliases in the barrel if you need the unprefixed base re-exports)
 - **Styling:** Input group uses injected CSS once per page (`nqui-combobox-styles-v1`) for trigger depth/shadow; component is `"use client"`.
+- **Docs location:** In-repo `packages/nqui/docs/components/`; in apps, `node_modules/@nqlib/nqui/docs/components/` (docs ship with the npm package). Skill: **nqui-components** (`.cursor/skills/nqui-components/SKILL.md`).
 
 ## Notes
 
-- **`useComboboxAnchor`:** ref for anchoring `ComboboxContent` when using chips / custom layout.
+- `**useComboboxAnchor`:** returns a ref to pass to `**PopoverAnchor`** (from `@nqlib/nqui`) wrapping the chips row so the dropdown positions correctly when using `**ComboboxChips**` / custom layout.
 - **Dropdown items:** spacing/hover treatment aligns with **Select** (`SelectItem`-style density).
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nqlib/nqui",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "A React component library with enhanced UI components and developer tools",
   "type": "module",
   "main": "./dist/nqui.cjs.js",
@@ -139,7 +139,6 @@
     "@radix-ui/react-direction": "^1.1.1",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-label": "^2.1.8",
-    "@radix-ui/react-popover": "^1.1.15",
     "@radix-ui/react-select": "^2.2.6",
     "@radix-ui/react-separator": "^1.1.8",
     "@radix-ui/react-slot": "^1.2.4",
@@ -178,7 +177,6 @@
     "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",
@@ -232,13 +230,9 @@
     },
     "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",

package/scripts/generate-docs.js

@@ -17,6 +17,8 @@ import { fileURLToPath } from 'url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const DOCS_DIR = join(__dirname, '../docs');
+/** Maintainer-only notes; not under docs/ so they are not shipped in the npm `docs` bundle. */
+const INTERNAL_NOTES_DIR = join(__dirname, '../internal-notes');
 const OUTPUT_DIR = join(__dirname, '../dist/docs');
 
 // Ensure output directory exists
@@ -37,7 +39,7 @@ function readDoc(filePath) {
 }
 
 function generateInstallDoc() {
-  const installPath = join(DOCS_DIR, 'internal-notes/INSTALLATION.md');
+  const installPath = join(INTERNAL_NOTES_DIR, 'INSTALLATION.md');
   let content = readDoc(installPath);
   
   if (!content) {

package/scripts/peer-deps.js

@@ -21,7 +21,6 @@ export const OPTIONAL_PEERS = [
   'sonner',
   'vaul',
   'react-resizable-panels',
-  '@base-ui/react',
 ];
 
 export const FULL_PEER_LIST = [...REQUIRED_PEERS, ...OPTIONAL_PEERS];

package/docs/internal-notes/APP_BUILDER_PACKAGE.md

@@ -1,86 +0,0 @@
-# App Builder Package (@nqlib/nqappbuilder)
-
-## Overview
-
-The App Builder has been extracted from nqui into a separate package `@nqlib/nqappbuilder` to reduce nqui's bundle size and allow independent versioning. The visual app builder includes a drag-and-drop canvas, widget palette, configurator, and registry system.
-
-## Installation
-
-```bash
-pnpm add @nqlib/nqappbuilder @nqlib/nqui
-# or
-npm install @nqlib/nqappbuilder @nqlib/nqui
-```
-
-## Peer Dependencies
-
-- `react` (^18.2.0)
-- `react-dom` (^18.2.0)
-- `@nqlib/nqui` (required) — provides UI components, design tokens, and utilities
-
-Consumers must install these alongside nqappbuilder.
-
-## Usage
-
-```tsx
-import {
-  AppBuilder,
-  AppBuilderProvider,
-  AppCanvas,
-  WidgetPalette,
-  WidgetConfigurator,
-  defaultRegistry,
-} from "@nqlib/nqappbuilder"
-
-// All-in-one component
-export default function MyAppBuilder() {
-  return (
-    <AppBuilderProvider registry={defaultRegistry}>
-      <AppBuilder />
-    </AppBuilderProvider>
-  )
-}
-
-// Or compose manually
-export default function CustomLayout() {
-  return (
-    <AppBuilderProvider registry={defaultRegistry}>
-      <aside>
-        <WidgetPalette />
-      </aside>
-      <main>
-        <AppCanvas showToolbar enableCollisionDetection />
-      </main>
-      <WidgetConfigurator />
-    </AppBuilderProvider>
-  )
-}
-```
-
-## Extending the Registry
-
-Use `createWidgetRegistry`, `extendRegistry`, or pass a custom `registry` to `AppBuilderProvider`:
-
-```tsx
-import {
-  createWidgetRegistry,
-  extendRegistry,
-  defaultRegistry,
-  buttonWidget,
-  containerWidget,
-} from "@nqlib/nqappbuilder"
-
-const myRegistry = extendRegistry(defaultRegistry, [
-  buttonWidget,
-  containerWidget,
-  myCustomWidget,
-])
-
-<AppBuilderProvider registry={myRegistry}>
-  <AppBuilder />
-</AppBuilderProvider>
-```
-
-## Documentation App
-
-Documentation maintainers: add a section or page for nqappbuilder in the documentation app. Link to this note for package details and migration context.

package/docs/internal-notes/BUILD_VERIFICATION.md

@@ -1,174 +0,0 @@
-# Build Verification Report
-
-This document provides a comprehensive comparison between source CSS files and the built `dist/styles.css` to ensure no content is missing or broken during the build process.
-
-## Verification Script
-
-Run the verification script after building:
-
-```bash
-npm run verify:build
-```
-
-Or manually:
-
-```bash
-node scripts/verify-build.js
-```
-
-## Verification Checks
-
-The verification script performs the following checks:
-
-### 1. @source inline() Directives
-- ✅ Verifies all 15 `@source inline()` directives are preserved
-- ✅ Checks that all categories are present (Layout, Spacing, Typography, etc.)
-- ✅ Ensures no directives are missing or duplicated
-
-### 2. :root CSS Variables
-- ✅ Extracts all CSS variables from `src/index.css`, `src/styles/colors.css`, and `src/styles/elevation.css`
-- ✅ Verifies all variables are present in the built CSS
-- ✅ Checks for missing or extra variables
-
-### 3. .dark CSS Variables
-- ✅ Extracts all dark mode CSS variables from source files
-- ✅ Verifies all dark mode variables are preserved
-- ✅ Ensures proper merging of variables from multiple sources
-
-### 4. Custom CSS Classes
-- ✅ Checks for custom `.nqui-*` classes (e.g., `.nqui-button-gradient`, `.nqui-debug-panel`)
-- ✅ Verifies all custom classes are present in the built CSS
-
-### 5. Utility Classes in @source inline()
-- ✅ Extracts all utility class names from `@source inline()` directives
-- ✅ Verifies all 137+ utility classes are preserved
-- ✅ Ensures no utility classes are missing
-
-### 6. Critical Patterns
-- ✅ Checks for presence of `@source inline()` directives
-- ✅ Verifies `:root` and `.dark` blocks exist
-- ✅ Validates specific elevation variables (--z-base, --z-content, etc.)
-- ✅ Validates specific color variables (--primary-500, --background, etc.)
-
-### 7. Unwanted Patterns
-- ✅ Ensures `@import` directives are removed
-- ✅ Ensures `@custom-variant` directives are removed
-- ✅ Ensures framework-specific `@source` directives are removed
-
-## Expected Results
-
-### File Sizes
-- **Source index.css**: ~20 KB
-- **Built styles.css**: ~35 KB (includes merged colors.css and elevation.css)
-- **Colors.css**: ~6 KB
-- **Elevation.css**: ~10 KB
-
-### Content Counts
-- **@source inline() directives**: 15 (17 occurrences including comments)
-- **:root blocks**: 1 (merged from all sources)
-- **.dark blocks**: 1 (merged from all sources)
-- **CSS variables**: ~240 total
-- **Custom classes**: 4 (.nqui-button-gradient, .nqui-button-shadow, .nqui-debug-panel, .nqui-shiki-container)
-- **@keyframes**: 6
-- **@layer base**: 1
-
-### Structure Verification
-- ✅ `@source inline()` directives present
-- ✅ `@theme inline` present
-- ✅ `:root` block present
-- ✅ `.dark` block present
-- ✅ Elevation variables present (11 variables)
-- ✅ Color variables present (all primary, background, foreground, etc.)
-- ✅ Custom classes present
-- ✅ No `@import` directives
-- ✅ No `@custom-variant` directives
-
-## Build Process
-
-The build process (`scripts/build-styles.js`) performs the following steps:
-
-1. **Extract @source inline() directives** - Preserves all `@source inline()` directives before processing
-2. **Remove framework-specific directives** - Removes `@import`, `@custom-variant`, and non-inline `@source` directives
-3. **Extract CSS variables** - Extracts `:root` and `.dark` blocks from:
-   - `src/index.css`
-   - `src/styles/colors.css`
-   - `src/styles/elevation.css`
-4. **Merge variables** - Merges variables from all sources in the correct order:
-   - Elevation variables first
-   - Color system variables second
-   - Additional variables from index.css last
-5. **Preserve custom classes** - Keeps all custom CSS classes (`.nqui-*`)
-6. **Preserve @theme inline** - Keeps the `@theme inline` block
-7. **Preserve @keyframes** - Keeps all animation keyframes
-8. **Add header** - Adds documentation header
-9. **Prepend @source inline()** - Adds extracted `@source inline()` directives at the top
-
-## Common Issues
-
-### Missing @source inline() Directives
-**Symptom**: Verification fails with "Missing @source inline() directives"
-
-**Cause**: The build script's regex might not be matching multiline directives correctly.
-
-**Fix**: Ensure the regex uses `[\s\S]*?` for multiline matching:
-```javascript
-const sourceInlineRegex = /\/\*[^*]*\*+(?:[^/*][^*]*\*+)*\/\s*@source\s+inline\([\s\S]*?\)\s*;/g;
-```
-
-### Missing CSS Variables
-**Symptom**: Verification fails with "Missing X variables"
-
-**Cause**: The extraction regex might not be handling nested braces correctly.
-
-**Fix**: Ensure the regex uses a pattern that handles nested braces:
-```javascript
-const regex = /:root\s*\{([^}]+(?:\{[^}]*\}[^}]*)*)\}/s;
-```
-
-### Duplicate @source inline() Directives
-**Symptom**: Verification shows more directives than expected
-
-**Cause**: The removal regex might not be matching correctly, causing directives to be added twice.
-
-**Fix**: Ensure the removal regex matches the extraction regex exactly.
-
-## Integration with CI/CD
-
-Add verification to your build pipeline:
-
-```yaml
-# Example GitHub Actions workflow
-- name: Build library
-  run: npm run build:lib
-
-- name: Verify build integrity
-  run: npm run verify:build
-```
-
-## Manual Verification
-
-To manually verify specific aspects:
-
-```bash
-# Check @source inline() directives
-grep -c "@source inline" dist/styles.css
-
-# Check CSS variables
-grep -c "--.*:" dist/styles.css
-
-# Check custom classes
-grep -c "\.nqui-" dist/styles.css
-
-# Check for unwanted patterns
-grep "@import" dist/styles.css  # Should return nothing
-grep "@custom-variant" dist/styles.css  # Should return nothing
-```
-
-## Related Files
-
-- `scripts/build-styles.js` - Build script that generates `dist/styles.css`
-- `scripts/verify-build.js` - Verification script
-- `src/index.css` - Main source CSS file
-- `src/styles/colors.css` - Color system variables
-- `src/styles/elevation.css` - Z-index elevation variables
-- `dist/styles.css` - Built CSS file (generated)