@jmruthers/pace-core 0.4.1 → 0.5.3

package/docs/print-components/examples/README.md

@@ -0,0 +1,204 @@
+# Print Components Examples
+
+> **📚 Complete working examples for all print components**
+
+This directory contains comprehensive examples demonstrating how to use pace-core print components in real-world scenarios.
+
+## 📋 Available Examples
+
+### 1. [Basic Report](./basic-report.tsx)
+Simple business report with header, data table, and footer.
+
+**Features:**
+- PrintLayout with A4 portrait orientation
+- PrintHeader with branding and metadata
+- PrintDataTable with grouping and styling
+- PrintFooter with page numbering
+- PrintButton for print functionality
+
+**Use Case:** Employee directories, simple reports, data summaries
+
+### 2. [Cover Page Report](./cover-page-report.tsx)
+Professional report with cover page and subsequent page headers.
+
+**Features:**
+- PrintCoverHeader for first page
+- PrintHeader for subsequent pages
+- PrintSection for content organization
+- PrintPageBreak for page control
+- Multi-section document structure
+
+**Use Case:** Annual reports, formal documents, executive summaries
+
+### 3. [Card Catalog](./card-catalog.tsx)
+Product catalog with card-based layout and grid system.
+
+**Features:**
+- PrintGrid for responsive layout
+- PrintCard for product display
+- Image integration with aspect ratios
+- Metadata display
+- Print-optimized card layouts
+
+**Use Case:** Product catalogs, directories, reference materials
+
+## 🚀 Getting Started
+
+### 1. Copy an Example
+```bash
+# Copy the basic report example
+cp docs/print-components/examples/basic-report.tsx src/components/MyReport.tsx
+```
+
+### 2. Install Dependencies
+```bash
+npm install @jmruthers/pace-core
+```
+
+### 3. Import CSS
+```tsx
+import '@jmruthers/pace-core/styles/core.css';
+```
+
+### 4. Customize for Your Needs
+- Replace sample data with your actual data
+- Update branding and metadata
+- Adjust styling and layout
+- Add your specific content
+
+## 🎨 Customization Examples
+
+### Custom Branding
+```tsx
+<PrintHeader 
+  title="Your Report Title"
+  branding={{
+    logo: "/your-logo.png",
+    companyName: "Your Company",
+    projectName: "Your Project",
+    version: "v1.0"
+  }}
+  metadata={[
+    { label: "Generated", value: new Date().toLocaleDateString() },
+    { label: "Author", value: "Your Name" }
+  ]}
+/>
+```
+
+### Custom Data Table
+```tsx
+<PrintDataTable 
+  data={yourData}
+  columns={[
+    { key: 'field1', header: 'Field 1', align: 'left' },
+    { key: 'field2', header: 'Field 2', align: 'center' },
+    { key: 'field3', header: 'Field 3', align: 'right', render: (value) => formatValue(value) }
+  ]}
+  title="Your Data Table"
+  grouping={{
+    enabled: true,
+    groupBy: 'category',
+    groupHeader: (group) => <CustomGroupHeader group={group} />
+  }}
+/>
+```
+
+### Custom Card Layout
+```tsx
+<PrintCard
+  title="Your Card Title"
+  subtitle="Your Subtitle"
+  variant="outlined"
+  size="large"
+  layout="horizontal"
+  image={{
+    src: "/your-image.jpg",
+    alt: "Your Image",
+    aspectRatio: "landscape"
+  }}
+  metadata={[
+    { label: "Field 1", value: "Value 1" },
+    { label: "Field 2", value: "Value 2" }
+  ]}
+>
+  <PrintText variant="body">
+    Your custom content goes here...
+  </PrintText>
+</PrintCard>
+```
+
+## 🔧 Advanced Patterns
+
+### Multi-Page Document
+```tsx
+<PrintLayout 
+  firstPageHeader={<PrintCoverHeader title="Document Title" />}
+  subsequentPageHeader={<PrintHeader title="Document Title" />}
+>
+  <PrintSection title="Introduction">
+    {/* Content */}
+  </PrintSection>
+  
+  <PrintPageBreak type="before" />
+  
+  <PrintSection title="Main Content">
+    {/* Content */}
+  </PrintSection>
+</PrintLayout>
+```
+
+### Responsive Grid
+```tsx
+<PrintGrid columns={4} printColumns={2} gap="lg">
+  {items.map(item => (
+    <PrintCard key={item.id} title={item.name} />
+  ))}
+</PrintGrid>
+```
+
+### Custom Styling
+```tsx
+<PrintCard 
+  className="custom-card-style"
+  title="Custom Styled Card"
+>
+  Content
+</PrintCard>
+```
+
+## 🎯 Best Practices
+
+### 1. Test Print Output
+Always test your layouts using browser print preview (Ctrl+P / Cmd+P).
+
+### 2. Use Semantic Components
+Choose the right component for your content:
+- `PrintDataTable` for tabular data
+- `PrintCard` for item summaries
+- `PrintSection` for content organization
+
+### 3. Optimize for A4
+Design for A4 page size as the primary target format.
+
+### 4. Leverage Grouping
+Use data grouping for better print organization.
+
+### 5. Use Page Breaks
+Control page breaks for better document flow.
+
+## 📚 Related Documentation
+
+- **[Print Components Guide](../README.md)** - Complete documentation
+- **[Quick Start Guide](../quick-start.md)** - 5-minute setup
+- **[API Reference](../api-reference.md)** - Complete component APIs
+- **[Troubleshooting](../troubleshooting.md)** - Common issues and solutions
+
+## 🆘 Need Help?
+
+- **Issues**: [GitHub Issues](https://github.com/jmruthers/pace-core/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/jmruthers/pace-core/discussions)
+- **Documentation**: [Full Documentation](../README.md)
+
+---
+
+**Ready to build?** Start with the [Basic Report Example](./basic-report.tsx) and customize it for your needs! 🚀

package/docs/print-components/examples/basic-report.tsx

@@ -0,0 +1,92 @@
+/**
+ * @file Basic Report Example
+ * @description Simple business report with header, data table, and footer
+ */
+
+import React from 'react';
+import { 
+  PrintLayout, 
+  PrintHeader, 
+  PrintDataTable, 
+  PrintText,
+  PrintButton,
+  PrintFooter 
+} from '@jmruthers/pace-core';
+
+// Sample data
+const employeeData = [
+  { id: 1, name: 'John Doe', department: 'Engineering', salary: 80000, status: 'Active' },
+  { id: 2, name: 'Jane Smith', department: 'Marketing', salary: 75000, status: 'Active' },
+  { id: 3, name: 'Bob Johnson', department: 'Sales', salary: 70000, status: 'Active' },
+  { id: 4, name: 'Alice Brown', department: 'Engineering', salary: 85000, status: 'Active' },
+  { id: 5, name: 'Charlie Wilson', department: 'Marketing', salary: 72000, status: 'Active' },
+];
+
+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()}` },
+  { key: 'status', header: 'Status', align: 'center' as const },
+];
+
+export function BasicReportExample() {
+  return (
+    <div className="space-y-4">
+      {/* Print Button */}
+      <PrintButton 
+        variant="primary" 
+        printSelector=".report-content"
+        beforePrint={() => console.log('Preparing to print...')}
+        afterPrint={() => console.log('Print completed!')}
+      >
+        Print Report
+      </PrintButton>
+
+      {/* Report Content */}
+      <div className="report-content">
+        <PrintLayout orientation="portrait" pageSize="A4">
+          <PrintHeader 
+            title="Employee Directory"
+            subtitle="Department Overview"
+            branding={{
+              companyName: "Acme Corporation",
+              projectName: "HR Analytics",
+              version: "v1.0"
+            }}
+            metadata={[
+              { label: "Generated", value: new Date().toLocaleDateString() },
+              { label: "Total Employees", value: employeeData.length.toString() }
+            ]}
+            printDate={true}
+          />
+          
+          <PrintDataTable 
+            data={employeeData}
+            columns={columns}
+            title="Employee Directory"
+            grouping={{
+              enabled: true,
+              groupBy: 'department',
+              groupHeader: (group) => (
+                <div className="font-bold text-lg bg-gray-100 p-2 border-b">
+                  {group} Department
+                </div>
+              )
+            }}
+            styling={{
+              headerStyle: 'solid',
+              rowStyle: 'striped',
+              cellPadding: 'normal'
+            }}
+          />
+
+          <PrintFooter 
+            pageNumbers={true}
+            customText="Confidential - Internal Use Only"
+            alignment="center"
+          />
+        </PrintLayout>
+      </div>
+    </div>
+  );
+}

package/docs/print-components/examples/card-catalog.tsx

@@ -0,0 +1,149 @@
+/**
+ * @file Card Catalog Example
+ * @description Product catalog with card-based layout
+ */
+
+import React from 'react';
+import { 
+  PrintLayout, 
+  PrintHeader,
+  PrintGrid,
+  PrintCard,
+  PrintButton,
+  PrintFooter
+} from '@jmruthers/pace-core';
+
+// Sample product data
+const products = [
+  {
+    id: 1,
+    name: 'Professional Widget',
+    category: 'Electronics',
+    price: '$299.99',
+    sku: 'PW-001',
+    stock: 'In Stock',
+    description: 'High-quality professional widget with advanced features',
+    image: '/products/widget-pro.jpg'
+  },
+  {
+    id: 2,
+    name: 'Standard Widget',
+    category: 'Electronics',
+    price: '$199.99',
+    sku: 'SW-002',
+    stock: 'In Stock',
+    description: 'Reliable standard widget for everyday use',
+    image: '/products/widget-standard.jpg'
+  },
+  {
+    id: 3,
+    name: 'Premium Widget',
+    category: 'Electronics',
+    price: '$399.99',
+    sku: 'PW-003',
+    stock: 'Limited',
+    description: 'Premium widget with cutting-edge technology',
+    image: '/products/widget-premium.jpg'
+  },
+  {
+    id: 4,
+    name: 'Basic Widget',
+    category: 'Electronics',
+    price: '$99.99',
+    sku: 'BW-004',
+    stock: 'In Stock',
+    description: 'Affordable basic widget for entry-level users',
+    image: '/products/widget-basic.jpg'
+  },
+  {
+    id: 5,
+    name: 'Enterprise Widget',
+    category: 'Electronics',
+    price: '$599.99',
+    sku: 'EW-005',
+    stock: 'In Stock',
+    description: 'Enterprise-grade widget for large organizations',
+    image: '/products/widget-enterprise.jpg'
+  },
+  {
+    id: 6,
+    name: 'Compact Widget',
+    category: 'Electronics',
+    price: '$149.99',
+    sku: 'CW-006',
+    stock: 'Out of Stock',
+    description: 'Compact widget perfect for space-constrained environments',
+    image: '/products/widget-compact.jpg'
+  },
+];
+
+export function CardCatalogExample() {
+  return (
+    <div className="space-y-4">
+      {/* Print Button */}
+      <PrintButton 
+        variant="primary" 
+        printSelector=".catalog-content"
+        beforePrint={() => console.log('Preparing product catalog...')}
+        afterPrint={() => console.log('Product catalog printed!')}
+      >
+        Print Product Catalog
+      </PrintButton>
+
+      {/* Catalog Content */}
+      <div className="catalog-content">
+        <PrintLayout orientation="portrait" pageSize="A4">
+          <PrintHeader 
+            title="Product Catalog 2024"
+            subtitle="Complete Widget Collection"
+            branding={{
+              companyName: "Widget Solutions Inc.",
+              projectName: "Product Catalog",
+              version: "v2024.1"
+            }}
+            metadata={[
+              { label: "Total Products", value: products.length.toString() },
+              { label: "Categories", value: "Electronics" },
+              { label: "Price Range", value: "$99.99 - $599.99" }
+            ]}
+            printDate={true}
+          />
+          
+          <PrintGrid columns={3} printColumns={2} gap="md">
+            {products.map(product => (
+              <PrintCard
+                key={product.id}
+                title={product.name}
+                subtitle={product.category}
+                variant="outlined"
+                size="medium"
+                layout="vertical"
+                backgroundColor="white"
+                image={{
+                  src: product.image,
+                  alt: product.name,
+                  aspectRatio: "square"
+                }}
+                metadata={[
+                  { label: "Price", value: product.price },
+                  { label: "SKU", value: product.sku },
+                  { label: "Stock", value: product.stock }
+                ]}
+              >
+                <PrintText variant="caption" color="muted">
+                  {product.description}
+                </PrintText>
+              </PrintCard>
+            ))}
+          </PrintGrid>
+
+          <PrintFooter 
+            pageNumbers={true}
+            customText="Widget Solutions Inc. - Product Catalog 2024"
+            alignment="center"
+          />
+        </PrintLayout>
+      </div>
+    </div>
+  );
+}

package/docs/print-components/examples/cover-page-report.tsx

@@ -0,0 +1,163 @@
+/**
+ * @file Cover Page Report Example
+ * @description Professional report with cover page and subsequent page headers
+ */
+
+import React from 'react';
+import { 
+  PrintLayout, 
+  PrintCoverHeader,
+  PrintHeader,
+  PrintSection, 
+  PrintText,
+  PrintDataTable,
+  PrintPageBreak,
+  PrintButton,
+  PrintFooter
+} from '@jmruthers/pace-core';
+
+// Sample financial data
+const quarterlyData = [
+  { quarter: 'Q1 2024', revenue: 1200000, profit: 300000, growth: 15 },
+  { quarter: 'Q2 2024', revenue: 1350000, profit: 350000, growth: 12 },
+  { quarter: 'Q3 2024', revenue: 1500000, profit: 400000, growth: 11 },
+  { quarter: 'Q4 2024', revenue: 1650000, profit: 450000, growth: 10 },
+];
+
+const financialColumns = [
+  { key: 'quarter', header: 'Quarter', align: 'left' as const },
+  { key: 'revenue', header: 'Revenue', align: 'right' as const, render: (value: number) => `$${value.toLocaleString()}` },
+  { key: 'profit', header: 'Profit', align: 'right' as const, render: (value: number) => `$${value.toLocaleString()}` },
+  { key: 'growth', header: 'Growth %', align: 'center' as const, render: (value: number) => `${value}%` },
+];
+
+export function CoverPageReportExample() {
+  return (
+    <div className="space-y-4">
+      {/* Print Button */}
+      <PrintButton 
+        variant="primary" 
+        printSelector=".report-content"
+        beforePrint={() => console.log('Preparing annual report...')}
+        afterPrint={() => console.log('Annual report printed!')}
+      >
+        Print Annual Report
+      </PrintButton>
+
+      {/* Report Content */}
+      <div className="report-content">
+        <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",
+                version: "v2024.1"
+              }}
+              logoSize="large"
+              titleSize="xl"
+              showDivider={true}
+              backgroundColor="#f8f9fa"
+              metadata={[
+                { label: "Period", value: "January 1 - December 31, 2024" },
+                { label: "Prepared by", value: "Finance Team" },
+                { label: "Approved by", value: "Board of Directors" }
+              ]}
+            />
+          }
+          subsequentPageHeader={
+            <PrintHeader
+              title="Annual Report 2024"
+              branding={{
+                logo: "/logo-small.png",
+                companyName: "Acme Corp"
+              }}
+            />
+          }
+        >
+          {/* Executive Summary */}
+          <PrintSection title="Executive Summary">
+            <PrintText variant="heading" weight="bold">
+              Overview
+            </PrintText>
+            <PrintText variant="body">
+              This annual report provides a comprehensive analysis of Acme Corporation's 
+              financial performance, strategic initiatives, and future outlook for 2024. 
+              We achieved record revenue growth while maintaining strong profitability 
+              and operational efficiency.
+            </PrintText>
+            
+            <PrintText variant="subheading" weight="semibold">
+              Key Highlights
+            </PrintText>
+            <PrintText variant="body">
+              • Record revenue of $5.7M, representing 12% year-over-year growth
+              • Strong profitability with 27% profit margins
+              • Successful expansion into three new markets
+              • 95% customer satisfaction rating maintained
+            </PrintText>
+          </PrintSection>
+
+          <PrintPageBreak type="before" />
+
+          {/* Financial Performance */}
+          <PrintSection title="Financial Performance">
+            <PrintText variant="heading" weight="bold">
+              Quarterly Results
+            </PrintText>
+            <PrintText variant="body">
+              Our quarterly performance demonstrates consistent growth and strong 
+              financial discipline across all business units.
+            </PrintText>
+            
+            <PrintDataTable 
+              data={quarterlyData}
+              columns={financialColumns}
+              title="Quarterly Financial Summary"
+              styling={{
+                headerStyle: 'solid',
+                rowStyle: 'striped',
+                cellPadding: 'normal'
+              }}
+            />
+          </PrintSection>
+
+          <PrintPageBreak type="before" />
+
+          {/* Strategic Initiatives */}
+          <PrintSection title="Strategic Initiatives">
+            <PrintText variant="heading" weight="bold">
+              Market Expansion
+            </PrintText>
+            <PrintText variant="body">
+              In 2024, we successfully expanded into three new geographic markets, 
+              establishing a strong presence in the European and Asian regions. 
+              This expansion contributed significantly to our revenue growth and 
+              diversified our customer base.
+            </PrintText>
+            
+            <PrintText variant="subheading" weight="semibold">
+              Technology Innovation
+            </PrintText>
+            <PrintText variant="body">
+              Our continued investment in technology and innovation has resulted in 
+              improved operational efficiency and enhanced customer experience. 
+              We launched two new product lines and upgraded our core platform.
+            </PrintText>
+          </PrintSection>
+
+          <PrintFooter 
+            pageNumbers={true}
+            customText="Acme Corporation - Annual Report 2024"
+            alignment="center"
+          />
+        </PrintLayout>
+      </div>
+    </div>
+  );
+}