@mt-gloss/ui 0.0.23 → 0.0.25

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

@@ -14,7 +14,7 @@ export type { MetricCardProps, CardShellProps } from '../primitives/dashboard/Me
 export type { StackedGroupCardProps, StackedValueEntry } from '../primitives/dashboard/MetricCard/StackedGroupCard';
 export type { CardBackProps } from '../primitives/dashboard/MetricCard/CardBack';
 export { ActionStrip, buildDefaultOverflow } from '../primitives/overlays/ActionStrip';
-export type { ActionStripProps, PrimaryAction, OverflowAction, ActionStripContext, ActionStripVariant, ActionStripMenuDirection, DefaultHandlers, } 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/StackedGroupCard.d.ts

@@ -1,9 +1,22 @@
 import { TrendData } from './types';
+import { PrimaryAction, OverflowAction } from '../../overlays/ActionStrip/types';
 export interface StackedValueEntry {
     timeframe: string;
     value: number | null;
     trend?: TrendData | null;
 }
+/**
+ * Phase 18 plan 18-01 — per-slot ActionStrip config shape returned by
+ * `slotToActionStripConfig(slotIdx)`. Composed from Phase 16 ActionStrip
+ * `PrimaryAction` + `OverflowAction` types so consumers import a single
+ * contract. Collapses CONTEXT §Per-slot API shape onto the two-array API.
+ */
+export interface SlotActionStripConfig {
+    primary: PrimaryAction[];
+    overflow: OverflowAction[];
+}
+/** Selector mapping slot index → ActionStrip config for that slot. */
+export type SlotToActionStripConfig = (slotIdx: number) => SlotActionStripConfig;
 export interface StackedGroupCardProps {
     title: string;
     prefix?: string;
@@ -44,6 +57,38 @@ export interface StackedGroupCardProps {
      *     padding so trend text on the right does not collide with the stroke.
      */
     sparklineInset?: 'padded' | 'bleed';
+    /**
+     * Phase 18 plan 18-01 — per-slot ActionStrip config selector. Called with
+     * the currently-hovered slot index; returns the `{primary, overflow}`
+     * arrays that ActionStrip will render while that slot is hovered.
+     *
+     * When omitted (back-compat), the existing Cluster D `onSlotHoverStart/End`
+     * surface is preserved byte-for-byte — no new callbacks fire, no new DOM
+     * attributes appear, parent ActionStrip falls back to card-default config.
+     *
+     * When supplied, the selector runs on each slot `pointerenter` AFTER
+     * `onSlotHoverStart`. The resolved config is forwarded to the parent via
+     * `onSlotActionStripConfigChange`. The selector is invoked inside a
+     * try/catch; throws produce `console.error` + a `(idx, null)` change
+     * callback so the parent can fall back to card-default.
+     *
+     * AP-12 (Phase 18 new anti-pattern guard): When this prop co-occurs with
+     * a legacy global-action prop (detected at mount as `onTableAction` in
+     * props), the component emits `console.warn('[StackedGroupCard AP-12] …')`
+     * exactly once per mount. Mixing per-slot + global dispatch is ambiguous;
+     * remove the legacy global prop.
+     */
+    slotToActionStripConfig?: SlotToActionStripConfig;
+    /**
+     * Phase 18 plan 18-01 — fires whenever the resolved per-slot config
+     * changes. `(slotIdx, config)` on enter; `(null, null)` when pointer
+     * leaves the card (NOT fired when leaving to a sibling slot; the
+     * existing Cluster E `relatedTarget` guard keeps the bridge active).
+     *
+     * Parent owns the ActionStrip render + `anchorX` wiring; this callback
+     * is the bridge between per-slot hover and parent-level config state.
+     */
+    onSlotActionStripConfigChange?: (slotIdx: number | null, config: SlotActionStripConfig | null) => void;
 }
 /**
  * StackedGroupCard -- Renders 3 mini metric values horizontally within a 2-col card.
@@ -66,6 +111,6 @@ export interface StackedGroupCardProps {
  * ```
  */
 export declare const StackedGroupCard: {
-    ({ title, prefix, suffix, values, timeframes, sparklineData, accentColor, pinnedTimeframe, onPinTimeframe, isStale, colSpan, onSlotHoverStart, onSlotHoverEnd, sparklineInset, }: StackedGroupCardProps): import("react/jsx-runtime").JSX.Element;
+    (props: StackedGroupCardProps): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };

package/lib/primitives/dashboard/MetricCard/__tests__/nyquist-11-fixtures.d.ts

@@ -0,0 +1,38 @@
+import { computeGutterAnchorX as ComputeGutterAnchorXFn } from '../utils/computeGutterAnchorX';
+export interface NyquistHarness {
+    /** Reference to the promoted math helper (assertion invariants call through it). */
+    computeGutterAnchorX: typeof ComputeGutterAnchorXFn;
+}
+export interface BehaviorDef {
+    /** 1-indexed for human readability in test output. */
+    id: number;
+    /** Short, greppable label. */
+    label: string;
+    /**
+     * The contract invariant this row pins. Either an assert-lambda that the
+     * runner invokes inside `it.each`, or `null` when the row is documented as
+     * covered by a sibling test file (runner skips but keeps the row in the
+     * matrix count pin).
+     */
+    assert: ((harness: NyquistHarness) => void | Promise<void>) | null;
+    /**
+     * When present, the runner skips the row with the returned reason string
+     * instead of calling `assert`. Used to document rows whose contract is
+     * pinned by a dedicated sibling test file (cross-reference maintained in
+     * 18-VALIDATION.md).
+     */
+    skipFor?: () => string | undefined;
+}
+/**
+ * The 9 NYQUIST-11 behaviors. Each row's `assert` OR `skipFor` is evaluated
+ * by the runner. Rows without an inline assert are documented in
+ * 18-VALIDATION.md as covered by sibling test files — they remain in the
+ * matrix so the row-count pin (9) catches silent drops.
+ */
+export declare const BEHAVIORS: BehaviorDef[];
+/**
+ * Row-count pin — NYQUIST-11 runner asserts exactly this number of rows.
+ * Changing the behavior set requires updating this constant and adding a
+ * line in 18-VALIDATION.md §NYQUIST-11 behavior matrix.
+ */
+export declare const BEHAVIOR_ROW_COUNT = 9;

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

@@ -13,7 +13,7 @@ export { useEdgeHoverResize } from './useEdgeHoverResize';
 export * from './flipAndStage';
 export * from './types';
 export type { CardBackProps } from './CardBack';
-export type { StackedGroupCardProps, StackedValueEntry } from './StackedGroupCard';
+export type { StackedGroupCardProps, StackedValueEntry, SlotActionStripConfig, SlotToActionStripConfig, } from './StackedGroupCard';
 export type { SlideOutRevealConfig, SlideOutRevealReturn } from './useSlideOutReveal';
 export type { ResizeState, ResizeDirection, ResizeMode, ResizeCommit, UseEdgeHoverResizeArgs, UseEdgeHoverResizeReturn, } from './useEdgeHoverResize';
 export type { EdgeHoverHandleProps } from './EdgeHoverHandle';
@@ -24,6 +24,8 @@ export { DonutChart } from './visualizations/DonutChart';
 export { ObjectArrow } from './visualizations/ObjectArrow';
 export { formatValue } from './utils/formatValue';
 export { formatTrend } from './utils/formatTrend';
+export { computeGutterAnchorX } from './utils/computeGutterAnchorX';
+export type { GutterAnchorInput } from './utils/computeGutterAnchorX';
 export { allVariantFixtures } from './fixtures/allVariants';
 export { loadingFixture, errorFixture, emptyFixture, staleFixture, staleSparklineFixture, staleDonutFixture, allStateFixtures, } from './fixtures/states';
 export { sparklineFixture, sparklineUpFixture } from './fixtures/sparklineCard';

package/lib/primitives/dashboard/MetricCard/utils/computeGutterAnchorX.d.ts

@@ -0,0 +1,48 @@
+/**
+ * computeGutterAnchorX — Pure math for per-slot gutter-actions anchor (AP-13).
+ *
+ * AP-13 invariant (Phase 18): The gutter pill's horizontal `anchorX` MUST be
+ * derived via this helper — never hardcoded pixel offsets. Consumers include
+ * reptime's `MetricCardGrid` stacked-group branch (via plan 18-02 swap) and
+ * gloss-side tests; source-grep guard in plan 18-05 enforces that no other
+ * `anchorX = <number>` computation exists outside this module.
+ *
+ * Stack cards host N equally-distributed metric slots along their width.
+ * When the pointer hovers a slot, the ActionStrip pill must slide to that
+ * slot's horizontal midpoint (or pill-left offset, if `pillWidthPx` is
+ * supplied) so metric-scoped actions visually hang off the hovered metric.
+ *
+ * Formula (slot-center, default):
+ *   anchorX = (activeSlotIdx + 0.5) * (cardWidthPx / slotCount)
+ *
+ * Formula (pill-left-offset, when `pillWidthPx` present and > 0 and finite):
+ *   anchorX = (activeSlotIdx + 0.5) * (cardWidthPx / slotCount) - pillWidthPx / 2
+ *   (so the pill's visual CENTER sits at slot-center — per UI-SPEC §Spacing)
+ *
+ * Returns `undefined` when any input is invalid so the caller can skip the
+ * transition entirely and leave the pill at its current position.
+ *
+ * This utility is zero-dep by design — promoted to @mt-gloss/ui so every
+ * consumer shares the same formula without copy-paste. Plan 18-01 (this plan)
+ * publishes; plan 18-02 swaps reptime's local gutterAnchor.ts helper to
+ * import from here (byte-for-byte behavior parity when `pillWidthPx` absent).
+ */
+export interface GutterAnchorInput {
+    /** Measured width of the stack card, in CSS pixels. MUST be > 0 and finite. */
+    cardWidthPx: number;
+    /** Number of slots in the stack card (typically 3 or 5). MUST be > 0 and finite. */
+    slotCount: number;
+    /**
+     * Index of the currently-hovered slot (0-based). `null` returns `undefined`
+     * so the caller can unset the anchor and let the pill return to default.
+     */
+    activeSlotIdx: number | null;
+    /**
+     * Optional pill width. When present and finite and > 0, the returned value
+     * is the pill-LEFT offset so the pill's CENTER sits at slot center. When
+     * absent, zero, negative, or non-finite, the returned value is the raw
+     * slot-center pixel (matches reptime's original helper byte-for-byte).
+     */
+    pillWidthPx?: number;
+}
+export declare function computeGutterAnchorX(input: GutterAnchorInput): number | undefined;

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

@@ -1,5 +1,5 @@
 export { ActionStrip } from './ActionStrip';
-export type { PrimaryAction, OverflowAction, ActionStripProps, ActionStripContext, ActionStripVariant, ActionStripMenuDirection, } from './types';
+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';

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

@@ -71,12 +71,16 @@ export interface OverflowAction {
     visibleWhen?: (ctx: ActionStripContext) => boolean;
 }
 /**
- * `'default'` is the standard pill + menu. `'config'` is a transitional variant
- * that replaces the More trigger with Save/Cancel pills during reconfig flow;
- * Phase 17 retires this variant entirely.
+ * 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 ActionStripVariant = 'default' | 'config';
-/** Menu-flip direction. Omit to let floating-ui's flip() middleware decide. */
 export type ActionStripMenuDirection = 'up' | 'down';
 /**
  * Public ActionStrip prop contract. Stable across Phase 16 plans 16-01..05.
@@ -92,8 +96,6 @@ export interface ActionStripProps {
     expanded: boolean;
     /** Called to toggle `expanded`. */
     onExpandedChange: (open: boolean) => void;
-    /** Defaults to 'default'. Phase 17 retires 'config'. */
-    variant?: ActionStripVariant;
     /** CardBack collapse-to-Undo. Preserved behavior #5. */
     isFlipped?: boolean;
     /** Called when the Undo button is clicked while isFlipped. */
@@ -110,8 +112,4 @@ export interface ActionStripProps {
     graphLabel?: string;
     /** Consumer-overridable tooltip for the Details pinned button. */
     detailsLabel?: string;
-    /** Config variant Save handler. Retired in Phase 17 — pass-through only this phase. */
-    onConfigSave?: () => void;
-    /** Config variant Cancel handler. Retired in Phase 17 — pass-through only this phase. */
-    onConfigCancel?: () => void;
 }

package/package.json

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