@nqlib/nqui 0.3.1 → 0.3.3

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/PUBLISHING.md

@@ -0,0 +1,339 @@
+# Publishing Guide
+
+This guide covers publishing to both **npmjs.com** (public, no auth needed) and **GitHub Packages** (requires GitHub account).
+
+## Prerequisites
+
+1. **Build the library**
+   ```bash
+   npm run build:lib
+   ```
+   Verify `dist/` folder contains all required files.
+
+2. **Authentication** (only needed for GitHub Packages)
+   - GitHub Personal Access Token with `write:packages` permission
+   - For npmjs.com: Create account at npmjs.com and run `npm login`
+
+## Publishing Options
+
+### Option 1: Publish to npmjs.com (Recommended for Public Use)
+
+**Why:** Anyone can install without authentication - works like `npm install react`
+
+**Important:** Scoped packages (`@nqlib/nqui`) require either:
+- An npm organization (paid, $7/month) - Create at: https://www.npmjs.com/org/create
+- OR use your username scope: `@ctesibius/nqui` (free)
+- OR publish unscoped: `nqui` (free, but name must be available)
+
+**Steps:**
+
+1. **Set up scope** (if using `@nqlib` scope):
+   - Create npm organization: https://www.npmjs.com/org/create
+   - Organization name: `nqlib`
+   - Requires paid plan ($7/month per user)
+
+2. **Enable 2FA on npmjs.com** (required for publishing)
+   - Go to: https://www.npmjs.com/settings/[your-username]/security
+   - Enable "Two-factor authentication"
+   - Follow the setup instructions (use an authenticator app like Google Authenticator or Authy)
+   - **OR** create a granular access token with "publish" permission and "bypass 2FA" enabled:
+     - Go to: https://www.npmjs.com/settings/[your-username]/tokens
+     - Click "Generate New Token" → "Granular Access Token"
+     - Select "Publish" permission
+     - Enable "Bypass 2FA" (if available)
+     - Copy the token (you'll only see it once!)
+
+3. **Login to npmjs.com** (one-time setup or when credentials expire)
+   ```bash
+   cd packages/nqui
+   npm login --registry=https://registry.npmjs.com
+   ```
+   - Username: Your npmjs.com username
+   - Password: Your npmjs.com password (or use the granular token as password if using token)
+   - Email: Your npmjs.com email
+   - OTP: Enter your 2FA code if prompted (if using 2FA)
+   
+   **Verify login:**
+   ```bash
+   npm whoami --registry=https://registry.npmjs.com
+   ```
+
+4. **Update version** (if needed)
+   ```bash
+   npm version patch   # 0.1.0 → 0.1.1
+   npm version minor   # 0.1.0 → 0.2.0
+   npm version major   # 0.1.0 → 1.0.0
+   ```
+
+5. **Publish**
+   ```bash
+   npm run publish:npm
+   # or
+   npm publish --registry=https://registry.npmjs.com --access=public
+   ```
+
+**Users install with:**
+```bash
+npm install @nqlib/nqui
+```
+No `.npmrc` or token needed! ✅
+
+---
+
+### Option 2: Publish to GitHub Packages
+
+**Why:** Good for organization packages, version control integration
+
+**Steps:**
+
+1. **Setup authentication** (one-time setup)
+   
+   **Option A: Using `.npmrc` file (Recommended)**
+   
+   Ensure `.npmrc` exists in the project root (`/Users/bnguyen/Desktop/Github/nqui/.npmrc`):
+   ```
+   //npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
+   @nqlib:registry=https://npm.pkg.github.com
+   ```
+   
+   **Before publishing, copy `.npmrc` to the package directory:**
+   ```bash
+   cd packages/nqui
+   cp ../../.npmrc .npmrc
+   ```
+   
+   **Option B: Interactive login**
+   ```bash
+   cd packages/nqui
+   npm login --registry=https://npm.pkg.github.com
+   ```
+   - Username: Your GitHub username
+   - Password: Your GitHub Personal Access Token (not password!)
+   - Email: Your GitHub email
+   
+   **Verify authentication:**
+   ```bash
+   npm whoami --registry=https://npm.pkg.github.com
+   ```
+
+2. **Update version** (if needed)
+   ```bash
+   npm version patch
+   ```
+
+3. **Publish**
+   ```bash
+   cd packages/nqui
+   # If using .npmrc method, ensure it's copied first:
+   cp ../../.npmrc .npmrc
+   
+   npm run publish:github
+   # or
+   npm publish --registry=https://npm.pkg.github.com
+   ```
+   
+   **Note:** The `.npmrc` file in `packages/nqui/` is gitignored and won't be committed.
+
+**Users install with:**
+```bash
+# Create .npmrc in their project
+echo "@nqlib:registry=https://npm.pkg.github.com" > .npmrc
+
+# Authenticate (they need their own GitHub token)
+npm login --registry=https://npm.pkg.github.com
+
+# Install
+npm install @nqlib/nqui
+```
+
+⚠️ **Note:** Users need GitHub account + token even for public packages.
+
+---
+
+### Option 3: Publish to Both Registries
+
+**Best of both worlds:** Maximum accessibility
+
+**Steps:**
+
+1. **Setup authentication for both registries**
+   
+   **For GitHub Packages:**
+   ```bash
+   cd packages/nqui
+   cp ../../.npmrc .npmrc
+   ```
+   
+   **For npmjs.com:**
+   ```bash
+   cd packages/nqui
+   npm login --registry=https://registry.npmjs.com
+   ```
+
+2. **Update version** (if needed)
+   ```bash
+   npm version patch
+   ```
+
+3. **Publish to both**
+   ```bash
+   cd packages/nqui
+   npm run publish:both
+   ```
+
+   This will:
+   - Publish to GitHub Packages first
+   - Then publish to npmjs.com
+
+**Users can choose:**
+- **npmjs.com**: `npm install @nqlib/nqui` (no auth needed)
+- **GitHub Packages**: Requires GitHub token (see Option 2)
+
+---
+
+### Publishing to Missing Registry Only
+
+If you've already published to one registry, you can publish the same version to the other:
+
+**Already on GitHub Packages, need npmjs.com:**
+```bash
+npm run publish:npm
+```
+
+**Already on npmjs.com, need GitHub Packages:**
+```bash
+npm run publish:github
+```
+
+**Note:** Different registries can have the same version number - they're independent.
+
+---
+
+## Version Management
+
+The `npm version` command automatically:
+- Updates `package.json` version
+- Creates a git tag
+- Commits the change
+
+**Version types:**
+- `patch`: Bug fixes (0.1.0 → 0.1.1)
+- `minor`: New features, backward compatible (0.1.0 → 0.2.0)
+- `major`: Breaking changes (0.1.0 → 1.0.0)
+
+---
+
+## Verification
+
+After publishing, verify:
+
+**npmjs.com:**
+- Visit: `https://www.npmjs.com/package/@nqlib/nqui`
+- Test install: `npm install @nqlib/nqui` (in a fresh project)
+
+**GitHub Packages:**
+- Visit: `https://github.com/nqlib/nqui/packages`
+- Check package visibility settings
+
+---
+
+## Troubleshooting
+
+### "401 Unauthorized" (GitHub Packages)
+- Verify token has `write:packages` permission
+- Check token hasn't expired
+- Ensure you're authenticated: `npm whoami --registry=https://npm.pkg.github.com`
+
+### "403 Forbidden" (GitHub Packages)
+- Verify repository ownership matches package scope (`@nqlib`)
+- Check package visibility settings in GitHub
+
+### "404 Not Found - Scope not found" (npmjs.com)
+- The scope `@nqlib` doesn't exist on npmjs.com
+- **Solution 1**: Create an npm organization named `nqlib` at https://www.npmjs.com/org/create (requires paid plan)
+- **Solution 2**: Change package name to `@ctesibius/nqui` (uses your username scope, free)
+- **Solution 3**: Publish as unscoped package `nqui` (check name availability first)
+
+### "403 Forbidden - Two-factor authentication required" (npmjs.com)
+- **Enable 2FA** on your npmjs.com account:
+  - Visit: https://www.npmjs.com/settings/[your-username]/security
+  - Enable "Two-factor authentication"
+- **OR** use a granular access token:
+  - Visit: https://www.npmjs.com/settings/[your-username]/tokens
+  - Create a token with "Publish" permission
+  - Use the token as your password when logging in
+
+### "404 Not Found" (npmjs.com)
+- Ensure package name is available (scoped packages like `@nqlib/nqui` are always available)
+- Verify you're logged in: `npm whoami`
+
+### "Package name already exists" (npmjs.com)
+- Someone else owns that name
+- Use a different scope or name
+
+---
+
+## Access Control Summary
+
+### npmjs.com
+- ✅ **Public packages**: Anyone can install, no authentication needed
+- ✅ **Private packages**: Requires paid npm account
+- ✅ **Scoped packages** (`@nqlib/nqui`): Always available, no name conflicts
+
+### GitHub Packages
+- ⚠️ **Public packages**: Anyone can install, but requires GitHub account + token
+- 🔒 **Private packages**: Requires explicit access grant
+- 📦 **Package visibility**: Inherits from repository visibility by default
+
+---
+
+## Recommended Workflow
+
+For maximum accessibility:
+
+1. **Publish to npmjs.com** (primary)
+   - Zero friction for users
+   - Standard npm experience
+
+2. **Also publish to GitHub Packages** (optional)
+   - For users who prefer GitHub ecosystem
+   - Better integration with GitHub Actions/CI
+
+**Complete workflow:**
+```bash
+# 1. Navigate to package directory
+cd packages/nqui
+
+# 2. Setup authentication
+cp ../../.npmrc .npmrc  # For GitHub Packages
+npm login --registry=https://registry.npmjs.com  # For npmjs.com (if not already logged in)
+
+# 3. Update version and publish
+npm version patch
+npm run publish:both
+```
+
+**Quick reference - Login commands:**
+```bash
+# Login to npmjs.com
+cd packages/nqui
+npm login --registry=https://registry.npmjs.com
+
+# Login to GitHub Packages (alternative to .npmrc)
+cd packages/nqui
+npm login --registry=https://npm.pkg.github.com
+
+# Verify authentication
+npm whoami --registry=https://registry.npmjs.com
+npm whoami --registry=https://npm.pkg.github.com
+```
+
+---
+
+## Security Notes
+
+- ✅ **DO**: Use `npm login` (stores credentials securely)
+- ✅ **DO**: Use environment variables in CI/CD
+- ❌ **DON'T**: Commit tokens to git
+- ❌ **DON'T**: Share tokens publicly
+- ✅ **DO**: Add `.npmrc` to `.gitignore` (already done)