@mt-gloss/ui 0.1.72 → 0.1.74

package/lib/primitives/dashboard/MetricCard/EdgeHoverHandle.d.ts

@@ -1,66 +0,0 @@
-import { ResizeState, ResizeDirection } from './useEdgeHoverResize';
-export interface EdgeHoverHandleProps {
-    state: ResizeState;
-    onPointerDown: (e: React.PointerEvent) => void;
-    onPointerUp: (e: React.PointerEvent) => void;
-    /**
-     * Bug E (260417-drag-resize-5th-attempt) — handle's own pointerenter/leave
-     * keeps the edge-hover zone alive when pointer crosses from sentinel to
-     * handle (they're siblings, so sentinel.pointerleave would otherwise collapse
-     * state to idle, hiding the handle mid-gesture).
-     */
-    onPointerEnter?: () => void;
-    onPointerLeave?: (e: React.PointerEvent) => void;
-    /**
-     * D-13 — right-edge resize only. Left-edge support dropped (CONTEXT D-13);
-     * narrowed to the literal 'right'. Prop retained so downstream data-edge
-     * attributes and future bidirectional revival can slot in without a
-     * breaking API change.
-     */
-    edge?: 'right';
-    /** D-16 — keyboard step handler (ArrowLeft → 'shrink', ArrowRight → 'grow'). */
-    onKeyboardStep?: (direction: ResizeDirection) => void;
-    /**
-     * Quick 260422-gfr — fires when the browser implicitly releases pointer
-     * capture from the <button> (window blur / Alt-Tab / modal focus steal /
-     * touchcancel). Consumers wire this to the hook's `cancel()` so the gesture
-     * deterministically exits `'dragging'` on capture loss. Companion to the
-     * window-level blur / visibilitychange / pointercancel listeners installed
-     * inside useEdgeHoverResize. See .planning/debug/resize-state-leak-cross-card.md.
-     */
-    onLostPointerCapture?: (e: React.PointerEvent) => void;
-    ariaLabel?: string;
-}
-/**
- * EdgeHoverHandle — Corner/edge handle affordance for the resize gesture.
- *
- * Visibility is derived from resize state: only visible when state is
- * 'handle-visible', 'dragging', or 'settling'. Invisible at 'idle' to avoid
- * colliding with the chip-menu click target on the value/row area.
- *
- * Motion contract (AN-06): opacity transitions driven by edge-hover.scss
- * using enterMs=180ms (enter) / exitMs=120ms (exit via ghost-preview).
- *
- * Pointer capture (debug 260417-qt00z / D-02+D-03 root cause): the handle is
- * only 10px wide. On pointerdown we call setPointerCapture(pointerId) so all
- * subsequent pointermove/pointerup events route to this element even after
- * the cursor leaves the handle's hit region. Without this, dragging rightward
- * (the natural grow gesture) moves the pointer off the handle within the
- * first few px — pointerup then fires on whatever is underneath, the handle's
- * React onPointerUp never runs, and the state machine stays stuck at
- * 'dragging' (so onResize is never called and the card never commits).
- *
- * Cross-card gesture suppression (260503-aff): during ANY drag/resize, the
- * resize handles on NON-source cards must hide so they don't compete with
- * the in-flight gesture's chrome. Achieved by AND-gating ONLY the
- * `'handle-visible'` branch on `useAffordanceVisibility().affordancesVisible`.
- * The `'dragging'` and `'settling'` branches stay un-gated to preserve the
- * SOURCE card's pointer-capture invariant — the source card's own handle MUST
- * remain visible (and pointer-capture-eligible) throughout its own gesture,
- * regardless of `affordancesVisible`. Non-source cards sit at
- * `'handle-visible'` or earlier, so when `affordancesVisible=false` (during
- * any global gesture + 200ms idle dwell), they hide. After the global
- * gesture settles back to idle and the dwell elapses, all handles re-emerge
- * together with the rest of the affordance chrome.
- */
-export declare const EdgeHoverHandle: import('react').ForwardRefExoticComponent<EdgeHoverHandleProps & import('react').RefAttributes<HTMLButtonElement>>;

