@eocrm/design-system 0.6.24 → 0.7.0

package/dist/components/Grid/Grid.css

@@ -0,0 +1,122 @@
+:root {
+  --grid-gap-xs: var(--space-1);
+  --grid-gap-sm: var(--space-2);
+  --grid-gap-md: var(--space-3);
+  --grid-gap-lg: var(--space-4);
+  --grid-gap-xl: var(--space-6);
+  --grid-gap-2xl: var(--space-8);
+}
+
+.Grid__grid__-YIZ- {
+  display: grid;
+  grid-template-columns: var(--grid-columns, repeat(auto-fit, minmax(240px, 1fr)));
+}
+
+.Grid__item__ARgDD {
+  grid-column: var(--grid-item-span, auto);
+}
+
+.Grid__gapXs__-HKJt {
+  gap: var(--grid-gap-xs);
+}
+
+.Grid__gapSm__L3FnJ {
+  gap: var(--grid-gap-sm);
+}
+
+.Grid__gapMd__Pz9qZ {
+  gap: var(--grid-gap-md);
+}
+
+.Grid__gapLg__TetLh {
+  gap: var(--grid-gap-lg);
+}
+
+.Grid__gapXl__otF_y {
+  gap: var(--grid-gap-xl);
+}
+
+.Grid__gap2xl__UdKRm {
+  gap: var(--grid-gap-2xl);
+}
+
+.Grid__alignItemsStart__NVlIN {
+  align-items: start;
+}
+
+.Grid__alignItemsCenter__8w88d {
+  align-items: center;
+}
+
+.Grid__alignItemsEnd___VP1u {
+  align-items: end;
+}
+
+.Grid__alignItemsStretch__RzU8w {
+  align-items: stretch;
+}
+
+.Grid__justifyItemsStart__kgO2b {
+  justify-items: start;
+}
+
+.Grid__justifyItemsCenter__UUKJZ {
+  justify-items: center;
+}
+
+.Grid__justifyItemsEnd__28n0Q {
+  justify-items: end;
+}
+
+.Grid__justifyItemsStretch__sLPxN {
+  justify-items: stretch;
+}
+
+.Grid__collapsible__zzcfA {
+  container-type: inline-size;
+}
+
+.Grid__stepContainer__NfaWT {
+  display: grid;
+  container-type: inline-size;
+}
+
+@container (max-width: 480px) {
+  .Grid__collapsible__zzcfA.Grid__collapseSm__eSEI5 > * {
+    grid-column: 1/-1;
+  }
+}
+@container (max-width: 640px) {
+  .Grid__collapsible__zzcfA.Grid__collapseMd__9EeuB > * {
+    grid-column: 1/-1;
+  }
+}
+@container (max-width: 768px) {
+  .Grid__collapsible__zzcfA.Grid__collapseLg__oU6gQ > * {
+    grid-column: 1/-1;
+  }
+}
+@container (max-width: 768px) {
+  .Grid__grid__-YIZ-.Grid__stepLg__Fs8E_ {
+    grid-template-columns: var(--grid-columns-lg, none);
+  }
+  .Grid__grid__-YIZ-.Grid__stepLg__Fs8E_ > .Grid__item__ARgDD {
+    grid-column: var(--grid-item-span-lg, auto);
+  }
+}
+@container (max-width: 640px) {
+  .Grid__grid__-YIZ-.Grid__stepMd__fQVqB {
+    grid-template-columns: var(--grid-columns-md, none);
+  }
+  .Grid__grid__-YIZ-.Grid__stepMd__fQVqB > .Grid__item__ARgDD {
+    grid-column: var(--grid-item-span-md, auto);
+  }
+}
+@container (max-width: 480px) {
+  .Grid__grid__-YIZ-.Grid__stepSm__T1TcS {
+    grid-template-columns: var(--grid-columns-sm, none);
+  }
+  .Grid__grid__-YIZ-.Grid__stepSm__T1TcS > .Grid__item__ARgDD {
+    grid-column: var(--grid-item-span-sm, auto);
+  }
+}

package/dist/components/Grid/Grid.d.ts

