@anuma/sdk 1.0.0 → 1.1.1

package/dist/design/index.d.mts

@@ -0,0 +1,561 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Anuma JSX AST — the in-memory model for slides and app mockups.
+ *
+ * Every artifact is a tree of `AnumaNode` values rooted at an `<Anuma.Deck>`
+ * (slides) or `<Anuma.Screen>` (apps — Stage 6+). There are no typed
+ * per-tag interfaces; the tree is tag-agnostic. Consumers walk the tree
+ * and dispatch on `node.tag`.
+ *
+ * Vocabulary (checked at parse time):
+ * - Containers: `<Anuma.Deck>`, `<Anuma.Slide>`, `<Anuma.Group>`.
+ * - Leaves: `<Anuma.Text>`, `<Anuma.Image>`, `<Anuma.Rect>`, `<Anuma.Circle>`,
+ *   `<Anuma.Line>`, `<Anuma.Icon>`.
+ *
+ * All coordinates are container-relative pixels — the slide canvas is
+ * 960×540 px, any child's `x`/`y`/`w`/`h` are pixels measured from the
+ * parent's top-left. Containers may opt into a flex layout with
+ * `layout="row" | "column"` plus `gap` / `padding` / `justify` / `align`;
+ * children inside a flex container skip `x`/`y` and flow instead.
+ *
+ * Numeric attrs are JSX expressions (`x={96}`), strings are quoted
+ * literals, booleans use `{true}`/`{false}` (or bare `hidden` for true).
+ * Dynamic expressions (`{someVar}`) are rejected in this version.
+ *
+ * @module tools/slides/jsx
+ */
+/** Scalar value an attribute can hold. */
+type AttrScalar = string | number | boolean;
+/**
+ * An object-valued attribute — used primarily for `style={{}}`. Keys are
+ * CSS property names in camelCase (`fontSize`, `borderRadius`, …); values
+ * are scalars.
+ */
+type AttrObject = Record<string, AttrScalar>;
+type AttrValue = AttrScalar | AttrObject;
+type AnumaChild = AnumaNode | string;
+/**
+ * A node in the Anuma tree. `tag` is the local name after `Anuma.` (e.g.
+ * `"Text"`, `"Slide"`). Children are other nodes for containers, or a
+ * single string (the body text) for `<Anuma.Text>`.
+ */
+interface AnumaNode {
+    tag: string;
+    attrs: Record<string, AttrValue>;
+    children: AnumaChild[];
+}
+
+/**
+ * Pure AST-mutation helpers for the design sandbox. The interaction
+ * layer determines INTENT (move this absolute element by [dx,dy], drop
+ * this flex child at index N) and these helpers produce the next
+ * AnumaNode tree. No DOM access here.
+ */
+
+type LayoutMode = "flex-row" | "flex-column" | "absolute";
+/** Tags that act as containers (not selectable / draggable themselves). */
+declare const NON_SELECTABLE_TAGS: ReadonlySet<string>;
+/**
+ * Determine how a node is positioned within its parent. A node whose
+ * parent has a `layout` attr of "row" or "column" is a flex child.
+ * Anything else (or top-level) is absolute.
+ */
+declare function getLayoutModeOf(deck: AnumaNode, childId: string): LayoutMode;
+/** True if the node's parent uses a flex layout. */
+declare function isFlexChild(deck: AnumaNode, childId: string): boolean;
+/**
+ * Where a dragged element will land on release. Computed each pointer
+ * move from the element under the cursor (via elementsFromPoint) and
+ * the target container's layout mode.
+ *   - flex: insert at `dropIndex` in target's children, strip x/y.
+ *   - absolute: insert into target with x/y/w/h in target's local
+ *     space. We carry w/h here (not just x/y) because flex children
+ *     don't store an explicit width — flex stretches them along the
+ *     cross axis. When such a child becomes absolute it needs explicit
+ *     dimensions or it collapses to content size; the caller measures
+ *     the element's current visual gBCR and passes those in.
+ */
+type DropTarget = {
+    kind: "flex";
+    parentId: string;
+    dropIndex: number;
+} | {
+    kind: "absolute";
+    parentId: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/** Layout mode of a container node based on its `layout` attr. */
+declare function containerLayoutMode(node: AnumaNode): LayoutMode;
+/**
+ * Commit a drag. Handles every case in one function so the caller
+ * doesn't have to branch on same-parent vs. cross-parent vs. mode-flip:
+ *   - flex → flex (same parent): reorder within parent
+ *   - flex → flex (different parent): move + reindex
+ *   - flex → absolute: move + add x/y at landing position
+ *   - absolute → absolute (same parent): just update x/y
+ *   - absolute → absolute (different parent): move + update x/y
+ *   - absolute → flex: move + strip x/y, reindex
+ */
+declare function commitDrop(deck: AnumaNode, elementId: string, target: DropTarget): AnumaNode;
+/** Bounds in slide-px, in the element's parent's local coordinate space. */
+type ResizeBounds = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/** Eight cardinal/intercardinal handle positions around a selected element. */
+type ResizeHandle = "nw" | "n" | "ne" | "e" | "se" | "s" | "sw" | "w";
+/**
+ * Direction of each handle in slide-px space:
+ *   dx = +1 if the handle is on the east edge, -1 west, 0 along x.
+ *   dy = +1 if the handle is on the south edge, -1 north, 0 along y.
+ */
+declare const RESIZE_HANDLE_DIRS: Record<ResizeHandle, {
+    dx: -1 | 0 | 1;
+    dy: -1 | 0 | 1;
+}>;
+/** CSS cursor value for each handle, so the user gets the right grab affordance. */
+declare const RESIZE_HANDLE_CURSORS: Record<ResizeHandle, string>;
+/**
+ * Commit a resize.
+ *   - Absolute children: write x/y/w/h (full resize freedom).
+ *   - Flex column children: write h only. The container's layout
+ *     determines position and the cross-axis (width) auto-stretches;
+ *     writing an explicit w would lock the child to its current
+ *     stretched width and break that auto-fill behavior the next time
+ *     the container resizes.
+ *   - Flex row children: symmetrically, write w only.
+ *
+ * The interaction layer paired with this only exposes the main-axis
+ * handle (s for column, e for row) on flex children, so the cross-axis
+ * dimension never gets touched in practice. This commit shape is the
+ * defensive backstop in case future call sites take a different path.
+ */
+declare function commitResize(deck: AnumaNode, elementId: string, bounds: ResizeBounds): AnumaNode;
+/**
+ * Commit a rotation. Writes `attrs.rotation` (degrees). The runtime
+ * applies it as `transform: rotate(...)` regardless of layout mode,
+ * so this works identically for absolute and flex children.
+ */
+declare function commitRotation(deck: AnumaNode, elementId: string, rotation: number): AnumaNode;
+/**
+ * True if all the given ids are absolute children of the same parent
+ * (and that parent isn't a flex container). This is the V0 condition
+ * for multi-drag: translating N elements by the same delta only makes
+ * sense when they share a coordinate frame (same parent's local space)
+ * and have x/y to translate (absolute, not flex). Mixed-parent or
+ * flex-included selections fall back to single-element drag.
+ */
+declare function canMultiDrag(deck: AnumaNode, ids: string[]): boolean;
+/**
+ * Translate every element in `elementIds` by `delta` (in their parent's
+ * local slide-px). Used for multi-drag commits. Elements without
+ * explicit attrs.x/y (flex children) are silently skipped — they
+ * shouldn't be in the set anyway per the canMultiDrag gate, but the
+ * defensive skip keeps a stray flex child from breaking the commit.
+ */
+declare function commitMultiDrag(deck: AnumaNode, elementIds: readonly string[], delta: {
+    x: number;
+    y: number;
+}): AnumaNode;
+/**
+ * Replace a Text node's children with a single string. The runtime
+ * stores text as one or more string children of an `<Anuma.Text>`
+ * node; we collapse to a single string on commit (which preserves
+ * line breaks in the string itself).
+ *
+ * No-op if the node isn't found, or if the supplied text matches the
+ * existing content (avoids spurious AST diffs / re-renders for
+ * commits triggered by blur with no actual change).
+ */
+declare function commitTextChange(deck: AnumaNode, elementId: string, newText: string): AnumaNode;
+/**
+ * Read the plain-text content of a node by joining its string children.
+ * Non-string children (nested AnumaNodes) are skipped; for simple Text
+ * elements that's the entire content.
+ */
+declare function getTextContent(node: AnumaNode): string;
+
+/**
+ * For a flex parent, compute which insertion slot the pointer is over.
+ * Reads child rects from the DOM (gBCR).
+ *
+ * Returns the index in `parent.children` AFTER removing the dragged
+ * child (so 0 = before all remaining siblings, N = after all of them).
+ */
+declare function computeFlexDropTarget(stage: HTMLElement, parentId: string, draggedId: string, axis: "row" | "column", pointerClient: {
+    x: number;
+    y: number;
+}, scale: number): {
+    index: number;
+    bounds: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+};
+/**
+ * Find the deepest container under the cursor that's not the dragged
+ * element or one of its descendants. Uses `elementsFromPoint` so the
+ * walk respects visual layering (the dragged element's translate makes
+ * it the topmost hit; we skip it and fall through).
+ */
+declare function findContainerAt(stage: HTMLElement, draggedId: string, pointerClient: {
+    x: number;
+    y: number;
+}): HTMLElement | null;
+/**
+ * Resolve the cursor into a DropTarget. The container under the cursor
+ * decides the drop's kind: a flex container produces a flex drop with
+ * a computed insertion index; an absolute container produces an
+ * absolute drop with x/y/w/h in container-local slide-px.
+ *
+ * For absolute drops, w/h come from the AST's intrinsic dims (not
+ * gBCR) — gBCR is the AABB and would inflate dimensions for rotated
+ * elements, accumulating scale across drops.
+ */
+declare function resolveDropTarget(deck: AnumaNode, stage: HTMLElement, draggedId: string, pointerClient: {
+    x: number;
+    y: number;
+}, scale: number): {
+    drop: DropTarget;
+    indicatorBounds: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+} | null;
+
+/**
+ * Walk the click path and return the first descendant of `stage` that
+ * carries a `data-id` and a non-container `data-anuma-tag`.
+ * `composedPath` works in both light and shadow DOM.
+ */
+declare function findElementIdFromEvent(e: {
+    nativeEvent: Event;
+} | Event, root: HTMLElement | null): string | null;
+/**
+ * Walk the click path and return the resize-handle direction (if any)
+ * the pointer landed on. Handles carry `data-resize-handle="<dir>"`.
+ * Pointer-down on a handle is unambiguously a resize; check this
+ * BEFORE the element-selection walk.
+ */
+declare function findResizeHandleFromEvent(e: PointerEvent): ResizeHandle | null;
+/** True if the pointer-down hit the rotate handle (`data-rotate-handle="true"`). */
+declare function findRotateHandleFromEvent(e: PointerEvent): boolean;
+/**
+ * Find every selectable element whose CENTER falls within the given
+ * client-px rect. Used by marquee selection.
+ *
+ * Center-in-rect (rather than rect-overlaps-element) matches Figma:
+ * dragging the marquee over a sliver of an element doesn't select it,
+ * but dragging across its center does.
+ */
+declare function findElementsInRect(stage: HTMLElement, rect: {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+}): string[];
+
+/**
+ * Axis-aligned bounds of an element relative to the stage origin, in
+ * slide-px. Edges + centers so we can pair-test all 9 alignment
+ * candidates per axis (left↔left, left↔center, left↔right, ...).
+ */
+type SnapBounds = {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+    cx: number;
+    cy: number;
+};
+/**
+ * A snap line to render. `axis: 'x'` is a vertical line at slide-x =
+ * `position`; `axis: 'y'` is horizontal at slide-y = `position`. The
+ * `start`/`end` range is along the OTHER axis, chosen to cover the
+ * dragged group + the matched sibling.
+ */
+type SnapGuide = {
+    axis: "x" | "y";
+    position: number;
+    start: number;
+    end: number;
+};
+/** Unrotated bounds + rotation of an element, in slide-px. */
+type SelectionBounds = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    rotation: number;
+};
+/** SelectionBounds plus the element's id. Used for multi-selection lists. */
+type IdBounds = SelectionBounds & {
+    id: string;
+};
+/**
+ * In-flight gesture state. Phases:
+ *   - 'pending': pointer is down but hasn't crossed the drag threshold.
+ *     `elementId === null` means the pointer-down landed on empty
+ *     canvas; promotion takes us to 'marquee'. Non-null elementId
+ *     promotes to 'dragging'.
+ *   - 'marquee': empty-canvas drag is now sweeping a selection rect.
+ *   - 'dragging': element drag is active. Drop target is recomputed
+ *     each pointer-move from what's under the cursor.
+ *   - 'resizing': pointer-down was on a resize handle.
+ *   - 'rotating': pointer-down was on the rotate handle.
+ */
+type Gesture = {
+    phase: "pending";
+    elementId: string | null;
+    startClient: {
+        x: number;
+        y: number;
+    };
+    shiftKey: boolean;
+} | {
+    phase: "marquee";
+    startClient: {
+        x: number;
+        y: number;
+    };
+    currentClient: {
+        x: number;
+        y: number;
+    };
+    additive: boolean;
+    initialSelection: ReadonlySet<string>;
+} | {
+    phase: "dragging";
+    elementId: string;
+    elementIds: string[];
+    startClient: {
+        x: number;
+        y: number;
+    };
+    delta: {
+        x: number;
+        y: number;
+    };
+    drop: DropTarget | null;
+    indicatorBounds: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    } | null;
+    startGroupBounds: SnapBounds | null;
+    guides: SnapGuide[];
+} | {
+    phase: "resizing";
+    elementId: string;
+    handle: ResizeHandle;
+    startClient: {
+        x: number;
+        y: number;
+    };
+    startBounds: ResizeBounds;
+    startCenter: {
+        x: number;
+        y: number;
+    };
+    rotation: number;
+    layoutMode: "absolute" | "flex-row" | "flex-column";
+    currentBounds: ResizeBounds;
+} | {
+    phase: "rotating";
+    elementId: string;
+    centerClient: {
+        x: number;
+        y: number;
+    };
+    startAngle: number;
+    startRotation: number;
+    currentRotation: number;
+};
+
+type CanvasOverlaysProps = {
+    /** Current gesture (drives marquee/guides/drop-indicator visibility). */
+    gesture: Gesture | null;
+    /** Single primary selection (when 1 selected). Null for 0 or >1. */
+    selectedId: string | null;
+    /** Full selection (drives multi-outline rendering). */
+    selectedIds: ReadonlySet<string>;
+    /** Bounds of the primary selection. Provided by useSelectionBounds. */
+    selectionBounds: SelectionBounds | null;
+    /** Bounds of every selected element. Provided by useMultiSelectionBounds. */
+    multiBounds: IdBounds[];
+    /** Editing target id (suppresses overlays so the edit overlay is unobstructed). */
+    editingId?: string | null;
+    /** AST root — needed to resolve the selected element's layout mode. */
+    deck: AnumaNode;
+    /** Slide-px → client-px scale. */
+    scale: number;
+};
+/**
+ * Renders all canvas overlays: selection outline + handles, multi-
+ * selection outlines, marquee, snap guides, flex drop indicator.
+ *
+ * Drawn in slide-px and scaled with the stage. Sits OUTSIDE the
+ * scaled stage in the same wrapper, so its coords are post-scale
+ * (multiplied by `scale` here). The marquee uses `position: fixed`
+ * since gesture coords are clientX/Y (viewport-relative).
+ */
+declare function CanvasOverlays({ gesture, selectedId, selectedIds, selectionBounds, multiBounds, editingId, deck, scale, }: CanvasOverlaysProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Read an element's gBCR-derived bounds in slide-px relative to the
+ * stage origin. `scale` converts client-px → slide-px (the AST stores
+ * positions in slide-px).
+ */
+declare function getStageRelativeBounds(el: HTMLElement, stage: HTMLElement, scale: number): SnapBounds;
+/** Outer envelope of multiple bounds — the dragged group's AABB. */
+declare function unionBounds(arr: readonly SnapBounds[]): SnapBounds | null;
+declare function computeSnap(start: SnapBounds, rawDelta: {
+    x: number;
+    y: number;
+}, others: readonly SnapBounds[], thresholdSlide: number): {
+    delta: {
+        x: number;
+        y: number;
+    };
+    guides: SnapGuide[];
+};
+
+type UseCanvasGesturesOpts = {
+    stageRef: React.RefObject<HTMLElement | null>;
+    deck: AnumaNode;
+    setDeck: (updater: AnumaNode | ((d: AnumaNode) => AnumaNode)) => void;
+    /** Slide-px to client-px scale. Pointer math divides client deltas by this. */
+    scale: number;
+    /** Suppress all gestures (e.g. magic-select active in slide editor). */
+    disabled?: boolean;
+    /** Controlled selection. When omitted, the hook manages internal state. */
+    selectedIds?: ReadonlySet<string>;
+    onSelectionChange?: (ids: ReadonlySet<string>) => void;
+    /** Called on double-click of a Text element. Host enters edit mode. */
+    onTextDoubleClick?: (elementId: string) => void;
+    /**
+     * Predicate for "should we ignore this pointer-down?" — used by hosts
+     * with their own overlays (e.g. the text-edit contenteditable). When
+     * true, the gesture handler bails immediately.
+     */
+    shouldIgnorePointerDown?: (e: React.PointerEvent<HTMLElement>) => boolean;
+    /**
+     * Called synchronously inside `onPointerDown` BEFORE any gesture
+     * starts, after `shouldIgnorePointerDown` returned false. Hosts use
+     * this to commit a pending text edit (so click-elsewhere ends the
+     * edit and starts a fresh gesture in the same event).
+     */
+    beforePointerDown?: () => void;
+};
+type UseCanvasGesturesReturn = {
+    selectedIds: ReadonlySet<string>;
+    /** Lone selected id when size===1, else null. */
+    selectedId: string | null;
+    setSelectedIds: (ids: ReadonlySet<string> | ((prev: ReadonlySet<string>) => ReadonlySet<string>)) => void;
+    gesture: Gesture | null;
+    /** Deck with in-flight resize/rotate patched for live rendering. */
+    renderedDeck: AnumaNode;
+    onPointerDown: (e: React.PointerEvent<HTMLElement>) => void;
+    onPointerMove: (e: React.PointerEvent<HTMLElement>) => void;
+    onPointerUp: (e: React.PointerEvent<HTMLElement>) => void;
+    onPointerCancel: (e: React.PointerEvent<HTMLElement>) => void;
+    onDoubleClick: (e: React.MouseEvent<HTMLElement>) => void;
+};
+/**
+ * Pointer-driven gesture state machine for an Anuma canvas.
+ *
+ * Handles: click-to-select, shift-click multi-select, marquee
+ * selection, drag (single + multi, cross-parent + flex-reorder),
+ * resize (8-handle for absolute, main-axis-only for flex), rotate,
+ * snap-to-edges, double-click-to-edit-text.
+ *
+ * Per-phase transition logic lives in `./transitions.ts`; this hook
+ * is the React glue (state, handlers, effects).
+ *
+ * Host responsibilities:
+ *   - Render the slide tree (`renderedDeck`) into a stage element.
+ *   - Wire `onPointerDown/Move/Up/Cancel` on a wrapper around the
+ *     stage (the stage itself has `transform: scale()` which would
+ *     distort pointer math).
+ *   - Wire `onDoubleClick` on the same wrapper.
+ *   - Render selection / handles / marquee / guides overlays
+ *     (typically via `<CanvasOverlays>`).
+ */
+declare function useCanvasGestures(opts: UseCanvasGesturesOpts): UseCanvasGesturesReturn;
+
+type UseCanvasKeyboardOpts = {
+    setDeck: (updater: AnumaNode | ((d: AnumaNode) => AnumaNode)) => void;
+    selectedIds: ReadonlySet<string>;
+    setSelectedIds: (ids: ReadonlySet<string>) => void;
+    /** Suppress all shortcuts (e.g. while inline-editing text). */
+    disabled?: boolean;
+    /** Optional undo/redo. When omitted, Cmd+Z is a no-op. */
+    undo?: () => void;
+    redo?: () => void;
+};
+declare function useCanvasKeyboard(opts: UseCanvasKeyboardOpts): void;
+
+type UseDeckHistoryReturn = {
+    deck: AnumaNode;
+    setDeck: (updater: AnumaNode | ((d: AnumaNode) => AnumaNode)) => void;
+    undo: () => void;
+    redo: () => void;
+    canUndo: boolean;
+    canRedo: boolean;
+    undoCount: number;
+    redoCount: number;
+};
+/**
+ * Drop-in replacement for `useState<AnumaNode>` that records every
+ * commit on an undo stack. Gesture handlers don't change — they still
+ * call `setDeck(d => commitX(d, ...))`. The hook intercepts each
+ * commit to push the new tree onto a history array.
+ *
+ * Forking on a commit truncates the redo branch — standard editor
+ * convention. If the updater returns the same reference it received
+ * (no-op commit), no snapshot is recorded.
+ *
+ * Limitations (V0):
+ *   - Each commit is its own undo step. Holding shift+arrow nudges
+ *     creates one entry per keypress; coalescing into a single drag
+ *     entry is future polish.
+ *   - History is per-mount. No persistence across page reloads.
+ */
+declare function useDeckHistory(initial: AnumaNode): UseDeckHistoryReturn;
+
+/**
+ * Read the unrotated bounds + rotation of the selected element, in
+ * slide-px relative to the stage origin.
+ *
+ * Recovery from gBCR: the runtime rotates around the element's center
+ * (transform-origin: 50% 50%), so AABB.center == element.center. We
+ * take the center from gBCR and the intrinsic w/h from `attrs`. The
+ * unrotated top-left is then center − (w/2, h/2). Falls back to gBCR
+ * dims for elements with no explicit attrs.w/h (auto-stretched flex
+ * children).
+ *
+ * useLayoutEffect (not useEffect) so the rect update runs between
+ * React's commit and the browser paint — without it, after a gesture
+ * commit there's one frame where the AST has updated but `bounds` is
+ * still stale (visible as the outline flickering at the old position).
+ */
+declare function useSelectionBounds(stageRef: React.RefObject<HTMLElement | null>, selectedId: string | null, deck: AnumaNode, scale: number): SelectionBounds | null;
+/**
+ * Bounds for every element in `selectedIds`. Same recovery logic as
+ * useSelectionBounds, just iterated. Returns `{ id, ...SelectionBounds }`
+ * per id so callers can render an outline per selection.
+ */
+declare function useMultiSelectionBounds(stageRef: React.RefObject<HTMLElement | null>, selectedIds: ReadonlySet<string>, deck: AnumaNode, scale: number): IdBounds[];
+
+export { CanvasOverlays, type CanvasOverlaysProps, type DropTarget, type Gesture, type IdBounds, type LayoutMode, NON_SELECTABLE_TAGS, RESIZE_HANDLE_CURSORS, RESIZE_HANDLE_DIRS, type ResizeBounds, type ResizeHandle, type SelectionBounds, type SnapBounds, type SnapGuide, type UseCanvasGesturesOpts, type UseCanvasGesturesReturn, type UseCanvasKeyboardOpts, type UseDeckHistoryReturn, canMultiDrag, commitDrop, commitMultiDrag, commitResize, commitRotation, commitTextChange, computeFlexDropTarget, computeSnap, containerLayoutMode, findContainerAt, findElementIdFromEvent, findElementsInRect, findResizeHandleFromEvent, findRotateHandleFromEvent, getLayoutModeOf, getStageRelativeBounds, getTextContent, isFlexChild, resolveDropTarget, unionBounds, useCanvasGestures, useCanvasKeyboard, useDeckHistory, useMultiSelectionBounds, useSelectionBounds };