@nqlib/nqui 0.3.2 → 0.3.3

package/docs/components/nqui-toaster.md

@@ -0,0 +1,44 @@
+# nqui Toaster
+
+> Toast notifications (sonner). Semantic types, promise pattern.
+
+## Import
+
+```tsx
+import { Toaster, toast } from "@nqlib/nqui"
+```
+
+## Setup
+
+```tsx
+// Add once (e.g. layout)
+<Toaster />
+```
+
+## Types
+
+```tsx
+toast.success("Saved")
+toast.error("Failed")
+toast.warning("Warning")
+toast.info("Info")
+toast("Default")
+toast.loading("Loading...")
+```
+
+## Promise
+
+```tsx
+toast.promise(fetchData(), {
+  loading: "Loading...",
+  success: "Done",
+  error: "Failed"
+})
+```
+
+## Options
+
+```tsx
+toast.success("Msg", { duration: 5000 })
+// Toaster: position, richColors, etc.
+```

package/docs/components/nqui-toggle-group.md

@@ -0,0 +1,21 @@
+# nqui ToggleGroup
+
+> Group of toggle buttons. Single or multiple selection.
+
+## Import
+
+```tsx
+import { ToggleGroup, ToggleGroupItem } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<ToggleGroup type="single" value={v} onValueChange={setV}>
+  <ToggleGroupItem value="a">A</ToggleGroupItem>
+  <ToggleGroupItem value="b">B</ToggleGroupItem>
+</ToggleGroup>
+<ToggleGroup type="multiple" value={vals} onValueChange={setVals}>
+  ...
+</ToggleGroup>
+```

package/docs/components/nqui-toggle.md

@@ -0,0 +1,15 @@
+# nqui Toggle
+
+> Toggle button. Core Radix.
+
+## Import
+
+```tsx
+import { Toggle } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Toggle pressed={pressed} onPressedChange={setPressed}>Toggle</Toggle>
+```

package/docs/components/nqui-tooltip.md

@@ -0,0 +1,24 @@
+# nqui Tooltip
+
+> Hover tooltip. Wrap app in TooltipProvider.
+
+## Import
+
+```tsx
+import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<TooltipProvider>
+  <Tooltip>
+    <TooltipTrigger asChild><Button>Hover</Button></TooltipTrigger>
+    <TooltipContent>Tooltip text</TooltipContent>
+  </Tooltip>
+</TooltipProvider>
+```
+
+## Provider
+
+Place once at app root (or layout).

package/docs/components/nqui-tracker.md

@@ -0,0 +1,38 @@
+# nqui Tracker
+
+> GitHub-style block strip. Activity/status visualization. Tooltips.
+
+## Import
+
+```tsx
+import { Tracker } from "@nqlib/nqui"
+import type { TrackerBlockProps } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Tracker
+  data={[
+    { color: "bg-emerald-600", tooltip: "Active" },
+    { color: "bg-red-600", tooltip: "Error" },
+    { tooltip: "No data" }
+  ]}
+/>
+```
+
+## Options
+
+```tsx
+<Tracker
+  data={data}
+  hoverEffect
+  defaultBackgroundColor="bg-muted"
+/>
+```
+
+## Notes
+
+- `color` must be Tailwind class (e.g. `bg-emerald-600`), not hex.
+- Wrap in `TooltipProvider` for tooltips.
+- Blocks without `color` use `defaultBackgroundColor`.

package/docs/internal-notes/BUILD_VERIFICATION.md

@@ -0,0 +1,174 @@
+# 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)