@@ -0,0 +1,99 @@
+import { type HTMLAttributes, type ReactElement } from 'react';
+import { type CollapseBreakpoint, type CollapseColumnsMap } from '../_internal/collapse.js';
+/** Gap between cells. Same scale as Stack/Cluster: pixels 4/8/12/16/24/32. */
+export type GridGap = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+/** Cross-axis (vertical within row) alignment of each cell. */
+export type GridAlignItems = 'start' | 'center' | 'end' | 'stretch';
+/** Main-axis (horizontal within track) alignment of each cell. */
+export type GridJustifyItems = 'start' | 'center' | 'end' | 'stretch';
+/** Container-width threshold below which a fixed-column grid collapses. `sm` 480px / `md` 640px / `lg` 768px. */
+export type GridCollapseBreakpoint = CollapseBreakpoint;
+export type { CollapseColumnsMap };
+/** Limited polymorphic element type. Covers the layout / semantic elements Grid is likely to render as. */
+export type GridAs = 'div' | 'section' | 'ul' | 'ol' | 'nav' | 'main' | 'aside' | 'article' | 'header' | 'footer';
+interface GridBaseProps {
+    /**
+     * Gap between cells.
+     * `xs` (4) / `sm` (8) / `md` (12, default) / `lg` (16) / `xl` (24) / `2xl` (32).
+     * Same scale as Stack and Cluster.
+     */
+    gap?: GridGap;
+    /**
+     * Cross-axis (vertical within row) alignment of each cell. Default browser
+     * behavior is `stretch`; omit to use the default. Useful for cards of varying intrinsic height.
+     */
+    alignItems?: GridAlignItems;
+    /**
+     * Main-axis (horizontal within track) alignment of each cell. Default
+     * browser behavior is `stretch`; omit to use the default.
+     */
+    justifyItems?: GridJustifyItems;
+    /** Element to render. Default `'div'`. Limited to `div`, `section`, `ul`, `ol`, `nav`, `main`, `aside`, `article`, `header`, `footer` rather than fully polymorphic. */
+    as?: GridAs;
+}
+interface GridFixedColumns extends GridBaseProps, HTMLAttributes<HTMLElement> {
+    /** Fixed number of equal-width columns. Mutually exclusive with `minColumnWidth`. */
+    columns: number;
+    minColumnWidth?: never;
+    /**
+     * Collapse to a single visual column when the GRID'S OWN width (container
+     * query, not viewport) drops below the preset: `sm` 480px / `md` 640px /
+     * `lg` 768px. Every child spans the full row below the threshold —
+     * `Grid.Item` spans included. Only valid with `columns` (auto-fit grids
+     * already reflow).
+     *
+     * Consumer inline `style={{ gridColumn }}` on a child still wins below the
+     * threshold (inline beats any stylesheet rule) — don't do that; use
+     * `Grid.Item span` instead.
+     *
+     * ❌ Anti-pattern: a `collapseBelow` grid must get its width from its
+     * parent. `container-type: inline-size` zeroes the grid's contribution to
+     * intrinsic sizing, so in an intrinsic-width context (`Split`'s default
+     * `auto` aside track, a `Cluster` item, `width: max-content`) it renders at
+     * width 0 — give the parent a concrete width instead. Whichever element
+     * carries the containment also becomes the containing block for
+     * absolutely-positioned descendants (layout containment) — the grid itself
+     * for the string form, the wrapper below for the map form.
+     *
+     * Also accepts a graduated breakpoint→columns map, e.g.
+     * `collapseBelow={{ md: 6, sm: 1 }}`: below 640px the grid re-templates to
+     * 6 columns (item spans clamp to fit — a span wider than the step becomes a
+     * full row), and below 480px to a single column. Use when jumping straight
+     * from N columns to 1 wastes tablet widths. When several breakpoints match,
+     * the smallest wins. Only `Grid.Item` children get span clamping; plain
+     * children auto-place into the step's tracks.
+     *
+     * ⚠️ The map form (and ONLY the map form) renders an extra wrapper `<div>`
+     * around the grid element — it carries `container-type: inline-size`,
+     * because re-templating the grid requires querying an ancestor, not the
+     * grid itself. Consequences: a `> child` CSS selector aimed at the grid from
+     * its parent now hits the wrapper instead, and layout the parent applies to
+     * "the Grid" (`flex: 1`, `grid-column`, `align-self` via `className`) lands
+     * on the grid *inside* the wrapper, where the parent's layout can't see it —
+     * put that layout on an element you control around the Grid. `ref`,
+     * `className`, `style`, `as` and all spread props stay on the grid element.
+     */
+    collapseBelow?: GridCollapseBreakpoint | CollapseColumnsMap;
+}
+interface GridAutoFit extends GridBaseProps, HTMLAttributes<HTMLElement> {
+    /**
+     * Minimum column width for auto-fit responsive layout. Columns reflow
+     * based on container width — no breakpoints needed. CSS length string
+     * like `'240px'` or `'15rem'`. Defaults to `'240px'` when neither
+     * `columns` nor `minColumnWidth` is provided.
+     */
+    minColumnWidth?: string;
+    columns?: never;
+    collapseBelow?: never;
+}
+/** Public props — discriminated union enforces mutual exclusion. */
+export type GridProps = GridFixedColumns | GridAutoFit;
+/**
+ * 2D layout primitive: a CSS Grid wrapper with token-driven gap.
+ * @see docs/components/Grid.md
+ */
+export declare const Grid: (<T extends GridProps>(props: T & {
+    ref?: React.Ref<HTMLElement>;
+}) => ReactElement) & {
+    Item: import("react").ForwardRefExoticComponent<import("./GridItem.js").GridItemProps & import("react").RefAttributes<HTMLElement>>;
+};

