@mt-gloss/ui 0.0.19 → 0.0.21

package/lib/composites/controls/ThresholdRamp/ThresholdRamp.d.ts

@@ -11,6 +11,15 @@ export interface ThresholdRampProps {
     onChange: (stops: ThresholdStop[]) => void;
     min?: number;
     max?: number;
+    /**
+     * Snap granularity for both drag and keyboard interactions. Values are
+     * rounded to `Math.round(raw / step) * step`. Default `0.01` matches the
+     * historical 2-decimal behavior. Pass `1` for integer snap, `0.0001` for
+     * 4-decimal snap, etc. Matches the `step` prop on `<Slider>` / `<RangeSlider>`.
+     * Must be a positive finite number; invalid values fall back to 0.01 with
+     * a dev-mode warning.
+     */
+    step?: number;
     disabled?: boolean;
 }
 /**
@@ -18,7 +27,7 @@ export interface ThresholdRampProps {
  * Renders a token-driven gradient strip with draggable stop handles.
  * Generic — no reptime domain strings. D-01, D-10, D-11 compliant.
  */
-export declare function ThresholdRamp({ stops, onChange, min, max, disabled, }: ThresholdRampProps): import("react/jsx-runtime").JSX.Element;
+export declare function ThresholdRamp({ stops, onChange, min, max, step, disabled, }: ThresholdRampProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace ThresholdRamp {
     var displayName: string;
 }

package/lib/composites/dashboard/QuickConfigPanel/QuickConfigPanel.d.ts

@@ -6,9 +6,14 @@ import { QuickConfigPanelProps } from './types';
  * Provides header + pill-menu chrome (Save / Cancel buttons).
  *
  * D-01: Generic — no reptime/entityType/metricInfo domain knowledge.
- * D-03: Panel width uses CSS var `--gloss-slot-width` (MetricGroupContainer slot sizing reuse; 180px fallback).
  * D-19: NOT a modal — role is not "dialog"; no aria-modal; no focus trap.
  * AN-01: `will-change: transform` on root element; panel transitions use transform/opacity only.
+ *
+ * Positioning (WR-03): the panel is CONSUMER-POSITIONED — placement is driven
+ * by the parent grid (CSS-grid placement adjacent to the active card) or by
+ * a wrapper element the consumer supplies. `anchorRect` is retained as an
+ * opaque pass-through for diagnostics; this component does NOT compute
+ * translate(x, y) from it. Width is sized via `--gloss-slot-width` (180px
+ * fallback) from the MetricGroupContainer slot primitive.
  */
-export declare function QuickConfigPanel({ sections, onCommit, onCancel, anchorRect: _anchorRect, // accepted for position math by consumer — not used internally
-title, }: QuickConfigPanelProps): import("react/jsx-runtime").JSX.Element;
+export declare function QuickConfigPanel({ sections, onCommit, onCancel, anchorRect: _anchorRect, title, }: QuickConfigPanelProps): import("react/jsx-runtime").JSX.Element;

package/lib/composites/dashboard/QuickConfigPanel/types.d.ts

@@ -15,8 +15,21 @@ export interface QuickConfigSection {
 /**
  * Props for QuickConfigPanel.
  * D-01: opaque — no reptime/entityType/metricInfo semantics.
- * D-03: anchorRect provides DOMRect for position math via MetricGroupContainer slot sizing.
  * D-19: Panel is NOT a modal — role is not "dialog".
+ *
+ * Positioning contract (WR-03 clarification):
+ *   The panel is CONSUMER-POSITIONED. Placement is driven by the parent grid
+ *   (e.g. MetricCardGrid uses CSS-grid placement adjacent to the active card)
+ *   or by a wrapper element supplied by the consumer. This composite does
+ *   NOT compute `translate(x, y)` from an anchor rect internally — the
+ *   historical D-03 plan for internal anchor-rect math was superseded by the
+ *   grid-placement approach adopted in Phase 13.
+ *
+ *   `anchorRect` is retained as an opaque pass-through so consumers can
+ *   forward a DOMRect for diagnostics / future position-math plugins, but
+ *   the panel chrome ignores it. Width is sized from the
+ *   `--gloss-slot-width` CSS var (MetricGroupContainer slot-primitive reuse,
+ *   180px fallback). Height is intrinsic.
  */
 export interface QuickConfigPanelProps {
     /** Sections to render in the panel body */
@@ -26,8 +39,9 @@ export interface QuickConfigPanelProps {
     /** Fired when the user clicks the Cancel pill */
     onCancel: () => void;
     /**
-     * DOMRect of the anchor card — used for extrude position math (D-03).
-     * Panel does not crash when undefined; layout defaults apply.
+     * Opaque anchor-rect pass-through (see positioning contract above).
+     * Not consumed internally — supplied for consumer instrumentation only.
+     * @deprecated for direct use — placement is consumer-managed via grid / wrapper styles.
      */
     anchorRect?: DOMRect;
     /**

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

@@ -38,6 +38,29 @@ export interface GutterActionsProps {
     onConfigSave?: () => void;
     /** Called when Cancel pill is clicked in config variant. */
     onConfigCancel?: () => void;
+    /**
+     * Cluster C (quick-260417-ago) — Singleton overflow-menu identifier.
+     *
+     * When provided, this GutterActions instance cooperates with
+     * `overflowMenuRegistry` so only one overflow menu across the whole
+     * dashboard may be open at a time. Opening menu N sets the registry's
+     * activeId to N; any OTHER instance sees active !== its own id and closes
+     * its menu automatically via onMenuToggle(false).
+     *
+     * If omitted, a useId() fallback is used so each instance still gets a
+     * unique registry key — the singleton behavior still works across cards.
+     */
+    menuId?: string;
+    /**
+     * Cluster D (quick-260417-ago) — Horizontal anchor offset in px from the
+     * card's left edge. When provided, overrides the pill's default
+     * `left: 50%` centered position; drives the per-slot gutter-slide
+     * choreography (180ms ease-out) for stack cards whose hovered slot moves
+     * horizontally.
+     *
+     * Undefined (default) preserves the pre-existing centered layout.
+     */
+    anchorX?: number;
 }
 /**
  * GutterActions - Pill + overflow menu interaction system.
@@ -61,6 +84,6 @@ export interface GutterActionsProps {
  * ```
  */
 export declare const GutterActions: {
-    ({ visible, menuOpen, onMenuToggle, onGraph, onDetails, onCustomize, onRemove, onWhatsThis, onExpand, onShrink, onMove, onReplace, onNavigate, onRetry, onRefresh, onQuickSettings, onFlipBack, isFlipped, onViewAsStack, onUnstack, canExpand, isGraphCard, colSpan, isGraphActive, isTableActive, graphLabel, detailsLabel, variant, onConfigSave, onConfigCancel, }: GutterActionsProps): import("react/jsx-runtime").JSX.Element;
+    ({ visible, menuOpen, onMenuToggle, onGraph, onDetails, onCustomize, onRemove, onWhatsThis, onExpand, onShrink, onMove, onReplace, onNavigate, onRetry, onRefresh, onQuickSettings, onFlipBack, isFlipped, onViewAsStack, onUnstack, canExpand, isGraphCard, colSpan, isGraphActive, isTableActive, graphLabel, detailsLabel, variant, onConfigSave, onConfigCancel, menuId, anchorX, }: GutterActionsProps): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };

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

@@ -25,6 +25,25 @@ export interface StackedGroupCardProps {
      * Default: undefined (fall back to measured capacity; backward compatible).
      */
     colSpan?: 1 | 2 | 3;
+    /**
+     * Cluster D (quick-260417-ago, item 3) — fired when the pointer enters
+     * slot `idx` with its `timeframe`. Consumer uses this to drive the
+     * gutter-actions horizontal anchor (anchorX) and inject metric-scoped
+     * action handlers (e.g. Transmitted → open transmitted-orders tab).
+     * Optional; no-op if omitted (back-compat).
+     */
+    onSlotHoverStart?: (idx: number, timeframe: string) => void;
+    /** Cluster D — fired when the pointer leaves the currently hovered slot. */
+    onSlotHoverEnd?: () => void;
+    /**
+     * Cluster D (item 15) — sparkline edge behavior.
+     *   'padded' (default, back-compat): current behavior; SparklineBg sits
+     *     within the CardShell's inner padding.
+     *   'bleed': SparklineBg is wrapped in a negative-margin container so it
+     *     extends to the card's LEFT, TOP, and BOTTOM edges. Right edge keeps
+     *     padding so trend text on the right does not collide with the stroke.
+     */
+    sparklineInset?: 'padded' | 'bleed';
 }
 /**
  * StackedGroupCard -- Renders 3 mini metric values horizontally within a 2-col card.
@@ -47,6 +66,6 @@ export interface StackedGroupCardProps {
  * ```
  */
 export declare const StackedGroupCard: {
-    ({ title, prefix, suffix, values, timeframes, sparklineData, accentColor, pinnedTimeframe, onPinTimeframe, isStale, colSpan, }: StackedGroupCardProps): import("react/jsx-runtime").JSX.Element;
+    ({ title, prefix, suffix, values, timeframes, sparklineData, accentColor, pinnedTimeframe, onPinTimeframe, isStale, colSpan, onSlotHoverStart, onSlotHoverEnd, sparklineInset, }: StackedGroupCardProps): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };

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

@@ -0,0 +1,25 @@
+/**
+ * overflowMenuRegistry — Module-scoped singleton tracker for MetricCard overflow menus.
+ *
+ * quick-260417-ago Cluster C (item 14): only one overflow menu may be open at a time.
+ * When menu B opens, menu A receives a notification via its useSyncExternalStore
+ * subscription and closes itself.
+ *
+ * Uses a plain module-level `activeId` + Set<listener> — no new dep (Zustand is
+ * over-engineering for one state field; Context would require hoisting the
+ * provider higher than the card tree, which complicates flag-off paths).
+ *
+ * React 19's useSyncExternalStore consumes `subscribe` / `getSnapshot` and keeps
+ * components in sync without triggering tearing under concurrent rendering.
+ *
+ * Exports:
+ *   - subscribe(fn): listen to activeId changes; returns unsubscribe
+ *   - getActive(): current activeId (or null)
+ *   - setActive(id | null): declare which menu is open; notifies all subscribers
+ *   - resetForTests(): clears state between vitest runs
+ */
+export declare function subscribe(listener: () => void): () => void;
+export declare function getActive(): string | null;
+export declare function setActive(next: string | null): void;
+/** Test-only: resets internal state. Not exported from the public barrel. */
+export declare function resetForTests(): void;

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

@@ -3,12 +3,18 @@ import { MetricCardGridProps } from './types';
 /**
  * Finds the best adjacent slot to extrude the QuickConfigPanel into.
  *
- * Priority: right → below → left → above.
- * Returns null if activeIndex is invalid or no candidates exist.
+ * Priority (for both extrude AND dim-cover): right → below → left → above.
+ *
+ * Two modes, distinguished by caller:
+ *   1. Extrude — first candidate whose index is `>= cardCount` (empty slot)
+ *   2. Dim-cover fallback — when every candidate is occupied (`< cardCount`),
+ *      returns the FIRST candidate in priority order (right wins for LTR
+ *      readability; falls through to below / left / above only when the edge
+ *      of the grid excludes earlier candidates). WR-05: the dim-cover fallback
+ *      intentionally shares the priority list above — future enhancement could
+ *      pick the neighbor closest to the viewport center for symmetric behavior.
  *
- * When all neighbors are occupied (packed grid), returns the right neighbor
- * index for dim-cover fallback — the caller distinguishes empty vs occupied
- * by checking if extrudeIndex >= cardCount.
+ * Returns null if activeIndex is invalid or no candidates exist.
  *
  * @param activeIndex  Index of the active card in the ordered visible-cards array (0-based)
  * @param cardCount    Total number of cards in the visible page

package/lib/wrappers/SortableZones/useSortableZones.d.ts

@@ -34,8 +34,16 @@ export interface UseSortableZonesConfig<T extends {
  * Pure React hook (useState, useCallback). Does NOT import DndContext —
  * SortableZones.tsx connects the event handlers to DndContext callbacks.
  *
- * Uncontrolled by default: zones state is initialised from config.zones and
- * managed internally. Call onZoneChange to sync back to parent.
+ * State model: **hybrid controlled + uncontrolled**.
+ * - Internal state is seeded from `config.zones` at mount.
+ * - Drag handlers mutate internal state and call `onZoneChange` to sync up.
+ * - If the parent later passes a structurally different `config.zones`
+ *   (different zoneKeys or item id orderings) while no drag is in flight,
+ *   the hook re-syncs to the new prop. This lets parents drive zones from
+ *   external events (e.g. store updates outside a drag) without being
+ *   surprised by a "frozen at mount" internal snapshot.
+ * - Mid-drag prop updates are ignored so a stale controlled value cannot
+ *   clobber the in-progress drag.
  *
  * Generic over T extends { id: string }. No reptime-specific types. D-06, D-04, D-11 compliant.
  */

package/package.json

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