@formicoidea/labre-framework-uml 0.42.0

package/dist/element-renderer.d.ts

@@ -0,0 +1,64 @@
+import { type ElementRenderer } from '@formicoidea/labre-core/blocks/surface';
+import type { UmlDiagramElementModel, UmlFragmentElementModel, UmlPartitionElementModel, UmlRegionElementModel, UmlSubjectElementModel } from '@formicoidea/labre-core/model';
+/**
+ * Canvas renderers for the four UML frames.
+ *
+ * There is almost no UML drawing code here: both are INSTANTIATIONS of the
+ * framework-background primitive, configured by the declarations in
+ * `background.ts`. The diagram frame adds exactly one thing the primitive has no
+ * vocabulary for — the cut-corner heading tag of Annex A — through the decorator
+ * in `frame-tag.ts`.
+ *
+ * Exported as functions as well as extensions because the fidelity suite drives
+ * them directly with a canvas stub.
+ */
+export declare const umlDiagram: ElementRenderer<UmlDiagramElementModel>;
+export declare const UmlDiagramRendererExtension: import("@formicoidea/labre-core/store/index.js").ExtensionType & {
+    identifier: import("@formicoidea/labre-core/_pkgs/global/di/types.js").ServiceIdentifier<ElementRenderer<UmlDiagramElementModel>>;
+};
+export declare const umlSubject: ElementRenderer<UmlSubjectElementModel>;
+export declare const UmlSubjectRendererExtension: import("@formicoidea/labre-core/store/index.js").ExtensionType & {
+    identifier: import("@formicoidea/labre-core/_pkgs/global/di/types.js").ServiceIdentifier<ElementRenderer<UmlSubjectElementModel>>;
+};
+export declare const umlPartition: ElementRenderer<UmlPartitionElementModel>;
+export declare const UmlPartitionRendererExtension: import("@formicoidea/labre-core/store/index.js").ExtensionType & {
+    identifier: import("@formicoidea/labre-core/_pkgs/global/di/types.js").ServiceIdentifier<ElementRenderer<UmlPartitionElementModel>>;
+};
+/** The composite state (§14.2.4) — one declaration, no orientation to turn. */
+export declare const umlRegion: ElementRenderer<UmlRegionElementModel>;
+export declare const UmlRegionRendererExtension: import("@formicoidea/labre-core/store/index.js").ExtensionType & {
+    identifier: import("@formicoidea/labre-core/_pkgs/global/di/types.js").ServiceIdentifier<ElementRenderer<UmlRegionElementModel>>;
+};
+/**
+ * A SPLIT fragment as it is painted: its declared `name` hidden behind operand
+ * zero's own guard.
+ *
+ * The contract is `background.ts`'s — an unsplit fragment's guard is the
+ * background's `name`, a split one's guards are its `operands[].name` and
+ * nothing else — and the writers keep it (`toolbar/config.ts` clears `name` as
+ * it splits, `import.ts` never writes both). This is the DEFENSIVE half: the
+ * declared guard label and operand zero's are anchored in the very same corner,
+ * so a document that still carries both — one written by an older build, or by
+ * hand — would paint two strings one over the other, which reads as a smudge
+ * rather than as a mistake. A shadowing own prop rather than a second
+ * declaration, because the suppression is conditional on another prop and the
+ * declaration language has no vocabulary for that (`visibleProp` gates on
+ * presence, never on absence).
+ *
+ * ## Exported, because the HIT TEST has to read the same declaration
+ *
+ * A suppression the renderer keeps to itself is a label drawn nowhere and
+ * clickable anyway: `UmlFragmentView` derives its rename boxes from
+ * `backgroundLabelHits`, and given the raw model that call still returns
+ * `name`'s box — so a double-click in the corner of such a document would open
+ * an editor on a string the canvas does not paint. The view therefore hit-tests
+ * against THIS declaration rather than the stored one
+ * (`element-view.ts`, `UmlFragmentView._painted`), which is the invariant the
+ * class comment there already claims: "a label can never be drawn in one place
+ * and clicked in another".
+ */
+export declare function umlFragmentAsPainted(model: UmlFragmentElementModel): UmlFragmentElementModel;
+export declare const umlFragment: ElementRenderer<UmlFragmentElementModel>;
+export declare const UmlFragmentRendererExtension: import("@formicoidea/labre-core/store/index.js").ExtensionType & {
+    identifier: import("@formicoidea/labre-core/_pkgs/global/di/types.js").ServiceIdentifier<ElementRenderer<UmlFragmentElementModel>>;
+};

