My Two-Perspectives App

Demonstrating the "Two-Perspective DSL" Approach

This example application showcases the new "Two-Perspective DSL" capability of the mcf-communication framework. It implements the same coordinator-worker pattern as my-headless-app but utilizes a more declarative approach for defining component interfaces and interactions.

Key Features Demonstrated

• Two-Perspective DSL:
  • Child Self-Definition: Components like WorkerComponent and CoordinatorComponent define their handled commands (onCommandName="handler") and emitted events (emits="...") directly within their own definition files (worker.component.html, coordinator.component.html) using definition tags (<worker-definition>, <coordinator-definition>).
  • Parent Usage: Parent components (AppComponent, CoordinatorComponent) use simple tags (<coordinator>, <worker>) in their templates to include children and declaratively bind to the child's emitted events using onEventName="parentHandler" attributes.
  • Matrix-Level DSL: A top-level <matrix-definition> component serves as an "outer container" for the environment, holding environment-level attributes like rootTopic and referencing <app> usage.
• Multi-Event Emission:
  • Support for defining multiple events in emits attribute (e.g., emits="SystemCompleted:direct, AnotherEvent:bubble").
• Declarative Command & Event Wiring: The framework automatically wires both the self-defined command handlers and the parent-listens-to-child event handlers based entirely on the DSL attributes, minimizing boilerplate code in the .component.ts files.
• No className in DSL: Component types are resolved via NodeFactory.register using the DSL tag names (both definition and usage tags), keeping the DSL clean.
• Recursive DSL Loading & Merging: The bootstrap.ts uses the loadComponentTreeRecursively logic (shared with my-headless-app) to find, load, and merge component definition files with their usage tags, creating a complete description tree for NodeFactory.

Table of Contents

• My Two-Perspectives App
  • Demonstrating the "Two-Perspective DSL" Approach
    • Key Features Demonstrated
  • Table of Contents
  • Architecture & Implementation Notes
  • Usage & Build Instructions
    • Building and Running
    • Testing
    • Important Notes
  • Logging
    • Running with Different Log Levels
    • Log Format in Code
  • Links to Docs
  • License
  • Matrix CLI Compatibility Requirements
    • Build Output
    • TypeScript Configuration (tsconfig.json)
    • Component Requirements

Architecture & Implementation Notes

• Framework: Relies on the core mcf-communication package, utilizing the enhanced NodeFactory and DslNodeDescription which support the two-perspective model.
• Bootstrapping (bootstrap.ts):
  • Implements loadComponentTreeRecursively to load and merge definition files (*.component.html) with usage tags.
  • Registers both definition tags (e.g., worker-definition) and usage tags (e.g., worker) with NodeFactory, mapping them to the same component class.
• DSL Files (*.component.html):
  • Definition Files: Use tags ending in -definition (e.g., <coordinator-definition>). Contain onCommandName="handler" attributes for self-commands and emits="EventA,EventB" to declare events. May also contain child tags defining the component's internal structure.
  • Usage in Parent Files: Use simple tags (e.g., <coordinator>) with an id. Contain onEventName="parentHandler" attributes for listening to child events.
• Component Logic (*.component.ts):
  • Handler methods match the onCommandName and onEventName attributes in the DSL.
  • No manual this.onCommand(...) calls are needed for commands defined via onCommandName in the definition DSL.

Usage & Build Instructions

1. Ensure you have Node.js and npm installed.
2. Clone the repository.
3. Install dependencies at the monorepo root: npm install
4. Navigate to the my-two-perspectives-app package directory: cd packages/my-two-perspectives-app
5. Install dependencies for this package (if not using workspace hoisting): npm install

Building and Running

This package uses tsc (the TypeScript compiler) for building the TypeScript source code and copying assets.

To build the package, run the build script:

npm run build

This will:

1. Cleans the dist directory (prebuild script).
2. Compiles TypeScript to JavaScript (build script using tsc).
3. Copies *.component.html DSL files to the dist/components/... directory structure (postbuild script).
4. Copies matrix.html to the dist directory (postbuild script).

To run the application after building:

# Run with debug logging enabled
npm run run

# OR run with only info logging (no debug)
npm run info

