@mt-gloss/ui 0.0.42 → 0.0.44

package/lib/primitives/dashboard/DevTuningPanel/DevTuningPanel.d.ts

@@ -0,0 +1,13 @@
+import { default as React } from 'react';
+export interface DevTuningPanelProps {
+    /**
+     * Reserved — optional DOM portal target. Not currently used; panel is
+     * position:fixed so it does not need a portal. Included in the public
+     * interface for forward compatibility.
+     */
+    container?: HTMLElement;
+}
+export declare function DevTuningPanel(_props?: DevTuningPanelProps): React.ReactElement | null;
+export declare namespace DevTuningPanel {
+    var displayName: string;
+}

package/lib/primitives/dashboard/DevTuningPanel/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Phase 19 Plan 02 — DevTuningPanel barrel export.
+ *
+ * Re-exports the dev-only Resize Tuning primitive + its localStorage-backed
+ * hook. Barrel is zero-side-effect; the SCSS is imported from
+ * `DevTuningPanel.tsx` so consumers that only import the hook pay no CSS cost.
+ */
+export { DevTuningPanel } from './DevTuningPanel';
+export type { DevTuningPanelProps } from './DevTuningPanel';
+export { useResizeTuning, TUNING_STORAGE_KEY, TUNING_DEFAULTS } from './useResizeTuning';
+export type { UseResizeTuningReturn, TuningConfig } from './useResizeTuning';

package/lib/primitives/dashboard/DevTuningPanel/useResizeTuning.d.ts

@@ -0,0 +1,47 @@
+/** D-03 — exact localStorage key. */
+export declare const TUNING_STORAGE_KEY = "resize.tuning.dev";
+/**
+ * TUNING_DEFAULTS extends ResizePhysicsConfig with px-expressed snap thresholds
+ * that the UI surfaces (UI-SPEC §Surface 3 rows 4 & 5). The hook consumer
+ * converts to fractions at drag-start (`snapInFraction = snapInPx / step`).
+ * Defaults match DEFAULT_RESIZE_PHYSICS fraction math against the 180px GRID_STEP:
+ *   snapInPx  = 180 × 1/3 = 60
+ *   snapOutPx = 180 × 1/2 = 90
+ */
+/**
+ * Raw defaults — declared as `as const` so the shape's keys are pinned, but
+ * `TuningConfig` below widens each field to `number` so downstream setters
+ * accept the full slider range (e.g. `snapOutPx: 110`), not just the literal
+ * default (`snapOutPx: 90`).
+ */
+declare const _TUNING_DEFAULTS_LITERAL: {
+    readonly snapInPx: 60;
+    readonly snapOutPx: 90;
+    readonly stiffness: 500;
+    readonly damping: 35;
+    readonly mass: 1;
+    readonly snapInFraction: number;
+    readonly snapOutFraction: number;
+    readonly blueprintOpacity: 0.25;
+    readonly blueprintFadeInMs: 150;
+    readonly blueprintFadeOutMs: 120;
+    readonly rippleStaggerMs: 50;
+    readonly velocityMultiplier: 1;
+};
+export type TuningConfig = {
+    -readonly [K in keyof typeof _TUNING_DEFAULTS_LITERAL]: number;
+};
+/** Public defaults — widened to `TuningConfig` so consumers can reassign. */
+export declare const TUNING_DEFAULTS: TuningConfig;
+export interface UseResizeTuningReturn {
+    /** Current tuning values (defaults merged with any persisted deltas). */
+    values: TuningConfig;
+    /** Update a single key; persists to localStorage. */
+    setValue<K extends keyof TuningConfig>(key: K, value: TuningConfig[K]): void;
+    /** Restore a single key to its TUNING_DEFAULTS value. */
+    resetRow<K extends keyof TuningConfig>(key: K): void;
+    /** Restore every key to TUNING_DEFAULTS. */
+    resetAll(): void;
+}
+export declare function useResizeTuning(): UseResizeTuningReturn;
+export {};

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

