@jmruthers/pace-core 0.5.76 → 0.5.78

package/docs/DOCUMENTATION_CHECKLIST.md

@@ -1,281 +0,0 @@
-# PACE Core Documentation Quality Checklist
-
-> **📚 For Contributors** | [← Documentation Home](./README.md) | [Style Guide](./style-guide.md)] | [Review Report](../DOCUMENTATION_REVIEW_REPORT.md)
-
-Use this checklist when creating or updating PACE Core documentation to ensure quality and consistency.
-
-## ✅ Pre-Writing Checklist
-
-### Determine Documentation Type
-
-- [ ] Is this a **new feature**? → Create/update relevant guides
-- [ ] Is this a **breaking change**? → Update breaking-changes.md
-- [ ] Is this a **bug fix**? → Update troubleshooting if relevant
-- [ ] Is this an **API change**? → Update api-reference/
-- [ ] Is this a **configuration change**? → Update installation/configuration docs
-
-### Identify Target Audience
-
-- [ ] **New users** → Getting started/quick-start
-- [ ] **Experienced users** → Implementation guides/API reference
-- [ ] **Advanced users** → Best practices/advanced patterns
-- [ ] **Troubleshooting** → Specific error/issue resolution
-
-## ✅ Content Quality Checklist
-
-### Structure
-
-- [ ] Has clear, descriptive title
-- [ ] Includes navigation breadcrumbs
-- [ ] Has table of contents (for long documents)
-- [ ] Uses consistent heading hierarchy (H1 → H2 → H3)
-- [ ] Ends with "Related" or "Next Steps" section
-- [ ] Includes version metadata (last updated, version)
-
-### Writing Quality
-
-- [ ] Uses active voice ("Create" not "should be created")
-- [ ] Explains "why" not just "what"
-- [ ] Uses simple, clear language
-- [ ] Avoids jargon without explanation
-- [ ] Provides context and background
-- [ ] Includes realistic, working examples
-
-### Code Examples
-
-- [ ] **Always includes imports** - Full import statements
-- [ ] **Always includes context** - Not just snippets
-- [ ] **Always explains purpose** - What it does and why
-- [ ] **Always handles errors** - Shows error handling
-- [ ] **Uses realistic data** - Meaningful variable names
-- [ ] **Tested and working** - Code actually runs
-- [ ] **Properly formatted** - Correct indentation and syntax
-
-### Accuracy
-
-- [ ] Matches current implementation
-- [ ] Uses correct API signatures
-- [ ] References correct version numbers
-- [ ] Links to existing files only
-- [ ] No broken references
-- [ ] Deprecated content is marked
-
-## ✅ Technical Checklist
-
-### Links and References
-
-```bash
-# Check for broken links
-grep -r "\[.*\](\./.*\.md)" your-file.md | while read line; do
-  # Extract the link
-  # Verify file exists
-  # Report broken links
-done
-```
-
-- [ ] All internal links work (relative paths)
-- [ ] All external links accessible
-- [ ] No orphan references (linking to non-existent files)
-- [ ] Link text is descriptive ("Installation Guide" not "here")
-- [ ] Uses correct markdown link syntax
-
-### Terminology
-
-- [ ] Uses "organisation" (British spelling) consistently
-- [ ] Uses consistent RBAC terminology
-- [ ] Consistent capitalization (e.g., "PACE Core" not "pace-core")
-- [ ] Consistent naming for components/hooks
-- [ ] Abbreviations defined on first use
-
-### Code Formatting
-
-- [ ] Proper syntax highlighting (```tsx, ```bash, etc.)
-- [ ] No trailing whitespace
-- [ ] Consistent indentation (2 spaces for TS/TSX)
-- [ ] Code is runnable/tested
-- [ ] Uses appropriate type annotations
-
-## ✅ Specific Section Checklists
-
-### Installation/Setup Documentation
-
-- [ ] Lists all requirements upfront
-- [ ] Provides command examples
-- [ ] Shows expected output
-- [ ] Includes troubleshooting section
-- [ ] Links to related configuration
-
-### API Documentation
-
-- [ ] Complete parameter descriptions
-- [ ] Return type specifications
-- [ ] Usage examples
-- [ ] Error handling examples
-- [ ] Related hooks/providers listed
-
-### Troubleshooting
-
-- [ ] Clear problem statement
-- [ ] Specific error messages
-- [ ] Step-by-step solution
-- [ ] Expected vs actual behavior
-- [ ] Links to related issues
-
-### Breaking Changes
-
-- [ ] **Required** - Must update breaking-changes.md
-- [ ] Clear before/after comparison
-- [ ] Migration steps provided
-- [ ] Impact assessment included
-- [ ] Version information included
-
-## ✅ Post-Writing Verification
-
-### Automated Checks
-
-```bash
-# Run these commands before committing
-
-# 1. Check for broken links
-npx markdown-link-check docs/**/*.md
-
-# 2. Lint markdown
-npx markdownlint docs/**/*.md
-
-# 3. Spell check
-npx cspell "docs/**/*.md"
-
-# 4. Verify all links resolve
-node scripts/verify-docs.js
-```
-
-- [ ] No broken links (verify after changes)
-- [ ] All code examples formatted correctly
-- [ ] No typos or spelling errors
-- [ ] Proper grammar throughout
-- [ ] Consistent formatting
-
-### Manual Review
-
-- [ ] Read through entire document
-- [ ] Verify all examples still work
-- [ ] Check that instructions are complete
-- [ ] Ensure navigation makes sense
-- [ ] Verify all referenced files exist
-- [ ] Add to appropriate index/nav
-
-## ✅ File-Specific Requirements
-
-### README Files
-
-- [ ] Single H1 heading (title)
-- [ ] Navigation links at top
-- [ ] Quick start section
-- [ ] Table of contents for long files
-- [ ] Links to related documentation
-- [ ] Version and date information
-
-### API Reference
-
-- [ ] Component/hook name in H1
-- [ ] Import statement example
-- [ ] Props/parameters table
-- [ ] Usage examples
-- [ ] Related components listed
-- [ ] Type definitions included
-
-### Implementation Guides
-
-- [ ] Step-by-step instructions
-- [ ] Code examples for each step
-- [ ] Common pitfalls noted
-- [ ] Best practices included
-- [ ] Related concepts linked
-- [ ] Troubleshooting section
-
-### Core Concepts
-
-- [ ] Clear explanation of concept
-- [ ] Visual aids (diagrams, if applicable)
-- [ ] Real-world use cases
-- [ ] How it fits with other concepts
-- [ ] Related implementation guides
-
-## ✅ Documentation Maintenance
-
-### Weekly
-
-- [ ] Check for new GitHub issues that need docs
-- [ ] Review recent PRs for doc updates needed
-- [ ] Update outdated information
-
-### Monthly
-
-- [ ] Audit all internal links
-- [ ] Review API reference accuracy
-- [ ] Update examples to match latest patterns
-- [ ] Check version numbers
-
-### Quarterly
-
-- [ ] Full documentation review
-- [ ] Update style guide based on lessons learned
-- [ ] Review and improve navigation
-- [ ] Assess documentation gaps
-
-## ❌ Common Mistakes to Avoid
-
-### Don't Do This
-
-```markdown
-<!-- ❌ BAD -->
-You can read the docs [here](./docs.md).
-The component accepts props and returns data.
-Just use this: <Button /> and it works.
-
-<!-- ✅ GOOD -->
-See the [Installation Guide](./installation-guide.md) for setup instructions.
-The Button component accepts onClick (function) and returns a button element.
-Use the Button component like this:
-```
-
-- ❌ Don't use "here" or "this" for link text
-- ❌ Don't assume context - provide it
-- ❌ Don't skip imports in code examples
-- ❌ Don't link to files that don't exist
-- ❌ Don't use vague examples (foo, bar, baz)
-- ❌ Don't forget error handling in examples
-- ❌ Don't write in passive voice when possible
-- ❌ Don't omit the "why" behind recommendations
-
-## ✅ Final Checklist Before Publishing
-
-- [ ] Content is accurate and up-to-date
-- [ ] All code examples tested
-- [ ] No broken links or references
-- [ ] Consistent with style guide
-- [ ] Added to appropriate navigation
-- [ ] Version metadata included
-- [ ] Reviewed by another contributor (if possible)
-- [ ] Related documentation updated
-
----
-
-## 📚 Resources
-
-- [Style Guide](./style-guide.md) - Complete style and formatting guide
-- [Documentation Index](./documentation-index.md) - All documentation organized by topic
-- [Review Report](../DOCUMENTATION_REVIEW_REPORT.md) - Latest documentation review findings
-- [Breaking Changes](./breaking-changes.md) - Track all breaking changes
-- [Quick Reference](./quick-reference.md) - Common tasks at a glance
-
----
-
-**Need Help?**
-
-- Questions about documentation? Check the [Style Guide](./style-guide.md)
-- Found a bug in documentation? File an issue or submit a PR
-- Want to contribute? Follow this checklist and the style guide
-
-**Last Updated:** 2025-01-XX | **Version:** v0.5.65+
-

