@mt-gloss/ui 0.1.6 → 0.1.8

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/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/gridMotionPrimitives.d.ts

@@ -0,0 +1,82 @@
+/**
+ * gridMotionPrimitives — Grid v2 shared motion vocabulary (Phase 0).
+ *
+ * Single source of truth for all timing, easing, color-token-name, and feedback
+ * constants consumed by Phases 1–5 (Grid Foundation, Cascade, Drag Feedback,
+ * Drag-to-Edge Auto-Advance, Resize + [×]). Zero behavior — framework-agnostic,
+ * no React, no Framer Motion, no hooks. Consumers import plain constants +
+ * `getMotionMode()` and decide how to apply them.
+ *
+ * Requirement mapping:
+ *   MOTION-01 (no fade-from-nowhere) — documented principle; enforced in review
+ *   MOTION-02 — cascadePhysics
+ *   MOTION-03 — swingReveal
+ *   MOTION-04 — colorTokens.rejection*, colorTokens.valid*, colorTokens.validCellStroke
+ *   MOTION-05 — rejectionFeedback
+ *   MOTION-06 — provisional, colorTokens.provisionalWash
+ *   MOTION-07 — HARD_CLIP
+ *   MOTION-08 — this file is the lone source; no inline timing/hex/easing in
+ *               consuming component code (grep-enforced in each consumer phase)
+ *   MOTION-09 — reducedMotion, getMotionMode()
+ *
+ * Structural precedent: libs/gloss-ui/src/lib/primitives/overlays/ActionStrip/motion.ts
+ */
+/** MOTION-02 — Forward (digest) and reverse (undo) cascade physics. Asymmetric by design. */
+export declare const cascadePhysics: {
+    readonly forwardStaggerMs: 50;
+    readonly reverseStaggerMs: 30;
+    readonly springStiffness: 380;
+    readonly springDamping: 32;
+    readonly reverseVelocityMultiplier: 1.4;
+};
+/** MOTION-03 — Swing-from-behind reveal (resize handle, [×] affordance, future hover-intent micro-affordances). */
+export declare const swingReveal: {
+    readonly enterDurationMs: 220;
+    readonly exitDurationMs: 140;
+    readonly enterEasing: "cubic-bezier(0.34, 1.56, 0.64, 1)";
+    readonly exitEasing: "cubic-bezier(0.4, 0, 1, 1)";
+    readonly translateOffsetPx: 4;
+};
+/** MOTION-05 — Rejection kinesthetic: ghost shiver on invalid drop. */
+export declare const rejectionFeedback: {
+    readonly shiverCycles: 3;
+    readonly shiverAmplitudePx: 2;
+    readonly shiverDurationMs: 180;
+    readonly validCellOpacity: 0.6;
+};
+/** MOTION-06 — Provisional section/dot materialize + dematerialize. */
+export declare const provisional: {
+    readonly materializeMs: 180;
+    readonly dematerializeMs: 140;
+    readonly easing: "cubic-bezier(0.22, 1, 0.36, 1)";
+    readonly dotStrokePx: 2;
+    readonly dividerDashGapPx: 4;
+};
+/** MOTION-09 — Substitution values when prefers-reduced-motion: reduce is active. */
+export declare const reducedMotion: {
+    readonly cascadeStaggerMs: 0;
+    readonly cascadeSpringCapMs: 120;
+    readonly swingEnterMs: 100;
+    readonly swingEnterStyle: "opacity";
+    readonly provisionalMs: 80;
+    readonly provisionalStyle: "opacity";
+    readonly shiverMs: 200;
+    readonly shiverStyle: "color-flash";
+};
+/**
+ * MOTION-07 — Hard-clip marker. True = when fixed neighbor grows over a card,
+ * cards clip at advancing edge (no fade). Downstream phases must reference this
+ * constant as the canonical source for the hard-clip rule.
+ */
+export declare const HARD_CLIP: true;
+/** MOTION-04, MOTION-06 — CSS custom property NAMES (not literals). Consumers use var(...). */
+export declare const colorTokens: {
+    readonly rejectionFill: "var(--gloss-rejection-fill)";
+    readonly rejectionStroke: "var(--gloss-rejection-stroke)";
+    readonly validFill: "var(--gloss-valid-fill)";
+    readonly validStroke: "var(--gloss-valid-stroke)";
+    readonly validCellStroke: "var(--gloss-valid-cell-stroke)";
+    readonly provisionalWash: "var(--gloss-provisional-wash)";
+};
+/** MOTION-09 — Motion mode resolver. Pure; SSR-safe; returns 'full' when window is undefined. */
+export declare function getMotionMode(): 'full' | 'reduced';

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

@@ -17,3 +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.6",
+  "version": "0.1.8",
   "type": "module",
   "publishConfig": {
     "access": "restricted"