package/dist/element-renderer.js

@@ -0,0 +1,114 @@
+import { createFrameworkBackgroundRenderer, ElementRendererExtension, } from '@formicoidea/labre-core/blocks/surface';
+import { UML_DIAGRAM_FRAME, UML_FRAGMENT_FRAME, UML_PARTITION_FRAME_H, UML_PARTITION_FRAME_V, UML_REGION_FRAME, UML_SUBJECT_FRAME, } from './background.js';
+import { UML_DIAGRAM_MARGIN, UML_FRAGMENT_BAND, UML_FRAGMENT_BORDER_WIDTH, UML_FRAGMENT_MARGIN, UML_FRAME_BAND_HEIGHT, UML_FRAME_BORDER_WIDTH, UML_FRAME_INK, UML_FRAME_TAG_CUT, UML_FRAME_TAG_FOOT, } from './consts.js';
+import { withUmlFrameTag } from './frame-tag.js';
+/**
+ * Canvas renderers for the four UML frames.
+ *
+ * There is almost no UML drawing code here: both are INSTANTIATIONS of the
+ * framework-background primitive, configured by the declarations in
+ * `background.ts`. The diagram frame adds exactly one thing the primitive has no
+ * vocabulary for — the cut-corner heading tag of Annex A — through the decorator
+ * in `frame-tag.ts`.
+ *
+ * Exported as functions as well as extensions because the fidelity suite drives
+ * them directly with a canvas stub.
+ */
+export const umlDiagram = withUmlFrameTag(UML_DIAGRAM_FRAME, {
+    // The DERIVED `<kind> <name>` the declaration's band label paints.
+    prop: 'heading',
+    bandHeight: UML_FRAME_BAND_HEIGHT,
+    foot: UML_FRAME_TAG_FOOT,
+    // The plot's left inset: the heading starts there, so a tag padded by the
+    // same number has its words centred in it, with one number and no drift.
+    padding: UML_DIAGRAM_MARGIN,
+    cut: UML_FRAME_TAG_CUT,
+    stroke: UML_FRAME_INK,
+    lineWidth: UML_FRAME_BORDER_WIDTH,
+});
+export const UmlDiagramRendererExtension = ElementRendererExtension(UML_DIAGRAM_FRAME.type, umlDiagram);
+export const umlSubject = createFrameworkBackgroundRenderer(UML_SUBJECT_FRAME);
+export const UmlSubjectRendererExtension = ElementRendererExtension(UML_SUBJECT_FRAME.type, umlSubject);
+/**
+ * The activity partition (§15.6.4), in whichever orientation the element
+ * declares.
+ *
+ * The one renderer in the pack that CHOOSES a declaration rather than being
+ * built from one, and the choice is two lines because the alternative is a
+ * change to the declaration language: a side band's edge and the geometry's deep
+ * margin are not things `variantProp` can vary (`background.ts` states the
+ * argument in full). So two renderers are built at module load — no work per
+ * frame — and the element's own prop picks between them.
+ *
+ * An orientation this build has never heard of paints the VERTICAL lane rather
+ * than nothing, the same promise the diagram frame's heading makes about an
+ * unknown kind.
+ */
+const umlPartitionV = createFrameworkBackgroundRenderer(UML_PARTITION_FRAME_V);
+const umlPartitionH = createFrameworkBackgroundRenderer(UML_PARTITION_FRAME_H);
+export const umlPartition = (model, ...rest) => (model.orientation === 'horizontal' ? umlPartitionH : umlPartitionV)(model, ...rest);
+export const UmlPartitionRendererExtension = ElementRendererExtension(UML_PARTITION_FRAME_V.type, umlPartition);
+/** The composite state (§14.2.4) — one declaration, no orientation to turn. */
+export const umlRegion = createFrameworkBackgroundRenderer(UML_REGION_FRAME);
+export const UmlRegionRendererExtension = ElementRendererExtension(UML_REGION_FRAME.type, umlRegion);
+/**
+ * The combined fragment (§17.6.4) — the second frame in the pack to wear Annex
+ * A's cut-corner pentagon, and the reason `frame-tag.ts` was written as a
+ * parameterised decorator rather than as the diagram frame's own private code.
+ *
+ * The word in the tag is the OPERATOR and not a derived heading: a fragment
+ * says one word about itself, and the guard is written down in the operand
+ * rather than beside the operator (`background.ts`).
+ */
+const paintUmlFragment = withUmlFrameTag(UML_FRAGMENT_FRAME, {
+    prop: 'operator',
+    bandHeight: UML_FRAGMENT_BAND,
+    foot: UML_FRAME_TAG_FOOT,
+    // The plot's left inset, as the diagram frame's padding is its own: the
+    // operator is written at the plot's left edge, so a tag padded by the same
+    // number has its word centred in it, with one number and no drift.
+    padding: UML_FRAGMENT_MARGIN,
+    cut: UML_FRAME_TAG_CUT,
+    stroke: UML_FRAME_INK,
+    lineWidth: UML_FRAGMENT_BORDER_WIDTH,
+});
+/**
+ * A SPLIT fragment as it is painted: its declared `name` hidden behind operand
+ * zero's own guard.
+ *
+ * The contract is `background.ts`'s — an unsplit fragment's guard is the
+ * background's `name`, a split one's guards are its `operands[].name` and
+ * nothing else — and the writers keep it (`toolbar/config.ts` clears `name` as
+ * it splits, `import.ts` never writes both). This is the DEFENSIVE half: the
+ * declared guard label and operand zero's are anchored in the very same corner,
+ * so a document that still carries both — one written by an older build, or by
+ * hand — would paint two strings one over the other, which reads as a smudge
+ * rather than as a mistake. A shadowing own prop rather than a second
+ * declaration, because the suppression is conditional on another prop and the
+ * declaration language has no vocabulary for that (`visibleProp` gates on
+ * presence, never on absence).
+ *
+ * ## Exported, because the HIT TEST has to read the same declaration
+ *
+ * A suppression the renderer keeps to itself is a label drawn nowhere and
+ * clickable anyway: `UmlFragmentView` derives its rename boxes from
+ * `backgroundLabelHits`, and given the raw model that call still returns
+ * `name`'s box — so a double-click in the corner of such a document would open
+ * an editor on a string the canvas does not paint. The view therefore hit-tests
+ * against THIS declaration rather than the stored one
+ * (`element-view.ts`, `UmlFragmentView._painted`), which is the invariant the
+ * class comment there already claims: "a label can never be drawn in one place
+ * and clicked in another".
+ */
+export function umlFragmentAsPainted(model) {
+    const operands = model.operands;
+    if (!Array.isArray(operands) || operands.length === 0)
+        return model;
+    if (!model.name)
+        return model;
+    return Object.create(model, {
+        name: { value: '', enumerable: true },
+    });
+}
+export const umlFragment = (model, ...rest) => paintUmlFragment(umlFragmentAsPainted(model), ...rest);
+export const UmlFragmentRendererExtension = ElementRendererExtension(UML_FRAGMENT_FRAME.type, umlFragment);