package/docs/TERMINOLOGY.md

@@ -1,231 +0,0 @@
-# PACE Core Terminology Reference
-
-> **📚 Reference**: Standard Terms | [← Documentation Home](./README.md)
-
-Standard terminology and naming conventions for PACE Core documentation and code.
-
----
-
-**Last Updated**: 2025-02-08 | **Version**: v0.5.65+
-
-## Purpose
-
-This document establishes consistent terminology across all PACE Core documentation, code examples, and API references. Always use these terms as specified.
-
-## Core Terms
-
-### Authentication & Users
-
-| Term | Usage | Example | Notes |
-|------|-------|---------|-------|
-| **user** | Lowercase noun | "the user logged in" | Generic user |
-| **User** | Capitalized when referring to type/class | `interface User` | TypeScript interface |
-| **authenticated user** | Use for logged-in users | "authenticated user session" | Preferred over "logged-in user" |
-| **session** | Lowercase | "user session" | Not "Session" |
-| **sign in / sign out** | Verb form | "sign in to your account" | Preferred over "login/logout" |
-| **login / logout** | Noun form | "login page", "logout button" | Only as nouns |
-
-### Organisations & Events
-
-| Term | Usage | Example | Notes |
-|------|-------|---------|-------|
-| **organisation** | Always use "organisation" | "select organisation" | British spelling (project standard) |
-| **organization** | ❌ Never use | - | American spelling - not used |
-| **event** | Lowercase noun | "select an event" | Specific event instance |
-| **Event** | Capitalized for type/component | `EventProvider` | Component/type name |
-| **organisation context** | Lowercase | "organisation context is required" | Security context |
-| **organisationId** | camelCase variable | `const { organisationId } = useOrganisation()` | Property name |
-| **eventId** | camelCase variable | `const { eventId } = useEvent()` | Property name |
-
-### RBAC & Permissions
-
-| Term | Usage | Example | Notes |
-|------|-------|---------|-------|
-| **RBAC** | All caps when referring to system | "the RBAC system" | Acronym |
-| **rbac** | Lowercase for paths/modules | `@jmruthers/pace-core/rbac` | Module path |
-| **permission** | Lowercase noun | "check permission" | Individual permission |
-| **Permission** | Capitalized for type/component | `Permission` type | TypeScript type |
-| **role** | Lowercase noun | "user role" | RBAC role |
-| **Role** | Capitalized for type | `Role` type | TypeScript type |
-| **scope** | Lowercase noun | "permission scope" | Security scope |
-| **Scope** | Capitalized for type | `Scope` type | TypeScript type |
-
-### Components & UI
-
-| Term | Usage | Example | Notes |
-|------|-------|---------|-------|
-| **component** | Lowercase noun | "create a component" | Generic component |
-| **Component** | Capitalized for component name | `DataTable` component | React component |
-| **page** | Lowercase noun | "create a page" | Application page |
-| **Page** | Capitalized for component | `LoginPage` | React component |
-| **modal / dialog** | Use "modal" or "dialog" | "open modal" | Both terms acceptable |
-| **button** | Lowercase noun | "click the button" | Generic button |
-| **Button** | Capitalized for component | `<Button>Click</Button>` | React component |
-
-### Data & API
-
-| Term | Usage | Example | Notes |
-|------|-------|---------|-------|
-| **data** | Lowercase noun | "fetch data" | Generic data |
-| **Data** | Capitalized for type | `UserData` type | TypeScript type |
-| **API** | All caps when referring to API | "call the API" | Acronym |
-| **api** | Lowercase for paths | `api/` directory | Directory path |
-| **RPC** | All caps when referring to RPC | "RPC function" | Acronym |
-| **rpc** | Lowercase for paths | `rpc/` directory | Directory path |
-
-## Naming Conventions
-
-### File Names
-
-| Pattern | Example | Usage |
-|---------|---------|-------|
-| **kebab-case** | `data-table.md` | Documentation files |
-| **camelCase** | `dataTable.tsx` | React components |
-| **PascalCase** | `DataTable.tsx` | Component file names |
-| **UPPER_SNAKE_CASE** | `API_KEY` | Environment variables |
-
-### Variable Names
-
-| Pattern | Example | Usage |
-|---------|---------|-------|
-| **camelCase** | `userId`, `isLoading` | Variables, functions |
-| **PascalCase** | `UserData`, `ApiClient` | Classes, interfaces |
-| **UPPER_SNAKE_CASE** | `MAX_RETRIES` | Constants |
-| **CONSTANT_CASE** | `API_BASE_URL` | Environment constants |
-
-### Property Names
-
-| Pattern | Example | Usage |
-|---------|---------|-------|
-| **camelCase** | `organisationId`, `appName` | Object properties |
-| **kebab-case** | `aria-label`, `data-testid` | HTML attributes |
-| **id** | Always lowercase | `id="user-123"` |
-
-## Common Mistakes to Avoid
-
-### ❌ Incorrect Usage
-
-```typescript
-// ❌ Wrong: Mixed spelling
-const organizationId = getOrganisationId();
-
-// ❌ Wrong: Inconsistent capitalization
-function getUser(userId: string) { }
-class userService { }
-
-// ❌ Wrong: Inconsistent terminology
-function checkUserPermission() { }
-function validateUserAccess() { }
-```
-
-### ✅ Correct Usage
-
-```typescript
-// ✅ Correct: Consistent terminology
-const organisationId = getOrganisationId();
-
-// ✅ Correct: Consistent capitalization
-function getUser(userId: string) { }
-class UserService { }
-
-// ✅ Correct: Consistent terminology
-function checkUserPermission() { }
-function checkUserPermission() { } // Same term used consistently
-```
-
-## Special Cases
-
-### App vs Application
-
-- **App**: When referring to a specific application instance (e.g., "my app", "the app")
-- **Application**: When referring to the software concept (e.g., "application architecture", "application state")
-- **appName**: Always use "appName" in code (property name)
-
-### Setup vs Set Up
-
-- **setup** (noun): "the setup process", "setup files"
-- **set up** (verb): "set up your environment", "I need to set up RBAC"
-
-### Login vs Sign In
-
-- **login** (noun): "login page", "login form"
-- **sign in** (verb): "sign in to your account", "user must sign in"
-- **Sign in** (title/button): "Sign In" button text
-
-### Props vs Properties
-
-- **props**: React component props (short form)
-- **properties**: Object properties in general
-- Both acceptable, but be consistent within a document
-
-## Version-Specific Terms
-
-### Current Version (v0.5.65+)
-
-- ✅ **UnifiedAuthProvider** (NOT AuthProvider)
-- ✅ **useUnifiedAuth** (NOT useAuth)
-- ✅ **requireOrganisationContext** (prop name)
-- ✅ **idleTimeoutMs** (prop name)
-- ✅ **warnBeforeMs** (prop name)
-
-### Deprecated Terms
-
-| Old Term | New Term | Version |
-|----------|----------|---------|
-| `AuthProvider` | `UnifiedAuthProvider` | v0.5.65+ |
-| `useAuth` | `useUnifiedAuth` | v0.5.65+ |
-| `setupRBAC()` | Not needed (automatic) | v0.5.65+ |
-
-## Documentation-Specific Terms
-
-### Section Headings
-
-- **Overview**: Introduction to the topic
-- **Quick Start**: Getting started quickly
-- **Implementation**: How to implement
-- **Examples**: Code examples
-- **Best Practices**: Recommended patterns
-- **Troubleshooting**: Common issues and fixes
-- **API Reference**: Complete API documentation
-
-### Navigation Terms
-
-- **← Back**: Link to previous page
-- **Next →**: Link to next page
-- **Related**: Links to related topics
-- **See Also**: Additional resources
-
-## Acronyms and Abbreviations
-
-| Term | Full Form | Usage |
-|------|-----------|-------|
-| **RBAC** | Role-Based Access Control | Always spelled out first time |
-| **RPC** | Remote Procedure Call | Used in code context |
-| **API** | Application Programming Interface | Standard term |
-| **UI** | User Interface | Standard term |
-| **UX** | User Experience | Standard term |
-| **WCAG** | Web Content Accessibility Guidelines | Spelled out first time |
-| **ARIA** | Accessible Rich Internet Applications | Used in accessibility context |
-| **Supabase** | Supabase (product name) | Always capitalized |
-
-## Quick Reference Checklist
-
-When writing documentation, ensure you:
-
-- [ ] Use **organisation** (British spelling), not organization
-- [ ] Use **sign in** (verb), not login
-- [ ] Use **camelCase** for variables, **PascalCase** for components
-- [ ] Use **lowercase** for generic terms, **Capitalized** for types/components
-- [ ] Be consistent within each document
-- [ ] Spell out acronyms first time they appear
-- [ ] Use standard PACE Core terms from this guide
-
-## Related Documentation
-
-- [Style Guide](./style-guide.md)
-- [Documentation Templates](./documentation-templates.md)
-- [API Reference](./api-reference/components.md)
-
----
-
-**Remember**: Consistency is key to professional, maintainable documentation!