package/lib/primitives/dashboard/MetricCard/__tests__/nyquist-10.fixture.d.ts

@@ -1,93 +0,0 @@
-/**
- * NYQUIST-10 — Phase 19.2 Cross-Card Hover-State Unification behavior matrix fixture.
- *
- * Parametrized behavior definitions that the NYQUIST-10 runner iterates over
- * via `it.each(BEHAVIOR_MATRIX)`. Each row pins one contract-level invariant
- * asserted by Phase 19.2 plans 19.2-01 / 19.2-02 / 19.2-03. The matrix acts as a
- * high-level regression net: if a future wave regresses ANY of the 10 rows,
- * the runner fails with a specific row label even if the underlying test
- * file lives elsewhere.
- *
- * Orthogonal axes (per VALIDATION.md §Orthogonal Sampling Matrix):
- *   - gridSize:     3 | 6 | 9 cards (leak-rate scaling)
- *   - intervalMs:   8 | 16 | 32 ms (event interval vs frame boundary)
- *   - eventCount:   10 | 20 | 40 (min signal / debug baseline / worst case)
- *   - cardType:     standard | stackable | mixed (StackedGroupCard hover unit)
- *   - dndActive:    boolean (dnd-kit drag suppression, RESEARCH Pitfall 4)
- *   - reducedMotion: boolean (prefers-reduced-motion parity)
- *
- * Row-count pin: the runner asserts exactly 10 rows so that accidentally
- * dropping or silently renaming a behavior fails fast.
- *
- * Invariant each row asserts (after 200ms settle — D-16):
- *   1. ≤1 card has `[data-visible="true"]` on its ActionStrip
- *   2. Every non-hovered card's `useEdgeHoverResize` state === 'idle'
- *   3. `hoveredCardId === expectedFinalCardId || null`
- *   4. `vi.getTimerCount() === 0`
- *
- * @see .planning/phases/19.2-cross-card-hover-state-unification/19.2-CONTEXT.md (D-16, D-17, D-18)
- * @see .planning/phases/19.2-cross-card-hover-state-unification/19.2-VALIDATION.md §Orthogonal Sampling Matrix
- * @see .planning/phases/19.2-cross-card-hover-state-unification/19.2-PATTERNS.md Analog 8 (nyquist-11-fixtures.ts)
- */
-export interface NyquistHarness {
-    /** Root grid container element (for dispatchEvent). */
-    gridRoot: HTMLElement;
-    /** Ordered list of card root elements (each has data-instance-id). */
-    cards: HTMLElement[];
-    /**
-     * Returns current hoveredCardId value from the grid (reads from
-     * data-hovered-card-id attribute on root, or a test-only prop hook).
-     */
-    getHoveredCardId: () => string | null;
-    /**
-     * Returns the useEdgeHoverResize state for a given card id — reads
-     * data-resize-state attribute from slot root.
-     */
-    getEdgeHoverStateFor: (cardId: string) => string;
-    /** Cleanup harness-mounted DOM. */
-    unmount: () => void;
-}
-export interface BehaviorParams {
-    gridSize: 3 | 6 | 9;
-    intervalMs: 8 | 16 | 32;
-    eventCount: 10 | 20 | 40;
-    cardType: 'standard' | 'stackable' | 'mixed';
-    dndActive: boolean;
-    reducedMotion: boolean;
-}
-export interface BehaviorDef {
-    /** 1-indexed for human readability in test output. */
-    id: number;
-    /** Short, greppable label. */
-    label: string;
-    /** Orthogonal axis values for this row. */
-    params: BehaviorParams;
-    /**
-     * The contract invariant this row pins. Either an assert-lambda that the
-     * runner invokes inside `it.each`, or `null` when the row is documented as
-     * covered by a sibling test file (runner skips but keeps the row in the
-     * matrix count pin). Wave 0 ships with `null` assert bodies; Task 2 wires
-     * the invariant body via it.each + harness mount, NOT via these callbacks.
-     */
-    assert: ((harness: NyquistHarness) => Promise<void>) | null;
-    /**
-     * When present, the runner skips the row with the returned reason string
-     * instead of calling `assert`. Used to document rows whose contract is
-     * pinned by a dedicated sibling test file (cross-reference maintained in
-     * 19.2-VALIDATION.md).
-     */
-    skipFor?: () => string | undefined;
-}
-/**
- * The 10 NYQUIST-10 behaviors. Each row's `assert` is `null` in Wave 0; the
- * invariant body lives in hoveredCardId.invariant.test.tsx driven by
- * `it.each(BEHAVIOR_MATRIX)`. Rows remain in the matrix so the row-count pin
- * (10) catches silent drops or reorder.
- */
-export declare const BEHAVIOR_MATRIX: BehaviorDef[];
-/**
- * Row-count pin — NYQUIST-10 runner asserts exactly this number of rows.
- * Changing the behavior set requires updating this constant and adding a
- * line in 19.2-VALIDATION.md §Orthogonal Sampling Matrix.
- */
-export declare const BEHAVIOR_ROW_COUNT = 10;