package/dist/components/Grid/Grid.js

@@ -0,0 +1,67 @@
+'use client';
+import Grid_module_default from "./Grid.module.js";
+import { GridItem } from "./GridItem.js";
+import { COLLAPSE_BREAKPOINTS, CollapseColumnsContext, collapseTrackTemplate } from "../_internal/collapse.js";
+import { forwardRef } from "react";
+import clsx from "clsx";
+import { jsx } from "react/jsx-runtime";
+// src/components/Grid/Grid.tsx
+var gapClass = {
+	xs: Grid_module_default.gapXs,
+	sm: Grid_module_default.gapSm,
+	md: Grid_module_default.gapMd,
+	lg: Grid_module_default.gapLg,
+	xl: Grid_module_default.gapXl,
+	"2xl": Grid_module_default.gap2xl
+};
+var alignItemsClass = {
+	start: Grid_module_default.alignItemsStart,
+	center: Grid_module_default.alignItemsCenter,
+	end: Grid_module_default.alignItemsEnd,
+	stretch: Grid_module_default.alignItemsStretch
+};
+var justifyItemsClass = {
+	start: Grid_module_default.justifyItemsStart,
+	center: Grid_module_default.justifyItemsCenter,
+	end: Grid_module_default.justifyItemsEnd,
+	stretch: Grid_module_default.justifyItemsStretch
+};
+var collapseClass = {
+	sm: Grid_module_default.collapseSm,
+	md: Grid_module_default.collapseMd,
+	lg: Grid_module_default.collapseLg
+};
+var stepClass = {
+	sm: Grid_module_default.stepSm,
+	md: Grid_module_default.stepMd,
+	lg: Grid_module_default.stepLg
+};
+var GridBase = forwardRef(function Grid({ gap = "md", alignItems, justifyItems, as = "div", columns, minColumnWidth, collapseBelow, className, style, ...rest }, ref) {
+	const template = columns !== void 0 ? collapseTrackTemplate(columns) : `repeat(auto-fit, minmax(${minColumnWidth ?? "240px"}, 1fr))`;
+	const collapseMap = typeof collapseBelow === "object" ? collapseBelow : void 0;
+	const collapseKeys = collapseMap ? COLLAPSE_BREAKPOINTS.filter((b) => collapseMap[b] !== void 0) : [];
+	const stepVars = Object.fromEntries(collapseKeys.map((b) => [`--grid-columns-${b}`, collapseTrackTemplate(collapseMap[b])]));
+	const grid = /* @__PURE__ */ jsx(as, {
+		ref,
+		className: clsx(Grid_module_default.grid, gapClass[gap], alignItems && alignItemsClass[alignItems], justifyItems && justifyItemsClass[justifyItems], typeof collapseBelow === "string" && Grid_module_default.collapsible, typeof collapseBelow === "string" && collapseClass[collapseBelow], ...collapseKeys.map((b) => stepClass[b]), className),
+		style: {
+			...style,
+			...stepVars,
+			["--grid-columns"]: template
+		},
+		...rest
+	});
+	return collapseMap && collapseKeys.length > 0 ? /* @__PURE__ */ jsx(CollapseColumnsContext.Provider, {
+		value: collapseMap,
+		children: /* @__PURE__ */ jsx("div", {
+			className: Grid_module_default.stepContainer,
+			children: grid
+		})
+	}) : grid;
+});
+/**
+* 2D layout primitive: a CSS Grid wrapper with token-driven gap.
+* @see docs/components/Grid.md
+*/
+var Grid = Object.assign(GridBase, { Item: GridItem });
+export { Grid };

