@oh-just-another/state 0.57.0

package/dist/overlay.d.ts

@@ -0,0 +1,262 @@
+import type { AnnotationId, Bounds, Transform, Vec2 } from "@oh-just-another/types";
+import { type Annotation, type Element, type Scene } from "@oh-just-another/scene";
+import { type RenderTarget } from "@oh-just-another/renderer-core";
+import { type HitZoneAttach, type HitZoneContainers, type HitZoneVisibility } from "./editor/hit-test.js";
+import type { Selection } from "./selection.js";
+export interface OverlayStyle {
+    readonly selectionStroke: string;
+    readonly selectionStrokeWidth: number;
+    readonly handleFill: string;
+    readonly handleStroke: string;
+    readonly drawingStroke: string;
+    readonly drawingDash: readonly number[];
+}
+export declare const DEFAULT_OVERLAY_STYLE: OverlayStyle;
+/**
+ * One selected element's contour halo: its outline loop(s) plus `outsetWorld`
+ * — how far the element's own border extends OUTSIDE the contour (world
+ * units; see `strokeOutsideExtent`). The halo is sized so it peeks exactly
+ * `SELECTION_HALO_PEEK_PX` screen px beyond contour + outset.
+ */
+export interface ElementHalo {
+    readonly loops: readonly (readonly Vec2[])[];
+    readonly outsetWorld: number;
+}
+/**
+ * Paint the contour selection halo for elements — a translucent stroke
+ * hugging each world-space outline loop. Drawn on the dedicated background
+ * layer (under the shapes) so it peeks out from behind them. The stroke is
+ * centred on the contour with width `2 × (outset + peek/zoom)`, so its outer
+ * edge lands exactly `peek` screen px beyond the element's VISIBLE edge
+ * (contour + border outset) at every zoom and border thickness. Sets the
+ * world transform itself; resets to identity at the end.
+ */
+export declare const paintElementSelectionHalo: (target: RenderTarget, w2s: Transform, halos: readonly ElementHalo[], zoom: number, style?: OverlayStyle) => void;
+/**
+ * Draws selection outlines, resize handles, and the rubber-band rectangle on
+ * the overlay layer. Pure draw — does not alter scene or state.
+ *
+ * Handles are sized in *screen* pixels regardless of zoom (4 × 4 CSS px) — the
+ * caller passes the viewport so this function can compensate.
+ */
+export interface LinkPreview {
+    /** World-space anchor on the source shape, or null for a free point. */
+    readonly from: Vec2;
+    readonly to: Vec2;
+    /**
+     * Optional full polyline (world) for an elbow preview — `[from, ...corners,
+     * to]`. When present it is drawn instead of the straight `from→to` line so
+     * the preview matches the orthogonal connector that will be committed.
+     */
+    readonly points?: readonly Vec2[];
+}
+/**
+ * Set of world-space points to render as port dots — used when the editor
+ * wants to show "you can attach here" affordances on a hovered shape in
+ * draw-edge mode.
+ */
+export interface PortOverlay {
+    readonly worldPoints: readonly Vec2[];
+    /** Highlight one of the points (the snap target). Optional. */
+    readonly activeIndex?: number;
+    /**
+     * Screen-px radius to draw the active dot at — lets the host scale it
+     * smoothly by cursor proximity (link-start grow). Falls back to
+     * `ANCHOR_DOT_ACTIVE_RADIUS` when unset.
+     */
+    readonly activeRadius?: number;
+    /**
+     * Visual role (standard model).
+     *   - link-start: shown on selection (where to drag from).
+     *   - link-attach: shown on hover / proximity (where to land).
+     */
+    readonly role?: "link-start" | "link-attach";
+}
+/**
+ * Selected edge with endpoint world positions. Renderer paints small
+ * handles on each end so the user can grab and re-bind them.
+ */
+export interface LinkSelection {
+    readonly from: Vec2;
+    readonly to: Vec2;
+    /** Existing bend points (world) — solid grab handles. */
+    readonly waypoints?: readonly Vec2[];
+    /** Segment midpoints (world) — smaller "add waypoint" handles. */
+    readonly midpoints?: readonly Vec2[];
+}
+/**
+ * Remote peer's cursor — world-space position plus identity. Rendered
+ * as a coloured arrow + name chip so the user can see who's pointing
+ * where. The local user's cursor is never in this list (the host
+ * filters by `clientId !== localId` before passing).
+ */
+export interface PeerCursor {
+    readonly position: Vec2;
+    readonly color: string;
+    readonly name: string;
+}
+/**
+ * Remote peer's selection — world-space bounding boxes that draw a
+ * dashed outline in the peer's colour. Computed by the host from the
+ * peer's `selection: ElementId[]` and the current scene shapes.
+ */
+export interface PeerSelection {
+    readonly color: string;
+    readonly bounds: readonly Bounds[];
+}
+export declare const renderOverlay: (scene: Scene, selection: Selection, target: RenderTarget, options?: {
+    drawingPreview?: Bounds;
+    /**
+     * WYSIWYG preview of the shape being drawn by drag (rect / ellipse):
+     * the would-be `Element` rendered through its real renderer so the
+     * user sees exactly the shape + default style they'll get on release
+     * (modern-style), instead of only a dashed rubber-band rect. Mutually
+     * exclusive with `drawingPreview` — the orchestrator sets one or the
+     * other (dashed only for the lasso / select rubber-band).
+     */
+    drawingPreviewElement?: Element;
+    edgePreview?: LinkPreview;
+    /**
+     * Port-dot affordances to paint. A single set (one shape's anchors)
+     * or several sets at once — e.g. the source's link-start dots AND the
+     * target's link-attach dots simultaneously while a link is dragged
+     * from a start anchor.
+     */
+    ports?: PortOverlay | readonly PortOverlay[];
+    edgeSelection?: LinkSelection;
+    /**
+     * World-space polylines (+ visual width) of every SELECTED link, painted
+     * as a persistent selection halo. Multi-select shows N halos; the sole-
+     * link endpoint/bend handles are still driven by `edgeSelection`.
+     */
+    selectedLinkPaths?: readonly {
+        readonly path: readonly Vec2[];
+        readonly width: number;
+    }[];
+    /**
+     * World-space bounds of the element a connector endpoint will FLOAT-attach
+     * to (drop on the body, not a dot). Painted as a brand outline so the user
+     * sees "this whole object" vs a specific point.
+     */
+    linkAttachHighlight?: Bounds;
+    /**
+     * Fallback bounds for the click-create ghost when no `ghostElementShape`
+     * is available — painted as a faded brand rect outline. Prefer
+     * `ghostElementShape` (the real shape). The connector is drawn separately
+     * by the orchestrator through the real link renderer.
+     */
+    ghostElement?: Bounds;
+    /**
+     * The would-be element itself (same-kind clone of the source) for the
+     * click-create ghost. When set it is rendered through its real renderer
+     * so the ghost looks like the actual shape (an ellipse ghosts as an
+     * ellipse), not a bounding rect. Falls back to a rect outline of
+     * `ghostElement` when absent.
+     */
+    ghostElementShape?: Element;
+    /**
+     * Combined world-space bounding box of a multi-selection (or a
+     * single group-typed shape's children union). When set the overlay
+     * paints a 1-px outline and resize handles on top of the per-shape
+     * selection outlines so the user can grab a group handle.
+     */
+    groupBounds?: Bounds;
+    /**
+     * Restrict the group-bounds handles to the four corners (aspect-
+     * locked resize) instead of the default 8 corner+midpoint set.
+     * Used by group-typed shapes which cannot be stretched
+     * independently along one axis.
+     */
+    groupAspectLocked?: boolean;
+    /**
+     * Drop-zone of the container currently under the dragged shape.
+     * Drawn as a dashed accent rect so the user sees where the element
+     * will be nested after release.
+     */
+    containerDropZone?: Bounds;
+    /**
+     * Live brush stroke preview during a `brush`-mode drag. Drawn as a
+     * variable-width fill so the user sees pressure modulation as they
+     * stroke. `origin` is in world coords; `points` are local-to-origin
+     * (matches the BrushElement memory layout).
+     */
+    brushPreview?: {
+        readonly origin: {
+            readonly x: number;
+            readonly y: number;
+        };
+        readonly points: readonly {
+            x: number;
+            y: number;
+            width: number;
+        }[];
+        readonly fill: string;
+    };
+    /**
+     * Remote peer cursors. Each one renders as a small coloured arrow
+     * with a name chip in the peer's colour, anchored at the world-
+     * space position. The local cursor never appears here.
+     */
+    peerCursors?: readonly PeerCursor[];
+    /**
+     * Remote peer selections. Each entry paints a dashed outline in
+     * the peer's colour around every world-space bbox in `bounds`.
+     */
+    peerSelections?: readonly PeerSelection[];
+    /**
+     * Annotation pins to render on the overlay. Each pin is a small
+     * circle anchored at the annotation's world position; resolved
+     * annotations get a muted colour. Highlighted pin (the one in
+     * `selectedAnnotation`) gets an accent ring.
+     */
+    annotations?: readonly Annotation[];
+    selectedAnnotation?: AnnotationId | null;
+    /**
+     * World bboxes of animated (GIF) shapes whose playback is paused
+     * (auto-stopped or held under prefers-reduced-motion). Each draws a
+     * small "play" chip so the user knows a click resumes it.
+     */
+    gifBadges?: readonly Bounds[];
+    /**
+     * In-canvas text editing chrome for the shape under edit. All rects
+     * are WORLD-space; the overlay projects them to screen. `caret` is
+     * `null` while blinked off. Selection rects render as a translucent
+     * highlight under the caret.
+     */
+    editingText?: {
+        readonly caret: {
+            readonly x: number;
+            readonly y: number;
+            readonly height: number;
+        } | null;
+        readonly caretColor: string;
+        readonly selectionRects: readonly Bounds[];
+    };
+    /**
+     * Debug: paint the mouse hit-zones (resize-handle slop, edge-
+     * endpoint radius, edge-body threshold) for **every** element, so
+     * the tuned values can be eyeballed. Off by default; toggled via
+     * the debug panel. Drawn first, under the real selection chrome.
+     */
+    debugHitZones?: boolean;
+    /**
+     * Debug: link-attach drop-zones (anchor catchment circles + edge bands)
+     * to paint while a link endpoint is being placed. Only meaningful with
+     * `debugHitZones` on; supplied by the orchestrator during a link drag.
+     */
+    debugAttachZones?: HitZoneAttach;
+    /**
+     * Debug: element drop-zones (frames + containers) to paint while an
+     * element is being dragged. Only meaningful with `debugHitZones` on;
+     * supplied by the orchestrator during an element drag.
+     */
+    debugContainerZones?: HitZoneContainers;
+    /**
+     * Which hit-zone categories are actionable right now (from
+     * `hitZoneVisibility`). Gates `drawHitZones` so it only paints the
+     * targets the user can act on. Defaults to the at-rest set when omitted.
+     */
+    debugHitZoneVisibility?: HitZoneVisibility;
+    style?: Partial<OverlayStyle>;
+}) => void;
+//# sourceMappingURL=overlay.d.ts.map

package/dist/overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../src/overlay.ts"],"names":[],"mappings":"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"}