@jmruthers/pace-core 0.5.181 → 0.5.183

package/docs/getting-started/installation-guide.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T14:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # PACE Core Installation Guide
@@ -17,7 +17,7 @@ reviewedBy: content-audit
 npm install @jmruthers/pace-core
 
 # 2. Install peer dependencies
-npm install @tanstack/react-table @radix-ui/react-checkbox @radix-ui/react-dialog @radix-ui/react-dropdown-menu @radix-ui/react-label @radix-ui/react-slot lucide-react class-variance-authority clsx tailwind-merge
+npm install react react-dom @tanstack/react-table @radix-ui/react-avatar @radix-ui/react-checkbox @radix-ui/react-dialog @radix-ui/react-label @radix-ui/react-progress @radix-ui/react-slot @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-toast @radix-ui/react-tooltip lucide-react react-day-picker react-hook-form react-router-dom clsx tailwind-merge zod
 
 # 3. Install Tailwind v4
 npm install -D @tailwindcss/vite tailwindcss@^4.0.0
@@ -36,9 +36,11 @@ npm install @jmruthers/pace-core
 
 **Required Peer Dependencies:**
 ```bash
-npm install @tanstack/react-table @radix-ui/react-checkbox @radix-ui/react-dialog @radix-ui/react-dropdown-menu @radix-ui/react-label @radix-ui/react-slot lucide-react class-variance-authority clsx tailwind-merge
+npm install react react-dom @tanstack/react-table @radix-ui/react-avatar @radix-ui/react-checkbox @radix-ui/react-dialog @radix-ui/react-label @radix-ui/react-progress @radix-ui/react-slot @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-toast @radix-ui/react-tooltip lucide-react react-day-picker react-hook-form react-router-dom clsx tailwind-merge zod
 ```
 
+**Note**: `@supabase/supabase-js` and `@tanstack/react-query` are included as dependencies and do not need to be installed separately.
+
 ### Step 2: Install Tailwind CSS v4
 
 **CRITICAL**: PACE Core requires Tailwind CSS v4 with the Vite plugin.
