@mt-gloss/ui 0.1.44 → 0.1.46

package/lib/composites/dashboard/BottomToolbar/SectionDots.d.ts

@@ -27,5 +27,10 @@ export interface SectionDotsProps {
     pulseIndex?: number;
     /** Phase 4 D-10 — monotonically-increasing nonce; bump to replay the pulse keyframe. */
     pulseNonce?: number;
+    /** Phase 12 D-09 — caller's currently-anchored section. Preferred over currentIndex. */
+    currentSection?: number;
+    /** Phase 12 D-09 — how many sections fit in viewport at once. Default 1 (preserves v2.0 model). */
+    sectionsPerView?: number;
 }
-export declare function SectionDots({ count, currentIndex, onSelect, 'aria-label': ariaLabel, provisionalIndex, pulseIndex, pulseNonce, }: SectionDotsProps): import("react/jsx-runtime").JSX.Element;
+export declare function SectionDots({ count, currentIndex, onSelect, 'aria-label': ariaLabel, provisionalIndex, pulseIndex, pulseNonce, currentSection, // D-08 back-compat shim
+sectionsPerView, }: SectionDotsProps): import("react/jsx-runtime").JSX.Element | null;

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

@@ -16,6 +16,10 @@ export interface DropAnchorCellProps extends React.HTMLAttributes<HTMLDivElement
     proximityOpacity?: number;
     /** Stable cell id for test selectors + future instrumentation. */
     ['data-cell-id']?: string;
+    /** Phase 13 D-07 — 'empty' renders dashed eligibility border via [data-state='empty'].
+     *  Border PERSISTS during drag/resize (PKG-04 invariant); only affordance GLYPHS hide
+     *  via useAffordanceVisibility(). The border IS the drop-target affordance. */
+    state?: 'empty';
     children?: React.ReactNode;
 }
 /**
@@ -34,4 +38,4 @@ export interface DropAnchorCellProps extends React.HTMLAttributes<HTMLDivElement
  *
  * Respects prefers-reduced-motion.
  */
-export declare function DropAnchorCell({ density, canAccept, blocked, proximityOpacity, className, children, ...rest }: DropAnchorCellProps): import("react/jsx-runtime").JSX.Element;
+export declare function DropAnchorCell({ density, canAccept, blocked, proximityOpacity, state, className, children, ...rest }: DropAnchorCellProps): import("react/jsx-runtime").JSX.Element;

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

