@mt-gloss/ui 0.0.22 → 0.0.24

package/lib/facade/data-display.d.ts

@@ -10,11 +10,11 @@ export { CardShell } from '../primitives/dashboard/MetricCard';
 export { TrendIndicator } from '../primitives/dashboard/MetricCard';
 export { StackedGroupCard } from '../primitives/dashboard/MetricCard';
 export { CardBack } from '../primitives/dashboard/MetricCard';
-export { GutterActions } from '../primitives/dashboard/MetricCard';
 export type { MetricCardProps, CardShellProps } from '../primitives/dashboard/MetricCard/types';
 export type { StackedGroupCardProps, StackedValueEntry } from '../primitives/dashboard/MetricCard/StackedGroupCard';
 export type { CardBackProps } from '../primitives/dashboard/MetricCard/CardBack';
-export type { GutterActionsProps } from '../primitives/dashboard/MetricCard/GutterActions';
+export { ActionStrip, buildDefaultOverflow } from '../primitives/overlays/ActionStrip';
+export type { ActionStripProps, PrimaryAction, OverflowAction, ActionStripContext, ActionStripMenuDirection, DefaultHandlers, } from '../primitives/overlays/ActionStrip';
 export { SparklineBg } from '../primitives/dashboard/MetricCard';
 export { BarsBg } from '../primitives/dashboard/MetricCard';
 export { DonutChart } from '../primitives/dashboard/MetricCard';

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

