@formicoidea/labre-core 0.31.0 → 0.33.0

package/dist/_pkgs/affine-block-surface/extensions/violation-detail-widget.d.ts

@@ -0,0 +1,330 @@
+import type { RootBlockModel } from '../../affine-model/index.js';
+import { WidgetComponent } from '../../std/index.js';
+import { nothing } from 'lit';
+import { type ExemptionScope, type ProvenanceSource, type ViolationSeverity } from './validation.js';
+export declare const VIOLATION_DETAIL_WIDGET = "affine-violation-detail-widget";
+/**
+ * Chrome wording, and only chrome: an English default so a catalogue-less
+ * playground reads correctly. A RULE's wording never gets a default — see
+ * {@link translateKey}.
+ *
+ * Exported because it is DATA, and the translation-key manifest walks it under
+ * the `com.labre.validation.severity.` prefix rather than restating the three
+ * wordings a second time. The keys behind a template literal are the ones a
+ * source scan cannot check; making the table the single declaration is what
+ * removes the question. Same for {@link EXEMPTION_FALLBACK}.
+ */
+export declare const SEVERITY_FALLBACK: Record<ViolationSeverity, string>;
+/** What the badge says of an excused violation, per scope of the exception. */
+export declare const EXEMPTION_FALLBACK: Record<ExemptionScope, string>;
+/**
+ * What the bubble calls each kind of authority a rule can claim
+ * ({@link RuleProvenance}).
+ *
+ * The one wording in this file that changes what a finding MEANS rather than
+ * how it looks: "Standard" tells an architect the diagram breaks a published
+ * specification, "Labre convention" tells them it does not. An external review
+ * of the BPMN pack asked for exactly this line, because a house style shown
+ * without it reads as a norm violation — and a tool that cannot be trusted on
+ * that distinction is a tool an architect stops believing.
+ *
+ * The word only; the CITATION beside it is the rule's own `reference`, rendered
+ * verbatim and never translated (a page number is the same in every language).
+ *
+ * Exported for the same reason {@link SEVERITY_FALLBACK} is: the manifest walks
+ * this table under `com.labre.validation.provenance.` instead of restating four
+ * wordings a source scan could not check behind a template key.
+ */
+export declare const PROVENANCE_FALLBACK: Record<ProvenanceSource, string>;
+/**
+ * The PERSISTENT half of the PF7 affordance, and the restitution behind it.
+ *
+ * `ValidationOverlay` flashes a bracket when a violation appears and fades it
+ * out a few seconds later. What survives that fade is this: a small amber
+ * badge pinned to the anchor for as long as the violation holds, and — on
+ * click — a bubble naming what is wrong.
+ *
+ * WHERE on the anchor follows what the anchor IS: the top-right corner of a
+ * box, the MIDDLE of a link. A diagonal connector's bounding box is a rectangle
+ * whose corners are on empty paper, and a badge there accuses the white space
+ * next to the trait rather than the trait (PO, 02/08). The choice is made once,
+ * in `validation.ts`, by the anchor's `kind`.
+ *
+ * ## Why DOM and not the canvas overlay
+ *
+ * Because it is clickable. Widgets render into the root block's
+ * `.widgets-container`, which covers the canvas; the container itself is
+ * `pointer-events: none` but explicitly re-enables them on each widget host
+ * (`.widgets-container > * { pointer-events: auto }`). What keeps the canvas
+ * usable is therefore not that rule but the host's geometry: it is an
+ * absolutely positioned, zero-sized box at the viewport origin, so it has no
+ * area to intercept anything and only its positioned children are hit. That is
+ * the house pattern for an affordance that takes clicks over the canvas
+ * (`edgeless-element-link`, whose hover bubble this one is modelled on,
+ * `edgeless-auto-connect`, `note-slicer`).
+ * Stopping the pointer pair there (see {@link ViolationDetailWidget._swallow})
+ * keeps the click off the element underneath, with no special case in
+ * `DefaultTool` and no change to the edgeless event dispatcher.
+ *
+ * ## Sizing
+ *
+ * Both markers are sized in MODEL units and multiplied by the board's own
+ * scale on the way to the screen, so they shrink with it instead of swelling —
+ * see the note on the mark constants in `validation.ts`. The exception is the
+ * hit area: a transparent box with a screen-pixel floor around the model-sized
+ * visual, so a badge three pixels wide stays reachable. That split is the
+ * `edgeless-auto-complete` pattern (a 24 px arrow inside a 44 px target).
+ *
+ * ## Sequencing
+ *
+ * The badge is shown only for anchors whose {@link anchorEmphasis} has reached
+ * zero — i.e. whose bracket has finished fading. While the bracket is up the
+ * widget renders an invisible band over it instead, so the mark on the canvas
+ * is clickable and opens the same bubble. The two markers are never on screen
+ * together.
+ *
+ * ## Exceptions (PF8)
+ *
+ * Every line of the bubble carries the way out of the rule it names — one
+ * click, never a detour through a settings panel. Taking it writes an exception
+ * on the elements the rule indicts, and the finding switches to "exception":
+ * it drops out of the flash and out of the bracket, keeps a muted badge, and
+ * keeps its line in the bubble with a **Revoke** that puts it back. Nothing is
+ * ever hidden — the board stays honest about the gaps it was told to live with.
+ *
+ * The second, wider way out — "ignore this rule on the whole map" — appears
+ * only once the same call has been made elsewhere on the board (PF8.4), and
+ * writes the exception on the framework's own background element.
+ *
+ * ## What it knows
+ *
+ * No rule LOGIC, and no hard-coded rule wording — the library must not put
+ * words in a framework's mouth. It consumes normalised {@link Violation}
+ * objects off `ValidationManager.violations$` and resolves their `messageKey`
+ * through the host's catalogue ({@link translateKey}), falling back to the raw
+ * key.
+ *
+ * The one thing it reads off the RULE rather than off the finding is
+ * {@link ValidationRule.provenance} — whether the sentence above it restates a
+ * published standard, a linter's recommendation, or a Labre house style. It is
+ * looked up by `ruleId` through {@link ValidationManager.ruleOf}, the same path
+ * this widget already walks to name a finding's framework when it reports an
+ * exception, and it is still declared data rather than logic: the widget
+ * chooses the LABEL for a source it is handed, and prints the citation
+ * verbatim.
+ */
+export declare class ViolationDetailWidget extends WidgetComponent<RootBlockModel> {
+    static styles: import("lit").CSSResult;
+    /**
+     * The anchor whose bubble is open, or `null`. Purely local UI state: which
+     * findings a user has looked at is nobody's business but this session's.
+     */
+    private accessor _openAnchorId;
+    private accessor _violations;
+    private _elementSubscription;
+    /** The surface {@link _elementSubscription} is attached to, if any. */
+    private _watchedSurface;
+    /** Fires once, when the oldest bracket finishes fading and a badge is due. */
+    private _handoverTimer;
+    get gfx(): import("../../std/gfx/controller.js").GfxController;
+    /**
+     * Every role vocabulary registered in this assembly, for the semantic half of
+     * "is this anchor an edge" — a link is marked in its MIDDLE, a box on its
+     * corner. Read on demand rather than cached: a framework's vocabulary arrives
+     * with its always-on render extension, and the registry is a map lookup.
+     */
+    private get _vocabularies();
+    private get _timeline();
+    /**
+     * Wake up at the exact instant the bracket hands over.
+     *
+     * The canvas half repaints itself on animation frames while it fades; the DOM
+     * half has nothing to react to, because no violation changed — only time
+     * passed. One timer, set to the earliest expiry and re-armed after each
+     * render, is all it takes; there is nothing to arm once every mark has
+     * settled, so a quiet board runs no clock.
+     */
+    private _scheduleHandover;
+    /**
+     * Follow a moving anchor, but only while something is flagged. On a clean
+     * board — the overwhelming majority of boards, and every board with no
+     * framework enabled — this subscription does not exist, so the busiest
+     * signal on the surface costs the widget nothing.
+     *
+     * Idempotent on purpose: `violations$` is handed a freshly built array on
+     * every 120 ms re-evaluation, so this runs constantly while a violation
+     * holds and must not tear the subscription down and rebuild it each time.
+     */
+    private _watchElements;
+    /**
+     * Forget the open bubble once its anchor stops being flagged.
+     *
+     * Not cosmetic: `render` would already skip a bubble whose anchor is gone,
+     * but a STALE `_openAnchorId` would silently match again if the same group
+     * were broken a second time, and the bubble would reappear on its own,
+     * unasked. A correction closes the bubble for good.
+     */
+    private _closeIfAnchorGone;
+    private readonly _onDocumentPointerDown;
+    /**
+     * Escape is listened for on the EDITOR HOST, not on `document`.
+     *
+     * The handler swallows the key so that, with a bubble open, Escape dismisses
+     * the bubble rather than clearing the canvas selection behind it — and a
+     * library has no business making that call for the whole page. Scoped to the
+     * host, the host application keeps its own global Escape (close the modal,
+     * leave full screen) whatever this widget is doing.
+     */
+    private readonly _onHostKeydown;
+    /**
+     * While a bubble is open, the CANVAS does not take the wheel (PO, 02/08).
+     *
+     * The bug it fixes has two halves and one cause. `EdgelessRootBlock` handles
+     * `wheel` off the event dispatcher, which listens on the editor host, and its
+     * handler `preventDefault()`s unconditionally before panning. So a wheel over
+     * an overflowing bubble (a) never scrolled the bubble, because the default
+     * action was cancelled on its way past, and (b) panned the board, which closed
+     * the bubble on `viewportUpdated` — the finding became unreadable at exactly
+     * the length it most needed reading.
+     *
+     * The fix is one CAPTURE-phase listener on the editor host that stops the
+     * event before it can reach any bubble-phase handler on that host — the
+     * dispatcher's included. What it deliberately does NOT do:
+     *
+     * - no `preventDefault()`. The default action is precisely what has to
+     *   survive: it is what scrolls the bubble. Cancelling it globally is the bug,
+     *   not the fix.
+     * - nothing on `document`. Outside the editor host the page keeps its wheel,
+     *   like it keeps its Escape ({@link _onHostKeydown}) — a library does not
+     *   freeze somebody else's page because one of its bubbles is open.
+     * - nothing while the bubble is closed. The listener is registered for the
+     *   widget's lifetime and returns on the first line, so a board with no
+     *   finding open behaves exactly as it did.
+     *
+     * The board is frozen wherever the pointer is, not only over the bubble, and
+     * that is the PO's call: the gesture belongs to the thing being read until it
+     * is dismissed, and dismissing it is one click anywhere.
+     */
+    private readonly _onHostWheel;
+    /**
+     * The edgeless `click` is SYNTHESISED by the event dispatcher from a
+     * `pointerdown`/`pointerup` pair observed on the editor host, and the tool
+     * then picks its target by coordinate — not by DOM target. Swallowing the
+     * native `click` would therefore not be enough: the pointer pair alone is
+     * what selects the element sitting under the badge (and starts dragging it).
+     *
+     * Stopping the pair on the affordance is what makes it click-through safe,
+     * and it costs nothing else: the dispatcher listens on an ancestor, so
+     * everything that is not aimed at the mark is untouched.
+     */
+    private readonly _swallow;
+    private readonly _toggle;
+    /** Open on the bracket, never toggle: a second click on a fading mark that
+     * has just been replaced by a badge would read as the bubble refusing to
+     * open. */
+    private readonly _open;
+    /**
+     * `WithDisposable` throws the disposable group away on disconnect and starts
+     * a fresh one on reconnect, while lit runs `firstUpdated` exactly once — so
+     * wiring set up there and nowhere else never comes back if the widget is
+     * detached and re-attached, and a persistent finding indicator would go
+     * silently dead. Wiring lives in one idempotent method, called from both.
+     */
+    private _wire;
+    connectedCallback(): void;
+    firstUpdated(): void;
+    /**
+     * Mirror "a bubble is open" onto the host as an attribute, so the stylesheet
+     * can raise the whole host over the toolbars for the duration (see the
+     * `:host([data-bubble-open])` rule). An attribute rather than an inline
+     * `z-index` because the value belongs with the other stacking decisions, in
+     * one place, next to the reason it exists.
+     */
+    updated(): void;
+    /**
+     * Roughly how tall the bubble will be, to decide WHETHER to flip. It only
+     * has to be good enough to pick a side; once flipped, the transform pins the
+     * bottom edge exactly, so an underestimate cannot push content off screen.
+     */
+    private _estimateBubbleHeight;
+    private _severityLabel;
+    /**
+     * The one line saying where the rule behind a finding gets its authority.
+     *
+     * Resolved through {@link ValidationManager.ruleOf}, which is the path this
+     * widget already uses to name a finding's framework when it reports an
+     * exception — the bubble consumes normalised {@link Violation}s and knows
+     * nothing about rules, so the manager is the only place a rule can come from.
+     *
+     * Rendered ONLY when the rule declares one. A rule that says nothing about
+     * its provenance gets no line and no invented one: the library must not put
+     * an authority in a framework's mouth any more than it puts words there
+     * (see {@link translateKey}). That is also why the fallback is chrome-only —
+     * the LABEL is ours, the citation is the framework's, and the citation is
+     * printed exactly as declared rather than translated.
+     */
+    private _renderProvenance;
+    /**
+     * Grant or revoke, then report it.
+     *
+     * The AUTHOR is deliberately not filled in here: the library has no seam for
+     * "who am I" (`UserProvider` resolves an id, it does not hand one out), and
+     * inventing one for this would be a bigger change than the feature. The field
+     * and `ValidationManager.setException` both carry the parameter, so a host
+     * that knows its user can populate it without a schema change.
+     */
+    private _setException;
+    private readonly _exception;
+    /**
+     * Whether the user has already made this same call elsewhere on the board.
+     *
+     * PF8.4 offers "ignore this rule on the whole map" only once the choice has
+     * been REPEATED — the first exception is a local judgement about one element,
+     * and pre-emptively offering to disarm a rule everywhere would turn a
+     * one-element decision into a map-wide one nobody asked for.
+     *
+     * Read off the ENGINE's own output — another finding of the same rule, on
+     * another element, that an exception already covers. Scanning the surface for
+     * elements merely carrying the key would count things that are not decisions:
+     * a neutral rectangle pasted from another board with a residual
+     * `validationExceptions` entry is never evaluated by this rule, so it must
+     * never be read as the user having arbitrated on it.
+     */
+    private _isRepeated;
+    /**
+     * The one line the bubble shows for a rule, and the ways out of it.
+     *
+     * `violations` are every finding of that rule on this anchor — one bubble line
+     * can stand for several indicted members of a group, and one click settles all
+     * of them.
+     */
+    private _renderEntry;
+    private _renderBubble;
+    /**
+     * Badge centre, in the CSS pixels of the widgets container.
+     *
+     * WHERE that is, per anchor kind, is `resolveViolationAnchors`' answer
+     * ({@link ViolationAnchor.markAt}) — a corner for a box, the middle of the
+     * trait for a link. Here it is one conversion of one model point, so the
+     * offsets scale with the mark instead of drifting away from it as the board
+     * is zoomed, and there is no second copy of the geometry to keep in step.
+     *
+     * Not `toViewCoord`: that answers in screen pixels, and the badge is drawn
+     * inside the container an embedding host may have scaled, so it states its
+     * placement the way the element it accuses does.
+     */
+    private _badgeAt;
+    private _renderBadge;
+    /**
+     * Four invisible strips hugging the outside of the bracket, so the mark the
+     * user is looking at is the thing they can click.
+     *
+     * Strips rather than one box over the anchor: the interior belongs to the
+     * element, which stays selectable and draggable throughout — the three
+     * seconds the bracket lasts are exactly when someone is most likely to grab
+     * the node and put it back on the map.
+     */
+    private _renderBracketHit;
+    render(): import("lit-html").TemplateResult<1> | typeof nothing;
+}
+export declare const violationDetailWidget: import("../../store/index.js").ExtensionType;