package/dist/components/Grid/Grid.module.js

@@ -0,0 +1,53 @@
+import "./Grid.css";
+// src/components/Grid/Grid.module.scss
+var grid = "Grid__grid__-YIZ-";
+var item = "Grid__item__ARgDD";
+var gapXs = "Grid__gapXs__-HKJt";
+var gapSm = "Grid__gapSm__L3FnJ";
+var gapMd = "Grid__gapMd__Pz9qZ";
+var gapLg = "Grid__gapLg__TetLh";
+var gapXl = "Grid__gapXl__otF_y";
+var gap2xl = "Grid__gap2xl__UdKRm";
+var alignItemsStart = "Grid__alignItemsStart__NVlIN";
+var alignItemsCenter = "Grid__alignItemsCenter__8w88d";
+var alignItemsEnd = "Grid__alignItemsEnd___VP1u";
+var alignItemsStretch = "Grid__alignItemsStretch__RzU8w";
+var justifyItemsStart = "Grid__justifyItemsStart__kgO2b";
+var justifyItemsCenter = "Grid__justifyItemsCenter__UUKJZ";
+var justifyItemsEnd = "Grid__justifyItemsEnd__28n0Q";
+var justifyItemsStretch = "Grid__justifyItemsStretch__sLPxN";
+var collapsible = "Grid__collapsible__zzcfA";
+var stepContainer = "Grid__stepContainer__NfaWT";
+var collapseSm = "Grid__collapseSm__eSEI5";
+var collapseMd = "Grid__collapseMd__9EeuB";
+var collapseLg = "Grid__collapseLg__oU6gQ";
+var stepLg = "Grid__stepLg__Fs8E_";
+var stepMd = "Grid__stepMd__fQVqB";
+var stepSm = "Grid__stepSm__T1TcS";
+var Grid_module_default = {
+	grid,
+	item,
+	gapXs,
+	gapSm,
+	gapMd,
+	gapLg,
+	gapXl,
+	gap2xl,
+	alignItemsStart,
+	alignItemsCenter,
+	alignItemsEnd,
+	alignItemsStretch,
+	justifyItemsStart,
+	justifyItemsCenter,
+	justifyItemsEnd,
+	justifyItemsStretch,
+	collapsible,
+	stepContainer,
+	collapseSm,
+	collapseMd,
+	collapseLg,
+	stepLg,
+	stepMd,
+	stepSm
+};
+export { alignItemsCenter, alignItemsEnd, alignItemsStart, alignItemsStretch, collapseLg, collapseMd, collapseSm, collapsible, Grid_module_default as default, gap2xl, gapLg, gapMd, gapSm, gapXl, gapXs, grid, item, justifyItemsCenter, justifyItemsEnd, justifyItemsStart, justifyItemsStretch, stepContainer, stepLg, stepMd, stepSm };

package/dist/components/Grid/GridItem.d.ts

