@jmruthers/pace-core 0.4.1 → 0.5.3

package/docs/print-components/quick-start.md

@@ -0,0 +1,363 @@
+# Print Components Quick Start
+
+> **⚡ Get up and running with print components in 5 minutes**
+
+This guide will walk you through creating your first print-optimized document using pace-core print components.
+
+## 🚀 Installation
+
+```bash
+npm install @jmruthers/pace-core
+```
+
+## 📦 Basic Setup
+
+### 1. Import Components
+
+```tsx
+import { 
+  PrintLayout, 
+  PrintHeader, 
+  PrintDataTable, 
+  PrintText,
+  PrintButton 
+} from '@jmruthers/pace-core';
+
+// Import the core CSS file
+import '@jmruthers/pace-core/styles/core.css';
+```
+
+### 2. Create Your First Print Document
+
+```tsx
+function MyReport() {
+  const data = [
+    { id: 1, name: 'John Doe', department: 'Engineering', salary: 80000 },
+    { id: 2, name: 'Jane Smith', department: 'Marketing', salary: 75000 },
+    { id: 3, name: 'Bob Johnson', department: 'Sales', salary: 70000 },
+  ];
+
+  const columns = [
+    { key: 'name', header: 'Name', align: 'left' as const },
+    { key: 'department', header: 'Department', align: 'center' as const },
+    { key: 'salary', header: 'Salary', align: 'right' as const, render: (value: number) => `$${value.toLocaleString()}` },
+  ];
+
+  return (
+    <div>
+      {/* Print Button */}
+      <PrintButton 
+        variant="primary" 
+        printSelector=".report-content"
+        beforePrint={() => console.log('Preparing to print...')}
+        afterPrint={() => console.log('Print completed!')}
+      >
+        Print Report
+      </PrintButton>
+
+      {/* Print Content */}
+      <div className="report-content">
+        <PrintLayout orientation="portrait" pageSize="A4">
+          <PrintHeader 
+            title="Employee Report"
+            subtitle="Department Overview"
+            branding={{
+              companyName: "Your Company",
+              projectName: "HR Analytics",
+              version: "v1.0"
+            }}
+            metadata={[
+              { label: "Generated", value: new Date().toLocaleDateString() },
+              { label: "Total Employees", value: data.length.toString() }
+            ]}
+          />
+          
+          <PrintDataTable 
+            data={data}
+            columns={columns}
+            title="Employee Directory"
+            grouping={{
+              enabled: true,
+              groupBy: 'department'
+            }}
+          />
+        </PrintLayout>
+      </div>
+    </div>
+  );
+}
+```
+
+## 🎨 Advanced Layout
+
+### Cover Page + Content Pages
+
+```tsx
+function AdvancedReport() {
+  return (
+    <PrintLayout 
+      orientation="portrait" 
+      pageSize="A4"
+      firstPageHeader={
+        <PrintCoverHeader
+          title="Annual Report 2024"
+          subtitle="Financial Performance & Strategic Overview"
+          branding={{
+            logo: "/logo.png",
+            companyName: "Acme Corporation",
+            tagline: "Innovation Through Excellence"
+          }}
+          logoSize="large"
+          titleSize="xl"
+          showDivider={true}
+          backgroundColor="#f8f9fa"
+        />
+      }
+      subsequentPageHeader={
+        <PrintHeader
+          title="Annual Report 2024"
+          branding={{
+            logo: "/logo-small.png",
+            companyName: "Acme Corp"
+          }}
+        />
+      }
+    >
+      <PrintSection title="Executive Summary">
+        <PrintText variant="heading">Overview</PrintText>
+        <PrintText variant="body">
+          This report provides a comprehensive analysis of our performance...
+        </PrintText>
+      </PrintSection>
+
+      <PrintPageBreak type="before" />
+
+      <PrintSection title="Financial Performance">
+        <PrintDataTable 
+          data={financialData}
+          columns={financialColumns}
+          title="Quarterly Results"
+        />
+      </PrintSection>
+    </PrintLayout>
+  );
+}
+```
+
+## 📊 Data Tables
+
+### Basic Table
+
+```tsx
+<PrintDataTable 
+  data={data}
+  columns={columns}
+  title="Sales Data"
+/>
+```
+
+### Grouped Table
+
+```tsx
+<PrintDataTable 
+  data={data}
+  columns={columns}
+  title="Sales by Region"
+  grouping={{
+    enabled: true,
+    groupBy: 'region',
+    groupHeader: (group) => (
+      <div className="font-bold text-lg bg-gray-100 p-2">
+        {group} Region
+      </div>
+    )
+  }}
+  styling={{
+    headerStyle: 'solid',
+    rowStyle: 'striped',
+    cellPadding: 'normal'
+  }}
+/>
+```
+
+## 🎴 Card Layouts
+
+### Basic Card
+
+```tsx
+<PrintCard
+  title="Product Information"
+  subtitle="Widget Pro"
+  image={{
+    src: "/product-image.jpg",
+    alt: "Widget Pro",
+    aspectRatio: "square"
+  }}
+  metadata={[
+    { label: "Price", value: "$99.99" },
+    { label: "SKU", value: "WP-001" },
+    { label: "Stock", value: "In Stock" }
+  ]}
+  layout="vertical"
+  size="medium"
+/>
+```
+
+### Card Grid
+
+```tsx
+<PrintGrid columns={3} printColumns={2}>
+  {products.map(product => (
+    <PrintCard
+      key={product.id}
+      title={product.name}
+      subtitle={product.category}
+      image={{ src: product.image, alt: product.name }}
+      metadata={[
+        { label: "Price", value: product.price },
+        { label: "Stock", value: product.stock }
+      ]}
+    />
+  ))}
+</PrintGrid>
+```
+
+## 📝 Typography
+
+### Text Variants
+
+```tsx
+<PrintText variant="heading" weight="bold">
+  Main Heading
+</PrintText>
+
+<PrintText variant="subheading" weight="semibold">
+  Section Heading
+</PrintText>
+
+<PrintText variant="body">
+  Regular paragraph text with proper line spacing and readability.
+</PrintText>
+
+<PrintText variant="caption" color="muted">
+  Small caption text for metadata
+</PrintText>
+```
+
+## 🎯 Print Testing
+
+### 1. Browser Print Preview
+- Press `Ctrl+P` (Windows) or `Cmd+P` (Mac)
+- Use print preview to test your layout
+- Check page breaks and margins
+
+### 2. Print Optimization
+```tsx
+// Enable print optimization (default: true)
+<PrintDataTable 
+  data={data}
+  columns={columns}
+  printOptimized={true}
+/>
+
+// Disable for screen-only content
+<PrintCard printOptimized={false}>
+  Interactive content
+</PrintCard>
+```
+
+### 3. Page Breaks
+```tsx
+// Force page break before element
+<PrintPageBreak type="before" />
+
+// Force page break after element
+<PrintPageBreak type="after" />
+
+// Avoid page breaks within element
+<PrintPageBreak type="avoid" />
+```
+
+## 🔧 Common Patterns
+
+### 1. Report with Cover Page
+```tsx
+<PrintLayout 
+  firstPageHeader={<PrintCoverHeader title="Report" />}
+  subsequentPageHeader={<PrintHeader title="Report" />}
+>
+  {/* Content */}
+</PrintLayout>
+```
+
+### 2. Multi-Section Document
+```tsx
+<PrintLayout>
+  <PrintSection title="Introduction">
+    <PrintText variant="body">Content...</PrintText>
+  </PrintSection>
+  
+  <PrintPageBreak type="before" />
+  
+  <PrintSection title="Data Analysis">
+    <PrintDataTable data={data} columns={columns} />
+  </PrintSection>
+</PrintLayout>
+```
+
+### 3. Card-Based Catalog
+```tsx
+<PrintGrid columns={3} printColumns={2}>
+  {items.map(item => (
+    <PrintCard
+      key={item.id}
+      title={item.name}
+      image={{ src: item.image, alt: item.name }}
+      metadata={[
+        { label: "Price", value: item.price },
+        { label: "Description", value: item.description }
+      ]}
+    />
+  ))}
+</PrintGrid>
+```
+
+## 🎨 Styling
+
+### Custom Classes
+```tsx
+<PrintCard 
+  className="custom-card-style"
+  title="Custom Styled Card"
+>
+  Content
+</PrintCard>
+```
+
+### Print-Specific Styles
+```css
+/* Custom print styles */
+@media print {
+  .custom-print-style {
+    color: #000;
+    background: #fff;
+  }
+}
+```
+
+## 🚀 Next Steps
+
+1. **Explore Examples** - Check out the [Examples](./examples/) directory
+2. **Read API Reference** - See [API Reference](./api-reference.md) for complete documentation
+3. **Customize Styling** - Learn about [Customization](./customization.md)
+4. **Advanced Features** - Discover [Advanced Usage](./advanced-usage.md)
+
+## 🆘 Need Help?
+
+- **Documentation**: [Full Documentation](./README.md)
+- **Issues**: [GitHub Issues](https://github.com/jmruthers/pace-core/issues)
+- **Examples**: [Complete Examples](./examples/)
+
+---
+
+**Ready for more?** Check out the [API Reference](./api-reference.md) to explore all available components and props! 🚀

package/docs/quick-reference.md

@@ -33,28 +33,48 @@ npm install @jmruthers/pace-core
 ### Basic App Setup
 ```tsx
 import React from 'react';
-import { UnifiedAuthProvider } from '@jmruthers/pace-core';
-import '@jmruthers/pace-core/styles/tokens';
+import { UnifiedAuthProvider, PaceAppLayout } from '@jmruthers/pace-core';
+import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
+
+// Import the core CSS file - app.css must come first for proper @theme processing
+import './app.css'; // Your app's color palette
+import '@jmruthers/pace-core/styles/core.css';
 
 function App() {
   return (
-    <UnifiedAuthProvider>
-      <YourApp />
+    <UnifiedAuthProvider supabaseClient={supabase} appName="My App">
+      <Router>
+        <Routes>
+          <Route path="/" element={
+            <PaceAppLayout appName="My Application">
+              <div className="container mx-auto px-4 py-6">
+                <h1>Welcome to My App</h1>
+                <p>Your content goes here</p>
+              </div>
+            </PaceAppLayout>
+          } />
+        </Routes>
+      </Router>
     </UnifiedAuthProvider>
   );
 }
 ```
 
 ### Tailwind Configuration
-```js
-// tailwind.config.js
-module.exports = {
-  content: [
-    './src/**/*.{js,ts,jsx,tsx}',
-    './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}',
+```ts
+// vite.config.ts
+import tailwindcss from '@tailwindcss/vite'
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
   ],
