@meetreeve/ui 0.15.0 → 0.16.0

package/README.md

@@ -187,6 +187,47 @@ the host must define `--color-popover`, `--color-popover-foreground`,
 `--color-border` and `--color-ring`, and Tailwind consumers must include this
 package's `dist` as a `@source` (see ResponsiveHeader above).
 
+## StageRail (DEV-13855)
+
+Domain-free "flow of cards": cards joined by connectors, left to right.
+
+```tsx
+import { StageRail, StageCardShell, StageConnector, StageRailMini } from "@meetreeve/ui/stage-rail";
+
+<StageRail
+  stages={steps}
+  getId={(s) => s.id}
+  leading={<TriggerCard />}              // fixed: never reorders, nothing inserts before it
+  trailing={<ExitCard />}                // fixed: nothing inserts after it
+  selectedId={selected}
+  onSelect={setSelected}
+  onInsertAt={(i) => insertStep(i)}
+  reorderable
+  onReorder={(from, to) => moveStep(from, to)}
+  editable={isDraft}                     // false: no +, no reorder
+  ruler={[{ label: "Start" }, ...steps.map((s) => ({ label: s.day })), { label: "End" }]}
+  renderCard={(s, i, ctx) => (
+    <StageCardShell selected={ctx.selected} dragging={ctx.dragging} dragHandle={ctx.reorderable}
+      onSelect={ctx.select} index={i + 1} className="w-64">
+      …
+    </StageCardShell>
+  )}
+  renderConnector={(prev, next, i, ctx) => (  // prev/next null = a fixed slot
+    <StageConnector label="2 days" onInsert={ctx.canInsert ? ctx.insert : undefined} dropActive={ctx.dropActive} />
+  )}
+/>
+```
+
+- Reorder is opt-in and starts only from a `[data-stage-drag-handle]` (the
+  shell's `dragHandle`), so inputs and buttons in cards and connectors never
+  start a drag. Clicks and keys from interactive descendants never select.
+- Styling uses the consumer's shadcn theme tokens (`bg-card`, `ring-primary`,
+  `ring-destructive`, `text-muted-foreground`, …), so light and dark follow the
+  host. Spacing reads `--mf-stage-*` with built-in fallbacks.
+- Fit: measure `scrollRef` and feed `computeFitZoomFromExtent({ zoom, scrollWidth, clientWidth })`
+  back into `zoom`. It can only zoom out; to fit a rail that already fits, jump
+  to 1, re-measure, and correct down.
+
 ## Tokens
 
 ```ts

package/dist/stage-rail/index.d.mts

@@ -0,0 +1,173 @@
+import * as react from 'react';
+import { ReactNode, Ref, HTMLAttributes } from 'react';
+
+interface StageCardContext {
+    /** 0-based position in `stages`. */
+    index: number;
+    selected: boolean;
+    /** This card is the one being pointer-dragged. */
+    dragging: boolean;
+    /** Pointer / Alt+arrow reorder is live — render a drag handle (`StageCardShell dragHandle`). */
+    reorderable: boolean;
+    /** Calls `onSelect(getId(stage))`. Wire it to `StageCardShell onSelect`. */
+    select: () => void;
+}
+interface StageConnectorContext {
+    /** `editable` and `onInsertAt` is set. */
+    canInsert: boolean;
+    /** Calls `onInsertAt(i)`. */
+    insert: () => void;
+    /** A pointer drag would land a stage in this gap. */
+    dropActive: boolean;
+}
+interface StageRailProps<T> {
+    stages: T[];
+    getId: (stage: T) => string;
+    renderCard: (stage: T, index: number, ctx: StageCardContext) => ReactNode;
+    /**
+     * The link between two rendered slots. `prev`/`next` are null for a fixed
+     * `leading`/`trailing` slot; `index` is where an inserted stage would land.
+     * Return null for no gap. Defaults to an inline `StageConnector`.
+     */
+    renderConnector?: (prev: T | null, next: T | null, index: number, ctx: StageConnectorContext) => ReactNode;
+    /** Fixed first slot (e.g. a trigger): never reorderable, nothing inserts before it. */
+    leading?: ReactNode;
+    /** Fixed last slot (e.g. an exit or an append target): nothing inserts after it. */
+    trailing?: ReactNode;
+    selectedId?: string | null;
+    onSelect?: (id: string) => void;
+    onInsertAt?: (index: number) => void;
+    /** Array-move semantics: `to` is the moved stage's final index. */
+    onReorder?: (from: number, to: number) => void;
+    /** Opt in to pointer (drag handle) and Alt+←/→ reorder. */
+    reorderable?: boolean;
+    /** false = read-only: no insert, no reorder. */
+    editable?: boolean;
+    /** One label per RENDERED slot, fixed slots included, drawn above it. */
+    ruler?: {
+        label: ReactNode;
+    }[];
+    /** CSS zoom on the track; pair with `computeFitZoomFromExtent` over `scrollRef`. */
+    zoom?: number;
+    /** The horizontal scroll element (measure scrollWidth/clientWidth for fit). */
+    scrollRef?: Ref<HTMLDivElement>;
+    className?: string;
+    "aria-label"?: string;
+}
+/**
+ * A horizontal "flow of cards": leading slot → stage cards → trailing slot,
+ * with connectors between every pair. Domain-free — cards and connectors are
+ * the consumer's render props. Snap-scrolls below md.
+ */
+declare function StageRail<T>({ stages, getId, renderCard, renderConnector, leading, trailing, selectedId, onSelect, onInsertAt, onReorder, reorderable, editable, ruler, zoom, scrollRef, className, "aria-label": ariaLabel, }: StageRailProps<T>): react.JSX.Element;
+
+/** True when `target` is (inside) an interactive element nested in `root` — not `root` itself. */
+declare function isInteractiveTarget(target: EventTarget | null, root: Element): boolean;
+interface StageCardShellProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSelect"> {
+    /** Click / Enter / Space on the card itself. Never fires from interactive descendants. */
+    onSelect?: () => void;
+    selected?: boolean;
+    disabled?: boolean;
+    /** Visual only — the body is never replaced. */
+    pending?: boolean;
+    /** Destructive ring; wins over `selected`. */
+    error?: boolean;
+    /** Dims the card while a drag (yours or StageRail's) is in flight. */
+    dragging?: boolean;
+    /** Show the visual drag handle (StageRail's pointer reorder grabs it; HTML5 consumers use `draggable`). */
+    dragHandle?: boolean;
+    /** Shown verbatim in the bottom-left dot (pass the 1-based number). Omitted when undefined. */
+    index?: number;
+    topLeft?: ReactNode;
+    topRight?: ReactNode;
+    /** Centred overlay revealed on card hover (and focus-within unless `overlayRevealOnFocus` is false). */
+    overlay?: ReactNode;
+    /** Also reveal `overlay` while focus is inside the card. false for bodies that hold focus (e.g. an iframe). */
+    overlayRevealOnFocus?: boolean;
+    /** Classes for the drag handle, merged last. */
+    handleClassName?: string;
+    /** Classes for the index dot, merged last. */
+    indexClassName?: string;
+    /** Bottom strip (e.g. an inline error). */
+    alert?: ReactNode;
+}
+/**
+ * The frame every stage card shares: ONE root div (ref + rest props land on
+ * it, so Radix `asChild` triggers and IntersectionObserver refs work), the
+ * consumer's body full-bleed inside, and absolutely-positioned slots over it.
+ * Stateless; hover is CSS-only via the `group/card` name.
+ */
+declare const StageCardShell: react.ForwardRefExoticComponent<StageCardShellProps & react.RefAttributes<HTMLDivElement>>;
+
+interface StageConnectorProps extends HTMLAttributes<HTMLElement> {
+    /** `inline` sits between cards; `append` is the tall end-of-rail target. */
+    variant?: "inline" | "append";
+    /** Without it (or when `disabled`) the inline `+` is not rendered and the append button is disabled. */
+    onInsert?: () => void;
+    disabled?: boolean;
+    /** Highlight as the live drop target (shows the inline `+` without hover). */
+    dropActive?: boolean;
+    /** Accessible name of the insert control. */
+    insertLabel?: string;
+    /** Inline: text / controls under the link (e.g. "2 days", an inline input). */
+    label?: ReactNode;
+    /** Inline: chip above the link (e.g. "38 waiting"). */
+    badge?: ReactNode;
+    /** Inline: 0–1 volume, scales the link's thickness (1px → 6px). */
+    weight?: number;
+    /** Append: the card height to match. Width is max(80, height * 0.45). */
+    height?: number;
+    /** Append: visible caption. */
+    appendText?: ReactNode;
+    /** Inline: show the `+` without hover on touch (hover:none) devices. */
+    touchAlwaysVisible?: boolean;
+    /** Inline: classes for the `+` button, merged last (its drop-active state included). */
+    insertClassName?: string;
+}
+/**
+ * The link between two stage cards. Rest props (HTML5 onDragOver / onDrop …)
+ * land on the hit-area root. Inline with no label/badge/weight it is exactly
+ * the 36×36 hit area — zero extra size. Horizontal only.
+ */
+declare function StageConnector({ variant, onInsert, disabled, dropActive, insertLabel, label, badge, weight, height, appendText, touchAlwaysVisible, insertClassName, className, style, onClick, ...rest }: StageConnectorProps): react.JSX.Element;
+
+interface StageRailMiniDot {
+    /** Names the stage in the accessible summary and the dot's tooltip. */
+    label: string;
+    key?: string;
+    /** Colour per kind, e.g. "bg-primary". */
+    className?: string;
+    /** Optional tiny icon; the dot grows to fit it. */
+    icon?: ReactNode;
+}
+/** Dot-sequence thumbnail of a rail for list rows: one dot per stage. */
+declare function StageRailMini({ dots, className, "aria-label": ariaLabel, }: {
+    dots: StageRailMiniDot[];
+    className?: string;
+    "aria-label"?: string;
+}): react.JSX.Element;
+
+/**
+ * Zoom that fits a rail's content into its scroll viewport, derived from the
+ * scroller's REAL rendered extent (ported from the Studio chain, DEV-3681:
+ * a closed-form gap model no-opped on overflowing chains).
+ *
+ * `zoom` is the zoom the extent was rendered AT. Content scales linearly with
+ * zoom; the scroller's own horizontal padding (`pad`, StageRail's md+ px-8 =
+ * 64) doesn't, so both extents shed it before the ratio. Clamped to
+ * [min, max] and rounded to 2dp.
+ *
+ * Caveat: DOM scrollWidth floor-clamps at clientWidth, so content that already
+ * fits measures ratio 1 and this echoes `zoom` — it can only zoom OUT. To fit
+ * a fitting rail, jump to `max`, re-measure, and correct down if it overshot.
+ */
+declare function computeFitZoomFromExtent({ zoom, scrollWidth, clientWidth, pad, min, max, }: {
+    zoom: number;
+    scrollWidth: number;
+    clientWidth: number;
+    pad?: number;
+    min?: number;
+    max?: number;
+}): number;
+
+export { type StageCardContext, StageCardShell, type StageCardShellProps, StageConnector, type StageConnectorContext, type StageConnectorProps, StageRail, StageRailMini, type StageRailMiniDot, type StageRailProps, computeFitZoomFromExtent, isInteractiveTarget };

package/dist/stage-rail/index.d.ts

@@ -0,0 +1,173 @@
+import * as react from 'react';
+import { ReactNode, Ref, HTMLAttributes } from 'react';
+
+interface StageCardContext {
+    /** 0-based position in `stages`. */
+    index: number;
+    selected: boolean;
+    /** This card is the one being pointer-dragged. */
+    dragging: boolean;
+    /** Pointer / Alt+arrow reorder is live — render a drag handle (`StageCardShell dragHandle`). */
+    reorderable: boolean;
+    /** Calls `onSelect(getId(stage))`. Wire it to `StageCardShell onSelect`. */
+    select: () => void;
+}
+interface StageConnectorContext {
+    /** `editable` and `onInsertAt` is set. */
+    canInsert: boolean;
+    /** Calls `onInsertAt(i)`. */
+    insert: () => void;
+    /** A pointer drag would land a stage in this gap. */
+    dropActive: boolean;
+}
+interface StageRailProps<T> {
+    stages: T[];
+    getId: (stage: T) => string;
+    renderCard: (stage: T, index: number, ctx: StageCardContext) => ReactNode;
+    /**
+     * The link between two rendered slots. `prev`/`next` are null for a fixed
+     * `leading`/`trailing` slot; `index` is where an inserted stage would land.
+     * Return null for no gap. Defaults to an inline `StageConnector`.
+     */
+    renderConnector?: (prev: T | null, next: T | null, index: number, ctx: StageConnectorContext) => ReactNode;
+    /** Fixed first slot (e.g. a trigger): never reorderable, nothing inserts before it. */
+    leading?: ReactNode;
+    /** Fixed last slot (e.g. an exit or an append target): nothing inserts after it. */
+    trailing?: ReactNode;
+    selectedId?: string | null;
+    onSelect?: (id: string) => void;
+    onInsertAt?: (index: number) => void;
+    /** Array-move semantics: `to` is the moved stage's final index. */
+    onReorder?: (from: number, to: number) => void;
+    /** Opt in to pointer (drag handle) and Alt+←/→ reorder. */
+    reorderable?: boolean;
+    /** false = read-only: no insert, no reorder. */
+    editable?: boolean;
+    /** One label per RENDERED slot, fixed slots included, drawn above it. */
+    ruler?: {
+        label: ReactNode;
+    }[];
+    /** CSS zoom on the track; pair with `computeFitZoomFromExtent` over `scrollRef`. */
+    zoom?: number;
+    /** The horizontal scroll element (measure scrollWidth/clientWidth for fit). */
+    scrollRef?: Ref<HTMLDivElement>;
+    className?: string;
+    "aria-label"?: string;
+}
+/**
+ * A horizontal "flow of cards": leading slot → stage cards → trailing slot,
+ * with connectors between every pair. Domain-free — cards and connectors are
+ * the consumer's render props. Snap-scrolls below md.
+ */
+declare function StageRail<T>({ stages, getId, renderCard, renderConnector, leading, trailing, selectedId, onSelect, onInsertAt, onReorder, reorderable, editable, ruler, zoom, scrollRef, className, "aria-label": ariaLabel, }: StageRailProps<T>): react.JSX.Element;
+
+/** True when `target` is (inside) an interactive element nested in `root` — not `root` itself. */
+declare function isInteractiveTarget(target: EventTarget | null, root: Element): boolean;
+interface StageCardShellProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSelect"> {
+    /** Click / Enter / Space on the card itself. Never fires from interactive descendants. */
+    onSelect?: () => void;
+    selected?: boolean;
+    disabled?: boolean;
+    /** Visual only — the body is never replaced. */
+    pending?: boolean;
+    /** Destructive ring; wins over `selected`. */
+    error?: boolean;
+    /** Dims the card while a drag (yours or StageRail's) is in flight. */
+    dragging?: boolean;
+    /** Show the visual drag handle (StageRail's pointer reorder grabs it; HTML5 consumers use `draggable`). */
+    dragHandle?: boolean;
+    /** Shown verbatim in the bottom-left dot (pass the 1-based number). Omitted when undefined. */
+    index?: number;
+    topLeft?: ReactNode;
+    topRight?: ReactNode;
+    /** Centred overlay revealed on card hover (and focus-within unless `overlayRevealOnFocus` is false). */
+    overlay?: ReactNode;
+    /** Also reveal `overlay` while focus is inside the card. false for bodies that hold focus (e.g. an iframe). */
+    overlayRevealOnFocus?: boolean;
+    /** Classes for the drag handle, merged last. */
+    handleClassName?: string;
+    /** Classes for the index dot, merged last. */
+    indexClassName?: string;
+    /** Bottom strip (e.g. an inline error). */
+    alert?: ReactNode;
+}
+/**
+ * The frame every stage card shares: ONE root div (ref + rest props land on
+ * it, so Radix `asChild` triggers and IntersectionObserver refs work), the
+ * consumer's body full-bleed inside, and absolutely-positioned slots over it.
+ * Stateless; hover is CSS-only via the `group/card` name.
+ */
+declare const StageCardShell: react.ForwardRefExoticComponent<StageCardShellProps & react.RefAttributes<HTMLDivElement>>;
+
+interface StageConnectorProps extends HTMLAttributes<HTMLElement> {
+    /** `inline` sits between cards; `append` is the tall end-of-rail target. */
+    variant?: "inline" | "append";
+    /** Without it (or when `disabled`) the inline `+` is not rendered and the append button is disabled. */
+    onInsert?: () => void;
+    disabled?: boolean;
+    /** Highlight as the live drop target (shows the inline `+` without hover). */
+    dropActive?: boolean;
+    /** Accessible name of the insert control. */
+    insertLabel?: string;
+    /** Inline: text / controls under the link (e.g. "2 days", an inline input). */
+    label?: ReactNode;
+    /** Inline: chip above the link (e.g. "38 waiting"). */
+    badge?: ReactNode;
+    /** Inline: 0–1 volume, scales the link's thickness (1px → 6px). */
+    weight?: number;
+    /** Append: the card height to match. Width is max(80, height * 0.45). */
+    height?: number;
+    /** Append: visible caption. */
+    appendText?: ReactNode;
+    /** Inline: show the `+` without hover on touch (hover:none) devices. */
+    touchAlwaysVisible?: boolean;
+    /** Inline: classes for the `+` button, merged last (its drop-active state included). */
+    insertClassName?: string;
+}
+/**
+ * The link between two stage cards. Rest props (HTML5 onDragOver / onDrop …)
+ * land on the hit-area root. Inline with no label/badge/weight it is exactly
+ * the 36×36 hit area — zero extra size. Horizontal only.
+ */
+declare function StageConnector({ variant, onInsert, disabled, dropActive, insertLabel, label, badge, weight, height, appendText, touchAlwaysVisible, insertClassName, className, style, onClick, ...rest }: StageConnectorProps): react.JSX.Element;
+
+interface StageRailMiniDot {
+    /** Names the stage in the accessible summary and the dot's tooltip. */
+    label: string;
+    key?: string;
+    /** Colour per kind, e.g. "bg-primary". */
+    className?: string;
+    /** Optional tiny icon; the dot grows to fit it. */
+    icon?: ReactNode;
+}
+/** Dot-sequence thumbnail of a rail for list rows: one dot per stage. */
+declare function StageRailMini({ dots, className, "aria-label": ariaLabel, }: {
+    dots: StageRailMiniDot[];
+    className?: string;
+    "aria-label"?: string;
+}): react.JSX.Element;
+
+/**
+ * Zoom that fits a rail's content into its scroll viewport, derived from the
+ * scroller's REAL rendered extent (ported from the Studio chain, DEV-3681:
+ * a closed-form gap model no-opped on overflowing chains).
+ *
+ * `zoom` is the zoom the extent was rendered AT. Content scales linearly with
+ * zoom; the scroller's own horizontal padding (`pad`, StageRail's md+ px-8 =
+ * 64) doesn't, so both extents shed it before the ratio. Clamped to
+ * [min, max] and rounded to 2dp.
+ *
+ * Caveat: DOM scrollWidth floor-clamps at clientWidth, so content that already
+ * fits measures ratio 1 and this echoes `zoom` — it can only zoom OUT. To fit
+ * a fitting rail, jump to `max`, re-measure, and correct down if it overshot.
+ */
+declare function computeFitZoomFromExtent({ zoom, scrollWidth, clientWidth, pad, min, max, }: {
+    zoom: number;
+    scrollWidth: number;
+    clientWidth: number;
+    pad?: number;
+    min?: number;
+    max?: number;
+}): number;
+
+export { type StageCardContext, StageCardShell, type StageCardShellProps, StageConnector, type StageConnectorContext, type StageConnectorProps, StageRail, StageRailMini, type StageRailMiniDot, type StageRailProps, computeFitZoomFromExtent, isInteractiveTarget };