# Using the Matrix CLI (recommended approach) - run from the root of the monorepo
# Ensure matrix-cli is built and available in your PATH or use npx
# npx matrix up packages/my-two-perspectives-app/dist/matrix.html
# OR specify a DSL file
# npx matrix up packages/my-two-perspectives-app/dist/matrix.html
# OR use watch mode for auto-rebuild on file changes
# npx matrix watch packages/my-two-perspectives-app/dist/matrix.html

Testing

This package uses Jest for running tests.

To run the tests, use the test script:

npm test

Note: This package currently has no test files, so running npm test will exit with code 0 and report "No tests found". The --passWithNoTests flag is used in the script to allow this.

Important Notes

• This app demonstrates the recommended way to use the framework going forward, leveraging the two-perspective DSL for maximum clarity and reduced boilerplate.
• Compare this implementation with my-headless-app to see the difference between the declarative (two-perspective) and imperative command handling approaches.
• The Matrix CLI with matrix.html is the recommended approach for running applications. It provides:
  • Auto-registration of components
  • Environment-level DSL with the <matrix-definition> component
  • Watch mode for auto-rebuild on file changes
• Manual vs. CLI Usage:
  • CLI (Recommended): Uses auto-registration by scanning dist/components and supports matrix up and matrix watch commands.
  • Manual: Still supported by calling bootstrapApp(...) directly, which uses manual NodeFactory.register(...) calls if process.env.MATRIX_AUTO_REGISTER is not set.
• DSL Merging: The system intelligently merges child definitions, so you don't need to duplicate <coordinator> or <worker> definitions in matrix.html if they're already referenced in app.component.html.

Logging

This application uses the logging system provided by the mcf-communication package:

Running with Different Log Levels

# Run with debug logging enabled (shows all logs)
npm run run
# OR
npm run debug

# Run with only info logging (no debug logs)
npm run info

Log Format in Code

All logs in the application follow a consistent format:

// Debug log with details
logDebug(`[ComponentName:${this.id}] Descriptive message`, {
  detailKey1: value1,
  detailKey2: value2
});

// Info log (always shown)
logInfo(`[ComponentName:${this.id}] Important status update`);

For more details on the logging system, see the mcf-communication README.

Links to Docs

• Root Project README
• Root Docs Folder
• Design Log: Two-Perspective DSL Implementation
• Design Log: Matrix CLI Auto-Registration
• Design Log: Matrix CLI Watch Mode
• mcf-communication README
• my-headless-app README

License

MIT

Matrix CLI Compatibility Requirements

To ensure that this package can be correctly installed and executed by the Matrix CLI (matrix install, matrix up), specific build and configuration standards must be met.

Build Output

The package must be built so that the compiled JavaScript (.js) files and any necessary assets (like .html templates) are placed directly within the dist/ directory. The structure within dist/ must mirror the structure of the src/ directory.

For example:

• src/components/app/app.component.ts should compile to dist/components/app/app.component.js.
• src/components/app/app.component.html should be copied to dist/components/app/app.component.html.

This structure is essential for the Matrix CLI's dynamic loading and component registration mechanisms.

TypeScript Configuration (tsconfig.json)

The tsconfig.json file plays a critical role in achieving the required build output structure. It is highly recommended to use the tsconfig.json from the mcf-communication package as a template or baseline, as it contains settings proven to work with the Matrix CLI.

Key settings that influence compatibility include:

• outDir: Must be set to "./dist".
• rootDir: Should typically be set to "./src".
• module: Needs to be compatible with the CLI's loading mechanism (e.g., "NodeNext" or "CommonJS" depending on the project setup).
• noEmit: Must be false to ensure JavaScript files are generated.

Important: Avoid modifying the tsconfig.json file unless you fully understand how the changes will impact the final build output structure in the dist/ directory. Incorrect configuration can prevent the Matrix CLI from installing or running the package.

Component Requirements

• Base Class: All components intended to be managed by the Matrix framework must extend BaseCommunicationComponent from the mcf-communication package.
• Exports: Components must be exported from their corresponding compiled JavaScript (.js) files within the dist/ directory structure. This allows the Matrix CLI's auto-registration mechanism to discover and register them correctly during the matrix up process.