@mt-gloss/ui 0.1.7 → 0.1.9

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

@@ -4,11 +4,28 @@
  * Renders `count` buttons inside a `role="tablist"`. Click dispatches
  * `onSelect(index)`. Keyboard ← → loop forward/backward with wrap semantics
  * (D-25). Hollow default, filled for the current section.
+ *
+ * Phase 4 — drag-to-edge-auto-advance — additive extension per D-09/D-10/D-11:
+ * - `provisionalIndex` marks an unconfirmed section with hollow-stroke dot
+ *   (`data-state='provisional-hollow'`) and `aria-label='Unconfirmed section'`.
+ * - `pulseIndex` triggers the refuse-pulse animation (`data-state='pulse'`).
+ * - `pulseNonce` is composited into the React `key` for the pulsed index so a
+ *   nonce bump forces a re-mount — which restarts the CSS keyframe animation
+ *   even if the same index is pulsed twice in a row.
+ *
+ * All new props are optional; omitting them preserves the Phase 23 two-state
+ * `data-state='current'|'hollow'` render exactly (parity contract).
  */
 export interface SectionDotsProps {
     count: number;
     currentIndex: number;
     onSelect: (index: number) => void;
     'aria-label'?: string;
+    /** Phase 4 D-09 — index of the unconfirmed ("provisional") section, if any. */
+    provisionalIndex?: number;
+    /** Phase 4 D-09 — index of the dot currently playing the refuse pulse, if any. */
+    pulseIndex?: number;
+    /** Phase 4 D-10 — monotonically-increasing nonce; bump to replay the pulse keyframe. */
+    pulseNonce?: number;
 }
-export declare function SectionDots({ count, currentIndex, onSelect, 'aria-label': ariaLabel, }: SectionDotsProps): import("react/jsx-runtime").JSX.Element;
+export declare function SectionDots({ count, currentIndex, onSelect, 'aria-label': ariaLabel, provisionalIndex, pulseIndex, pulseNonce, }: SectionDotsProps): import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,55 @@
+import { MotionValue } from 'framer-motion';
+import * as React from 'react';
+/**
+ * Per-card MotionValue pair carried alongside its cardId. Consumers (Plan 05
+ * integration) derive this from `useDragFeedback.cascadePreview.motionValues`
+ * via `Array.from(motionValues.entries(), ([cardId, { x, y }]) => ({ cardId, x, y }))`.
+ *
+ * **Scalar x/y (NOT a tuple MV)** — framer-motion's `style.x` and `style.y`
+ * consume scalar MotionValue<number>. Matches the per-card per-axis precedent
+ * in `useEdgeHoverResize.ts:495-547` (ghostWidth + spring-back-on-cancel).
+ */
+export interface CascadePreviewItem {
+    cardId: string;
+    x: MotionValue<number>;
+    y: MotionValue<number>;
+}
+export interface CascadePreviewProps {
+    items: CascadePreviewItem[];
+    /** Render-prop children — called once per item. Consumer owns the per-card
+     *  display (typically a clone of the displaced source card). */
+    children: (item: CascadePreviewItem) => React.ReactNode;
+    className?: string;
+}
+/**
+ * Phase 3 DRAG-07/08/09 — per-card cascade-preview render primitive.
+ *
+ * Renders N `<motion.div>` siblings keyed by `item.cardId` (DRAG-09 stable
+ * keys — same cardId across re-renders retains the same DOM node so the
+ * consumer's MotionValue drives transform without a remount).
+ *
+ * Each child:
+ *   - `key={item.cardId}` — React reconciliation stability (DRAG-09)
+ *   - `data-card-id={item.cardId}` — test hook + attribute-selector targeting
+ *   - `style.x = item.x`, `style.y = item.y` — framer-motion reads MVs directly
+ *   - `aria-hidden="true"` — displaced cards are visually cloned during preview;
+ *     the semantic source card retains focus/aria surface
+ *   - `pointer-events: none` + `will-change: transform` via SCSS
+ *
+ * Returns `null` when `items.length === 0` so the consumer does not render an
+ * empty fragment wrapper.
+ *
+ * **MotionValue ownership**: CascadePreview does NOT instantiate MotionValues.
+ * The consumer (Plan 05 inside MetricCardGrid) owns the per-instance
+ * `useRef<Map<cardId, {x, y}>>` reconciliation (see useDragFeedback.ts
+ * `reconcileMotionValues`). Module-scope MVs would cross-contaminate between
+ * grid instances; this primitive is purely presentational. See
+ * `useRubberBandGhost.ts:57-61` precedent.
+ *
+ * **Rendering-layer invariants**:
+ *   - Rendered inside the grid container (NOT inside `<DragOverlay>`); DragOverlay
+ *     hosts the DragGhost only.
+ *   - Consumer places this inside a `position: relative` parent so `position:
+ *     absolute` items stack correctly.
+ */
+export declare function CascadePreview({ items, children, className, }: CascadePreviewProps): JSX.Element | null;

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

