@mt-gloss/ui 0.0.24 → 0.0.26

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/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/package.json

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