-  // ... rest of config
-};
+})
 ```
 
 ## 🔐 Authentication
@@ -339,12 +359,18 @@ import tailwindcss from '@tailwindcss/vite';
 
 export default defineConfig({
   plugins: [
-    tailwindcss() // ✅ Simple - theme is included in CSS
+    tailwindcss({
+      // CRITICAL: Include pace-core components for scanning
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
   ],
 });
 
-// index.css
-@import '@jmruthers/pace-core/styles/tailwind-v4-theme';
+// main.tsx
+import '@jmruthers/pace-core/styles/core.css';
 ```
 
 **What's included automatically**:
@@ -364,13 +390,16 @@ module.exports = {
   content: ["./src/**/*.{js,jsx,ts,tsx}"],
 };
 
-// index.css
-@import '@jmruthers/pace-core/styles/tokens';
+// index.css or main.tsx
+import './app.css'; // Your app's color palette (must come first)
+import '@jmruthers/pace-core/styles/core.css';
 ```
 
 ### Using Design Tokens
 ```tsx
-import '@jmruthers/pace-core/styles/tokens';
+// Import the core CSS file
+import './app.css'; // Your app's color palette (must come first)
+import '@jmruthers/pace-core/styles/core.css';
 
 // Use in your CSS
 .my-component {
@@ -382,22 +411,11 @@ import '@jmruthers/pace-core/styles/tokens';
 
 ### Custom Themes
 ```tsx
-import { ThemeProvider } from '@jmruthers/pace-core';
-
-function App() {
-  return (
-    <ThemeProvider
-      theme={{
-        colors: {
-          primary: '#your-primary-color',
-          secondary: '#your-secondary-color',
-        },
-      }}
-    >
-      <YourApp />
-    </ThemeProvider>
-  );
-}
+// Define your custom colors in app.css
+// @theme static {
+//   --color-primary: #your-primary-color;
+//   --color-secondary: #your-secondary-color;
+// }
 ```
 
 ## 🔧 Utilities
@@ -406,8 +424,7 @@ function App() {
 ```tsx
 import { 
   useDebounce, 
-  useToast, 
-  useTheme 
+  useToast
 } from '@jmruthers/pace-core';
 
 function SearchComponent() {