package/dist/element-view.d.ts

@@ -0,0 +1,234 @@
+import type { BackgroundLabelHit, EditableBackgroundLabel, FrameworkBackgroundDef } from '@formicoidea/labre-core/blocks/surface';
+import { DeclaredBackgroundView } from '@formicoidea/labre-core/blocks/surface';
+import type { UmlDiagramElementModel, UmlFragmentElementModel, UmlPartitionElementModel, UmlRegionElementModel, UmlSubjectElementModel } from '@formicoidea/labre-core/model';
+import type { EditorHost } from '@formicoidea/labre-core/std';
+import type { PointTestOptions } from '@formicoidea/labre-core/std/gfx';
+/**
+ * The one gesture every UML frame carries: a double-click on the name edits it
+ * in place.
+ *
+ * The gesture itself — the rotation arithmetic, the widened `includesPoint`,
+ * the double-click handler and the `<input>` — is the library's shared one,
+ * `DeclaredBackgroundView` (issue #355, R14: extend, never copy). What this
+ * class adds is only what UML answers differently: WHICH words a double-click
+ * aims at, and the model those words are read from.
+ *
+ * Which labels exist, where they sit and what they SAY all come from the
+ * declaration the renderer paints (`backgroundLabelHits`), so a label can never
+ * be drawn in one place and clicked in another — which is why this class has no
+ * coordinates of its own.
+ *
+ * ponytail: like every other framework view in the library, only `name` may be
+ * written — see {@link UmlDiagramView} for what that costs the diagram frame,
+ * whose drawn label is not `name`.
+ */
+declare abstract class UmlFrameView<T extends UmlDiagramElementModel | UmlSubjectElementModel | UmlPartitionElementModel | UmlRegionElementModel | UmlFragmentElementModel> extends DeclaredBackgroundView<T> {
+    /**
+     * The model this view hit-tests against — the one the RENDERER was handed.
+     *
+     * The stored model for every frame but one, and the hook exists for that one:
+     * a combined fragment paints through `umlFragmentAsPainted`, which hides a
+     * declared `name` that operand zero's guard already covers. The boxes
+     * `backgroundLabelHits` derives are only the drawn words if they are derived
+     * from the same declaration — otherwise the suppressed corner stays clickable
+     * and opens an editor on a string nothing paints.
+     *
+     * A getter and not a cached value: the props it reads are the document's, and
+     * a view outlives every edit to them.
+     */
+    protected get _painted(): T;
+    /**
+     * The declaration's editable labels, element-local, derived from the PAINTED
+     * model — see {@link _painted}. This is `DeclaredBackgroundView.labelAt`'s
+     * own walk with that one substitution, which is why the frames below do not
+     * call `super.labelAt`.
+     */
+    protected _hits(w: number, h: number): BackgroundLabelHit[];
+    /**
+     * Which region of the frame aims at the name, given an ELEMENT-LOCAL point.
+     *
+     * The DRAWN WORDS by default — the box `backgroundLabelHits` derives from the
+     * very anchor the renderer paints at. That is the right answer for a name
+     * written INSIDE the plot, over the drawing, where anything wider would
+     * swallow clicks meant for the elements around it: the subject's name sits in
+     * its top-left corner, and this is its whole story.
+     *
+     * A frame whose name has a band of its own overrides this — see
+     * {@link UmlDiagramView}.
+     */
+    protected labelAt(lx: number, ly: number, w: number, h: number): EditableBackgroundLabel | null;
+    /**
+     * The name label, answered over a whole BAND rather than over its words —
+     * for the frames whose name has a strip of its own.
+     *
+     * @param inBand whether the point is in the frame's band, as the frame's own
+     * band helper (`board-hit.ts`) decides.
+     */
+    protected _nameInBand(inBand: boolean, w: number, h: number): EditableBackgroundLabel | null;
+}
+/**
+ * The sheet a UML diagram is drawn on. Double-click ANYWHERE in its heading band
+ * to rename it.
+ *
+ * The band and not the words, which is the first thing this subclass changes —
+ * the same call the C4 board and the BPMN pool's participant band both make: a
+ * strip you may only double-click the eleven characters of is a target that lies
+ * about where it is. Here it also buys something they do not need: the tag is
+ * drawn round the words with padding on either side, so a user aiming at the
+ * pentagon they can see is inside the zone whether or not they hit a glyph.
+ *
+ * The second is what the editor opens on, and that is the one place UML parts
+ * company with the C4 board it is modelled on. Annex A's heading is
+ * `<kind> <name>` — a derived string, joined from a closed discriminant the
+ * picker owns and a name the author owns — so opening on the drawn words would
+ * hand the user `class Orders` to edit, and committing it would write the kind
+ * INTO the name, to be prefixed again on the next paint. The editor therefore
+ * opens on `name` — the author's half — and writes `name` back, never the drawn
+ * label's own prop: `heading` is a getter, and a getter is not somewhere a
+ * rename can land.
+ */
+export declare class UmlDiagramView extends UmlFrameView<UmlDiagramElementModel> {
+    static type: string;
+    protected get def(): FrameworkBackgroundDef;
+    protected labelAt(lx: number, ly: number, w: number, h: number): EditableBackgroundLabel | null;
+}
+/** The rectangle drawn round a system's use cases. Double-click its name. */
+export declare class UmlSubjectView extends UmlFrameView<UmlSubjectElementModel> {
+    static type: string;
+    protected get def(): FrameworkBackgroundDef;
+}
+/**
+ * An activity swimlane (§15.6.4). Double-click ANYWHERE in its name band to
+ * rename it — across the top of a vertical lane, down the left edge of a
+ * horizontal one.
+ *
+ * The band and not the words, the same call the diagram frame makes: a strip you
+ * may only double-click the eight characters of is a target that lies about
+ * where it is. It matters more here than on the sheet, because a partition is
+ * TRANSPARENT: every point that is not its own furniture falls through to the
+ * actions drawn inside it, so the header is the only place a user can take hold
+ * of the lane at all.
+ *
+ * The declaration this hit-tests against is chosen by the element's own
+ * `orientation`, through the one function that makes that choice — so the view,
+ * the renderer and the band helper cannot disagree about which edge the band is
+ * on.
+ */
+export declare class UmlPartitionView extends UmlFrameView<UmlPartitionElementModel> {
+    static type: string;
+    protected get def(): FrameworkBackgroundDef;
+    protected labelAt(lx: number, ly: number, w: number, h: number): EditableBackgroundLabel | null;
+}
+/**
+ * A composite state (§14.2.4). Double-click anywhere in its name band to rename
+ * it.
+ *
+ * The partition's story with no orientation to turn: the band is across the top,
+ * always, because that is where §14.2.4 writes a state's name.
+ */
+export declare class UmlRegionView extends UmlFrameView<UmlRegionElementModel> {
+    static type: string;
+    protected get def(): FrameworkBackgroundDef;
+    protected labelAt(lx: number, ly: number, w: number, h: number): EditableBackgroundLabel | null;
+}
+/**
+ * A COMBINED FRAGMENT (§17.6.4). Two gestures of its own, on top of the rename
+ * every UML frame carries:
+ *
+ * - **dblclick on a GUARD** — the `[condition]` written in an operand's
+ *   top-left corner — edits that guard in place. On an unsplit fragment there
+ *   is one, and it is the element's own `name`; once the box has been cut into
+ *   operands each of them carries its own, in `operands[i].name`;
+ * - **drag on an internal operand SEPARATOR** moves the dashed line, taking
+ *   from one operand and giving to the other.
+ *
+ * ## The operator is NOT renamed here
+ *
+ * Double-clicking the pentagon does nothing, deliberately. `operator` is a
+ * closed discriminant of thirteen values (§17.6.4 plus §17.7.4's `ref`) and it
+ * is picked from the toolbar; a free-text editor over it would let an author
+ * type `altt` and lose every rule, every reading and every export that keys on
+ * the word. The same call the diagram frame's `kind` already makes.
+ *
+ * ## How the separator drag takes the gesture
+ *
+ * Armed, exactly as `BpmnPoolView`'s is and for the reason stated there:
+ * `GfxElementModelView.dispatch` reports a drag as handled whenever a handler
+ * is REGISTERED, so a permanent `dragstart` would make the fragment
+ * undraggable. The handlers are attached while the pointer is over a separator
+ * of a SELECTED fragment and detached the moment it is not.
+ *
+ * ponytail: a ROTATED fragment is not accounted for by the separator drag —
+ * its pointer is converted to element-local coordinates by subtraction, so the
+ * separator boxes assume an upright frame (the guards do not: the shared base
+ * de-rotates before {@link labelAt}). The same reserve `board-hit.ts`
+ * documents; nothing rotates a framework background today.
+ */
+export declare class UmlFragmentView extends UmlFrameView<UmlFragmentElementModel> {
+    static type: string;
+    /** The separator the pointer is over, and the handlers armed for it. */
+    private _armed;
+    /** Everything a separator drag needs, frozen at `dragstart`. */
+    private _drag;
+    protected get def(): FrameworkBackgroundDef;
+    /**
+     * The suppression the renderer applies, read back here so the rename boxes
+     * are the drawn words and nothing else.
+     *
+     * On a SPLIT fragment written by an older build the stored model carries both
+     * `name` and `operands`, and the canvas paints operand zero's guard over the
+     * declared one's corner — i.e. paints `name` nowhere. `umlFragmentAsPainted`
+     * is the single statement of which of the two wins; calling it here is what
+     * keeps {@link labelAt}'s fallback from opening an editor on the invisible
+     * corner. The operand branch of that method is unaffected: it reads
+     * `operands`, which the suppression never touches.
+     */
+    protected get _painted(): UmlFragmentElementModel;
+    onCreated(): void;
+    onDestroyed(): void;
+    /**
+     * The operand guards first, the declaration's own label second.
+     *
+     * The order is the order the gestures win in, and it only matters on a SPLIT
+     * fragment: the first operand's corner is the very corner the declared
+     * `guard` label is anchored in. The operand takes it, because on a split
+     * fragment the guards live in `operands` and `name` has been moved into the
+     * first of them (`background.ts` states the contract) — handing the
+     * double-click to `name` would open an editor on a string nothing paints.
+     */
+    protected labelAt(lx: number, ly: number, w: number, h: number): EditableBackgroundLabel | null;
+    private _operands;
+    /**
+     * Write one operand's guard, dropping the key entirely when it is cleared.
+     *
+     * The same shape `renameBpmnLane` writes: an absent `name` is an unguarded
+     * operand — which is what an `else` branch with no condition is — and an
+     * empty string left in the array would be a key that means nothing and
+     * paints nothing.
+     *
+     * No undo boundary here: the shared editor captures one before it calls a
+     * label's `commit`.
+     */
+    private _writeGuard;
+    /**
+     * A fragment is SELECTED by its border and its operator band — but the
+     * internal operand separators are twelve-unit strips in the middle of the
+     * plot, and they must still receive their pointer events.
+     *
+     * Not a selection zone: a click between two messages still goes to whatever
+     * is under it, because picking asks the MODEL. This only decides where the
+     * fragment's own gestures are heard.
+     */
+    includesPoint(x: number, y: number, options: PointTestOptions, host: EditorHost): boolean;
+    /** Whether this fragment may be written to at all. */
+    private get _writable();
+    private _leave;
+    private _localPoint;
+    /** One pass over the pointer: the cursor, and whether a drag is armed. */
+    private _updateHover;
+    private _disarm;
+    private _onDragStart;
+    private _onDragMove;
+    private _onDragEnd;
+}
+export {};