@@ -1,21 +1,54 @@
 import * as React from 'react';
 /**
- * Phase 23 — EMPTY-PACK-01 — `[×]` empty-cell pack affordance per D-19 / D-20.
+ * Phase 13 — Track G — Add/Remove/Collapse (D-04, D-05, D-06, D-19).
  *
- * Renders a small top-right button on an empty cell that, when clicked, requests
- * right-neighbor left-shift via `onPack()`. When `enabled=false` (all cells to
- * the right are also empty), the affordance is fully hidden (returns `null`).
+ * Hosts BOTH the `+` (add) and `×` (collapse/pack) glyphs on every empty cell.
  *
- * stopPropagation() on the button prevents the click from bubbling to the parent
- * DropAnchorCell's onClick (which opens the MetricCatalog). Without it, clicking
- * "×" would pack AND open the catalog simultaneously.
+ * **D-04 host-primitive count vs SwingReveal-JSX count clarification**
+ * (recorded per Phase 13 revision iteration 1 checker WARNING):
+ *
+ * D-04 in CONTEXT.md reads "Single SwingReveal wrapper". Functionally that
+ * refers to the single host primitive (`EmptyCellPackAffordance`) wrapping
+ * both glyphs as flat siblings — i.e., one host component owns the empty-cell
+ * chrome. The implementation uses TWO `<SwingReveal>` JSX wrappers (one per
+ * glyph) because D-19 requires INDEPENDENT visibility gating: the `+` glyph
+ * is always visible (`visible={true}`) while the `×` glyph is D-19-gated
+ * (`visible={enabled}`). A single `<SwingReveal>` cannot express two
+ * independent `visible` props on its children, so the two-wrapper shape IS
+ * the correct realization of D-04's functional intent. Host-primitive count
+ * = 1; SwingReveal JSX count = 2 for D-19 independent gating.
+ *
+ * `stopPropagation()` on each glyph button prevents the click from bubbling
+ * to the parent DropAnchorCell's `onClick` (which opens the MetricCatalog).
+ * Without it, clicking a glyph would pack/add AND open the catalog
+ * simultaneously.
+ *
+ * PKG-04 hide-during-drag is NOT implemented in this primitive — it is
+ * deferred to Phase 12 (Track D — AFF-01) via the `useAffordanceVisibility()`
+ * hook seam declared in `../hooks/useAffordanceVisibility.ts`. Phase 13 ships
+ * the seam with a `{ affordancesVisible: true }` stub; Phase 12 fills the
+ * gridChannels-driven implementation. Until then, glyphs remain visible
+ * during drag/resize — Phase 13's UAT scenarios for hide-during-drag verify
+ * the seam exists but cannot exercise the gate behaviour.
+ *
+ * @see .planning/phases/13-track-g-add-remove-collapse/13-CONTEXT.md §D-04, §D-06, §D-10, §D-18
  */
 export interface EmptyCellPackAffordanceProps {
-    /** D-19 — hide when all cells to the right are also empty. Consumer decides. */
+    /** D-19 gate for × glyph only. + is always visible regardless. */
     enabled: boolean;
-    onPack: () => void;
-    ariaLabel?: string;
+    /** D-04 — × click handler. Renamed from onPack for D-04 / UI-SPEC alignment. */
+    onCollapse?: () => void;
+    /** D-04 — + click handler. Always-visible glyph; clicking opens catalog. */
+    onAdd?: () => void;
+    /** Default: 'Add card to this cell' */
+    addGlyphLabel?: string;
+    /** Default: 'Pack row — shift cards left' */
+    collapseGlyphLabel?: string;
     className?: string;
     style?: React.CSSProperties;
+    /** @deprecated Use onCollapse. Maintained for one minor cycle. */
+    onPack?: () => void;
+    /** @deprecated Use collapseGlyphLabel. Maintained for one minor cycle. */
+    ariaLabel?: string;
 }
-export declare function EmptyCellPackAffordance({ enabled, onPack, ariaLabel, className, style, }: EmptyCellPackAffordanceProps): import("react/jsx-runtime").JSX.Element;
+export declare function EmptyCellPackAffordance({ enabled, onCollapse, onAdd, addGlyphLabel, collapseGlyphLabel, className, style, onPack, ariaLabel, }: EmptyCellPackAffordanceProps): import("react/jsx-runtime").JSX.Element;

package/lib/primitives/dashboard/GestureState/GestureStateProvider.d.ts

