things-api 0.9.0 → 0.10.0

package/dist/write/vectors/ui-drag.d.ts

@@ -0,0 +1,188 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { UiRunner } from "./ui.ts";
+export type SidebarPlacement = {
+    kind: "before";
+    uuid: string;
+    title: string;
+} | {
+    kind: "after";
+    uuid: string;
+    title: string;
+} | {
+    kind: "first";
+} | {
+    kind: "last";
+};
+export interface SidebarDragSpec {
+    targetUuid: string;
+    targetTitle: string;
+    placement: SidebarPlacement;
+}
+/** Ordered area state read from the database between hops (the assert seam). */
+export interface AreaSidebarState {
+    /** Areas ordered by TMArea."index" (== sidebar order once materialized). */
+    areas: {
+        uuid: string;
+        title: string;
+        index: number;
+    }[];
+    /** Digest over every untrashed task's area assignment (invariance tripwire). */
+    assignmentsDigest: string;
+}
+/**
+ * Auxiliary seams the ui vector needs beyond osascript dispatch. The sidebar
+ * drag driver asserts the database between hops; the client wires `areaState`
+ * to the open connection. Absent (e.g. the capabilities surface, which never
+ * executes), a drag op refuses cleanly.
+ */
+export interface UiDriveAux {
+    areaState?: () => AreaSidebarState;
+}
+/** The client-side default aux: reads area order + assignments from the DB. */
+export declare function createUiDriveAux(db: DatabaseSync): UiDriveAux;
+export interface SidebarRect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface SidebarRowInfo extends SidebarRect {
+    /** Concatenated descendant static-text segments, joined with "|". */
+    text: string;
+}
+export interface SidebarSnapshot {
+    /** The sidebar scroll-area viewport rect (the visible band). */
+    viewport: SidebarRect | null;
+    /** Vertical scroll fraction 0..1 from the AXScrollBar, when exposed. */
+    scroll: number | null;
+    rows: SidebarRowInfo[];
+}
+/** Snapshot: sidebar rows (text + frames), viewport rect, scroll fraction. */
+export declare function jxaSidebarSnapshotScript(): string;
+/**
+ * Scroll: move the pointer over the sidebar center (wheel events target the
+ * surface under the cursor), then post `clicks` line-unit wheel events.
+ * Positive clicks move the CONTENT down (earlier rows return, row y grows);
+ * negative clicks reveal lower rows (row y shrinks) — AXDRAG1-b.
+ */
+export declare function jxaSidebarScrollScript(clicks: number): string;
+/**
+ * Drag: the NATIVE1 gesture verbatim — move, down, 3px wiggle to open the drag
+ * session, ~25 interpolated drag events, a settle so the drop indicator locks,
+ * then up. Coordinates are AX-resolved frames + slot-boundary geometry computed
+ * by the caller in the SAME snapshot generation.
+ */
+export declare function jxaSidebarDragScript(sx: number, sy: number, tx: number, ty: number): string;
+/**
+ * Rung 2 — scroll-while-held (AXDRAG2-a: wheel events DO scroll the list while
+ * a drag is held, and AX frames re-resolve fresh mid-drag). One atomic
+ * gesture: grab the source, post wheel events until the anchor row's LIVE
+ * frame enters the visible band (direction re-derived every tick from the
+ * live frame), then move to the live-computed boundary and drop. No static
+ * corrections are needed — the mid-drag layout already reflects the lifted
+ * source. If the anchor never arrives within the tick budget, the script
+ * Escape-aborts (AXDRAG1-d: byte-identical index vector) and reports it.
+ */
+export declare function jxaSidebarHeldScrollDragScript(sx: number, sy: number, anchorTitle: string | null, // null = drop below the last row (to-last)
+maxTicks: number): string;
+/** Median height of the table's spacer rows (rows with no static text). */
+export declare function medianSpacerHeight(rows: SidebarRowInfo[]): number | null;
+/**
+ * Slot pitch estimate: the median y-delta between adjacent resolved area rows
+ * (falls back to entity-row height + spacer height when fewer than two area
+ * rows resolve).
+ */
+export declare function slotPitch(orderedAreaRows: {
+    title: string;
+    row: SidebarRowInfo;
+}[], allRows: SidebarRowInfo[]): number;
+/**
+ * The boundary Y that inserts ABOVE `ref`: the midpoint of the region between
+ * `ref` and the row immediately above it (the spacer row's center when a
+ * spacer sits there; the shared edge when rows are contiguous). With no row
+ * above, half a spacer height above `ref` (derived, not assumed).
+ */
+export declare function boundaryAboveRow(allRows: SidebarRowInfo[], ref: SidebarRowInfo): number;
+/**
+ * The boundary Y that drops BELOW the final table row (to-last). The drop
+ * zone below the last entity IS the trailing spacer row when one exists
+ * (AXDRAG1-b landed to-last inside it) — its center keeps the drop in the
+ * scrollable band even when the list is pinned to the bottom.
+ */
+export declare function boundaryBelowLast(allRows: SidebarRowInfo[]): number | null;
+export declare function parseSidebarSnapshot(stdout: string): SidebarSnapshot | null;
+/**
+ * Does a row's static-text carry this exact title as a segment? Sidebar row
+ * text concatenates descendant static texts with "|" (AXDRAG1: e.g.
+ * "Area-05.|Source Toggle Template|Area-05") — an exact segment match avoids
+ * substring collisions; the trailing-dot variant covers the AXDescription-like
+ * first segment some rows carry.
+ */
+export declare function rowMatchesTitle(text: string, title: string): boolean;
+/** All rows matching known area titles, in visual (y) order. */
+export declare function areaRowsInOrder(rows: SidebarRowInfo[], titles: readonly string[]): {
+    title: string;
+    row: SidebarRowInfo;
+}[];
+/** Find a single area row by title; ambiguous or missing → null. */
+export declare function findAreaRow(rows: SidebarRowInfo[], title: string): SidebarRowInfo | null;
+/**
+ * The source's group span: lifting an area collapses its row AND its visible
+ * nested project rows. Computed from resolved frames as the distance from the
+ * source area row's top to the NEXT area row's top (falls back to the median
+ * slot pitch when the source is the last area).
+ */
+export declare function sourceGroupSpan(orderedAreaRows: {
+    title: string;
+    row: SidebarRowInfo;
+}[], sourceTitle: string, allRows: SidebarRowInfo[]): number;
+/**
+ * Static drop boundary Y for the requested placement, computed against the
+ * CURRENT snapshot. Every placement reduces to "insert above area R" (the
+ * mid-gap above R's row) except to-last, which drops below the final table row.
+ */
+export declare function staticBoundaryY(orderedAreaRows: {
+    title: string;
+    row: SidebarRowInfo;
+}[], allRows: SidebarRowInfo[], sourceTitle: string, placement: SidebarPlacement): {
+    y: number;
+    anchor: string;
+} | {
+    error: string;
+};
+/**
+ * Correct a static boundary for the mid-drag layout: a DOWNWARD drag (boundary
+ * below the source) sees everything below the source shift up by the source's
+ * group span the instant it is picked up (AXDRAG1-a). Upward drags use static
+ * coordinates unchanged.
+ */
+export declare function correctedDropY(staticY: number, sourceCenterY: number, span: number): number;
+export declare function inBand(y: number, viewport: SidebarRect, pad?: number): boolean;
+/**
+ * Grab/drop x: a fixed FRACTION of the row's resolved width (≈ the label area
+ * NATIVE1 clicked at x+170 on a 240px row), clear of the leading icon and the
+ * trailing counters — derived from the frame, not a pixel offset.
+ */
+export declare function grabPoint(row: SidebarRowInfo): {
+    x: number;
+    y: number;
+};
+/** Is the requested placement already satisfied in this DB state? */
+export declare function placementSatisfied(state: AreaSidebarState, targetUuid: string, placement: SidebarPlacement): boolean;
+export interface DragDriveResult {
+    ok: boolean;
+    /** Human-readable outcome (hop count, rung) or the refusal reason. */
+    detail: string;
+    /** A gesture may have landed before the failure — recovery state, honestly. */
+    recovered?: boolean;
+}
+/**
+ * The rung-2 anchor: every placement reduces to "drop above this area row"
+ * (title) or "drop below the last row" (null). `undefined` = unresolvable.
+ */
+export declare function rung2AnchorTitle(rows: SidebarRowInfo[], areaTitles: readonly string[], sourceTitle: string, placement: SidebarPlacement): string | null | undefined;
+/**
+ * Drive the full ladder. `preState` is captured ONCE up front for the whole
+ * move (recovery + the caller's undo capture both key off it, not per hop).
+ */
+export declare function driveSidebarAreaReorder(spec: SidebarDragSpec, run: UiRunner, aux: UiDriveAux, sleep?: (ms: number) => Promise<void>): Promise<DragDriveResult>;