@@ -0,0 +1,2 @@
+export { CascadePreview } from './CascadePreview';
+export type { CascadePreviewProps, CascadePreviewItem } from './CascadePreview';

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

@@ -0,0 +1,35 @@
+import { MotionValue } from 'framer-motion';
+import * as React from 'react';
+export interface DragGhostProps {
+    /** 'ok' = blue dashed (--gloss-valid-stroke/fill); 'rejected' = pink solid (--gloss-rejection-stroke/fill) */
+    tint: 'ok' | 'rejected';
+    colSpan: 1 | 2 | 3;
+    colWidth: number;
+    rowHeight: number;
+    gap: number;
+    /** From parent useSpring(cursorMV, cascadePhysics.spring) — produces the 60ms ease-out lag */
+    x: MotionValue<number>;
+    y: MotionValue<number>;
+    /** Dragged card render (passed from consumer) */
+    children?: React.ReactNode;
+    className?: string;
+}
+/**
+ * Phase 3 DRAG-01/02 — presentational ghost card rendered inside dnd-kit `<DragOverlay>`.
+ *
+ * Spring-driven x/y MotionValue props produce the 60ms ease-out cursor lag
+ * (per Phase 0 `cascadePhysics.spring` {stiffness:380, damping:32}).
+ *
+ * `data-tint` flips between 'ok' (dashed blue) and 'rejected' (solid pink) based on
+ * `predictCascade()` result emitted by `useDragFeedback.ghost.tint`. Reduced-motion
+ * CSS override strips the 1.02 scale + elevated shadow + transitions.
+ *
+ * **Consumer invariants (Plan 04 MUST honor — from Plan 00 spike + Plan 01 JSDoc):**
+ *  1. Render inside `<DragOverlay dropAnimation={null}>`
+ *  2. `x` / `y` are per-instance `useRef<MotionValue<number>>` (NEVER module-scope)
+ *  3. Parent wraps raw cursor MotionValues via `useSpring(cursor, cascadePhysics.spring)`
+ *     — DragGhost itself is purely presentational and never instantiates springs.
+ *
+ * `aria-hidden="true"` because the dragged card semantics belong to the source, not the ghost.
+ */
+export declare function DragGhost({ tint, colSpan, colWidth, rowHeight, gap, x, y, children, className, }: DragGhostProps): JSX.Element;

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

@@ -0,0 +1,2 @@
+export { DragGhost } from './DragGhost';
+export type { DragGhostProps } from './DragGhost';

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

@@ -6,6 +6,14 @@ export interface DropAnchorCellProps extends React.HTMLAttributes<HTMLDivElement
     canAccept: boolean;
     /** Brief not-allowed pulse when user attempts drop on occupied. */
     blocked?: boolean;
+    /**
+     * DRAG-05 — cursor-driven continuous opacity. When provided, the cell
+     * renders with `data-proximity-driven='true'` and an inline CSS var
+     * `--_proximity-opacity: {value}` that overrides the discrete `data-density`
+     * bucket opacity. Phase 23 callers that only pass `density` + `canAccept`
+     * see zero behavior change. `canAccept='false'` still suppresses opacity.
+     */
+    proximityOpacity?: number;
     /** Stable cell id for test selectors + future instrumentation. */
     ['data-cell-id']?: string;
     children?: React.ReactNode;
