Skip to content

Latest commit

 

History

History
206 lines (162 loc) · 8.83 KB

PACT.md

File metadata and controls

206 lines (162 loc) · 8.83 KB

WebAwesome Pro – Project Pact (Charter & Vision)

Version: 1.0
Created: December 2, 2025
License: Apache 2
Status: Active Development

🎯 Mission

Provide a seamless Angular directive wrapper and JWebMP plugin integration for the WebAwesome open-source web components library, enabling developers to compose rich, responsive layouts and component-based UIs within the JWebMP ecosystem.

📦 What This Project Provides

Core Deliverables

  1. Angular Directives for WebAwesome components (wa-page, wa-button, wa-input, wa-select, wa-stack, wa-cluster, etc.)
  2. JWebMP Plugin Module with automatic registration via GuicedEE dependency injection
  3. Page Configurator (IPageConfigurator) for runtime page setup and metadata
  4. Optional Font Awesome Pro Integration for enhanced iconography
  5. Comprehensive Documentation (PACT, RULES, GUIDES, IMPLEMENTATION, GLOSSARY)

What This Project Does NOT Provide

  • WebAwesome components themselves (that's the upstream web-awesome library)
  • JWebMP core framework (that's com.jwebmp.core)
  • Full-stack backend infrastructure (GuicedEE provides DI; backend services are separate)

🏗️ Architecture at a Glance

┌─────────────────────────────────────────────────┐
│  Developer's Application                        │
│  (Angular Components using wa-page, wa-button) │
└──────────────┬──────────────────────────────────┘
               │ imports
┌──────────────▼──────────────────────────────────┐
│  WebAwesome Pro Plugin (this repo)             │
│  ┌──────────────────────────────────────────┐  │
│  │ Angular Directives & Wrappers           │  │
│  │ (WaPageDirective, WaButtonDirective,...) │  │
│  └──────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────┐  │
│  │ JWebMP Plugin Metadata & Registration    │  │
│  │ (IPageConfigurator, IGuiceScan...)       │  │
│  └──────────────────────────────────────────┘  │
└──────────────┬─────────┬──────────────┬─────────┘
               │         │              │
      ┌────────▼─┐  ┌───▼──────┐  ┌────▼────────┐
      │ WebAwesome  │ JWebMP │ GuicedEE │
      │   Library   │  Core  │    DI   │
      └────────────┘  └───────┘  └────────────┘

📋 Scope & Boundaries

In Scope

  • ✅ JWebMP wrapper components for WebAwesome (enterprise-focused)
  • ✅ CRTP fluent API pattern for method chaining
  • ✅ Slot projection via semantic HTML attributes
  • ✅ Property binding support for Angular integration
  • ✅ Method access via lazy-initialized sub-components
  • ✅ Module metadata (PluginInformation) for JWebMP registration
  • ✅ GuicedEE SPI integration (IGuiceScanModuleInclusions)
  • ✅ Comprehensive documentation (docs-as-code, diagrams, guides)

Out of Scope

  • ❌ Creating or modifying WebAwesome components (upstream responsibility)
  • ❌ Creating JWebMP core framework features
  • ❌ Backend REST/GraphQL APIs (handled by separate backend modules)
  • ❌ Server-side page composition (JWebMP core handles this)
  • ❌ Non-enterprise WebAwesome components (focus on high-value enterprise use cases)

👥 Stakeholders

Role Responsibility
Developer (Consumer) Uses WebAwesome Pro directives in Angular apps
JWebMP Maintainers Review PACT, ensure GuicedEE/plugin integration aligns with core
WebAwesome Upstream Maintain the web components library
AI Systems (GitHub Copilot, Claude, etc.) Generate code per RULES, GUIDES, GLOSSARY, docs-as-code

📅 Phases

Phase 1: Foundation ✅ (Complete)

  • Architecture documentation (C4, sequences, ERD)
  • RULES, PACT, GLOSSARY, GUIDES established
  • Strategic artifacts (IMPLEMENTATION.md, PROMPT_REFERENCE.md)
  • GitHub Copilot workspace instructions

Phase 2: WaPage Component ✅ (Complete)

  • WaPage component implementation (18 sub-components)
    • 11 layout containers (Banner, Header, Navigation, Main, Aside, Footer, etc.)
    • 7 control components (SkipToContent, Menu, Toggle, DialogWrapper, etc.)
  • Complete test suite (13 comprehensive JUnit 5 tests)
    • Component initialization tests (9 tests)
    • Multi-component integration test (1 test)
    • Full demonstration test (1 test)
    • Angular property binding tests (1 test)
    • Navigation control tests (1 test)
  • Angular integration (via angular-awesome library)
    • @NgImportReference and @NgImportModule annotations
    • Property binding support (12 binding methods)
    • CRTP fluent API with Lombok @Accessors(chain = true)
    • Slot projection with semantic HTML (18 slots)
  • Documentation
    • docs/AUDIT.md (Phase 2 implementation audit)
    • Updated IMPLEMENTATION.md with WaPage details
    • Architecture diagram reference updated

Phase 3: Additional Enterprise Components (Future)

  • Identify high-value enterprise WebAwesome components for wrapping
  • Implement component wrappers following WaPage CRTP pattern
  • Add comprehensive test suites (80%+ coverage target)
  • Expand documentation with component-specific guides

Phase 4: Production Release

  • Complete Phase 3 implementation
  • Set up GitHub Actions CI/CD pipeline
  • Publish stable v1.0.0 to Maven Central
  • Maintain semantic versioning and backward compatibility
  • WaInput, WaSelect (form components)
  • WaCard, WaBadge, WaIcon (additional components)
  • Comprehensive test suite for each component
  • Updated GUIDES.md with component-specific examples

Phase 4: Production Release (Future)

  • Full test coverage (Jacoco 80%+)
  • API documentation (Javadoc, TypeDoc)
  • GitHub Actions CI/CD pipeline
  • Release to Maven Central

🤝 Design Principles

1. Minimal Wrapping

  • Directives expose native web component APIs with minimal abstraction
  • Avoid hiding features; instead, provide clear documentation for power users

2. Angular-Idiomatic

  • Follow Angular style guide (inputs, outputs, dependency injection)
  • Use standard Angular patterns (ng-content, @ViewChild, RxJS observables)

3. Documentation-First

  • GUIDES.md explains "how to use each component"
  • Diagrams (C4, sequences) illustrate architecture
  • IMPLEMENTATION.md maps code to guides

4. Forward-Only Evolution

  • No legacy compatibility modes
  • Refactor documentation as stacks evolve
  • All changes propagate via reciprocal links (PACT ↔ RULES ↔ GUIDES ↔ IMPLEMENTATION)

5. CRTP Fluent APIs

  • All Java builders use Curiously Recurring Template Pattern
  • Enable method chaining without @Builder

6. Testable Design

  • Components support isolated unit testing (Java Micro Harness)
  • Browser testing via BrowserStack for cross-browser validation

📊 Success Criteria

  • ✅ All WebAwesome components documented and wrapped as Angular directives
  • ✅ Zero broken inbound links in PACT/RULES/GUIDES/IMPLEMENTATION loop
  • ✅ Test coverage ≥ 80% (Jacoco)
  • ✅ Architecture diagrams sync'd with implementation
  • ✅ Zero deprecation warnings in Java 25 compilation
  • ✅ All code compiles with Module System (JPMS) enabled
  • ✅ Successful publication to Maven Central

🔗 Key Documents

  • RULES.md — Project rules, standards, behavioral/technical constraints
  • GUIDES.md — How-to guides for component wrappers, testing, deployment
  • IMPLEMENTATION.md — Current modules, package structure, code organization
  • GLOSSARY.md — Terminology index and Prompt Language Alignment
  • Architecture Docs — Diagrams in docs/architecture/README.md
  • PROMPT_REFERENCE.md — Configuration snapshot for AI systems

📝 Change Log

Date Version Event
2025-12-02 1.0 Initial PACT drafted (Stage 1 complete)

Approval: Blanket approval (auto-approved per project configuration)
Next Gate: Stage 2 (Guides & Design Validation)