@@ -17,6 +17,6 @@ import { CardShellProps } from './types';
  * ```
  */
 export declare const CardShell: {
-    ({ contentSlot, children, colSpan, isStale, isRetrying, beta, disabled, style, accentRing, onGraph, onDetails, onCustomize, onRemove, onWhatsThis, onExpand, onShrink, onMove, onReplace, onNavigate, onRetry, onRefresh, enableQuickSettings, onUpdateTimeframe, instanceTimeframe, cardTitle, quickConfigSlot, onViewAsStack, onUnstack, isStackedGroup, onUpdateStackedTimeframes, instanceStackedTimeframes, isGraphActive, isTableActive, isGraphCard, canExpand, anchorX, cardRef: externalCardRef, }: CardShellProps): import("react/jsx-runtime").JSX.Element;
+    ({ contentSlot, children, colSpan, isStale, isRetrying, beta, disabled, style, accentRing, onGraph, onDetails, onCustomize, onRemove, onWhatsThis, onExpand, onShrink, onMove, onReplace, onNavigate, onRetry, onRefresh, enableQuickSettings, onUpdateTimeframe, instanceTimeframe, cardTitle, quickConfigSlot, onViewAsStack, onUnstack, isStackedGroup, onUpdateStackedTimeframes, instanceStackedTimeframes, isGraphActive, isTableActive, isGraphCard, canExpand, anchorX, extensionOverflow, cardRef: externalCardRef, }: CardShellProps): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };

package/lib/primitives/dashboard/MetricCard/flipAndStage/types.d.ts

@@ -36,6 +36,13 @@ export interface FlipAndStageInternalState {
     activeCardId: string | null;
     activeDimensionId: string | null;
     dirtyState: Record<string, unknown>;
+    /**
+     * Phase 17: which dimension section the overlay should render.
+     * `null` means no section is open. Independent of `state` — the overlay
+     * is only shown after an explicit setOpenSection() call; `cancelConfig()`
+     * and `commitConfig()` MUST null this out (per 17-UI-SPEC §Sequencing).
+     */
+    openSection: string | null;
 }
 /**
  * The full value exposed by useFlipAndStage and FlipAndStageContext.
@@ -48,6 +55,8 @@ export interface FlipAndStageInternalState {
  * - `commitConfig` — persist edits and return to idle; optional patch merged into dirty
  * - `cancelConfig` — discard edits and return to idle
  * - `setDirty` — merge additional edits into dirtyState
+ * - `openSection` — (Phase 17) which dimension section the overlay should render
+ * - `setOpenSection` — (Phase 17) mutate openSection; cancel/commit auto-null it
  */
 export interface FlipAndStageValue {
     activeCardId: string | null;
@@ -70,6 +79,17 @@ export interface FlipAndStageValue {
     cancelConfig: () => void;
     /** Merge additional dirty fields. Successive calls accumulate (not replace). */
     setDirty: (patch: Record<string, unknown>) => void;
+    /**
+     * Phase 17: which dimension section the overlay should render.
+     * `null` = no section open. Independent of `state` — the overlay is only
+     * rendered once a consumer explicitly calls `setOpenSection(id)`.
+     */
+    openSection: string | null;
+    /**
+     * Phase 17: mutate openSection. `cancelConfig()` and `commitConfig()` MUST
+     * null this out as part of their state reset (per 17-UI-SPEC §Sequencing).
+     */
+    setOpenSection: (id: string | null) => void;
 }
 /**
  * Options for useFlipAndStage.

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

@@ -2,7 +2,6 @@ export { MetricCard } from './MetricCard';
 export { CardShell } from './CardShell';
 export { CardBack } from './CardBack';
 export { TrendIndicator } from './TrendIndicator';
-export { GutterActions } from './GutterActions';
 export { StackedGroupCard } from './StackedGroupCard';
 export { StatusModeCard } from './StatusModeCard';
 export { StatusSlotChipMenu } from './StatusSlotChipMenu';
@@ -14,7 +13,6 @@ export { useEdgeHoverResize } from './useEdgeHoverResize';
 export * from './flipAndStage';
 export * from './types';
 export type { CardBackProps } from './CardBack';
-export type { GutterActionsProps } from './GutterActions';
 export type { StackedGroupCardProps, StackedValueEntry } from './StackedGroupCard';
 export type { SlideOutRevealConfig, SlideOutRevealReturn } from './useSlideOutReveal';
 export type { ResizeState, ResizeDirection, ResizeMode, ResizeCommit, UseEdgeHoverResizeArgs, UseEdgeHoverResizeReturn, } from './useEdgeHoverResize';

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

@@ -1,25 +1 @@
-/**
- * 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;
+export * from '../../overlays/ActionStrip/overflowMenuRegistry';

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

@@ -178,15 +178,29 @@ export interface CardShellProps {
     isGraphCard?: boolean;
     canExpand?: boolean;
     /**
-     * Horizontal anchor (px from card's left edge) forwarded to GutterActions.
+     * Horizontal anchor (px from card's left edge) forwarded to ActionStrip.
      *
-     * When provided, overrides GutterActions' default `left: 50%` centered pill
+     * When provided, overrides ActionStrip's default `left: 50%` centered pill
      * position. Drives the per-slot gutter-slide choreography for stack cards
      * (Cluster W quick-260417-d5z item 3 / gutter hover slide). Undefined
      * preserves the pre-existing centered layout.
      *
-     * @see GutterActionsProps.anchorX
+     * @see ActionStripProps.anchorX
      */
     anchorX?: number;
+    /**
+     * Consumer-supplied overflow menu entries that CardShell concatenates into
+     * the ActionStrip `overflow` prop after the default set (settings / remove
+     * / replace / refresh) and before the footer `whats-this`.
+     *
+     * Per D-04 (variant ownership), gloss primitives stay reptime-agnostic:
+     * extensions like Move / Customize are constructed at the reptime
+     * consumer and passed in via this prop (usually sourced from
+     * `CARD_MENU_EXTENSIONS.getExtensions(cardType, baseOrder)` per AP-09).
+     *
+     * Phase 16 plan 16-06 Task 3 adds this prop; reptime adopts it for
+     * cardType-specific Move / Customize opt-in.
+     */
+    extensionOverflow?: import('../../overlays/ActionStrip').OverflowAction[];
     cardRef?: RefObject<HTMLDivElement | null>;
 }

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

@@ -1,42 +1 @@
-type SlideDirection = 'down' | 'left';
-type AnimationPhase = 'hidden' | 'entering-behind' | 'entering-front' | 'visible' | 'exiting-front' | 'exiting-behind';
-export interface SlideOutRevealConfig {
-    slideDirection?: SlideDirection;
-    behindDuration?: number;
-    frontDuration?: number;
-    easing?: string;
-    behindEasing?: string;
-    zBehind?: number;
-    zFront?: number;
-}
-export interface SlideOutRevealStyle {
-    transform: string;
-    zIndex: number;
-    transition: string;
-    pointerEvents: 'auto' | 'none';
-}
-export interface SlideOutRevealReturn {
-    phase: AnimationPhase;
-    handleTransitionEnd: () => void;
-    style: SlideOutRevealStyle;
-}
-/**
- * useSlideOutReveal -- 6-state slide-out animation hook.
- *
- * Two-phase reveal: element slides from behind a parent surface (z-index behind),
- * then once it emerges, z-index switches to front and it settles at resting position.
- * Exit is the reverse sequence.
- *
- * @example
- * ```ts
- * import { useSlideOutReveal } from '@mt-gloss/ui';
- *
- * const { phase, handleTransitionEnd, style } = useSlideOutReveal(isVisible, {
- *   slideDirection: 'down',
- *   zBehind: 1,
- *   zFront: 16,
- * });
- * ```
- */
-export declare function useSlideOutReveal(visible: boolean, config?: SlideOutRevealConfig): SlideOutRevealReturn;
-export {};
+export * from '../../overlays/ActionStrip/useSlideOutReveal';

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

@@ -0,0 +1,13 @@
+import { default as React } from 'react';
+import { ReconfigBacksideButtonsProps, ReconfigDimension } from './types';
+/**
+ * Verbatim button labels per 17-UI-SPEC §Copywriting Contract.
+ * Exported as a const to make future localization extraction a single edit.
+ */
+declare const LABELS: Record<ReconfigDimension, string>;
+/**
+ * ReconfigBacksideButtons — renders the type-picker button strip on a
+ * metric-card backside. See module doc for parent wiring contract.
+ */
+export declare const ReconfigBacksideButtons: React.FC<ReconfigBacksideButtonsProps>;
+export { LABELS as RECONFIG_BACKSIDE_LABELS };

package/lib/primitives/dashboard/ReconfigBacksideButtons/__tests__/fixtures/nyquist-10-matrix.d.ts

@@ -0,0 +1,19 @@
+import { ReconfigDimension } from '../../types';
+export type Nyquist10Archetype = 'standard' | 'stacked-group' | 'order-status-stack';
+export interface Nyquist10MatrixRow {
+    /** cardType the matrix row describes. */
+    cardType: Nyquist10Archetype;
+    /** Dimension under test (the backside button to click). */
+    dimension: ReconfigDimension;
+    /** All dimensions expected on the backside for this cardType. */
+    expectedBacksideDimensions: ReadonlyArray<ReconfigDimension>;
+    /** data-section-id that MUST be the sole rendered section post-click. */
+    expectedOverlaySectionId: string;
+}
+export declare const NYQUIST_10_MATRIX: ReadonlyArray<Nyquist10MatrixRow>;
+/** Row count pin consumed by the contract runner. */
+export declare const NYQUIST_10_ROW_COUNT: number;
+/** The 3 archetypes enumerated (stable order, useful for grouped describes). */
+export declare const NYQUIST_10_ARCHETYPES: ReadonlyArray<Nyquist10Archetype>;
+/** Matrix lookup — parity check against reptime's CARD_TYPE_DIMENSION_MATRIX. */
+export declare const NYQUIST_10_DIMENSIONS_BY_CARD_TYPE: Readonly<Record<Nyquist10Archetype, ReadonlyArray<ReconfigDimension>>>;

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

@@ -0,0 +1,5 @@
+/**
+ * Phase 17, Plan 01 — ReconfigBacksideButtons barrel.
+ */
+export { ReconfigBacksideButtons, RECONFIG_BACKSIDE_LABELS } from './ReconfigBacksideButtons';
+export type { ReconfigBacksideButtonsProps, ReconfigDimension } from './types';

package/lib/primitives/dashboard/ReconfigBacksideButtons/types.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Phase 17, Plan 01: ReconfigBacksideButtons primitive — public type contracts.
+ *
+ * Renders the card-back type-picker strip (one button per configurable
+ * dimension). Buttons only — NO dropdowns, NO popovers. See 17-UI-SPEC
+ * §Backside type-picker button labels for the full spec.
+ *
+ * @module primitives/dashboard/ReconfigBacksideButtons/types
+ */
+/**
+ * The six configurable dimensions exposable on any metric card backside.
+ * Per-card-type matrix lives downstream in reptime (`CARD_TYPE_DIMENSION_MATRIX`).
+ */
+export type ReconfigDimension = 'timeframe' | 'threshold' | 'slots' | 'size' | 'color' | 'pinned';
+/**
+ * Public props for ReconfigBacksideButtons.
+ *
+ * Minimal by design — no optional prop beyond these four. Parent wires
+ * onDimensionSelect to `flipAndStage.setOpenSection(dim)` + `flipToFace()`.
+ */
+export interface ReconfigBacksideButtonsProps {
+    /**
+     * Dimensions to render (order is preserved; empty array → component
+     * returns null — parent should avoid rendering at all for excluded types).
+     */
+    dimensions: ReadonlyArray<ReconfigDimension>;
+    /**
+     * Fired on button click. Parent wires:
+     *   flipAndStage.setOpenSection(dimension)
+     *   flipAndStage.flipToFace()
+     * in that order.
+     */
+    onDimensionSelect: (dimension: ReconfigDimension) => void;
+    /**
+     * Highlights the active dimension with aria-current="true" + persisted
+     * hover tint. Used when re-entering the backside with a previously-
+     * launched overlay still in memory.
+     */
+    activeDimension?: ReconfigDimension | null;
+    /**
+     * Screen-reader label substitution — rendered as
+     * `aria-label="Configure {ariaCardTypeLabel}: choose a dimension"` on root.
+     */
+    ariaCardTypeLabel?: string;
+    /** Optional consumer-provided class appended to the BEM root class. */
+    className?: string;
+}

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

@@ -7,6 +7,7 @@ export * from './UnifiedBreakdownTable';
 export * from './ChartControlBar';
 export * from './UnifiedContextMenu';
 export * from './TimeFrame';
+export * from './ReconfigBacksideButtons';
 export * from './MetricCardGrid';
 export * from './TabbedDataView';
 export * from './MetricGroupContainer';

package/lib/primitives/overlays/ActionStrip/ActionStrip.d.ts

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+import { ActionStripProps, OverflowAction } from './types';
+/**
+ * D5 pure-icon bypass predicate. When every overflow entry is promotable AND
+ * all promotable fit the expanded budget, expansion grows the strip + runs icon
+ * ingress ONLY — no border-radius morph, no vertical menu surface.
+ */
+export declare function isPureIconBypass(overflow: readonly OverflowAction[], expandedBudgetSlots: number): boolean;
+export declare const ActionStrip: React.FC<ActionStripProps>;

package/lib/primitives/overlays/ActionStrip/__tests__/fixtures/nyquist-09-parity-matrix.d.ts

@@ -0,0 +1,18 @@
+export type FlipDir = 'up' | 'down';
+export type Variant = 'default' | 'config';
+export interface ParityHarness {
+    row: ParityRow;
+}
+export interface ParityRow {
+    behaviorId: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+    behaviorLabel: string;
+    flip: FlipDir;
+    variant: Variant;
+    /** Skip reason (row still emits as `test.skip` so it is visible in vitest output). */
+    skip?: string;
+    /** Concrete assertion executed by `it.each` runner. */
+    assert: (harness: ParityHarness) => Promise<void> | void;
+}
+export declare const PARITY_MATRIX: ParityRow[];
+/** Row count = 9 × 2 × 2 = 36. Exposed for assertion convenience in the runner. */
+export declare const MATRIX_ROW_COUNT: number;

package/lib/primitives/overlays/ActionStrip/defaultActions.d.ts

@@ -0,0 +1,32 @@
+import { OverflowAction } from './types';
+/**
+ * The three promotable default overflow ids, in canonical order. Callsites
+ * that want to filter or extend the default set reference these ids directly.
+ *
+ * Note: `refresh` is part of the D4 catalog but NOT listed here because it is
+ * a context-specific action (only fires when a card has a refresh affordance).
+ * Consumers that need Refresh pass `onRefresh` — `buildDefaultOverflow` emits
+ * the entry when present. For registry-level "is this id part of the default
+ * set?" checks, include 'refresh' in the superset.
+ */
+export declare const DEFAULT_OVERFLOW_IDS: readonly ["settings", "remove", "replace"];
+/** The single non-promotable footer id. */
+export declare const DEFAULT_FOOTER_IDS: readonly ["whats-this"];
+/** Optional handlers for the default overflow set. Absent handlers omit entries. */
+export interface DefaultHandlers {
+    onSettings?: () => void;
+    onRemove?: () => void;
+    onReplace?: () => void;
+    onRefresh?: () => void;
+    onWhatsThis?: () => void;
+}
+/**
+ * Build the D4 default overflow set. Emits one entry per handler provided,
+ * preserving canonical order (`settings`, `remove`, `replace`, `refresh`,
+ * `whats-this`) and tagging `isPromotable: true` for everything except the
+ * footer `whats-this`.
+ *
+ * @param handlers - per-card handler map; absent handlers omit entries.
+ * @returns `OverflowAction[]` in canonical order, `order` monotonic from 0.
+ */
+export declare function buildDefaultOverflow(handlers: DefaultHandlers): OverflowAction[];

package/lib/primitives/overlays/ActionStrip/index.d.ts

@@ -0,0 +1,7 @@
+export { ActionStrip } from './ActionStrip';
+export type { PrimaryAction, OverflowAction, ActionStripProps, ActionStripContext, ActionStripMenuDirection, } from './types';
+export { subscribe, getActive, setActive, resetForTests, } from './overflowMenuRegistry';
+export { useSlideOutReveal } from './useSlideOutReveal';
+export type { SlideOutRevealConfig, SlideOutRevealReturn, SlideOutRevealStyle, } from './useSlideOutReveal';
+export { DEFAULT_OVERFLOW_IDS, DEFAULT_FOOTER_IDS, buildDefaultOverflow, } from './defaultActions';
+export type { DefaultHandlers } from './defaultActions';

package/lib/primitives/overlays/ActionStrip/motion.d.ts

@@ -0,0 +1,148 @@
+/**
+ * ActionStrip — Framer Motion choreography constants (Phase 16 plan 16-02).
+ *
+ * Every exported constant maps to an exact row in `.planning/phases/16-overflow-menu-reliability/16-UI-SPEC.md`
+ * §Motion & Choreography. If a test for the timing table ever fails, either:
+ *   1) UI-SPEC was updated and the constant below must change to match, OR
+ *   2) the constant was changed accidentally and must be reverted.
+ *
+ * These values are consumed by `ActionStrip.tsx`; they are exported so tests can
+ * assert against them directly (no fragile source-grep of inline numbers).
+ *
+ * NO automatic-height keyframes anywhere — AP guard enforced by Test 8 in
+ * `__tests__/choreography.test.tsx`. Use `scaleY` for menu open/close.
+ */
+export declare const TIMING: {
+    readonly STRIP_EXPAND_MS: 250;
+    readonly STRIP_COLLAPSE_MS: 180;
+    readonly ICON_INGRESS_MS: 150;
+    readonly ICON_STAGGER_MS: 50;
+    readonly ICON_EGRESS_MS: 120;
+    readonly MENU_OPEN_MS: 250;
+    readonly MENU_CLOSE_MS: 120;
+    readonly BORDER_RADIUS_MS: 200;
+    readonly ANCHOR_X_MS: 180;
+    readonly FEEDBACK_PRESS_MS: 100;
+    readonly FEEDBACK_CHECK_MS: 600;
+    readonly FLIP_COLLAPSE_MAX_WIDTH_MS: 250;
+    readonly FLIP_COLLAPSE_OPACITY_MS: 200;
+    readonly GRACE_CLOSE_MS: 300;
+    readonly REDUCED_MOTION_MS: 10;
+};
+/** Framer Motion spring physics (UI-SPEC row "Expand (click) — Strip width"). */
+export declare const SPRING: {
+    type: "spring";
+    stiffness: number;
+    damping: number;
+};
+/** UI-SPEC row "Reveal (hover) — front phase" and Expand — Icon ingress: cubic-bezier(0.22, 1, 0.36, 1). */
+export declare const EASE_OUT: readonly [0.22, 1, 0.36, 1];
+type FlipDirection = 'up' | 'down';
+/**
+ * Pill border-radius morph. UI-SPEC §Motion & Choreography row "Expand (click)
+ * — Border-radius" + §Up/Down Flip Mirror Contract (D7).
+ *
+ * Three named variants cover: collapsed (8px all-round), expanded-down (bottom
+ * corners flat, menu hangs below), expanded-up (top corners flat, menu sits
+ * above — mirror of expanded-down).
+ */
+export declare function buildPillVariants(reduced: boolean): {
+    collapsed: {
+        borderRadius: number;
+        transition: {
+            duration: number;
+            ease: "easeOut";
+        };
+    };
+    'expanded-down': {
+        borderRadius: string;
+        transition: {
+            duration: number;
+            ease: "easeOut";
+        };
+    };
+    'expanded-up': {
+        borderRadius: string;
+        transition: {
+            duration: number;
+            ease: "easeOut";
+        };
+    };
+};
+/**
+ * Vertical menu scaleY + opacity + y-offset. UI-SPEC §Motion rows "Expand —
+ * Menu drop" + "Collapse — Menu hide" + §Up/Down Flip Mirror "Menu entry
+ * y-translation".
+ *
+ * `custom` is the flip direction — `down` enters from y:-4, `up` from y:+4.
+ * Menu is asymmetric: open 250ms ease-out; close 120ms ease-in.
+ */
+export declare function buildMenuVariants(reduced: boolean): {
+    initial: (dir: FlipDirection) => {
+        opacity: number;
+        scaleY: number;
+        y: number;
+    };
+    animate: {
+        opacity: number;
+        scaleY: number;
+        y: number;
+        transition: {
+            duration: number;
+            ease: "easeOut";
+        };
+    };
+    exit: {
+        opacity: number;
+        scaleY: number;
+        transition: {
+            duration: number;
+            ease: "easeIn";
+        };
+    };
+};
+/**
+ * Promoted-icon ingress / egress. UI-SPEC §Motion rows "Expand — Icon ingress"
+ * + "Collapse — Icon egress". Stagger is owned by the parent container variant.
+ */
+export declare function buildIconVariants(reduced: boolean): {
+    initial: {
+        opacity: number;
+        scale: number;
+    };
+    animate: {
+        opacity: number;
+        scale: number;
+        transition: {
+            duration: number;
+            ease: "easeOut";
+        };
+    };
+    exit: {
+        opacity: number;
+        scale: number;
+        transition: {
+            duration: number;
+            ease: "easeIn";
+        };
+    };
+};
+/**
+ * Parent-container staggerChildren variants. UI-SPEC §Motion row "Expand —
+ * Icon ingress: 50ms stagger". Collapse has no stagger (asymmetric per D9).
+ */
+export declare function buildStripContainerVariants(reduced: boolean): {
+    collapsed: {
+        transition: {
+            staggerChildren: number;
+            staggerDirection: -1;
+        };
+    };
+    expanded: {
+        transition: {
+            staggerChildren: number;
+        };
+    };
+};
+export declare function transformOriginFor(dir: FlipDirection): 'top center' | 'bottom center';
+export {};

package/lib/primitives/overlays/ActionStrip/overflowMenuRegistry.d.ts

@@ -0,0 +1,30 @@
+/**
+ * overflowMenuRegistry — Module-scoped singleton tracker for ActionStrip overflow menus.
+ *
+ * MOVED from `primitives/dashboard/MetricCard/overflowMenuRegistry.ts` in Phase 16
+ * plan 16-01 alongside the GutterActions → ActionStrip rewrite. The legacy path
+ * re-exports from this module so existing consumers continue to compile during
+ * the multi-plan transition.
+ *
+ * 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/overlays/ActionStrip/types.d.ts

@@ -0,0 +1,115 @@
+import { ReactNode } from 'react';
+/**
+ * Runtime context forwarded to every action's `visibleWhen()` predicate.
+ *
+ * Known keys reflect today's call-site usage (error gating, card kind, column span,
+ * graph card affordance, expand capability). Unknown keys are permitted to keep the
+ * extension surface non-breaking as new card types add discriminators.
+ */
+export interface ActionStripContext {
+    /** True when the card is in a retry/error state — gates Retry vs Graph/Details mutex. */
+    isErrorState?: boolean;
+    /** Card subtype discriminator (e.g., 'trend', 'statusMode', 'stackedGroup'). */
+    cardType?: string;
+    /** Column span of the hosting card; some actions (Expand/Shrink) key on this. */
+    colSpan?: 1 | 2 | 3;
+    /** True when the host card has a graph affordance (enables Expand in menu). */
+    isGraphCard?: boolean;
+    /** True when the host card is currently expandable (card-level capability gate). */
+    canExpand?: boolean;
+    /** Extension point for future visibleWhen predicates — additions are non-breaking. */
+    [key: string]: unknown;
+}
+/**
+ * Pinned strip button. Always present in the collapsed pill when `visibleWhen` passes.
+ *
+ * Supports feedback animation (pressed → Check flash) and active-state color
+ * inversion (`isActive` + `activeColor` + `activeIcon`). Preserved behaviors #6/#7
+ * from D3 of the rewrite decisions.
+ */
+export interface PrimaryAction {
+    /** Stable identifier for test hooks + layoutId assignment. */
+    id: string;
+    /** Resting icon. */
+    icon: ReactNode;
+    /** Optional icon swapped in when `isActive` is true (e.g., Check after Graph toggle). */
+    activeIcon?: ReactNode;
+    /** Tooltip label (native `title=`). */
+    label: string;
+    /** Click handler. */
+    onClick: () => void;
+    /** True when the action is the currently-active view (drives color inversion). */
+    isActive?: boolean;
+    /** When true, render 100ms pressed-state + 600ms Check flash on click. */
+    showFeedback?: boolean;
+    /** Arbitrary CSS color string for the active state (e.g., '#4f46e5' for Graph). */
+    activeColor?: string;
+    /** Predicate; action is hidden when returns false. Runs on every render. */
+    visibleWhen?: (ctx: ActionStripContext) => boolean;
+}
+/**
+ * Overflow menu entry. Rendered in the vertical menu by default; may be promoted
+ * into the expanded strip when `isPromotable: true` and there's budget.
+ *
+ * `order` sets monotonic rank used for promotion priority and menu rendering.
+ * The lone non-promotable entry today is "What's this?" (footer).
+ */
+export interface OverflowAction {
+    /** Stable identifier for test hooks. */
+    id: string;
+    /** Icon; required only when the action may be promoted into the strip. */
+    icon?: ReactNode;
+    /** Menu-item text / promoted-button tooltip. */
+    label: string;
+    /** Click handler. */
+    onClick: () => void;
+    /** True = eligible for promotion into the expanded strip; false = vertical-only. */
+    isPromotable: boolean;
+    /** Monotonic rank for promotion priority + vertical render order. */
+    order: number;
+    /** Predicate; action is hidden when returns false. Runs on every render. */
+    visibleWhen?: (ctx: ActionStripContext) => boolean;
+}
+/**
+ * Menu-flip direction. Omit to let floating-ui's flip() middleware decide.
+ *
+ * AP-13 — the reconfig-surface pass-through variant was retired in Phase 17
+ * (plan 17-04): its type alias and Save / Cancel pass-through props were
+ * removed along with the render branch. Cancel / close now live in the
+ * Phase 17 overlay header, not inside ActionStrip. Only lingering references
+ * allowed in source: skip-marker strings in NYQUIST-09 parity-matrix fixtures
+ * under `__tests__/fixtures/`. Any resurrection in source is a regression and
+ * is blocked by `nyquist-10-ap-guards.test.ts` (AP-13 source-grep).
+ */
+export type ActionStripMenuDirection = 'up' | 'down';
+/**
+ * Public ActionStrip prop contract. Stable across Phase 16 plans 16-01..05.
+ */
+export interface ActionStripProps {
+    /** Pinned strip buttons (Graph, Details, Navigate, Retry, etc.). */
+    primary: PrimaryAction[];
+    /** Overflow entries (Settings, Remove, Replace, Refresh, What's this?). */
+    overflow: OverflowAction[];
+    /** From `useSlideOutReveal` — true when the consumer card is hovered/focused. */
+    visible: boolean;
+    /** Sticky-on-click expansion state. */
+    expanded: boolean;
+    /** Called to toggle `expanded`. */
+    onExpandedChange: (open: boolean) => void;
+    /** CardBack collapse-to-Undo. Preserved behavior #5. */
+    isFlipped?: boolean;
+    /** Called when the Undo button is clicked while isFlipped. */
+    onFlipBack?: () => void;
+    /** Stack-card slot-slide horizontal anchor in px. Preserved behavior #3. */
+    anchorX?: number;
+    /** Optional override; omit to let floating-ui flip() decide. Re-measured at expand click. */
+    menuDirection?: ActionStripMenuDirection;
+    /** Singleton registry key. Preserved behavior #1. Auto-generated if omitted. */
+    menuId?: string;
+    /** Runtime context forwarded to action visibleWhen() predicates. */
+    context?: ActionStripContext;
+    /** Consumer-overridable tooltip for the Graph pinned button. */
+    graphLabel?: string;
+    /** Consumer-overridable tooltip for the Details pinned button. */
+    detailsLabel?: string;
+}