@mt-gloss/ui 0.0.19 → 0.0.20

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/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.20",
   "type": "module",
   "publishConfig": {
     "access": "restricted"