@mt-gloss/ui 0.0.47 → 0.0.48

package/lib/facade/data-display.d.ts

@@ -19,8 +19,6 @@ export { SparklineBg } from '../primitives/dashboard/MetricCard';
 export { BarsBg } from '../primitives/dashboard/MetricCard';
 export { DonutChart } from '../primitives/dashboard/MetricCard';
 export { ObjectArrow } from '../primitives/dashboard/MetricCard';
-export { useSlideOutReveal } from '../primitives/dashboard/MetricCard';
-export type { SlideOutRevealConfig, SlideOutRevealReturn } from '../primitives/dashboard/MetricCard/useSlideOutReveal';
 export { TimeFrame, HybridDatePicker } from '../primitives/dashboard/TimeFrame';
 export type { TimeFrameProps, HybridDatePickerProps } from '../primitives/dashboard/TimeFrame';
 export { resolvePreset, resolveEvent, smartDateFormat, formatDateRange as formatDateRangeInterpretation } from '@mt-gloss/utils/dateInterpretation';

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

@@ -17,6 +17,6 @@ import { CardShellProps } from './types';
  * ```
  */
 export declare const CardShell: {
-    ({ contentSlot, children, colSpan, isStale, isRetrying, beta, disabled, style, accentRing, onGraph, onDetails, onCustomize, onRemove, onWhatsThis, onExpand, onShrink, onMove, onReplace, onNavigate, onRetry, onRefresh, enableQuickSettings, onUpdateTimeframe, instanceTimeframe, cardTitle, quickConfigSlot, onViewAsStack, onUnstack, isStackedGroup, onUpdateStackedTimeframes, instanceStackedTimeframes, isGraphActive, isTableActive, isGraphCard, canExpand, anchorX, extensionOverflow, cardRef: externalCardRef, }: CardShellProps): import("react/jsx-runtime").JSX.Element;
+    ({ contentSlot, children, colSpan, isStale, isRetrying, beta, disabled, style, accentRing, onGraph, onDetails, onCustomize, onRemove, onWhatsThis, onExpand, onShrink, onMove, onReplace, onNavigate, onRetry, onRefresh, enableQuickSettings, onUpdateTimeframe, instanceTimeframe, cardTitle, quickConfigSlot, onViewAsStack, onUnstack, isStackedGroup, onUpdateStackedTimeframes, instanceStackedTimeframes, isGraphActive, isTableActive, isGraphCard, canExpand, anchorX, extensionOverflow, cardRef: externalCardRef, hovered, }: CardShellProps): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };

package/lib/primitives/dashboard/MetricCard/__tests__/_testSupport/gridHoverListeners.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Test-only duplicate of
+ *   reptime-cloud/react-dashboard/app/components/MetricCards/gridHoverListeners.ts
+ *
+ * Phase 19.2 Plan 19.2-03 Task 3 — the production helper lives in the reptime
+ * consumer repo because the grid-level pointerover listener wiring is reptime-
+ * scoped (MetricCardGrid is not part of @mt-gloss/ui). For the NYQUIST-10
+ * invariant runner to mount + exercise the listener inside gloss-ui's jsdom
+ * test environment, we mirror the helper here.
+ *
+ * RULE: This file MUST stay byte-for-byte equivalent in behavior to the reptime
+ * source. When the reptime helper changes (debounce semantics, drag freeze,
+ * disabled filter), update this copy as well. The file exists ONLY to support
+ * the `hoveredCardId.invariant.test.tsx` harness — do NOT import it from any
+ * production gloss file.
+ *
+ * If gloss-ui ever ships a MetricCardGrid primitive of its own, promote the
+ * helper to a shared location and retire both copies.
+ */
+export declare const HOVER_IDLE_DEBOUNCE_MS = 100;
+export interface InstallGridHoverListenersOptions {
+    onHoveredCardIdChange: (nextId: string | null) => void;
+    draggedCardIdRef: {
+        current: string | null;
+    };
+    debounceMs?: number;
+    isDisabledCard?: (el: Element) => boolean;
+}
+export declare function installGridHoverListeners(root: HTMLElement, options: InstallGridHoverListenersOptions): () => void;

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

@@ -0,0 +1,93 @@
+/**
+ * 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/index.d.ts

@@ -8,7 +8,6 @@ export { StatusSlotChipMenu } from './StatusSlotChipMenu';
 export type { StatusSlotChipMenuProps, ChipMenuAction } from './StatusSlotChipMenu';
 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';
@@ -18,7 +17,6 @@ export * from './flipAndStage';
 export * from './types';
 export type { CardBackProps } from './CardBack';
 export type { StackedGroupCardProps, StackedValueEntry, SlotActionStripConfig, SlotToActionStripConfig, } from './StackedGroupCard';
-export type { SlideOutRevealConfig, SlideOutRevealReturn } from './useSlideOutReveal';
 export type { ResizeState, ResizeDirection, ResizeMode, ResizeCommit, UseEdgeHoverResizeArgs, UseEdgeHoverResizeReturn, } from './useEdgeHoverResize';
 export type { EdgeHoverHandleProps } from './EdgeHoverHandle';
 export type { GhostPreviewProps } from './GhostPreview';

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

@@ -136,6 +136,21 @@ export interface CardShellProps {
     beta?: boolean;
     disabled?: boolean;
     style?: CSSProperties;
+    /**
+     * Optional controlled hover state (Phase 19.2 D-02 / D-03 / D-08).
+     *
+     * When provided, CardShell DOES NOT track hover internally. Grid-authoritative
+     * consumers (e.g. `MetricCardGrid` in reptime-cloud) derive hover from a
+     * single container-level `pointerover`/`pointerleave` listener and thread
+     * `hovered={id === hoveredCardId}` to each slot (D-15).
+     *
+     * When undefined (default; backward-compat), falls back to internal
+     * `useState` driven by `onMouseEnter`/`onMouseLeave`, with the legacy 180ms
+     * leave-delay REMOVED (D-08 — CSS animation handles the fade).
+     *
+     * @default undefined (uncontrolled)
+     */
+    hovered?: boolean;
     /**
      * When true, renders a 2px accent ring around the card shell using box-shadow
      * (NOT border, to avoid reflow). Used to indicate config mode is active (D-09).

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

@@ -38,20 +38,35 @@ export interface UseEdgeHoverResizeArgs {
      */
     maxColSpan?: 1 | 2 | 3;
     /**
-     * Polish Fix #7 (0.0.46 UAT) — optional slot-scoped container element.
-     * When provided, the hook installs a window-level pointermove listener
-     * during 'dwelling' and 'handle-visible' states. If the cursor's target
-     * is NOT within `containerRef.current`, the hook force-calls
-     * `leaveEdgeZone()` — self-heal that fires when a consumer's own
-     * pointerleave guard (e.g. MetricCardSlot's `closest('.edge-hover-sentinel')`)
-     * incorrectly matches a SIBLING card's sentinel during a rapid sweep,
-     * leaving this card stuck at 'handle-visible' while the pointer has
-     * already moved on. Drag/settling are exempt (pointer capture owns the
-     * gesture); the self-heal only resets pre-gesture hover state.
+     * @deprecated since Phase 19.2 — superseded by `forceIdle`; retained for
+     * consumer-side compat until Phase 19.2 cutover ships. The window-level
+     * pointermove self-heal ("Polish Fix #7") that used this ref has been
+     * removed (D-04 ¶2). New code should pass `forceIdle` instead.
+     *
+     * Historical note: When provided, the hook installed a window-level
+     * pointermove listener during 'dwelling' and 'handle-visible' states to
+     * detect the cursor leaving `containerRef.current`. This was fragile under
+     * cross-card sweeps — grid-driven `forceIdle` is the correct pattern.
      */
     containerRef?: React.RefObject<Element | null> | {
         current: Element | null;
     };
+    /**
+     * 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;
@@ -113,4 +128,4 @@ export interface UseEdgeHoverResizeReturn {
  *  - 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, enterMs, exitMs, maxColSpan, containerRef, }: UseEdgeHoverResizeArgs): UseEdgeHoverResizeReturn;
+export declare function useEdgeHoverResize({ currentColSpan, stackable, onResize, onCancel, step, gap, tuning, dwellMs, enterMs, exitMs, maxColSpan, containerRef, forceIdle, }: UseEdgeHoverResizeArgs): UseEdgeHoverResizeReturn;

package/lib/primitives/overlays/ActionStrip/index.d.ts

@@ -1,7 +1,5 @@
 export { ActionStrip } from './ActionStrip';
 export type { PrimaryAction, OverflowAction, ActionStripProps, ActionStripContext, ActionStripMenuDirection, } from './types';
 export { subscribe, getActive, setActive, resetForTests, } from './overflowMenuRegistry';
-export { useSlideOutReveal } from './useSlideOutReveal';
-export type { SlideOutRevealConfig, SlideOutRevealReturn, SlideOutRevealStyle, } from './useSlideOutReveal';
 export { DEFAULT_OVERFLOW_IDS, DEFAULT_FOOTER_IDS, buildDefaultOverflow, } from './defaultActions';
 export type { DefaultHandlers } from './defaultActions';

package/lib/primitives/overlays/ActionStrip/types.d.ts

@@ -90,7 +90,11 @@ export interface ActionStripProps {
     primary: PrimaryAction[];
     /** Overflow entries (Settings, Remove, Replace, Refresh, What's this?). */
     overflow: OverflowAction[];
-    /** From `useSlideOutReveal` — true when the consumer card is hovered/focused. */
+    /**
+     * True when the consumer card is hovered/focused. Drives the CSS-owned
+     * slide-reveal animation via the root motion.div's `data-visible` attribute
+     * (Phase 19.2 D-07 / D-07a — see ActionStrip.scss @keyframes).
+     */
     visible: boolean;
     /** Sticky-on-click expansion state. */
     expanded: boolean;

package/package.json

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