@@ -0,0 +1,23 @@
+import { type HTMLAttributes } from 'react';
+import { type GridItemSpan } from '../_internal/gridSpan.js';
+export type { GridItemSpan };
+/** Elements `Grid.Item` can render as. `'li'` pairs with `<Grid as="ul">`. */
+export type GridItemAs = 'div' | 'li' | 'section' | 'article' | 'aside';
+export interface GridItemProps extends HTMLAttributes<HTMLElement> {
+    /**
+     * Column span. Omit for a single track (auto placement).
+     * - number — `span N` of the parent's `columns`.
+     * - `'25%' | '33%' | '50%' | '67%' | '75%'` — fractions of a 12-column
+     *   grid; use with `columns={12}` (other counts won't produce the named
+     *   fraction — documented, not validated).
+     * - `'100%'` / `'full'` — the entire row; safe with any Grid variant.
+     */
+    span?: GridItemSpan;
+    /** Element to render. Default `'div'`. Use `'li'` inside `<Grid as="ul">`. */
+    as?: GridItemAs;
+}
+/**
+ * A cell of `<Grid>` with an explicit column span.
+ * @see docs/components/Grid.md
+ */
+export declare const GridItem: import("react").ForwardRefExoticComponent<GridItemProps & import("react").RefAttributes<HTMLElement>>;

package/dist/components/Grid/GridItem.js

@@ -0,0 +1,28 @@
+'use client';
+import { resolveCollapsedGridItemSpan, resolveGridItemSpan } from "../_internal/gridSpan.js";
+import { CollapseColumnsContext } from "../_internal/collapse.js";
+import Grid_module_default from "./Grid.module.js";
+import { forwardRef, useContext } from "react";
+import clsx from "clsx";
+import { jsx } from "react/jsx-runtime";
+// src/components/Grid/GridItem.tsx
+/**
+* A cell of `<Grid>` with an explicit column span.
+* @see docs/components/Grid.md
+*/
+var GridItem = forwardRef(function GridItem({ span, as = "div", className, style, ...rest }, ref) {
+	const resolved = resolveGridItemSpan(span);
+	const collapseMap = useContext(CollapseColumnsContext);
+	const collapseVars = collapseMap ? Object.fromEntries(Object.keys(collapseMap).map((b) => [`--grid-item-span-${b}`, resolveCollapsedGridItemSpan(span, collapseMap[b])])) : void 0;
+	return /* @__PURE__ */ jsx(as, {
+		ref,
+		className: clsx(Grid_module_default.item, className),
+		style: {
+			...style,
+			...collapseVars,
+			["--grid-item-span"]: resolved ?? "auto"
+		},
+		...rest
+	});
+});
+export { GridItem };

package/dist/components/Grid/index.d.ts

@@ -0,0 +1,3 @@
+export { Grid } from './Grid.js';
+export type { GridProps, GridGap, GridAlignItems, GridJustifyItems, GridAs, GridCollapseBreakpoint, CollapseColumnsMap, } from './Grid.js';
+export type { GridItemProps, GridItemSpan, GridItemAs } from './GridItem.js';

package/dist/components/Highlight/Highlight.css

@@ -0,0 +1,68 @@
+:root {
+  --highlight-color: var(--ring-accent);
+  --highlight-ring-width: var(--border-width);
+  --highlight-radius: 0px;
+  --highlight-z: calc(var(--z-app-chrome) - 1);
+  --highlight-wave-duration: 2200ms;
+  --highlight-wave-delay: 1100ms;
+  --highlight-wave-reach: var(--space-5);
+  --highlight-wave-edge: var(--border-width-emphasis);
+  --highlight-wave-glow: 22px;
+  --highlight-fade: var(--transition-slow);
+}
+
+.Highlight__overlay__i0Uhh {
+  z-index: var(--highlight-z);
+  pointer-events: none;
+  border-radius: var(--highlight-radius);
+  outline: var(--highlight-ring-width) solid var(--highlight-color);
+  outline-offset: 0;
+  --wave-reach: var(--highlight-wave-reach);
+  --wave-radius: var(--highlight-radius);
+  --wave-peak: 0.9;
+}
+.Highlight__overlay__i0Uhh::before, .Highlight__overlay__i0Uhh::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border: var(--highlight-wave-edge) solid var(--highlight-color);
+  border-radius: inherit;
+  box-shadow: inset 0 0 var(--highlight-wave-glow) calc(var(--highlight-wave-glow) / 4) color-mix(in srgb, var(--highlight-color) 55%, transparent);
+  opacity: var(--opacity-hidden);
+  pointer-events: none;
+  animation: Highlight__attention-wave__xMjfm var(--highlight-wave-duration) cubic-bezier(0.2, 0.6, 0.4, 1) infinite;
+}
+.Highlight__overlay__i0Uhh::after {
+  animation-delay: var(--highlight-wave-delay);
+}
+@media (prefers-reduced-motion: reduce) {
+  .Highlight__overlay__i0Uhh::before, .Highlight__overlay__i0Uhh::after {
+    display: none;
+  }
+}
+@keyframes Highlight__attention-wave__xMjfm {
+  0% {
+    inset: 0;
+    opacity: var(--wave-peak);
+  }
+  100% {
+    inset: calc(-1 * var(--wave-reach));
+    opacity: var(--opacity-hidden);
+    border-radius: calc(var(--wave-radius) + var(--wave-reach));
+  }
+}
+
+.Highlight__overlay__i0Uhh[data-in-overlay] {
+  z-index: var(--z-overlay-floating);
+}
+
+.Highlight__overlay__i0Uhh[data-stage=fading] {
+  opacity: var(--opacity-hidden);
+  transition: opacity var(--highlight-fade);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .Highlight__overlay__i0Uhh[data-stage=fading] {
+    transition: none;
+  }
+}