@@ -26,4 +34,4 @@ export interface DropAnchorCellProps extends React.HTMLAttributes<HTMLDivElement
  *
  * Respects prefers-reduced-motion.
  */
-export declare function DropAnchorCell({ density, canAccept, blocked, className, children, ...rest }: DropAnchorCellProps): import("react/jsx-runtime").JSX.Element;
+export declare function DropAnchorCell({ density, canAccept, blocked, proximityOpacity, className, children, ...rest }: DropAnchorCellProps): import("react/jsx-runtime").JSX.Element;

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

@@ -1,5 +1,5 @@
 import * as React from 'react';
-export type SectionDividerState = 'hidden' | 'revealed' | 'emphasized';
+export type SectionDividerState = 'hidden' | 'revealed' | 'emphasized' | 'provisional';
 export interface SectionDividerProps extends React.HTMLAttributes<HTMLDivElement> {
     state: SectionDividerState;
     /** Left-to-right cascade position (0, 1, 2, ...) multiplied by staggerMs for animation-delay. */

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

@@ -0,0 +1,39 @@
+export interface SnapOutlineProps {
+    cell: {
+        section: 0 | 1 | 2 | 3;
+        col: 0 | 1 | 2;
+        row: 0 | 1 | 2;
+    };
+    colSpan: 1 | 2 | 3;
+    rowSpan: 1;
+    colWidth: number;
+    gap: number;
+    rowHeight: number;
+    /** DRAG-06 default 120ms cubic-bezier(0.4, 0, 0.2, 1) on transform. */
+    transitionMs?: number;
+    className?: string;
+}
+/**
+ * Phase 3 DRAG-06 — single 2px snap outline, 120ms cubic-bezier transition on transform.
+ *
+ * Renders a `position: absolute` 2px solid border rectangle, translated to the
+ * target cell via `translate({left}px, {top}px)` where:
+ *   - `left = cell.col * (colWidth + gap)`
+ *   - `top  = cell.row * (rowHeight + gap)`
+ *   - `width  = colSpan * colWidth + (colSpan - 1) * gap`
+ *   - `height = rowHeight`
+ *
+ * Transitions the transform at `${transitionMs ?? 120}ms cubic-bezier(0.4, 0, 0.2, 1)`.
+ * Under `prefers-reduced-motion: reduce`, `transition: none !important` strips
+ * the slide (SCSS-level override; see snap-outline.scss).
+ *
+ * Rendering-layer invariants (Plan 05 MUST honor):
+ *  - `position: absolute` consumer — parent is the grid container with `position: relative`.
+ *  - `pointer-events: none` (aria-hidden); does NOT intercept drag events.
+ *  - 2px solid border using `var(--gloss-valid-stroke)` (Phase 0 color token).
+ *  - Rendered INSIDE the grid container, NOT inside `<DragOverlay>`; DragOverlay
+ *    hosts the DragGhost only (see Plan 02). The `dropAnimation={null}` invariant
+ *    on DragOverlay (Plan 00 spike + Plan 01 header) does not apply here — SnapOutline
+ *    is not a DragOverlay child.
+ */
+export declare function SnapOutline({ cell, colSpan, colWidth, gap, rowHeight, transitionMs, className, }: SnapOutlineProps): JSX.Element;

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

@@ -0,0 +1,2 @@
+export { SnapOutline } from './SnapOutline';
+export type { SnapOutlineProps } from './SnapOutline';

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

@@ -17,4 +17,7 @@ export * from './DropAnchorCell';
 export * from './SpilloverArc';
 export * from './SectionDivider';
 export * from './EmptyCellPackAffordance';
+export * from './DragGhost';
+export * from './SnapOutline';
+export * from './CascadePreview';
 export * from './gridMotionPrimitives';

package/package.json

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