@@ -0,0 +1,49 @@
+import { LifecycleState } from '../gridChannels';
+import * as React from 'react';
+/**
+ * Discriminator for the in-flight gesture (D-03).
+ * `null` when no gesture is active.
+ */
+export type GestureType = 'drag' | 'resize' | null;
+/**
+ * Read-only snapshot of the grid's gesture lifecycle, exposed to primitives that
+ * must short-circuit BEHAVIOR (not just visuals) during drag or resize (D-03).
+ *
+ * Per D-02, `isActive` is true iff `lifecycle ∈ ['active', 'settling']`.
+ * `arming` does NOT count as active — keeping affordances visible during arming
+ * avoids flicker on cancelled gestures.
+ */
+export interface GestureState {
+    /** True when a gesture is in `active` or `settling` lifecycle (D-02). */
+    isActive: boolean;
+    /** Which gesture is in flight, or `null` when idle. */
+    type: GestureType;
+    /** Discrete lifecycle state from Phase 9 `gridChannels.LifecycleState`. */
+    lifecycle: LifecycleState;
+}
+export interface GestureStateProviderProps {
+    value: GestureState;
+    children: React.ReactNode;
+}
+/**
+ * Context provider for grid gesture lifecycle (D-03 hybrid pattern, gloss half).
+ *
+ * Mounted once in the grid root (reptime `MetricCardGrid.tsx` for v3.1).
+ * Wraps children with no DOM element of its own — preserves the
+ * `display: contents` chain at MetricCardGrid.tsx:2740.
+ */
+export declare function GestureStateProvider({ value, children }: GestureStateProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Read the active gesture lifecycle from the grid root.
+ *
+ * Returns `{ isActive: false, type: null, lifecycle: 'idle' }` when no provider
+ * is mounted (graceful default — primitives outside a grid still render normally).
+ *
+ * **Cross-phase contract (Phase 12 D-03 — DO NOT collapse to a single boolean):**
+ * - Phase 13 PKG-04 consumes `type === 'drag'` to no-op `+`/`×` click handlers.
+ * - The richer shape `{ isActive, type, lifecycle }` future-proofs downstream
+ *   consumers that need lifecycle granularity (e.g., distinguishing 'settling').
+ *
+ * @see .planning/phases/12-track-de-affordance-section-nav/12-CONTEXT.md D-03
+ */
+export declare function useGestureState(): GestureState;

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

@@ -0,0 +1 @@
+export * from './GestureStateProvider';

package/lib/primitives/dashboard/hooks/useAffordanceVisibility.d.ts

@@ -0,0 +1,28 @@
+/**
+ * useAffordanceVisibility — Phase 13 D-10 / D-18 contract section 3.
+ *
+ * Returns the visibility flag for empty-cell affordance glyphs (+ and ×) during
+ * drag/resize gestures (PKG-04 hide-on-active rule).
+ *
+ * **Phase 13 ships a stub** that returns `{ affordancesVisible: true }` unconditionally.
+ * **Phase 12 fills the real implementation** when its affordance state machine ships
+ * (Track D — AFF-01). The contract Phase 12 must honor:
+ *
+ * - Read gridChannels lifecycle state for the `chrome` channel.
+ * - Return `{ affordancesVisible: true }` when LifecycleState ∈ ['idle', 'arming']
+ *   (matches `gridChannels.chrome.applicableStates`).
+ * - Return `{ affordancesVisible: false }` when LifecycleState === 'active' or 'settling'
+ *   (matches `gridChannels.hideOnActive.applicableStates`).
+ *
+ * The DropAnchorCell `state='empty'` dashed border is NOT gated by this hook —
+ * the border persists during drag/resize because it IS the drop-target affordance
+ * (D-07 critical invariant).
+ *
+ * @see .planning/phases/13-track-g-add-remove-collapse/13-CONTEXT.md §D-10, §D-18
+ * @see .planning/phases/09-track-a-gev-foundation/HANDOFF.json#contracts.channels (chrome, hideOnActive)
+ */
+export interface UseAffordanceVisibilityReturn {
+    /** true when affordance glyphs (+ and ×) should render; false during drag/resize. */
+    affordancesVisible: boolean;
+}
+export declare function useAffordanceVisibility(): UseAffordanceVisibilityReturn;

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

@@ -13,10 +13,12 @@ export * from './TabbedDataView';
 export * from './MetricGroupContainer';
 export * from './DevTuningPanel';
 export * from './ResizeEnvelope';
+export * from './GestureState';
 export * from './DropAnchorCell';
 export * from './SpilloverArc';
 export * from './SectionDivider';
 export * from './EmptyCellPackAffordance';
+export * from './hooks/useAffordanceVisibility';
 export * from './DragGhost';
 export * from './SnapOutline';
 export * from './CascadePreview';

package/package.json

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