@jmruthers/pace-core 0.2.4

package/docs/style-guide.md

@@ -0,0 +1,522 @@
+# PACE Core Documentation Style Guide
+
+This comprehensive style guide ensures consistency, clarity, and maintainability across all PACE Core documentation. This is the single source of truth for documentation standards.
+
+## 📋 Table of Contents
+
+1. [Writing Principles](#writing-principles)
+2. [Formatting Standards](#formatting-standards)
+3. [Content Structure](#content-structure)
+4. [Code Examples](#code-examples)
+5. [Cross-References](#cross-references)
+6. [Component Documentation](#component-documentation)
+7. [API Reference Standards](#api-reference-standards)
+8. [Troubleshooting Guidelines](#troubleshooting-guidelines)
+9. [Maintenance Checklist](#maintenance-checklist)
+10. [Quality Assurance](#quality-assurance)
+
+## 📝 Writing Principles
+
+### 1. Clarity First
+- **Use simple, clear language** - Avoid jargon and technical complexity
+- **Be specific** - Provide concrete examples and exact code snippets
+- **Explain the "why"** - Don't just show what to do, explain why it's important
+- **Use active voice** - "Create a component" not "A component should be created"
+
+### 2. Developer-Focused
+- **Start with practical examples** - Show working code first
+- **Provide complete examples** - Include imports, setup, and usage
+- **Include error handling** - Show how to handle common issues
+- **Use realistic data** - Use meaningful variable names and values
+
+### 3. Consistent Structure
+- **Use consistent headings** - Follow the established hierarchy
+- **Standardize code blocks** - Use consistent formatting and syntax highlighting
+- **Maintain uniform examples** - Use consistent variable names and patterns
+
+## 🎨 Formatting Standards
+
+### Headings
+
+```markdown
+# Main Title (H1) - Only in README files
+## Section Title (H2) - Major sections
+### Subsection (H3) - Subsections
+#### Detail (H4) - Specific details
+##### Note (H5) - Important notes
+```
+
+### Code Blocks
+
+**TypeScript/JavaScript:**
+```tsx
+// ✅ Good - Complete, runnable example
+import { useCan } from '@jmruthers/pace-core';
+
+function UserActions({ userId, scope }) {
+  const { hasPermission, isLoading } = useCan();
+  const [canEdit, setCanEdit] = useState(false);
+
+  useEffect(() => {
+    const checkPermission = async () => {
+      if (!isLoading) {
+        const editPerm = await hasPermission('update:users', { userId, scope });
+        setCanEdit(editPerm);
+      }
+    };
+    
+    checkPermission();
+  }, [hasPermission, isLoading, userId, scope]);
+
+  return (
+    <div>
+      {canEdit && <EditButton />}
+    </div>
+  );
+}
+```
+
+**SQL:**
+```sql
+-- ✅ Good - Clear, commented SQL
+SELECT 
+  user_id,
+  organisation_id,
+  role,
+  status
+FROM rbac_organisation_roles 
+WHERE user_id = 'user-123' 
+  AND organisation_id = 'org-456'
+  AND status = 'active';
+```
+
+### Callouts and Alerts
+
+```markdown
+> **📚 New Developer?** Start with the [Quick Start Guide](./quick-start.md) to get up and running in 5 minutes.
+
+> **🔄 Migrating?** If you're upgrading from the legacy RBAC system, see the [Migration Guide](./migration/rbac-migration.md) for step-by-step instructions.
+
+> **⚠️ Important**: Always include organisation context in permission checks.
+
+> **💡 Tip**: Use batch permission checking for better performance when checking multiple permissions.
+```
+
+### Lists and Bullets
+
+```markdown
+- **Use bold for key terms** - Makes scanning easier
+- **Keep items parallel** - Use consistent grammar and structure
+- **Limit to 7 items** - Break longer lists into subsections
+- **Use numbered lists for steps** - When order matters
+```
+
+## 📚 Content Structure
+
+### File Organization
+
+```
+docs/
+├── README.md                    # Main entry point
+├── getting-started/            # Onboarding content
+│   ├── installation.md
+│   ├── quick-start.md
+│   └── examples/
+├── core-concepts/              # Fundamental concepts
+│   ├── authentication.md
+│   ├── rbac-system.md
+│   └── permissions.md
+├── rbac/                       # RBAC module docs
+│   ├── README.md
+│   ├── quick-start.md
+│   ├── api-reference.md
+│   ├── examples.md
+│   ├── advanced-patterns.md
+│   └── troubleshooting.md
+├── implementation-guides/      # Practical guides
+│   ├── app-layout.md
+│   ├── permission-enforcement.md
+│   └── data-tables.md
+├── api-reference/              # Complete API docs
+│   ├── components.md
+│   ├── hooks.md
+│   └── types.md
+├── best-practices/             # Production patterns
+│   ├── security.md
+│   ├── performance.md
+│   └── testing.md
+├── migration/                  # Migration guides
+│   └── rbac-migration.md
+└── troubleshooting/            # Problem solving
+    ├── common-issues.md
+    └── debugging.md
+```
+
+### Standard Sections
+
+Each documentation file should include:
+
+1. **Title and Description** - Clear purpose and overview
+2. **Prerequisites** - What readers need to know first
+3. **Quick Start** - Get up and running quickly
+4. **Detailed Guide** - Comprehensive coverage
+5. **Examples** - Practical, working examples
+6. **API Reference** - Complete technical details
+7. **Troubleshooting** - Common issues and solutions
+8. **Next Steps** - What to read next
+
+## 💻 Code Examples
+
+### Example Standards
+
+1. **Complete and Runnable**
+   ```tsx
+   // ✅ Good - Complete example with imports
+   import React, { useState, useEffect } from 'react';
+   import { useCan } from '@jmruthers/pace-core';
+
+   function UserActions({ userId, scope }) {
+     const { hasPermission, isLoading } = useCan();
+     const [canEdit, setCanEdit] = useState(false);
+
+     useEffect(() => {
+       const checkPermission = async () => {
+         if (!isLoading) {
+           const editPerm = await hasPermission('update:users', { userId, scope });
+           setCanEdit(editPerm);
+         }
+       };
+       
+       checkPermission();
+     }, [hasPermission, isLoading, userId, scope]);
+
+     if (isLoading) return <div>Loading permissions...</div>;
+
+     return (
+       <div>
+         {canEdit && <button>Edit User</button>}
+       </div>
+     );
+   }
+   ```
+
+2. **Error Handling Included**
+   ```tsx
+   // ✅ Good - Includes error handling
+   try {
+     const canEdit = await hasPermission('update:users', { userId, scope });
+     setCanEdit(canEdit);
+   } catch (error) {
+     console.error('Permission check failed:', error);
+     setCanEdit(false);
+   }
+   ```
+
+3. **Consistent Naming**
+   ```tsx
+   // ✅ Good - Consistent variable names
+   const userId = 'user-123';
+   const scope = { organisationId: 'org-456' };
+   const permission = 'update:users';
+   ```
+
+### Code Block Guidelines
+
+- **Use TypeScript** - Always use `.tsx` for React components
+- **Include imports** - Show all necessary imports
+- **Add comments** - Explain complex logic
+- **Handle edge cases** - Show loading states, error handling
+- **Use realistic data** - Use meaningful variable names and values
+
+## 🔗 Cross-References
+
+### Internal Links
+
+```markdown
+<!-- ✅ Good - Clear, descriptive links -->
+See the [RBAC Quick Start Guide](./rbac/quick-start.md) for a complete example.
+
+<!-- ❌ Avoid - Vague links -->
+See [this guide](./rbac/quick-start.md) for more info.
+```
+
+### Link Patterns
+
+- **Use descriptive text** - Link text should explain what the reader will find
+- **Keep links current** - Update links when files are moved or renamed
+- **Use relative paths** - Use `./` for same directory, `../` for parent directory
+- **Test all links** - Verify links work before publishing
+
+## 🧩 Component Documentation
+
+### Component Structure
+
+Each component should be documented with:
+
+1. **Overview** - What the component does
+2. **Props** - Complete prop interface with types
+3. **Usage** - Basic usage example
+4. **Variants** - Different variants and states
+5. **Accessibility** - Accessibility features and requirements
+6. **Examples** - Practical usage examples
+7. **Troubleshooting** - Common issues and solutions
+
+### Example Component Documentation
+
+```markdown
+## Button
+
+A versatile button component with multiple variants and states.
+
+### Props
+
+```typescript
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link';
+  size?: 'default' | 'sm' | 'lg' | 'icon';
+  asChild?: boolean;
+  className?: string;
+}
+```
+
+### Usage
+
+```tsx
+import { Button } from '@jmruthers/pace-core';
+
+// Default button
+<Button onClick={handleClick}>
+  Click me
+</Button>
+
+// Destructive button
+<Button variant="destructive" size="lg">
+  Delete
+</Button>
+```
+
+### Variants
+
+- **default**: Primary button with solid background
+- **destructive**: Red button for dangerous actions
+- **outline**: Bordered button with transparent background
+- **secondary**: Secondary button with muted styling
+- **ghost**: Transparent button with hover effects
+- **link**: Button styled as a link
+
+### Accessibility
+
+- Supports keyboard navigation
+- Proper ARIA attributes
+- Focus management
+- Screen reader support
+```
+
+## 📋 API Reference Standards
+
+### Hook Documentation
+
+```markdown
+## useCan
+
+Hook for checking user permissions with caching and error handling.
+
+### Signature
+
+```typescript
+function useCan(): {
+  hasPermission: (permission: Permission, scope?: Scope) => Promise<boolean>;
+  hasAnyPermission: (permissions: Permission[], scope?: Scope) => Promise<boolean>;
+  hasAllPermissions: (permissions: Permission[], scope?: Scope) => Promise<boolean>;
+  isLoading: boolean;
+  error: Error | null;
+}
+```
+
+### Parameters
+
+- **permission**: The permission to check
+- **scope**: Optional scope context (organisation, event, etc.)
+
+### Returns
+
+- **hasPermission**: Function to check a single permission
+- **hasAnyPermission**: Function to check if user has any of the permissions
+- **hasAllPermissions**: Function to check if user has all permissions
+- **isLoading**: Whether the permission check is in progress
+- **error**: Any error that occurred during the check
+
+### Example
+
+```tsx
+import { useCan } from '@jmruthers/pace-core';
+
+function UserActions({ userId }) {
+  const { hasPermission, isLoading } = useCan();
+  const [canEdit, setCanEdit] = useState(false);
+
+  useEffect(() => {
+    const checkPermission = async () => {
+      const editPerm = await hasPermission('update:users', { userId });
+      setCanEdit(editPerm);
+    };
+    
+    checkPermission();
+  }, [hasPermission, userId]);
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      {canEdit && <EditButton />}
+    </div>
+  );
+}
+```
+```
+
+## 🆘 Troubleshooting Guidelines
+
+### Common Issues Structure
+
+```markdown
+## Common Issues
+
+### Issue: Permission Check Always Returns False
+
+**Symptoms:**
+- Permission checks return false even for valid permissions
+- No error messages are displayed
+
+**Causes:**
+1. Missing organisation context
+2. Incorrect permission format
+3. User not authenticated
+
+**Solutions:**
+
+1. **Check Organisation Context**
+   ```tsx
+   // ❌ Wrong - Missing organisation context
+   const canEdit = await hasPermission('update:users');
+   
+   // ✅ Correct - Include organisation context
+   const canEdit = await hasPermission('update:users', { 
+     organisationId: currentOrganisation.id 
+   });
+   ```
+
+2. **Verify Permission Format**
+   ```tsx
+   // ❌ Wrong - Incorrect format
+   const canEdit = await hasPermission('update users');
+   
+   // ✅ Correct - Use colon format
+   const canEdit = await hasPermission('update:users');
+   ```
+
+3. **Check Authentication**
+   ```tsx
+   const { user, isLoading } = useUnifiedAuth();
+   
+   if (isLoading) return <div>Loading...</div>;
+   if (!user) return <div>Please log in</div>;
+   ```
+
+**Prevention:**
+- Always include organisation context in permission checks
+- Use TypeScript for permission type safety
+- Test permission checks in development
+```
+
+## 🔧 Maintenance Checklist
+
+### Before Publishing
+
+- [ ] **Accuracy** - All code examples work and are current
+- [ ] **Completeness** - All necessary information is included
+- [ ] **Clarity** - Content is easy to understand
+- [ ] **Consistency** - Follows style guide and patterns
+- [ ] **Code examples** - All code is tested and working
+- [ ] **Links** - All internal and external links work
+- [ ] **Formatting** - Consistent markdown formatting
+- [ ] **Images** - All images are optimized and accessible
+- [ ] **Navigation** - Clear path through the content
+- [ ] **Examples** - Practical, real-world examples
+- [ ] **Troubleshooting** - Common issues are addressed
+- [ ] **Next steps** - Clear guidance on what to do next
+
+### Regular Updates
+
+1. **Review quarterly** - Check for outdated information
+2. **Update examples** - Ensure code examples work with current versions
+3. **Test links** - Verify all links are still valid
+4. **Gather feedback** - Ask developers about confusing sections
+
+### Version Control
+
+- **Update with code changes** - Documentation should reflect current implementation
+- **Maintain changelog** - Track documentation changes
+- **Test before merging** - Verify all examples work
+- **Review with team** - Get feedback from other developers
+
+## 🎯 Quality Assurance
+
+### Content Review
+
+1. **Technical Accuracy**
+   - All code examples compile and run
+   - API references match actual implementation
+   - Import paths are correct
+   - Environment variables are accurate
+
+2. **Completeness**
+   - All exported components are documented
+   - All hooks have usage examples
+   - All props are documented with types
+   - Common use cases are covered
+
+3. **Consistency**
+   - Terminology is consistent throughout
+   - Code examples follow the same patterns
+   - Formatting is uniform
+   - Cross-references are accurate
+
+4. **User Experience**
+   - Clear navigation path
+   - Practical examples
+   - Troubleshooting guidance
+   - Next steps provided
+
+### Testing Process
+
+1. **Code Examples** - Test all code examples in isolation
+2. **Links** - Verify all internal and external links
+3. **Cross-References** - Check all cross-references are accurate
+4. **Import Paths** - Verify all import paths work
+5. **Environment Variables** - Check environment variable names
+
+### Review Process
+
+1. **Self-Review** - Author reviews against checklist
+2. **Technical Review** - Another developer reviews for accuracy
+3. **User Testing** - Test with new developers
+4. **Final Review** - Final check before publishing
+
+## 📊 Metrics and Monitoring
+
+### Documentation Health
+
+- **Broken Links** - Monitor and fix broken links
+- **Outdated Examples** - Track examples that need updates
+- **User Feedback** - Collect and act on user feedback
+- **Search Success** - Monitor search success rates
+
+### Improvement Areas
+
+- **Common Questions** - Document frequently asked questions
+- **Pain Points** - Address common developer pain points
+- **Missing Content** - Identify and fill content gaps
+- **Outdated Information** - Keep information current
+
+This comprehensive style guide ensures that PACE Core documentation is consistent, helpful, and maintainable. Follow these guidelines to create excellent developer documentation that helps users succeed with the library.