@jmruthers/pace-core 0.4.1 → 0.5.1

package/docs/print-components/README.md

@@ -0,0 +1,258 @@
+# Print Components
+
+> **🎨 Print-Optimized Layout System** | [Quick Start](./quick-start.md) | [API Reference](./api-reference.md) | [Examples](./examples/)
+
+A comprehensive suite of print-optimized React components designed for creating professional reports, documents, and printable content. Built with print-first design principles and A4 page optimization.
+
+## 🚀 Quick Start
+
+```bash
+npm install @jmruthers/pace-core
+```
+
+```tsx
+import { 
+  PrintLayout, 
+  PrintHeader, 
+  PrintDataTable, 
+  PrintText 
+} from '@jmruthers/pace-core';
+
+// Import the core CSS file
+import '@jmruthers/pace-core/styles/core.css';
+
+function ReportPage() {
+  return (
+    <PrintLayout orientation="portrait" pageSize="A4">
+      <PrintHeader 
+        title="Monthly Report"
+        branding={{
+          companyName: "Your Company",
+          projectName: "Q4 Analytics"
+        }}
+      />
+      <PrintDataTable 
+        data={reportData}
+        columns={columns}
+        title="Sales Summary"
+      />
+    </PrintLayout>
+  );
+}
+```
+
+## 📋 Overview
+
+The print components system provides everything you need to create professional, print-optimized documents:
+
+### **Core Components**
+- **`PrintLayout`** - Base layout with page size and orientation control
+- **`PrintHeader`** - Flexible headers with branding and metadata
+- **`PrintCoverHeader`** - Cover page headers for first pages
+- **`PrintFooter`** - Page footers with numbering and content
+- **`PrintText`** - Print-optimized typography system
+
+### **Data Components**
+- **`PrintDataTable`** - Print-optimized data tables with grouping
+- **`PrintCard`** - Flexible card layouts for content
+- **`PrintSection`** - Content organization with columns
+- **`PrintGrid`** - Responsive grid system
+
+### **Utility Components**
+- **`PrintButton`** - Print functionality with callbacks
+- **`PrintPageBreak`** - Explicit page break controls
+- **`PrintDivider`** - Visual separators
+
+## 🎯 Use Cases
+
+### **1. Business Reports**
+Create professional reports with data tables, charts, and executive summaries.
+
+```tsx
+<PrintLayout orientation="landscape" pageSize="A4">
+  <PrintCoverHeader 
+    title="Q4 Financial Report"
+    subtitle="Performance Analysis & Strategic Overview"
+    branding={{
+      logo: "/logo.png",
+      companyName: "Acme Corp",
+      version: "v2024.1"
+    }}
+  />
+  <PrintDataTable 
+    data={financialData}
+    columns={financialColumns}
+    grouping={{ enabled: true, groupBy: 'quarter' }}
+  />
+</PrintLayout>
+```
+
+### **2. Document Generation**
+Build user guides, technical documentation, and manuals.
+
+```tsx
+<PrintLayout orientation="portrait" pageSize="A4">
+  <PrintHeader title="User Manual" />
+  <PrintSection title="Getting Started">
+    <PrintText variant="heading">Installation</PrintText>
+    <PrintText variant="body">
+      Follow these steps to install the application...
+    </PrintText>
+  </PrintSection>
+  <PrintPageBreak type="before" />
+  <PrintSection title="Configuration">
+    {/* More content */}
+  </PrintSection>
+</PrintLayout>
+```
+
+### **3. Card-Based Layouts**
+Create catalogs, directories, and reference materials.
+
+```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>
+```
+
+## 🎨 Design System
+
+### **Print Optimization**
+- **A4 Page Support** - Optimized for A4 portrait and landscape
+- **Print Media Queries** - Automatic print-specific styling
+- **High Contrast** - Optimized colors for print readability
+- **Page Breaks** - Intelligent page break management
+- **Margins** - Proper print margins and safe areas
+
+### **Typography**
+- **Print-Optimized Fonts** - 12pt base size for readability
+- **Consistent Hierarchy** - Heading, subheading, body, caption variants
+- **High Contrast** - Black text on white background for print
+
+### **Layout Principles**
+- **Print-First Design** - Optimized for print, works on screen
+- **Responsive Breakpoints** - Different layouts for screen vs print
+- **Consistent Spacing** - Standardized spacing system
+- **Clear Hierarchy** - Visual hierarchy optimized for print
+
+## 🔧 Configuration
+
+### **Page Sizes**
+```tsx
+// A4 Portrait (default)
+<PrintLayout pageSize="A4" orientation="portrait" />
+
+// A4 Landscape
+<PrintLayout pageSize="A4" orientation="landscape" />
+
+// Future: A3, A5 support
+<PrintLayout pageSize="A3" orientation="portrait" />
+```
+
+### **Headers & Footers**
+```tsx
+// Different headers for first page vs subsequent pages
+<PrintLayout 
+  firstPageHeader={<PrintCoverHeader title="Annual Report" />}
+  subsequentPageHeader={<PrintHeader title="Annual Report" />}
+>
+  {/* Content */}
+</PrintLayout>
+```
+
+### **Print Optimization**
+```tsx
+// Enable print optimization (default: true)
+<PrintDataTable 
+  data={data}
+  columns={columns}
+  printOptimized={true}
+/>
+
+// Disable for screen-only layouts
+<PrintCard printOptimized={false}>
+  Content
+</PrintCard>
+```
+
+## 📚 Documentation
+
+### **Getting Started**
+- **[Quick Start Guide](./quick-start.md)** - 5-minute setup
+- **[Installation Guide](./installation.md)** - Detailed setup
+- **[Examples](./examples/)** - Complete working examples
+
+### **Component Reference**
+- **[API Reference](./api-reference.md)** - Complete component APIs
+- **[Props Reference](./props-reference.md)** - Detailed prop documentation
+- **[Type Definitions](./types.md)** - TypeScript interfaces
+
+### **Advanced Usage**
+- **[Customization Guide](./customization.md)** - Styling and theming
+- **[Performance Guide](./performance.md)** - Optimization tips
+- **[Troubleshooting](./troubleshooting.md)** - Common issues and solutions
+
+### **Integration**
+- **[React Integration](./react-integration.md)** - Using with React apps
+- **[Next.js Integration](./nextjs-integration.md)** - Next.js specific setup
+- **[Vite Integration](./vite-integration.md)** - Vite configuration
+
+## 🎯 Best Practices
+
+### **1. Use Print-First Design**
+Design your layouts with print in mind, then adapt for screen.
+
+### **2. Test Print Output**
+Always test your layouts using browser print preview (Ctrl+P / Cmd+P).
+
+### **3. Optimize for A4**
+Design for A4 page size as the primary target format.
+
+### **4. Use Semantic Components**
+Choose the right component for your content type:
+- `PrintDataTable` for tabular data
+- `PrintCard` for item summaries
+- `PrintSection` for content organization
+
+### **5. Leverage Grouping**
+Use data grouping for better print organization:
+
+```tsx
+<PrintDataTable 
+  data={data}
+  columns={columns}
+  grouping={{
+    enabled: true,
+    groupBy: 'department',
+    groupHeader: (group) => <DepartmentHeader group={group} />
+  }}
+/>
+```
+
+## 🔗 Related Documentation
+
+- **[Main Documentation](../README.md)** - Complete pace-core documentation
+- **[Styling Guide](../styles/README.md)** - Design system and theming
+- **[Component Library](../api-reference/components.md)** - All available components
+- **[Migration Guide](../migration/README.md)** - Upgrading from previous versions
+
+## 📞 Support
+
+- **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 get started?** Check out the [Quick Start Guide](./quick-start.md) to build your first print-optimized document in 5 minutes! 🚀