package/dist/components/Highlight/Highlight.d.ts

@@ -0,0 +1,56 @@
+import { type ReactElement } from 'react';
+import type { PaletteColor } from '../../palette/palette.js';
+export interface HighlightProps {
+    /**
+     * Turns the highlight on. Each false → true change starts it once: the ring
+     * and waves show, the optional scroll and focus run, and after `duration` it fades
+     * out and `onDone` fires. Setting it back to false early removes the ring at
+     * once WITHOUT calling `onDone`. Keeping it `true` doesn't restart anything;
+     * toggle false → true to highlight again.
+     */
+    active: boolean;
+    /**
+     * How long the ring holds before fading, in ms. Read when the highlight
+     * starts; changing it mid-run has no effect. A non-finite value
+     * (`Infinity`, `NaN`) keeps it on until `active` goes false. Default: `3000`.
+     */
+    duration?: number;
+    /**
+     * Called once, after the fade ends (straight after `duration` under
+     * `prefers-reduced-motion`). Typically clears the consumer's `active`
+     * state. Not called when `active` is cleared early or on unmount.
+     */
+    onDone?: () => void;
+    /**
+     * On activation, scroll the child to the vertical centre of its scroll
+     * container. Smooth, or instant under `prefers-reduced-motion`.
+     * Default: `false`.
+     */
+    scrollIntoView?: boolean;
+    /**
+     * On activation, move focus to the child (`preventScroll`, so it never
+     * fights `scrollIntoView`). The child must be focusable: give a
+     * non-interactive block (`Card`, `<section>`, `<tr>`) `tabIndex={-1}`.
+     * Highlight never adds it for you. Default: `false`.
+     */
+    focus?: boolean;
+    /**
+     * Ring and wave colour, from the shared palette (its saturated `fg` half,
+     * readable in both themes). Unset = the accent ring colour. Use a palette
+     * colour when the highlight should match the thing it points to (e.g. a
+     * category colour); leave it unset otherwise.
+     */
+    color?: PaletteColor;
+    /**
+     * Exactly one element that forwards `ref` to a DOM element (nothing else is
+     * needed): any DS component, or a native element such as `<tr>` or `<li>`.
+     * Highlight renders no wrapper and changes nothing on the child but a
+     * `data-highlight` attribute; the ring is drawn on a separate overlay.
+     */
+    children: ReactElement;
+}
+/**
+ * Temporary attention ring + outward waves around any single block, with optional scroll and focus.
+ * @see docs/components/Highlight.md
+ */
+export declare function Highlight({ active, duration, onDone, scrollIntoView, focus, color, children, }: HighlightProps): import("react").JSX.Element;

package/dist/components/Highlight/Highlight.js