package/lib/primitives/dashboard/MetricCard/useEdgeHoverResize.d.ts

@@ -1,130 +0,0 @@
-import { MotionValue } from 'motion/react';
-import { ResizePhysicsConfig } from './resizePhysics';
-export type ResizeState = 'idle' | 'dwelling' | 'handle-visible' | 'dragging' | 'settling' | 'cancelled';
-export type ResizeDirection = 'grow' | 'shrink';
-export type ResizeMode = 'slot-fill' | 'sparkline-fidelity';
-export interface ResizeCommit {
-    direction: ResizeDirection;
-    targetColSpan: 1 | 2 | 3;
-    mode: ResizeMode;
-}
-export interface UseEdgeHoverResizeArgs {
-    currentColSpan: 1 | 2 | 3;
-    stackable: boolean;
-    onResize: (commit: ResizeCommit) => void;
-    onCancel?: () => void;
-    /** D-14 — colWidth snapshot passed per-render; captured at pointerdown. Default: 180px (1280px viewport). */
-    step?: number;
-    /**
-     * Grid gap (px) between adjacent columns. Used to compute the ghost's
-     * left-anchored width as `colSpan * step + (colSpan - 1) * gap`. Default: 0
-     * (single-column grids). Rework 260419-v2 — ghost is width-driven, not
-     * translateX-driven; this is the companion scalar.
-     */
-    gap?: number;
-    /** D-03 panel override; falls back to DEFAULT_RESIZE_PHYSICS. */
-    tuning?: Partial<ResizePhysicsConfig>;
-    /** Hover dwell time before handle appears. Default: 60ms */
-    dwellMs?: number;
-    /**
-     * Grace period (ms) after pointer leaves the edge zone before collapsing to idle.
-     * Prevents the handle from disappearing on brief mouse-off during natural mouse
-     * movement (e.g. crossing the sentinel/handle gap). Default: 150ms.
-     */
-    graceExitMs?: number;
-    /** AN-06 enter motion duration exposed for consumer CSS. Default: 180ms */
-    enterMs?: number;
-    /** AN-06 exit motion duration exposed for consumer CSS. Default: 120ms */
-    exitMs?: number;
-    /**
-     * Max colSpan supported by the grid (D-13 — right-edge-only grow). Default: 3.
-     * Used to clamp ghostWidth writes during drag so the ghost cannot grow
-     * past the maximum-allowed column width at any cursor position (debug
-     * session 260419-ghost-slides-across-page — AP-17 companion invariant).
-     *
-     * Bug fix 260420-resize-past-sections — this cap is now enforced on the
-     * COMMIT path as well (onPointerUp + onKeyboardStep + hysteresisSnap).
-     * Previously only the live ghost width was clamped; onPointerUp passed
-     * raw `dx` to hysteresisSnap whose forward walk + final clamp used a
-     * hardcoded `3`, letting fast drags commit `targetColSpan = 3` past the
-     * section boundary.
-     */
-    maxColSpan?: 1 | 2 | 3;
-    /**
-     * Phase 19.2 D-04 — grid-driven synchronous idle reset.
-     *
-     * When `true`, the hook synchronously clears pending dwell/touch-idle
-     * timers and transitions state to `'idle'`. Protects the drag grip:
-     * no-op during `'dragging'` or `'settling'` states (pointer-captured;
-     * spring owns settle; see D-05 + D-11 + debug/260419-hover-state-stuck-multi-card.md).
-     *
-     * Replaces the legacy "Polish Fix #7" window-pointermove self-heal
-     * (now deleted — grid-driven beats window-driven; D-04 ¶2).
-     *
-     * Prop-driven only. DO NOT add a ref-based imperative path (D-05).
-     *
-     * @default undefined (treated as false — hook runs normally)
-     */
-    forceIdle?: boolean;
-}
-export interface UseEdgeHoverResizeReturn {
-    state: ResizeState;
-    enterEdgeZone: () => void;
-    leaveEdgeZone: () => void;
-    handleProps: {
-        onPointerDown: (e: React.PointerEvent) => void;
-        onPointerUp: (e: React.PointerEvent) => void;
-        onPointerEnter: () => void;
-        onPointerLeave: () => void;
-    };
-    /**
-     * Live preview during drag. Always clamped to 1..3.
-     * Reflects the colSpan the user would commit at the current cursor position,
-     * with hysteresis snap (D-06).
-     */
-    previewColSpan: 1 | 2 | 3;
-    ghostProps: {
-        visible: boolean;
-        targetColSpan: 1 | 2 | 3;
-        /**
-         * D-07 rework 260419-v2 — MotionValue driving ghost WIDTH (left-anchored).
-         * The ghost LEFT edge is pinned at the slot origin; the ghost RIGHT edge
-         * follows the cursor; `ghostWidth` carries that width imperatively with
-         * zero React re-renders per pointermove. Supersedes the prior `motionX`
-         * translateX semantic (which slid the entire ghost horizontally — see
-         * debug session 260419-ghost-slides-across-page).
-         */
-        ghostWidth: MotionValue<number>;
-        enterMs: number;
-        exitMs: number;
-    };
-    /** D-16 — keyboard resize step (grow/shrink by 1) on focused handle. */
-    onKeyboardStep: (direction: ResizeDirection) => void;
-    /** D-19 — touch tap-to-reveal: show handle immediately on touch pointerdown on card body. */
-    onTouchReveal: () => void;
-    /** D-19 — outside-tap dismissal for touch. */
-    onTouchDismiss: () => void;
-    /** D-18 — cancel (used by parent; springs back if dragging). */
-    cancel: () => void;
-}
-/**
- * useEdgeHoverResize — Phase 19 reworked state machine for edge-hover-to-resize.
- *
- * Changes vs Phase 10.5 original:
- *  - MotionValue ghost tracking (D-07) — zero React re-renders per pointermove
- *  - Hysteresis snap (D-06) replaces Math.round(dx/step)
- *  - Velocity ring buffer (D-09) feeds spring commit
- *  - Spring commit via framer-motion animate() (D-08: stiffness 500, damping 22, mass 1 — retuned 260419 for visible overshoot, was damping 35)
- *  - 'settling' state (D-12) hard-blocks re-engagement during spring
- *  - committed state removed (D-05) — rolls into settling → idle
- *  - Keyboard step (D-16): onKeyboardStep('grow'|'shrink')
- *  - Escape spring-back with cursor velocity (D-15)
- *  - Touch tap-to-reveal with 5s idle (D-19)
- *  - prefers-reduced-motion bypass (D-22) — instant transform
- *
- * Preserved invariants:
- *  - Bug A React 19 updater purity — side effects fire OUTSIDE setState updaters
- *  - Bug E handle pointerenter keeps zone alive on sentinel→handle crossover
- *  - Dwell timer cleanup on unmount
- */
-export declare function useEdgeHoverResize({ currentColSpan, stackable, onResize, onCancel, step, gap, tuning, dwellMs, graceExitMs, enterMs, exitMs, maxColSpan, forceIdle, }: UseEdgeHoverResizeArgs): UseEdgeHoverResizeReturn;