57 lines
1.9 KiB
Markdown
57 lines
1.9 KiB
Markdown
|
# Widget Envelope Convention
|
||
|
|
|
||
|
|
Every rendered widget in inter-hub wraps its HSX in the `widgetEnvelope` helper
|
||
|
|
from `Application.Helper.View`. This injects a stable set of `data-*` attributes
|
||
|
|
that enable client-side event capture without coupling to implementation details.
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
```haskell
|
||
|
|
import Application.Helper.View (widgetEnvelope)
|
||
|
|
|
||
|
|
-- In any view:
|
||
|
|
widgetEnvelope widget [hsx|
|
||
|
|
<button class="...">Click me</button>
|
||
|
|
|]
|
||
|
|
```
|
||
|
|
|
||
|
|
## Emitted HTML
|
||
|
|
|
||
|
|
```html
|
||
|
|
<div
|
||
|
|
class="ihf-widget"
|
||
|
|
data-widget-id="<uuid>"
|
||
|
|
data-widget-type="chart"
|
||
|
|
data-hub-id="<uuid>"
|
||
|
|
data-capability-ref="pipeline.run"
|
||
|
|
data-view-context="ops/dashboard"
|
||
|
|
data-policy-scope="internal"
|
||
|
|
data-widget-version="3"
|
||
|
|
>
|
||
|
|
<!-- inner content -->
|
||
|
|
<div class="ihf-widget-controls">
|
||
|
|
<a href="/widgets/<uuid>/annotations" class="ihf-annotate-btn">Annotate</a>
|
||
|
|
</div>
|
||
|
|
</div>
|
||
|
|
```
|
||
|
|
|
||
|
|
## Attributes
|
||
|
|
|
||
|
|
| Attribute | Source | Purpose |
|
||
|
|
|-----------|--------|---------|
|
||
|
|
| `data-widget-id` | `widget.id` | Stable identity for event capture |
|
||
|
|
| `data-widget-type` | `widget.widgetType` | Semantic role of the widget |
|
||
|
|
| `data-hub-id` | `widget.hubId` | Which hub owns this widget |
|
||
|
|
| `data-capability-ref` | `widget.capabilityRef` | Link to hub capability |
|
||
|
|
| `data-view-context` | `widget.viewContext` | Logical location in the UI |
|
||
|
|
| `data-policy-scope` | `widget.policyScope` | Governance policy boundary |
|
||
|
|
| `data-widget-version` | `widget.version` | Version at render time |
|
||
|
|
|
||
|
|
## Rules
|
||
|
|
|
||
|
|
1. **Every interactive hub element** that participates in governance must be wrapped.
|
||
|
|
2. The `data-widget-id` is the capture key — the event capture endpoint uses it as `widget_id`.
|
||
|
|
3. Do not add or remove `data-*` attributes without updating both this convention doc and
|
||
|
|
the event capture client script.
|
||
|
|
4. The "Annotate" control is always rendered. It links to the full annotation thread for the widget.
|