@@ -0,0 +1,82 @@
+'use client';
+import { mergeRefs } from "../_internal/refs.js";
+import { HighlightOverlay } from "./HighlightOverlay.js";
+import { Children, cloneElement, useEffect, useMemo, useRef, useState } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+// src/components/Highlight/Highlight.tsx
+/** Mirrors `--highlight-fade` (`--transition-slow`, 260ms). */
+var FADE_MS = 260;
+function prefersReducedMotion() {
+	return typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+/**
+* Temporary attention ring + outward waves around any single block, with optional scroll and focus.
+* @see docs/components/Highlight.md
+*/
+function Highlight({ active, duration = 3e3, onDone, scrollIntoView = false, focus = false, color, children }) {
+	const child = Children.only(children);
+	const nodeRef = useRef(null);
+	const [node, setNode] = useState(null);
+	const [stage, setStage] = useState("on");
+	const [prevActive, setPrevActive] = useState(active);
+	if (active !== prevActive) {
+		setPrevActive(active);
+		if (active) setStage("on");
+	}
+	const latest = useRef({
+		onDone,
+		duration,
+		scrollIntoView,
+		focus
+	});
+	useEffect(() => {
+		latest.current = {
+			onDone,
+			duration,
+			scrollIntoView,
+			focus
+		};
+	});
+	useEffect(() => {
+		if (!active) return;
+		const node = nodeRef.current;
+		if (node) {
+			if (latest.current.scrollIntoView) node.scrollIntoView({
+				block: "center",
+				inline: "nearest",
+				behavior: prefersReducedMotion() ? "auto" : "smooth"
+			});
+			if (latest.current.focus) node.focus({ preventScroll: true });
+		} else if (process.env.NODE_ENV !== "production") console.warn("Highlight: child did not attach the ref — it must forward ref to a DOM element");
+		const { duration: hold } = latest.current;
+		if (!Number.isFinite(hold)) return;
+		let fadeTimer;
+		const finish = () => {
+			setStage("done");
+			latest.current.onDone?.();
+		};
+		const holdTimer = setTimeout(() => {
+			if (prefersReducedMotion()) finish();
+			else {
+				setStage("fading");
+				fadeTimer = setTimeout(finish, FADE_MS);
+			}
+		}, hold);
+		return () => {
+			clearTimeout(holdTimer);
+			clearTimeout(fadeTimer);
+		};
+	}, [active]);
+	const childRef = child.props.ref;
+	const ref = useMemo(() => mergeRefs(nodeRef, setNode, childRef), [childRef]);
+	const phase = active && stage !== "done" ? stage : void 0;
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [cloneElement(child, {
+		"data-highlight": phase,
+		ref
+	}), phase && node && /* @__PURE__ */ jsx(HighlightOverlay, {
+		target: node,
+		stage: phase,
+		color
+	})] });
+}
+export { Highlight };

package/dist/components/Highlight/Highlight.module.js

@@ -0,0 +1,8 @@
+import "./Highlight.css";
+// src/components/Highlight/Highlight.module.scss
+var overlay = "Highlight__overlay__i0Uhh";
+var Highlight_module_default = {
+	overlay,
+	"attention-wave": "Highlight__attention-wave__xMjfm"
+};
+export { Highlight_module_default as default, overlay };

package/dist/components/Highlight/HighlightOverlay.d.ts

@@ -0,0 +1,30 @@
+import { type PaletteColor } from '../../palette/palette.js';
+type Box = {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+} | null;
+/**
+ * The part of `el` not clipped by an ancestor with `overflow` ≠ `visible` or
+ * by the viewport, in viewport coordinates; `null` when nothing shows.
+ *
+ * Floating UI's `platform.getClippingRect` would do this, but it reads a
+ * private per-call cache (`this._c`) that only `computePosition` sets, so it
+ * throws when called directly — hence this walk.
+ * ponytail: ignores ancestors a positioned child escapes (an absolute child of
+ * a non-positioned `overflow: hidden` box) and `contain: paint`; switch to
+ * Floating UI's clipping-ancestor logic if a consumer hits one.
+ */
+export declare function visibleRect(el: HTMLElement): Box;
+/**
+ * Decorative ring + outward waves over `target`'s visible rect (internal to
+ * `<Highlight>`). Portaled to `<body>` and `position: fixed`, so no scroll
+ * container or `overflow` clips it and nothing on the target changes.
+ */
+export declare function HighlightOverlay({ target, stage, color, }: {
+    target: HTMLElement;
+    stage: 'on' | 'fading';
+    color?: PaletteColor;
+}): import("react").ReactPortal;
+export {};