@@ -88,6 +90,108 @@ export default defineConfig({
 - Only ~292 CSS rules will be generated instead of 800+ needed
 - The entire purpose of using this UI library will be defeated
 
+#### Advanced Vite Configuration Options
+
+**CSS-First Approach (v0.4.16+, Recommended):**
+
+PACE Core v0.4.16+ uses Tailwind v4's CSS-first approach with `@source` directives in `core.css`. This automatically scans the published source files without requiring complex Vite configuration:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      // Only need to scan your app's source files
+      // pace-core source files are automatically scanned via @source directives
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+})
+```
+
+**Explicit Source File Scanning (Fallback):**
+
+If the CSS-first approach doesn't work, you can explicitly include pace-core source files:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      // Explicitly include pace-core source files for scanning
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+})
+```
+
+**PostCSS Alternative:**
+
+If you prefer PostCSS over Vite plugin:
+
+```javascript
+// tailwind.config.js
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: [
+    './src/**/*.{js,ts,jsx,tsx}',
+    './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+}
+```
+
+**Hybrid Approach (Fallback):**
+
+If source file scanning doesn't work, try this hybrid approach:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        // Try source files first
+        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}',
+        // Fallback: also scan dist files
+        './node_modules/@jmruthers/pace-core/dist/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+})
+```
+
+**What This Configuration Does:**
+
+1. **Scans Your Source Files**: Detects Tailwind classes in your app's source code
+2. **Scans Pace-Core Source Files**: Ensures all Tailwind classes used in pace-core components are included
+3. **Generates Complete CSS**: Creates a CSS file with all necessary utility classes
+4. **Enables Proper Styling**: Allows pace-core components to render with correct styles
+
 ### Step 4: Import Core Styles
 
 **⚠️ CRITICAL**: Import the CSS file in your app's entry point.
@@ -240,13 +344,22 @@ See [Migration Guide](../migration-guides/unified-auth-provider-mandatory-timeou
 
 **Cause**: Tailwind not scanning pace-core source files
 
-**Solution**: Update Vite config to include:
-```typescript
-content: [
-  './src/**/*.{js,ts,jsx,tsx}',
-  './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
-]
-```
+**Solution**: Update Vite config to include pace-core source files in content scanning. See [Advanced Vite Configuration Options](#advanced-vite-configuration-options) above.
+
+### Issue: Still only 292 CSS rules instead of 800+
+
+**Solution**: 
+1. Update to pace-core v0.4.15+
+2. Use source file paths: `./node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}`
+3. Clear build cache and rebuild
+
+### Issue: Source files not found
+
+**Solution**: Ensure you're using pace-core v0.4.15+ which includes source files in the published package
+
+### Issue: Colors don't work (text-main-900, bg-sec-500, etc.)
+
+**Solution**: Verify the CSS file is imported and content scanning includes pace-core source files
 
 ### Issue: TypeScript errors with unified auth
 
@@ -264,13 +377,79 @@ Before asking for help, verify:
 - [ ] All required peer dependencies installed
 - [ ] Test component renders with proper styling
 
+## ♿ Accessibility
+
+The installation process ensures accessibility from the start:
+
+- **WCAG 2.1 AA compliant** - All PACE Core components meet accessibility standards
+- **Semantic HTML** - Components use proper semantic elements
+- **Screen Reader Support** - All components include proper ARIA labels
+- **Keyboard Navigation** - Full keyboard support for all interactive elements
+- **Color Contrast** - Design system colors meet WCAG contrast requirements
+
+### Accessibility Best Practices
+
+1. **Import CSS correctly** - The core.css file includes all accessibility styles
+2. **Use semantic HTML** - Prefer semantic elements in your app code
+3. **Test with screen readers** - Verify your app works with assistive technologies
+4. **Maintain focus indicators** - Don't remove or hide focus styles
+5. **Test keyboard navigation** - Ensure all interactive elements are keyboard accessible
+
+## ⚠️ Edge Cases
+
+### Installation Failures
+
+When installation fails:
+- Check Node.js version (requires 18+)
+- Verify npm registry access
+- Clear npm cache: `npm cache clean --force`
+- Try installing peer dependencies separately
+- Check for version conflicts
+
+### Build Configuration Issues
+
+When build configuration doesn't work:
+- Verify Vite config syntax is correct
+- Check that Tailwind v4 is installed (not v3)
+- Ensure content paths are correct
+- Clear build cache and restart dev server
+- Check for conflicting PostCSS configurations
+
+### CSS Import Issues
+
+When CSS doesn't load:
+- Verify import path is correct
+- Check that CSS file exists in node_modules
+- Ensure import is in entry point (not component)
+- Verify CSS is imported before component usage
+- Check browser console for 404 errors
+
+### Peer Dependency Conflicts
+
+When peer dependencies conflict:
+- Check package.json for version mismatches
+- Use `npm ls` to identify conflicts
+- Update conflicting packages to compatible versions
+- Consider using `npm install --legacy-peer-deps` as temporary workaround
+- Verify all required packages are installed
+
+### Version Compatibility Issues
+
+When versions are incompatible:
+- Check PACE Core version requirements
+- Verify Tailwind v4 compatibility
+- Update to latest compatible versions
+- Check breaking changes in release notes
+- Review migration guides for major version updates
+
 ---
 
-**Last Updated:** 2025-01-XX | **Version:** v0.5.65+
+**Last Updated:** 2025-01-28 | **Version:** v0.5.181
 
 ## Next Steps
 
 - **[Quick Start Guide](./quick-start.md)** - Build your first app
+- **[Quick Reference](./quick-reference.md)** - Common imports and commands
 - **[API Reference](../api-reference/components.md)** - Explore all components
 - **[Styling Guide](../styles/README.md)** - Understand the design system
 - **[Troubleshooting](../troubleshooting/styling-issues.md)** - Fix common problems

package/docs/getting-started/local-development.md

@@ -0,0 +1,303 @@
+---
+lastUpdated: 2025-11-18T14:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
+---
+
+# Local Development Setup
+
+This guide explains how to use `@jmruthers/pace-core` locally in your consuming apps without publishing to npm. This is perfect for active development when you want to see changes immediately.
+
+## Quick Start
+
+### Option 1: npm link (Recommended)
+
+**npm link** creates a symlink between your local pace-core package and your consuming app, allowing you to use the local version without modifying package.json.
+
+#### Step 1: Build and Link pace-core
+
+From the `pace-core` repository root:
+
+```bash
+npm run link:core
+```
+
+This will build the package and create a global symlink automatically.
+
+#### Step 2: Link in Your Consuming App
+
+In your consuming app's directory:
+
+```bash
+# Link to the local package
+npm link @jmruthers/pace-core
+```
+
+That's it! Your app will now use the local version of pace-core.
+
+#### Step 3: Watch for Changes (Optional)
+
+To automatically rebuild when you make changes to pace-core:
+
+```bash
+# In pace-core root directory, run watch mode
+npm run build:core:watch
+```
+
+This will watch for changes and automatically rebuild the package.
+
+#### Unlinking
+
+When you're done with local development:
+
+```bash
+# In your consuming app
+npm unlink @jmruthers/pace-core
+
+# Reinstall from npm
+npm install @jmruthers/pace-core
+
+# In pace-core (optional, cleans up global link)
+npm run unlink:core
+```
+
+---
+
+### Option 2: file: Protocol
+
+Use the `file:` protocol to reference the local package directly in your consuming app's `package.json`.
+
+#### Step 1: Build pace-core
+
+From the `pace-core` repository root:
+
+```bash
+npm run build:core
+```
+
+#### Step 2: Update package.json in Consuming App
+
+In your consuming app's `package.json`, replace the pace-core dependency:
+
+```json
+{
+  "dependencies": {
+    "@jmruthers/pace-core": "file:../path/to/pace-core/packages/core"
+  }
+}
+```
+
+**Important:** Use an absolute or relative path to the `packages/core` directory (not the root).
+
+#### Step 3: Install
+
+```bash
+npm install
+```
+
+#### Step 4: Watch for Changes
+
+Keep pace-core building automatically:
+
+```bash
+# In pace-core root directory
+npm run build:core:watch
+```
+
+#### Reverting to Published Version
+
+When done, change back to the published version:
+
+```json
+{
+  "dependencies": {
+    "@jmruthers/pace-core": "^0.5.181"
+  }
+}
+```
+
+Then run `npm install`.
+
+---
+
+### Option 3: Workspace (Monorepo)
+
+If your consuming apps are in the same monorepo as pace-core, you can use npm workspaces.
+
+#### Setup
+
+In the root `package.json` (pace-core root):
+
+```json
+{
+  "workspaces": [
+    "packages/*",
+    "../your-consuming-app"
+  ]
+}
+```
+
+Then in your consuming app's `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@jmruthers/pace-core": "*"
+  }
+}
+```
+
+Run `npm install` from the root, and npm will automatically link the workspace packages.
+
+---
+
+## Development Workflow
+
+### Recommended Workflow
+
+1. **Terminal 1:** Run watch mode in pace-core
+   ```bash
+   cd /path/to/pace-core
+   npm run build:core -- --watch
+   ```
+
+2. **Terminal 2:** Run your consuming app
+   ```bash
+   cd /path/to/your-app
+   npm run dev
+   ```
+
+3. Make changes to pace-core → watch rebuilds → consuming app hot-reloads
+
+### Building Before Testing
+
+If you're not using watch mode, remember to rebuild after making changes:
+
+```bash
+# In pace-core
+npm run build:core
+```
+
+The consuming app should pick up the changes automatically if using Vite's HMR.
+
+---
+
+## Troubleshooting
+
+### Changes Not Appearing
+
+1. **Ensure the package is built:**
+   ```bash
+   npm run build:core
+   ```
+
+2. **Check the link:**
+   ```bash
+   # In consuming app
+   ls -la node_modules/@jmruthers/pace-core
+   # Should show a symlink (->) pointing to pace-core/packages/core
+   ```
+
+3. **Clear cache and reinstall:**
+   ```bash
+   # In consuming app
+   rm -rf node_modules/.vite
+   npm unlink @jmruthers/pace-core
+   npm link @jmruthers/pace-core
+   ```
+
+### TypeScript Errors
+
+If TypeScript can't find types:
+
+1. **Rebuild pace-core** to regenerate `.d.ts` files:
+   ```bash
+   npm run build:core
+   ```
+
+2. **Restart your TypeScript server** in your IDE
+
+3. **Check tsconfig.json** includes the linked package:
+   ```json
+   {
+     "compilerOptions": {
+       "paths": {
+         "@jmruthers/pace-core": ["./node_modules/@jmruthers/pace-core"]
+       }
+     }
+   }
+   ```
+
+### Vite HMR Not Working
+
+If hot module replacement isn't picking up changes:
+
+1. **Restart the dev server:**
+   ```bash
+   # Stop and restart
+   npm run dev
+   ```
+
+2. **Check Vite config** includes pace-core in content scanning:
+   ```ts
+   // vite.config.ts
+   export default defineConfig({
+     // ... your config
+     css: {
+       // Ensure pace-core source is scanned
+     }
+   })
+   ```
+
+### Multiple Consuming Apps
+
+If you have multiple apps using the linked package:
+
+```bash
+# Link once in pace-core (from root)
+npm run link:core
+
+# Link in each consuming app
+cd ../app1 && npm link @jmruthers/pace-core
+cd ../app2 && npm link @jmruthers/pace-core
+```
+
+All apps will use the same linked version.
+
+---
+
+## Best Practices
+
+1. **Always build before linking** - Ensure `dist/` is up to date
+2. **Use watch mode** - Automatically rebuild on changes
+3. **Test in consuming app** - Verify changes work in real usage
+4. **Unlink before publishing** - Don't publish with local links active
+5. **Version consistency** - Keep version numbers in sync for easier debugging
+
+---
+
+## Switching Between Local and Published
+
+### Quick Switch Script
+
+Create a script in your consuming app to toggle between local and published:
+
+```json
+{
+  "scripts": {
+    "use-local-pace": "npm uninstall @jmruthers/pace-core && npm link @jmruthers/pace-core",
+    "use-published-pace": "npm unlink @jmruthers/pace-core && npm install @jmruthers/pace-core"
+  }
+}
+```
+
+---
+
+## Summary
+
+- **npm link**: Best for active development, easy to toggle
+- **file: protocol**: Simple, but requires editing package.json
+- **Workspace**: Best for monorepo setups
+
+For most use cases, **npm link** is the recommended approach as it's flexible and doesn't require modifying package.json files.
+

package/docs/getting-started/quick-reference.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T14:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Quick Reference