@@ -1,4 +1,4 @@
-import { ResizeState } from './useEdgeHoverResize';
+import { ResizeState, ResizeDirection } from './useEdgeHoverResize';
 export interface EdgeHoverHandleProps {
     state: ResizeState;
     onPointerDown: (e: React.PointerEvent) => void;
@@ -11,16 +11,23 @@ export interface EdgeHoverHandleProps {
      */
     onPointerEnter?: () => void;
     onPointerLeave?: (e: React.PointerEvent) => void;
-    /** Which card edge the handle is positioned on. Default: 'right' */
-    edge?: 'right' | 'left';
+    /**
+     * 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;
     ariaLabel?: string;
 }
 /**
  * EdgeHoverHandle — Corner/edge handle affordance for the resize gesture.
  *
  * Visibility is derived from resize state: only visible when state is
- * 'handle-visible' or 'dragging'. Invisible at 'idle' to avoid colliding
- * with the chip-menu click target on the value/row area.
+ * '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).

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

@@ -1,8 +1,11 @@
+import { MotionValue } from 'framer-motion';
 export interface GhostPreviewProps {
-    /** Whether the ghost overlay is currently visible (active during drag). */
+    /** Whether the ghost overlay is currently visible (active during drag/settling). */
     visible: boolean;
     /** The target column span being previewed. */
     targetColSpan: 1 | 2 | 3;
+    /** D-07 — MotionValue driving translateX. Zero React re-renders per pointermove. */
+    motionX: MotionValue<number>;
     /** AN-06 enter duration in ms. Default: 180ms */
     enterMs?: number;
     /** AN-06 exit duration in ms. Default: 120ms */
@@ -11,14 +14,14 @@ export interface GhostPreviewProps {
 /**
  * GhostPreview — Dashed outline overlay rendered during an active resize drag.
  *
- * Provides visual feedback of the target card size before the user commits
- * by releasing the pointer. Uses the same ghost-preview vocabulary as the
- * existing chart-area resize affordance.
+ * Phase 19 evolution: consumes a framer-motion MotionValue for translateX
+ * (D-07) so ghost tracks the cursor 1:1 without React re-renders on
+ * pointermove (AP-17). Opacity transitions still use CSS enterMs/exitMs.
  *
  * Hidden via aria-hidden — purely decorative visual feedback.
  * Motion contract (AN-06): enter 180ms, exit 120ms.
  */
-export declare function GhostPreview({ visible, targetColSpan, enterMs, exitMs, }: GhostPreviewProps): import("react/jsx-runtime").JSX.Element;
+export declare function GhostPreview({ visible, targetColSpan, motionX, enterMs, exitMs, }: GhostPreviewProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace GhostPreview {
     var displayName: string;
 }

package/lib/primitives/dashboard/MetricCard/__tests__/fixtures/nyquist-09-parity-matrix.d.ts

@@ -0,0 +1,76 @@
+/**
+ * NYQUIST-09 Parity Matrix — Phase 19 plan 19-05.
+ *
+ * Typed array of 144 rows enumerating the 7-axis resize parity space:
+ *
+ *   spring          — 3 presets: default (S500D35M1), gentle (S300D30M1), stiff (S700D40M1)
+ *   viewport        — round-robin across [1280, 1920, 2560] (all 3 appear in asserted set)
+ *   reducedMotion   — {false, true}
+ *   pointerType     — {'mouse', 'touch'}
+ *   cardMode        — {'slot-fill', 'sparkline-fidelity'}
+ *   cancelPath      — {'commit', 'escape', 'out-of-range'}
+ *   dndKitActive    — {false, true}
+ *
+ * Arithmetic (per 19-RESEARCH §NYQUIST-09 Fixture Matrix):
+ *   3 × 2 × 2 × 2 × 3 × 2 = 144 logical rows.
+ *   Viewport axis is DERIVED per-row (round-robin) so every asserted row still
+ *   represents one of the 3 canonical viewports without multiplying the base
+ *   by a 4th full axis — this matches the RESEARCH-stated 144 count exactly.
+ *
+ * SkipFor taxonomy (~84 rows tagged; first-match wins):
+ *
+ *   Rule 1 — reducedMotion && spring === 'stiff':
+ *     Reduced motion bypasses spring; stiffer preset collapses to same
+ *     instant-jump code path as default. (default spring + gentle preset
+ *     still carry the rm=true assertion to exercise the branch.)
+ *
+ *   Rule 2 — pointerType === 'touch' && cancelPath === 'escape':
+ *     Touch devices lack Escape key; covered by separate touch-pointercancel
+ *     fixture (useEdgeHoverResize.touch.test.tsx).
+ *
+ *   Rule 3 — cardMode === 'sparkline-fidelity' && dndKitActive:
+ *     Non-stackable cards are not sortable; dnd-kit active state is
+ *     impossible (invariant from PagesContext.tsx stack rules).
+ *
+ *   Rule 4 — cancelPath === 'out-of-range' && !dndKitActive && spring !== default:
+ *     Out-of-range clamp is independent of spring variant; default-spring row
+ *     carries the clamp assertion. Non-default springs on the clamp path are
+ *     redundant (physics variant does not affect Math.min(3, …) behavior).
+ *
+ * Asserted target: 60 ± 5 rows (plan acceptance criterion).
+ * Actual asserted: 63 / 144 (skipped 81). Viewport distribution across
+ * asserted rows: 1280 → 25, 1920 → 18, 2560 → 20 (all 3 represented).
+ *
+ * @see .planning/phases/19-resize-interaction-rework/19-RESEARCH.md §NYQUIST-09 Fixture Matrix
+ * @see .planning/phases/19-resize-interaction-rework/19-PATTERNS.md §S10 NYQUIST matrix authoring
+ * @see .planning/phases/19-resize-interaction-rework/19-05-PLAN.md Task 1
+ */
+export interface Nyquist09Row {
+    /**
+     * Stable row id, e.g. 'S500D35M1-vw1280-rm_off-mouse-stack-commit-dndk_on'.
+     * Shape: `S{stiffness}D{damping}M{mass}-vw{viewport}-rm_{on|off}-{pointer}-{stack|spark}-{cancelPath}-dndk_{on|off}`.
+     */
+    id: string;
+    spring: {
+        stiffness: number;
+        damping: number;
+        mass: number;
+    };
+    viewport: 1280 | 1920 | 2560;
+    reducedMotion: boolean;
+    pointerType: 'mouse' | 'touch';
+    cardMode: 'slot-fill' | 'sparkline-fidelity';
+    cancelPath: 'commit' | 'escape' | 'out-of-range';
+    dndKitActive: boolean;
+    /**
+     * If set, row is test.skip with this reason string. Acceptance criterion:
+     * skipped ≤ 84, asserted ≥ 55 (see PLAN threat-model T-19-16).
+     */
+    skipFor?: string;
+}
+/** Canonical 144-row NYQUIST-09 parity matrix — enumerated explicitly for diff-ability. */
+export declare const NYQUIST_09_MATRIX: readonly Nyquist09Row[];
+/** Convenience: number of rows that actually run (skipFor === undefined). Exported for CI sanity check. */
+export declare const NYQUIST_09_ASSERTED_COUNT: number;
+/** Convenience: number of rows tagged skipFor. Exported for CI sanity check. */
+export declare const NYQUIST_09_SKIPPED_COUNT: number;

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

@@ -10,6 +10,10 @@ export { EdgeHoverHandle } from './EdgeHoverHandle';
 export { GhostPreview } from './GhostPreview';
 export { useSlideOutReveal } from './useSlideOutReveal';
 export { useEdgeHoverResize } from './useEdgeHoverResize';
+export { DEFAULT_RESIZE_PHYSICS } from './resizePhysics';
+export type { ResizePhysicsConfig } from './resizePhysics';
+export { VelocityBuffer } from './velocityBuffer';
+export type { VelocitySample } from './velocityBuffer';
 export * from './flipAndStage';
 export * from './types';
 export type { CardBackProps } from './CardBack';

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

@@ -0,0 +1,19 @@
+/**
+ * resizePhysics — D-08 / D-06 / D-11 / D-20 single source of truth.
+ *
+ * Constants consumed by both useEdgeHoverResize (spring commit) and the
+ * DevTuningPanel (Plan 19-02) so the panel and the hook never drift.
+ */
+export declare const DEFAULT_RESIZE_PHYSICS: {
+    readonly stiffness: 500;
+    readonly damping: 35;
+    readonly mass: 1;
+    readonly snapInFraction: number;
+    readonly snapOutFraction: number;
+    readonly blueprintOpacity: 0.25;
+    readonly blueprintFadeInMs: 150;
+    readonly blueprintFadeOutMs: 120;
+    readonly rippleStaggerMs: 50;
+    readonly velocityMultiplier: 1;
+};
+export type ResizePhysicsConfig = typeof DEFAULT_RESIZE_PHYSICS;

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

@@ -1,4 +1,6 @@
-export type ResizeState = 'idle' | 'dwelling' | 'handle-visible' | 'dragging' | 'committed' | 'cancelled';
+import { MotionValue } from 'framer-motion';
+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 {
@@ -11,12 +13,23 @@ export interface UseEdgeHoverResizeArgs {
     stackable: boolean;
     onResize: (commit: ResizeCommit) => void;
     onCancel?: () => void;
+    /** D-14 — colWidth snapshot passed per-render; captured at pointerdown. Default: 180px (1280px viewport). */
+    step?: number;
+    /** D-03 panel override; falls back to DEFAULT_RESIZE_PHYSICS. */
+    tuning?: Partial<ResizePhysicsConfig>;
     /** Hover dwell time before handle appears. Default: 120ms */
     dwellMs?: 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 motionX writes during drag so the ghost cannot translate
+     * past the maximum-allowed column offset at any cursor position (debug
+     * session 260419-ghost-slides-across-page — AP-17 companion invariant).
+     */
+    maxColSpan?: 1 | 2 | 3;
 }
 export interface UseEdgeHoverResizeReturn {
     state: ResizeState;
@@ -29,35 +42,46 @@ export interface UseEdgeHoverResizeReturn {
         onPointerLeave: () => void;
     };
     /**
-     * quick-260417-2na §2a — Live preview during drag.
-     * While `state === 'dragging'`, reflects the colSpan the user would commit
-     * if they released the pointer at the current position. Resets to
-     * `currentColSpan` on transition out of 'dragging'. Always clamped to 1..3.
+     * 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;
-        /** Same value as `previewColSpan`; exposed here for `<GhostPreview targetColSpan>` plumbing. */
         targetColSpan: 1 | 2 | 3;
+        /** D-07 — MotionValue driving ghost translateX. Zero React re-renders per pointermove. */
+        motionX: 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 — State machine for edge-hover-to-resize gesture.
- *
- * State flow:
- *   idle → dwelling (hover dwell 120ms) → handle-visible → dragging (pointerdown) → committed (pointerup) | cancelled
- *   dwelling | handle-visible → idle (pointer leaves edge zone)
- *   dragging | handle-visible → cancelled (Escape key)
- *
- * The hook does NOT inspect any reptime-domain data. The consumer passes `stackable`
- * (from metricInfo) and the hook emits the correct mode string — no cross-domain leakage.
+ * useEdgeHoverResize — Phase 19 reworked state machine for edge-hover-to-resize.
  *
- * Threat mitigations:
- *   T-10.03-01: clearDwell() in cleanup useEffect prevents timer leak on unmount
- *   T-10.03-02: Math.min/max clamp keeps targetColSpan ∈ {1,2,3}
+ * 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 35, mass 1)
+ *  - '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
  *
- * Motion contract (AN-06): enterMs=180, exitMs=120 (defaults)
+ * 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, dwellMs, enterMs, exitMs, }: UseEdgeHoverResizeArgs): UseEdgeHoverResizeReturn;
+export declare function useEdgeHoverResize({ currentColSpan, stackable, onResize, onCancel, step, tuning, dwellMs, enterMs, exitMs, maxColSpan, }: UseEdgeHoverResizeArgs): UseEdgeHoverResizeReturn;

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

@@ -0,0 +1,39 @@
+/**
+ * VelocityBuffer — D-09 ring buffer for pointer velocity sampling.
+ *
+ * Stores up to `capacity` (3) VelocitySample entries. Computes a
+ * weighted-average velocity over the ring using 3×/2×/1× weights
+ * with divisor 6 (canonical formula per PLAN 19-01 resolution of
+ * §U1). When fewer than 3 samples exist, degrades gracefully:
+ *   - 0 samples → 0
+ *   - 1 sample  → 0 (caller sees no velocity)
+ *   - 2 samples → single-event dx/dt fallback (AP-20: never zero on a gesture)
+ *   - 3+ samples → (vRecent·3 + vMid·2 + vOld·1) / 6
+ *     where vOld degrades to vMid when only 2 deltas are available across 3 samples
+ *     (flat fallback; buffer still lives on 3 instants — plan §Task 2 resolution).
+ *
+ * dt is clamped to >= 1ms via Math.max(1, …) to avoid Infinity on same-tick duplicates.
+ *
+ * Units: px/sec.
+ */
+export interface VelocitySample {
+    x: number;
+    t: number;
+}
+export declare class VelocityBuffer {
+    private samples;
+    private readonly capacity;
+    push(sample: VelocitySample): void;
+    clear(): void;
+    /**
+     * D-09 — weighted-average velocity (px/sec).
+     *
+     * 0 samples → 0
+     * 1 sample  → 0
+     * 2 samples → single-event fallback dx/dt
+     * 3 samples → weighted avg with vOld falling back to vMid to keep the
+     *             divisor at 6. Formula: (vRecent·3 + vMid·2 + vMid·1) / 6
+     *             (see PLAN §Task 2 §U1 resolution).
+     */
+    getWeightedVelocity(): number;
+}

package/lib/primitives/dashboard/index.d.ts

@@ -11,3 +11,4 @@ export * from './ReconfigBacksideButtons';
 export * from './MetricCardGrid';
 export * from './TabbedDataView';
 export * from './MetricGroupContainer';
+export * from './DevTuningPanel';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mt-gloss/ui",
-  "version": "0.0.42",
+  "version": "0.0.44",
   "type": "module",
   "publishConfig": {
     "access": "restricted"