Jacob Schmidt 827f3303a2 feat: add initial Docus setup and sync tool for documentation generation

- Created package.json for Docus with necessary scripts and dependencies.
- Implemented sync-docus-docs.mjs to automate the generation of documentation files from source markdown.
- Defined mappings for generated pages and virtual routes to ensure proper linking in documentation.
- Added static content files for the documentation structure, including navigation and index pages.

2026-04-21 16:07:27 -05:00

2.6 KiB

Raw Blame History

Client Common Usage Guide

The client common addon contains shared browser UI bridge declarations and common client-side browser integration patterns.

Purpose

Use forge_client_common when a browser-backed feature UI needs reusable screen lifecycle behavior:

active browser control tracking
browser ready state
pending event queues
ExecJS payload delivery
shared bridge object inheritance through createHashMapObject

Feature addons still own their app-specific events and server RPC mapping.

Shared Bridge

Initialize the bridge declarations with:

private _webUIDeclarations = call forge_client_common_fnc_initWebUIBridge;
private _bridgeDeclaration = _webUIDeclarations get "bridgeDeclaration";

Feature bridges can inherit from the shared declaration:

GVAR(MyUIBridgeBaseClass) = compileFinal createHashMapFromArray [
    ["#base", _bridgeDeclaration],
    ["#type", "MyUIBridgeBaseClass"],
    ["handleReady", compileFinal {
        params [["_control", controlNull, [controlNull]]];

        _self call ["setActiveBrowserControl", [_control]];
        _self call ["sendEvent", ["myAddon::hydrate", createHashMap, _control]];
    }]
];

Event Delivery

sendEvent builds this payload:

{
  "event": "myAddon::event",
  "data": {}
}

If the browser control is missing or not ready, the payload is queued on the screen object. When the screen marks ready, flushPendingEvents delivers the queue.

Screen Lifecycle

The shared screen object tracks:

Field	Purpose
`control`	Active browser control.
`readyState`	Whether the browser app has sent its ready event.
`pendingEvents`	Outbound events waiting for a ready browser.

Call handleClose or dispose when a display closes so stale controls and queued events are cleared.

Current Consumers

The common bridge pattern is used by the newer bank, CAD, garage, and organization client bridges. Store currently keeps its own bridge object and browser bridge function names.

Usage Rules

Keep bridge inheritance in feature addons thin and explicit.
Keep shared code generic; do not add bank, CAD, org, or store-specific logic to common.
Prefer namespaced events such as garage::sync.
Send hash maps or arrays that can be safely serialized with toJSON.
Avoid direct extension calls from the client bridge; send CBA server events.

2.6 KiB Raw Blame History