@weasel-js/core 0.5.0

package/dist/types-BJ8_cyT7.d.ts

@@ -0,0 +1,130 @@
+/** One bit per debug feature; absent keys are off. */
+interface DebugConfig {
+    hitboxes?: boolean;
+    handles?: boolean;
+    bounds?: boolean;
+    origins?: boolean;
+    snap?: boolean;
+    layers?: boolean;
+    /** Render each tracked node's id as a label at the top-left of its
+     *  bounds. Pulls from the same `recordBounds` stream `bounds` uses, so
+     *  no extra sink calls are required to enable. */
+    ids?: boolean;
+    /** Rolling FPS counter rendered in the top-left corner of the canvas.
+     *  Tracks the rate at which the debug overlay's draw callback runs;
+     *  this matches the canvas's effective repaint rate. */
+    fps?: boolean;
+    /** Optional per-feature color overrides; falls back to the default theme. */
+    theme?: Partial<DebugTheme>;
+}
+type DebugFeature = 'hitboxes' | 'handles' | 'bounds' | 'origins' | 'snap' | 'layers' | 'ids' | 'fps';
+interface DebugTheme {
+    hitboxFill: string;
+    hitboxStroke: string;
+    handle: string;
+    bounds: string;
+    origin: string;
+    snap: string;
+    layerText: string;
+    layerTextBg: string;
+    /** Color for the per-node id label rendered when `config.ids` is on. */
+    idText: string;
+    /** Foreground / background for the FPS panel. */
+    fpsText: string;
+    fpsTextBg: string;
+}
+type HandleKind = 'corner' | 'rotation' | 'anchor';
+type HitShape = {
+    kind: 'rect';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation?: number;
+} | {
+    kind: 'circle';
+    cx: number;
+    cy: number;
+    r: number;
+} | {
+    kind: 'path';
+    d: Path2D;
+};
+interface RecordedHitbox {
+    id: string;
+    kind: 'body' | 'handle' | 'rotation' | 'anchor';
+    shape: HitShape;
+}
+interface RecordedHandle {
+    id: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    kind: HandleKind;
+}
+interface RecordedBounds {
+    id: string;
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+interface RecordedOrigin {
+    id: string;
+    point: {
+        x: number;
+        y: number;
+    };
+}
+interface RecordedSnap {
+    point: {
+        x: number;
+        y: number;
+    };
+    accepted: boolean;
+}
+interface RecordedLayer {
+    id: string;
+    label: string;
+    space: 'world' | 'screen';
+    index: number;
+}
+interface DebugSnapshot {
+    hitboxes: RecordedHitbox[];
+    handles: RecordedHandle[];
+    bounds: RecordedBounds[];
+    origins: RecordedOrigin[];
+    snap: RecordedSnap[];
+    layers: RecordedLayer[];
+}
+interface DebugSink {
+    recordHitbox(id: string, kind: 'body' | 'handle' | 'rotation' | 'anchor', shape: HitShape): void;
+    recordHandle(id: string, position: {
+        x: number;
+        y: number;
+    }, kind: HandleKind): void;
+    recordBounds(id: string, bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): void;
+    recordOrigin(id: string, point: {
+        x: number;
+        y: number;
+    }): void;
+    recordSnapCandidate(point: {
+        x: number;
+        y: number;
+    }, accepted: boolean): void;
+    recordLayer(id: string, label: string, space: 'world' | 'screen', index: number): void;
+    /** Clears every non-snap array. Called at the start of each Canvas render. */
+    beginFrame(): void;
+    /** Clears the snap array. Called at gesture end. */
+    clearSnap(): void;
+}
+
+export type { DebugSink as D, HandleKind as H, RecordedBounds as R, DebugConfig as a, DebugSnapshot as b, DebugTheme as c, DebugFeature as d, HitShape as e, RecordedHandle as f, RecordedHitbox as g, RecordedLayer as h, RecordedOrigin as i, RecordedSnap as j };

package/dist/types-B_-khFM0.d.ts

@@ -0,0 +1,331 @@
+import { Op } from '@weasel-js/history';
+
+type ContainerBounds = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+interface LayoutChild<TPose> {
+    id: string;
+    pose: TPose;
+}
+interface DropTarget<TPose> {
+    /** Where the dragged child lands if this target is picked. */
+    pose: TPose;
+    /** Reference point for distance metrics (snap algorithms). */
+    origin: {
+        x: number;
+        y: number;
+    };
+    /** Optional axis-aligned region (world units) used by region-aware snaps
+     *  (e.g. `containedThenNearest`). When present, a pointer inside this rect
+     *  is treated as a containment hit on this target. Strategies that emit
+     *  region-shaped targets (gutters, drop-zones) should populate this.
+     *  Strategies whose targets are point-like (free-form, snap-point) can omit
+     *  it and rely on `origin`-distance snaps. */
+    hitBounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Strategy-private metadata (e.g. cell coords for tile-grid). */
+    meta?: unknown;
+}
+interface LayoutSnap<TPose> {
+    pickTarget(targets: DropTarget<TPose>[], pointer: {
+        x: number;
+        y: number;
+    }): DropTarget<TPose> | null;
+}
+interface LayoutContainer {
+    id: string;
+    bounds: ContainerBounds;
+}
+interface LayoutDragged<TPose> {
+    id: string;
+    /** The pose the dragged child currently has (pre-drop). */
+    originPose: TPose;
+    /** The pose the gesture proposes (pointer-driven, pre-snap). */
+    pose: TPose;
+    sourceContainerId: string | null;
+}
+interface LayoutStrategy<TPose> {
+    childPoses(container: LayoutContainer, children: ReadonlyArray<LayoutChild<TPose>>): Map<string, TPose>;
+    getDropTargets(container: LayoutContainer, children: ReadonlyArray<LayoutChild<TPose>>, dragged: LayoutDragged<TPose>): DropTarget<TPose>[];
+    reflowPoses(container: LayoutContainer, children: ReadonlyArray<LayoutChild<TPose>>, dragged: LayoutDragged<TPose>, target: DropTarget<TPose> | null): Map<string, TPose>;
+    commitDrop(container: LayoutContainer, children: ReadonlyArray<LayoutChild<TPose>>, dragged: LayoutDragged<TPose>, target: DropTarget<TPose> | null): Op[];
+    snap: LayoutSnap<TPose>;
+    /** Optional: predicate for whether a world-space point is inside this
+     *  container. When absent, callers fall back to an axis-aligned bounding-box
+     *  test on the container's pose. Strategies whose containers aren't
+     *  rectangular (circles, irregular zones) implement this to override the
+     *  AABB default. */
+    contains?(containerPose: TPose, point: {
+        x: number;
+        y: number;
+    }): boolean;
+}
+
+/**
+ * Opaque clipboard payload. `items` is `unknown[]` so each app's clipboard
+ * adapter stores whatever shape it wants; the kit never inspects entries.
+ *
+ * The adapter is responsible for both producing snapshots
+ * (`snapshotSelection`) and consuming them (`commitPaste`). Type safety lives
+ * at that boundary, not in the kit.
+ */
+interface ClipboardSnapshot {
+    items: unknown[];
+}
+/**
+ * SnapTarget — where a dragged node would re-parent to if released.
+ *
+ * `slotPose` is the pose (in world coordinates) the node should snap to
+ * within the target. `metadata` is an opaque pass-through for app-specific
+ * snap details (slot index, visual hint, etc.).
+ */
+interface SnapTarget<TPose = unknown> {
+    parentId: string;
+    slotPose: TPose;
+    metadata?: unknown;
+}
+/**
+ * Full scene adapter. Most consumers implement narrow per-hook subsets
+ * (MoveAdapter, ResizeAdapter, ClipboardAdapter, ...) — TypeScript's
+ * structural typing means a wider adapter satisfies any narrower interface.
+ *
+ * **Pose semantics:** `getPose` / `setPose` work in **local** coordinates —
+ * relative to the node's direct parent (or world, for root-parented nodes).
+ * The kit composes world poses via `composeWorldPose` when it needs to
+ * render, hit-test, or snap. For the common axis-aligned rect pose,
+ * `composeRectPose` / `decomposeRectPose` ship as the canonical compose pair.
+ */
+interface SceneAdapter<TNode extends {
+    id: string;
+}, TPose> {
+    getNodes(): TNode[];
+    getNode(id: string): TNode | undefined;
+    getSelection(): string[];
+    hitTest(worldX: number, worldY: number): string | null;
+    getPose(id: string): TPose;
+    getParent(id: string): string | null;
+    setPose(id: string, pose: TPose): void;
+    setParent(id: string, parentId: string | null): void;
+    insertNode(node: TNode): void;
+    removeNode(id: string): void;
+    setSelection(ids: string[]): void;
+    applyOps?(ops: Op[], label?: string): void;
+}
+/**
+ * Narrow adapter for `useMove`. Includes optional snap-target
+ * lookup; apps without container-snapping leave it out.
+ */
+interface MoveAdapter<TNode extends {
+    id: string;
+}, TPose> {
+    getNode(id: string): TNode | undefined;
+    /** Enumerate all nodes. `<Canvas>` derives a default rect-pose `pickEvery`
+     *  and the scene-iteration loop from this. */
+    getNodes(): TNode[];
+    getPose(id: string): TPose;
+    /** Optional. Required only by hierarchy-aware paths: layout-pass drop
+     *  targeting (`getLayout` present), nested-hit collapse
+     *  (`pickTopMostHit`), and group-pose composition. Flat scenes may omit. */
+    getParent?(id: string): string | null;
+    setPose(id: string, pose: TPose): void;
+    /** Optional. Used only by reparent ops (e.g. drag-into-container drops via
+     *  layout strategies). Flat scenes that never reparent may omit. */
+    setParent?(id: string, parentId: string | null): void;
+    /** Optional: see SceneAdapter.applyOps. */
+    applyOps?(ops: Op[], label: string): void;
+    findSnapTarget?(draggedId: string, worldX: number, worldY: number): SnapTarget<TPose> | null;
+    /** Optional: direct children of `id`. When present (alongside the
+     *  `cascadeWorldPose` option on `useMove`), dragging a node
+     *  auto-cascades its descendants in the live overlay so structurally-
+     *  grouped children visually follow the parent during the drag. No
+     *  additional ops are generated — children's local poses don't change
+     *  when the parent's local pose moves. */
+    getChildren?(id: string): string[];
+    /** Optional: layout strategy attached to a container, or null if the
+     *  container uses absolute positioning (default behavior). When present,
+     *  `useMove` uses the strategy to compute drop targets, sibling reflow,
+     *  and the commit op batch when a drag ends over the container. */
+    getLayout?(containerId: string): LayoutStrategy<TPose> | null;
+}
+/**
+ * Narrow adapter for `useResize`. Mirrors `MoveAdapter`'s shape
+ * minus reparenting and snap-target lookup.
+ * TPose is constrained to { x, y, width, height } inline to avoid a circular
+ * import with interactions/types.ts.
+ */
+interface ResizeAdapter<TNode extends {
+    id: string;
+}, TPose> {
+    getNode(id: string): TNode | undefined;
+    getPose(id: string): TPose;
+    setPose(id: string, pose: TPose): void;
+    /** Optional: see SceneAdapter.applyOps. */
+    applyOps?(ops: Op[], label: string): void;
+}
+/**
+ * Narrow adapter for `useRotate`. Mirrors `ResizeAdapter`'s shape — rotate
+ * mutates pose only and never reparents. TPose is left fully generic so
+ * non-rect rotated poses (e.g. a `RotatedPath`) compose without changes.
+ */
+interface RotateAdapter<TNode extends {
+    id: string;
+}, TPose> {
+    getNode(id: string): TNode | undefined;
+    getPose(id: string): TPose;
+    setPose(id: string, pose: TPose): void;
+    /** Optional: see SceneAdapter.applyOps. */
+    applyOps?(ops: Op[], label: string): void;
+}
+/**
+ * Narrow adapter for `useAreaSelect`. Transient: no checkpoint, no
+ * history. The hook calls `applyOps(ops)` instead of `applyOps(ops, label)`.
+ */
+/**
+ * Narrow adapter for `useAreaSelect`. Transient: no checkpoint, no
+ * history. The hook calls `applyOps(ops)` instead of `applyOps(ops, label)`.
+ *
+ * All fields are **optional** — area-select is opt-in. `useSelectTool` only
+ * wires the default marquee behavior when `hitTestArea`, `getSelection`,
+ * `setSelection`, and `applyOps` are all present on the adapter; otherwise
+ * the gesture short-circuits (empty-space drags do nothing, sub-threshold
+ * empty clicks still clear selection via the tool's `onClick` path).
+ * Demos that don't need marquee selection can omit these methods entirely.
+ */
+interface AreaSelectAdapter {
+    /** Returns ids of nodes intersecting the world-space rect. */
+    hitTestArea?(rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): string[];
+    /** Current selection — read by behaviors to compute additive merges. */
+    getSelection?(): string[];
+    /** Mutator wired by `setSelection` op. */
+    setSelection?(ids: string[]): void;
+    /** Apply ops without checkpointing or pushing a history entry. The optional
+     *  `label` parameter is accepted (and ignored by transient implementations)
+     *  so that this signature is compatible with `MoveAdapter.applyOps`. */
+    applyOps?(ops: Op[], label?: string): void;
+}
+/**
+ * Hit mode for `LassoSelectAdapter.hitTestLasso`:
+ *   - 'centers'   — bounds center inside polygon.
+ *   - 'intersect' — bounds intersect polygon (any overlap).
+ *   - 'enclosed'  — bounds fully inside polygon.
+ */
+type LassoHitMode = 'centers' | 'intersect' | 'enclosed';
+/**
+ * Narrow adapter for `useLassoSelect`. Extends `AreaSelectAdapter` with a
+ * polygon hit-test method. Transient — uses `applyOps` like its rectangular
+ * sibling. `hitTestLasso` is optional; when omitted, `useLassoTool` skips
+ * wiring the default behavior (same opt-in pattern as `hitTestArea`).
+ */
+interface LassoSelectAdapter extends AreaSelectAdapter {
+    /** Hit-test against a closed polygon. Vertex order may be CW or CCW; the
+     *  closing edge from last → first is implicit. */
+    hitTestLasso?(polygon: ReadonlyArray<{
+        x: number;
+        y: number;
+    }>, mode: LassoHitMode): string[];
+}
+/**
+ * Narrow adapter for `useInsert` and `useClipboardOps`. The kit knows
+ * nothing about what tool is active or what shape to construct; it asks the
+ * adapter to produce node(s) given gesture or paste inputs.
+ *
+ * Drag-rectangle path: `commitInsert(bounds)` returns one new node or null.
+ * Clipboard paste path: `commitPaste(clipboard, offset)` returns the array of
+ *   newly-materialized nodes (in order). Both empty array and array of
+ *   length N are valid; the kit wraps each entry in an `InsertOp`.
+ *
+ * `snapshotSelection(ids)` builds the payload that paste later consumes.
+ * `getPasteOffset` is optional; the kit defaults to a fixed grid-cell offset
+ * supplied by the consumer (passed to `useClipboardOps` options if needed; see
+ * the hook for resolution order).
+ */
+interface InsertAdapter<TNode extends {
+    id: string;
+}> {
+    /** Materialize a new node from drag-rect bounds (drag-to-insert tools).
+     *  Optional — hooks that don't drive insertion (e.g. `useClone`,
+     *  read-only clipboard) won't call it, and `sceneToAdapter` only fills
+     *  it in when `options.commitInsert` is supplied. Hooks that *do* call
+     *  it (insert tools) document the requirement at their own surface. */
+    commitInsert?(bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): TNode | null;
+    /** Materialize one or more new nodes from a clipboard snapshot. Optional
+     *  — required by `useClipboard.paste`, ignored by other consumers. */
+    commitPaste?(clipboard: ClipboardSnapshot, offset: {
+        dx: number;
+        dy: number;
+    }, ctx?: {
+        dropPoint?: {
+            worldX: number;
+            worldY: number;
+        };
+    }): TNode[];
+    /** Snapshot the current selection into the clipboard payload shape.
+     *  Optional — required by `useClipboard.copy` / `cut` and `useClone`'s
+     *  ghost capture, ignored by other consumers. */
+    snapshotSelection?(ids: string[]): ClipboardSnapshot;
+    getPasteOffset?(clipboard: ClipboardSnapshot): {
+        dx: number;
+        dy: number;
+    };
+    /** Mutator wired by `insertNode`-using ops (kit-side InsertOp). */
+    insertNode(node: TNode): void;
+    /** Mutator wired by `setSelection` ops batched alongside paste. */
+    setSelection(ids: string[]): void;
+    /** Optional: see SceneAdapter.applyOps. */
+    applyOps?(ops: Op[], label: string): void;
+    /** Returns the current selection. Used by clone behaviors. */
+    getSelection(): string[];
+}
+/**
+ * Optional surface that lets `buildSceneTree` walk the adapter by layer.
+ * Adapters that don't implement this fall back to flat rendering in Canvas's
+ * scene layer.
+ */
+interface LayerEnumerableAdapter<TLayer extends string = string> {
+    getLayers?(): readonly {
+        id: TLayer;
+        visible: boolean;
+    }[];
+}
+/**
+ * Optional adapter mixin for sibling z-order.
+ *
+ * Both methods are optional. Reorder ops and `useReorder` no-op when
+ * either is absent — adopt z-order incrementally without breaking existing
+ * adapters.
+ *
+ * **Convention:** array order IS z-order. Index 0 is the bottom of the
+ * stack, the last index is the top. Hit-testing should iterate the returned
+ * list in REVERSE (top to bottom). Render layers iterate FORWARD (bottom to
+ * top).
+ *
+ * For groups, `parentId` may be a group id; the group adapter routes
+ * `getChildren`/`setChildOrder` to the group's `members[]` array.
+ */
+interface OrderedAdapter {
+    /** Ordered children of `parentId` (or root siblings if null), in z-order:
+     *  index 0 is bottom, last index is top. */
+    getChildren?(parentId: string | null): string[];
+    /** Rewrite the order of `parentId`'s children. Length and contents must
+     *  match the existing children — reorder only, no add/remove. */
+    setChildOrder?(parentId: string | null, ids: string[]): void;
+}
+
+export type { AreaSelectAdapter as A, ClipboardSnapshot as C, DropTarget as D, InsertAdapter as I, LayoutStrategy as L, MoveAdapter as M, OrderedAdapter as O, RotateAdapter as R, SnapTarget as S, LassoHitMode as a, LassoSelectAdapter as b, ResizeAdapter as c, SceneAdapter as d, LayerEnumerableAdapter as e, LayoutSnap as f, ContainerBounds as g, LayoutChild as h, LayoutContainer as i, LayoutDragged as j };