@antadesign/anta 0.3.30 → 0.3.32

package/dist/components/Box.d.ts

@@ -14,6 +14,13 @@ export interface BoxProps extends BaseProps {
      * pixels; a string is any CSS length or two-value gap (`'1rem'`,
      * `'8px 16px'`). Applies while the Box is a flex or grid container. */
     gap?: number | string;
+    /** CSS selector for descendants whose border boxes are included in
+     * `measurement.rects` when Box measures. Coordinates are relative to this
+     * Box's top-left border edge; matches are in document order. Box reads and
+     * compares matching rects for each measurement event. With `observe="scroll"`,
+     * use `throttle` when the selector matches many descendants; it also delays
+     * CSS state updates after the initial read. */
+    includeRectsFor?: string;
     /** Inner spacing, matching CSS `padding`. Numbers are pixels; strings accept
      * CSS shorthand, percentages, and custom properties. Omission adds no style. */
     padding?: number | string;
@@ -31,9 +38,13 @@ export interface BoxProps extends BaseProps {
      * overflow adds content observation; hidden edges and scroll add scroll reads.
      * Without handlers or `fade`, omission stays idle. */
     observe?: BoxObservation | readonly BoxObservation[];
-    /** Minimum interval between measurement events, in milliseconds. The first
-     * report has no added delay; a trailing report delivers the latest values.
-     * Active observers and CSS clipping states are not throttled.
+    /** Keeps measurement events and CSS clipping states current outside the
+     * viewport. Has no effect unless `observe` or `fade` selects measurement. */
+    observeOffscreen?: boolean;
+    /** Minimum interval between measurements, in milliseconds. The initial
+     * measurement runs immediately; a trailing read updates CSS states and
+     * delivers the latest event. Descendant rects are read only for emitted
+     * events. The `measurement` getter always reads fresh values.
      * @defaultValue 0 */
     throttle?: number;
     /** Fades out every edge that currently hides clipped content, and drops the
@@ -43,8 +54,9 @@ export interface BoxProps extends BaseProps {
      * length.
      * @defaultValue 24 */
     fadeSize?: number | string;
-    /** Fired when a selected measurement field changes. `detail` contains all
-     * fields changed since the last event and a full current snapshot. */
+    /** Fired when a selected measurement field changes. `detail.changed` contains
+     * fields changed since the previous event; `detail.current` includes the full
+     * snapshot with matching rects. Rect changes alone do not trigger an event. */
     onMeasureChange?: (event: CustomEvent<BoxMeasurementChange>, detail: BoxMeasurementChange) => void;
     /** Fired after Box's browser and local rendering context changes. `detail`
      * contains the changed fields and a full current snapshot. */
@@ -65,4 +77,4 @@ export interface BoxProps extends BaseProps {
  * </Box>
  * ```
  */
-export declare const Box: ({ display, round, gap, padding, margin, observe, throttle, fade, fadeSize, onMeasureChange, onContextChange, className, style, children, ...rest }: BoxProps) => any;
+export declare const Box: ({ display, round, gap, includeRectsFor, padding, margin, observe, observeOffscreen, throttle, fade, fadeSize, onMeasureChange, onContextChange, className, style, children, ...rest }: BoxProps) => any;

package/dist/components/Box.js

@@ -18,9 +18,11 @@ const Box = ({
   display,
   round,
   gap,
+  includeRectsFor,
   padding,
   margin,
   observe,
+  observeOffscreen,
   throttle,
   fade,
   fadeSize,
@@ -42,9 +44,11 @@ const Box = ({
       display: display === "block" ? void 0 : display,
       round: roundAttr(round),
       gap: gap != null ? "" : void 0,
+      "include-rects-for": includeRectsFor,
       padding: padding != null ? "" : void 0,
       margin: margin != null ? "" : void 0,
       observe: observeAttr(observe, onMeasureChange, onContextChange),
+      "observe-offscreen": observeOffscreen ? "" : void 0,
       throttle,
       fade: fade ? "" : void 0,
       "fade-size": fade && fadeSize != null ? cssLength(fadeSize) : void 0,

package/dist/components/Expander.d.ts

@@ -23,16 +23,24 @@ export interface ExpanderProps extends Omit<BaseProps, "title"> {
      *  bare disclosure).
      *  @defaultValue 'secondary' */
     priority?: "primary" | "secondary" | "tertiary";
-    /** Outdent the chevron into the left gutter so the title and body sit
-     *  flush with surrounding content (the docs-header layout). Only takes
-     *  effect with `priority="tertiary"` — on the filled priorities the
-     *  container edge has to bound the chevron, so it's a no-op there. */
+    /** Align the title and body with surrounding content on a tertiary
+     *  expander. With the default start indicator, the mark hangs in the
+     *  gutter; an end indicator stays inside its edge. */
     outdent?: boolean;
-    /** Header actions (e.g. buttons, tags) rendered at the end of the
-     *  header row, OUTSIDE the toggle trigger — clicking them never
-     *  toggles, they're separately focusable, and screen readers see them
-     *  as separate controls. */
+    /** Header actions rendered outside the toggle trigger. With an end
+     *  indicator, actions sit between the title and indicator. */
     actions?: React.ReactNode;
+    /** Built-in disclosure mark, a decorative node, or separate closed/open
+     *  visuals. Other primitive values leave the indicator empty. Custom nodes
+     *  are passive; use `actions` for controls.
+     *  @defaultValue 'chevron' */
+    indicator?: "chevron" | "triangle" | "plus" | React.ReactNode | {
+        closed: React.ReactNode;
+        open: React.ReactNode;
+    };
+    /** Place the disclosure mark before the title or after the actions.
+     *  @defaultValue 'start' */
+    indicatorPlacement?: "start" | "end";
     /** Disables the header: not clickable or focusable, hover affordance
      *  off, text dimmed. The open state freezes as-is — disabling an open
      *  expander keeps it open. `actions` stay live; disable them
@@ -76,4 +84,4 @@ export interface ExpanderProps extends Omit<BaseProps, "title"> {
  * giving real controlled semantics (a consumer can reject a toggle). See
  * STATEFUL-COMPONENTS.md.
  */
-export declare const Expander: ({ title, level, tone, priority, outdent, actions, disabled, round, open, defaultOpen, onStateChange, className, style, children, ...rest }: ExpanderProps) => any;
+export declare const Expander: ({ title, level, tone, priority, outdent, actions, indicator, indicatorPlacement, disabled, round, open, defaultOpen, onStateChange, className, style, children, ...rest }: ExpanderProps) => any;

package/dist/components/Expander.js

@@ -1,4 +1,4 @@
-import { jsx, jsxs } from "@antadesign/anta/jsx-runtime";
+import { Fragment, jsx, jsxs } from "@antadesign/anta/jsx-runtime";
 import { nativeStateChange, neutralToneAttr, toneStyle, roundStyle, roundAttr } from "../anta_helpers";
 const Expander = ({
   title,
@@ -7,6 +7,8 @@ const Expander = ({
   priority,
   outdent,
   actions,
+  indicator,
+  indicatorPlacement,
   disabled,
   round,
   open,
@@ -18,6 +20,10 @@ const Expander = ({
   ...rest
 }) => {
   const controlled = open !== void 0;
+  const presetIndicator = typeof indicator === "string" && (indicator === "chevron" || indicator === "triangle" || indicator === "plus") ? indicator : void 0;
+  const pairedIndicator = indicator != null && typeof indicator === "object" && "closed" in indicator && "open" in indicator ? indicator : void 0;
+  const useCustomSlot = indicator != null && !presetIndicator && !pairedIndicator;
+  const customIndicator = typeof indicator === "object" ? indicator : null;
   const computedStyle = roundStyle(round, "--expander-round", toneStyle(tone, "--expander-tone-source", style));
   const titleNode = typeof title === "object" && title !== null ? /* @__PURE__ */ jsx("span", { slot: "title", style: { display: "contents" }, children: title }) : /* @__PURE__ */ jsx("a-expander-summary", { slot: "title", children: title });
   return /* @__PURE__ */ jsxs(
@@ -31,6 +37,8 @@ const Expander = ({
       outdent: outdent ? "" : void 0,
       round: roundAttr(round),
       disabled: disabled ? "" : void 0,
+      indicator: presetIndicator,
+      "indicator-placement": indicatorPlacement && indicatorPlacement !== "start" ? indicatorPlacement : void 0,
       onstatechange: onStateChange ? (e) => {
         const { event, detail, isOwn } = nativeStateChange(e);
         if (isOwn && detail)
@@ -45,6 +53,11 @@ const Expander = ({
       children: [
         titleNode,
         actions != null && /* @__PURE__ */ jsx("span", { slot: "actions", children: actions }),
+        pairedIndicator && /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsx("span", { slot: "indicator", "data-when": "closed", "aria-hidden": "true", inert: true, children: pairedIndicator.closed }),
+          /* @__PURE__ */ jsx("span", { slot: "indicator", "data-when": "open", "aria-hidden": "true", inert: true, children: pairedIndicator.open })
+        ] }),
+        useCustomSlot && /* @__PURE__ */ jsx("span", { slot: "indicator", "aria-hidden": "true", inert: true, children: customIndicator }),
         /* @__PURE__ */ jsx("a-expander-details", { children })
       ]
     }

package/dist/components/InputDate.js

@@ -1,5 +1,6 @@
 import { Fragment, jsx, jsxs } from "@antadesign/anta/jsx-runtime";
 import { useMemo, useState } from "../jsx-runtime";
+import { isModifiedNavigationKey } from "../anta_helpers";
 import { Temporal } from "temporal-polyfill";
 import {
   parseISODate,
@@ -138,6 +139,7 @@ const InputDate = ({
         },
         onChange: (e) => resolve(e.currentTarget.value),
         onKeyDown: (e) => {
+          if (isModifiedNavigationKey(e)) return;
           if ((e.key === "ArrowDown" || e.key === "ArrowUp") && !disabled) {
             e.preventDefault();
             setFocusNonce((n) => n + 1);

package/dist/components/MenuItem.d.ts

@@ -28,19 +28,19 @@ export interface MenuItemCommonProps extends BaseProps {
     /** Mark the item as selected. On a plain row (no `selectionIndicator`) this is
      *  a persistent background tint, the same resting fill a pressed row shows —
      *  also the way to flag the current page on a link item. On a checkable row
-     *  (`selectionIndicator` set) it instead drives the leading `checkbox` / `radio`
-     *  indicator and the row's `aria-checked`. */
+     *  (`selectionIndicator` set) it instead drives the indicator and the row's
+     *  `aria-checked`. */
     selected?: boolean;
-    /** Semantic tone — colors the label, icon, and hover/selected tint (and the
-     *  `checkbox`/`radio` indicator, which adopts it). A named tone, or any literal
-     *  CSS color (`'#ff1493'`, `'rebeccapurple'`) for a one-off custom tone whose
+    /** Semantic tone — colors the label, icon, hover/selected tint, and selection
+     *  indicator. A named tone, or any literal CSS color (`'#ff1493'`,
+     *  `'rebeccapurple'`) for a one-off custom tone whose
      *  hue + chroma are kept while the lightness is pinned to match the brand text.
      *  `critical` is the destructive action; `neutral` (the default) is the standard
      *  gray.
      *  @defaultValue neutral */
     tone?: 'neutral' | 'brand' | 'info' | 'success' | 'warning' | 'critical' | (string & {});
     /** Apply `tone` to every row state, or only while the row is selected. In
-     *  `selected` scope, an unselected row and its checkbox/radio indicator stay
+     *  `selected` scope, an unselected row and its indicator stay
      *  neutral.
      *  @defaultValue 'all' */
     toneScope?: ToneScope;
@@ -103,8 +103,10 @@ export type MenuItemActionMode = {
      *  - `'radio'` → `role="menuitemradio"`, a leading passive `<a-radio>`; tint dropped.
      *  - `'check'` → `role="menuitemradio"`, a trailing check glyph on the selected
      *    row *and* the background tint (the canonical single-select look).
+     *  - `'switch'` → `role="menuitemcheckbox"`, a trailing passive `<a-switch>`;
+     *    selecting the row keeps its menu open.
      *  Omit for a plain row (the default). */
-    selectionIndicator?: 'checkbox' | 'radio' | 'check';
+    selectionIndicator?: 'checkbox' | 'radio' | 'check' | 'switch';
     /** Only meaningful with `selectionIndicator="checkbox"`: render the box in the
      *  mixed state (`aria-checked="mixed"`) — e.g. a "Select all" row when some but
      *  not all of its options are selected. */

package/dist/components/MenuItem.js

@@ -93,12 +93,13 @@ const MenuItem = ({
   ...rest
 }) => {
   const leadingIcon = icon;
-  const checkable = selectionIndicator === "checkbox" || selectionIndicator === "radio" || selectionIndicator === "check";
-  const role = selectionIndicator === "checkbox" ? "menuitemcheckbox" : selectionIndicator === "radio" || selectionIndicator === "check" ? "menuitemradio" : "menuitem";
+  const checkable = selectionIndicator === "checkbox" || selectionIndicator === "radio" || selectionIndicator === "check" || selectionIndicator === "switch";
+  const role = selectionIndicator === "checkbox" || selectionIndicator === "switch" ? "menuitemcheckbox" : selectionIndicator === "radio" || selectionIndicator === "check" ? "menuitemradio" : "menuitem";
   const ariaChecked = !checkable ? void 0 : selectionIndicator === "checkbox" && indeterminate ? "mixed" : selected ? "true" : "false";
   const keepTint = selected && (selectionIndicator === void 0 || selectionIndicator === "check");
   const effectiveTone = toneScope === "selected" && !selected ? void 0 : tone;
   const toneAttr = neutralToneAttr(effectiveTone);
+  const switchBehavior = selectionIndicator === "switch" ? { "data-menu-open": "" } : {};
   const declaredShortcuts = rest["aria-keyshortcuts"];
   const keyShortcuts = kbd ? shortcutLabel(kbd) : void 0;
   const kbdNode = kbd ? /* @__PURE__ */ jsx("kbd", { "aria-hidden": declaredShortcuts ?? keyShortcuts ? "true" : void 0, children: kbd }) : null;
@@ -149,6 +150,7 @@ const MenuItem = ({
       onmenuselect: onSelect ? (e) => onSelect(e, { value, label }) : void 0,
       class: className,
       ...rest,
+      ...switchBehavior,
       children: [
         indicator != null ? (
           // `min-height: 1lh` makes the wrapper one text line tall and centers the node
@@ -191,6 +193,23 @@ const MenuItem = ({
         labelNode,
         children,
         kbdNode,
+        selectionIndicator === "switch" && indicator == null && /* @__PURE__ */ jsx(
+          "a-switch",
+          {
+            "data-menu-item-switch": "",
+            "aria-hidden": "true",
+            tabIndex: -1,
+            state: selected ? "checked" : "unchecked",
+            disabled: disabled ? "" : void 0,
+            size: "small",
+            tone: toneAttr,
+            style: toneStyle(
+              effectiveTone,
+              "--switch-tone-source",
+              toneStyle(effectiveTone, "--switch-off-tone-source")
+            )
+          }
+        ),
         (() => {
           let trailing = submenu ? iconTrailing ?? "chevron-right" : iconTrailing;
           if (!submenu && !iconTrailing && selectionIndicator === "check" && indicator == null)

package/dist/components/Text.js

@@ -1,9 +1,8 @@
 import { jsx, jsxs } from "@antadesign/anta/jsx-runtime";
-import { neutralToneAttr, toneStyle } from "../anta_helpers";
+import { lineClamp, neutralToneAttr, toneStyle } from "../anta_helpers";
 import { Tooltip } from "./Tooltip";
 const Text = ({ priority, tone, size, inline, truncate, expandable, collapsible, className, style, children, ...rest }) => {
-  const n = typeof truncate === "number" ? truncate : truncate ? 1 : null;
-  const lineCount = n != null && n >= 1 ? n : null;
+  const lineCount = lineClamp(truncate);
   const toneAttr = neutralToneAttr(tone);
   const computedStyle = toneStyle(
     toneAttr,

package/dist/components/Title.d.ts

@@ -14,9 +14,15 @@ export interface TitleProps extends BaseProps {
      *  kept while lightness/chroma are pinned per priority in oklch.
      *  @defaultValue neutral */
     tone?: 'neutral' | 'brand' | 'info' | 'success' | 'warning' | 'critical' | (string & {});
+    /** Truncate with a trailing ellipsis. `true` (or `1`) clamps to a
+     *  single line; any integer ≥ 2 clamps to that many lines; `0` or a
+     *  negative value means no truncation. A clipped JSX `Title` shows its
+     *  text content in a tooltip by default. Nest a `<Tooltip>` to provide
+     *  your own tooltip instead. */
+    truncate?: boolean | number;
 }
 /**
- * Block-level heading with level 1-6, priority, and tone.
+ * Block-level heading with level 1-6, priority, tone, and optional truncation.
  *
  * Renders an `<a-title>` styled tag (no JS, no shadow DOM) with
  * `role="heading"` and `aria-level={level}` set by this wrapper for
@@ -57,4 +63,4 @@ export interface TitleProps extends BaseProps {
  * </Title>
  * ```
  */
-export declare const Title: ({ level, priority, tone, className, style, children, ...rest }: TitleProps) => any;
+export declare const Title: ({ level, priority, tone, truncate, className, style, children, ...rest }: TitleProps) => any;

package/dist/components/Title.js

@@ -1,19 +1,30 @@
-import { jsx } from "@antadesign/anta/jsx-runtime";
-import { neutralToneAttr, toneStyle } from "../anta_helpers";
-const Title = ({ level = 2, priority, tone, className, style, children, ...rest }) => {
+import { jsx, jsxs } from "@antadesign/anta/jsx-runtime";
+import { lineClamp, neutralToneAttr, toneStyle } from "../anta_helpers";
+import { Tooltip } from "./Tooltip";
+const Title = ({ level = 2, priority, tone, truncate, className, style, children, ...rest }) => {
+  const lineCount = lineClamp(truncate);
   const toneAttr = neutralToneAttr(tone);
-  return /* @__PURE__ */ jsx(
+  const computedStyle = toneStyle(
+    toneAttr,
+    "--title-tone-source",
+    lineCount != null ? { ...style, ["--line-clamp"]: lineCount } : style
+  );
+  return /* @__PURE__ */ jsxs(
     "a-title",
     {
       level: String(level),
       priority,
       tone: toneAttr,
+      truncate: lineCount != null ? String(lineCount) : void 0,
       role: "heading",
       "aria-level": level,
       class: className,
-      style: toneStyle(toneAttr, "--title-tone-source", style),
+      style: computedStyle,
       ...rest,
-      children
+      children: [
+        children,
+        lineCount != null && /* @__PURE__ */ jsx(Tooltip, { truncatedOnly: true, "data-anta-text-tooltip": "" })
+      ]
     }
   );
 };

package/dist/elements/a-box.css

@@ -1 +1 @@
-@layer base,anta,components,utilities;@layer anta.reset,anta.components,anta.theme;@layer anta.components{a-box{display:block;min-width:0}a-box[display=inline-block]{display:inline-block}a-box[display=flex]{display:flex}a-box[display=inline-flex]{display:inline-flex}a-box[display=grid]{display:grid}a-box[display=inline-grid]{display:inline-grid}a-box[gap]{gap:var(--box-gap, normal);@supports (border-radius: attr(probe type(<length>),1px)){--box-gap: attr(gap type(<length>))}}a-box[padding]{padding:var(--box-padding, 0px);@supports (padding: attr(padding type(*))){--box-padding: attr(padding type(*), 0px)}}a-box[margin]{margin:var(--box-margin, 0px);@supports (margin: attr(margin type(*))){--box-margin: attr(margin type(*), 0px)}}a-box[round]{border-radius:var(--box-round, 999px);@supports (border-radius: attr(probe type(<length>),1px)){--box-round: attr(round type(<length>))}}a-box[fade]{--box-fade-size: 24px;--box-fade-x: linear-gradient(transparent, transparent);--box-fade-y: linear-gradient(transparent, transparent);--box-fade-to-start: to left;--box-fade-to-end: to right}a-box[fade]:is(:state(hidden-start-x),:state(hidden-end-x),:state(hidden-start-y),:state(hidden-end-y)){mask-image:linear-gradient(#000,#000),var(--box-fade-x),var(--box-fade-y);mask-clip:border-box,padding-box,padding-box;mask-origin:border-box,padding-box,padding-box;mask-composite:exclude,add,add;mask-repeat:no-repeat;mask-size:100% 100%}a-box[fade][fade-size]{--box-fade-size: 24px;@supports (border-radius: attr(probe type(<length>),1px)){--box-fade-size: attr(fade-size type(<length>), 24px)}}a-box[fade]:dir(rtl){--box-fade-to-start: to right;--box-fade-to-end: to left}a-box[fade]:state(hidden-end-x){--box-fade-x: linear-gradient(var(--box-fade-to-end), transparent calc(100% - var(--box-fade-size)), black)}a-box[fade]:state(hidden-start-x){--box-fade-x: linear-gradient(var(--box-fade-to-start), transparent calc(100% - var(--box-fade-size)), black)}a-box[fade]:state(hidden-start-x):state(hidden-end-x){--box-fade-x: linear-gradient( to right, black, transparent var(--box-fade-size), transparent calc(100% - var(--box-fade-size)), black )}a-box[fade]:state(hidden-end-y){--box-fade-y: linear-gradient(to bottom, transparent calc(100% - var(--box-fade-size)), black)}a-box[fade]:state(hidden-start-y){--box-fade-y: linear-gradient(to top, transparent calc(100% - var(--box-fade-size)), black)}a-box[fade]:state(hidden-start-y):state(hidden-end-y){--box-fade-y: linear-gradient( to bottom, black, transparent var(--box-fade-size), transparent calc(100% - var(--box-fade-size)), black )}}
+@layer base,anta,components,utilities;@layer anta.reset,anta.components,anta.theme;@property --box-fade-start-x-strength{syntax: "<number>"; inherits: false; initial-value: 0;}@property --box-fade-end-x-strength{syntax: "<number>"; inherits: false; initial-value: 0;}@property --box-fade-start-y-strength{syntax: "<number>"; inherits: false; initial-value: 0;}@property --box-fade-end-y-strength{syntax: "<number>"; inherits: false; initial-value: 0;}@layer anta.components{a-box{display:block;min-width:0;position:relative}a-box[display=inline-block]{display:inline-block}a-box[display=flex]{display:flex}a-box[display=inline-flex]{display:inline-flex}a-box[display=grid]{display:grid}a-box[display=inline-grid]{display:inline-grid}a-box[gap]{gap:var(--box-gap, normal);@supports (border-radius: attr(probe type(<length>),1px)){--box-gap: attr(gap type(<length>))}}a-box[padding]{padding:var(--box-padding, 0px);@supports (padding: attr(padding type(*))){--box-padding: attr(padding type(*), 0px)}}a-box[margin]{margin:var(--box-margin, 0px);@supports (margin: attr(margin type(*))){--box-margin: attr(margin type(*), 0px)}}a-box[round]{border-radius:var(--box-round, 999px);@supports (border-radius: attr(probe type(<length>),1px)){--box-round: attr(round type(<length>))}}a-box[fade]{--box-fade-size: 24px;--box-fade-left-strength: var(--box-fade-start-x-strength);--box-fade-right-strength: var(--box-fade-end-x-strength);transition:--box-fade-start-x-strength .14s ease-out,--box-fade-end-x-strength .14s ease-out,--box-fade-start-y-strength .14s ease-out,--box-fade-end-y-strength .14s ease-out}a-box[fade]:state(fade-mask-active){mask-image:linear-gradient(#000,#000),linear-gradient(to right,rgb(0 0 0 / var(--box-fade-left-strength)),transparent var(--box-fade-size),transparent calc(100% - var(--box-fade-size)),rgb(0 0 0 / var(--box-fade-right-strength))),linear-gradient(to bottom,rgb(0 0 0 / var(--box-fade-start-y-strength)),transparent var(--box-fade-size),transparent calc(100% - var(--box-fade-size)),rgb(0 0 0 / var(--box-fade-end-y-strength)));mask-clip:border-box,padding-box,padding-box;mask-origin:border-box,padding-box,padding-box;mask-composite:exclude,add,add;mask-repeat:no-repeat;mask-size:100% 100%}a-box[fade][fade-size]{--box-fade-size: 24px;@supports (border-radius: attr(probe type(<length>),1px)){--box-fade-size: attr(fade-size type(<length>), 24px)}}a-box[fade]:dir(rtl){--box-fade-left-strength: var(--box-fade-end-x-strength);--box-fade-right-strength: var(--box-fade-start-x-strength)}a-box[fade]:state(hidden-end-x){--box-fade-end-x-strength: 1}a-box[fade]:state(hidden-start-x){--box-fade-start-x-strength: 1}a-box[fade]:state(hidden-end-y){--box-fade-end-y-strength: 1}a-box[fade]:state(hidden-start-y){--box-fade-start-y-strength: 1}@media(prefers-reduced-motion:reduce){a-box[fade]{transition:none}}}

package/dist/elements/a-box.d.ts

@@ -11,6 +11,8 @@ import './a-box.css';
  * measurement fields or presets, including `context` and `all`. `fade` keeps
  * clipping states current without selecting event fields. A box with neither
  * runs no observers at all, including the shared visibility observer.
+ * `observe-offscreen` opts out of the pause: measurement keeps running while
+ * the box is off screen, and the box skips the visibility observer entirely.
  * The `measurement` / `context` / `isTruncated` getters still read on demand.
  *
  * Attributes rather than "is a listener attached" on purpose. A listener tally

package/dist/elements/a-box.js

@@ -1,8 +1,9 @@
 import { HTMLElementBase } from "../anta_helpers";
-import { throttle } from "es-toolkit";
+import { isEqual, throttle } from "es-toolkit";
 import { boxObservation } from "../box-observation";
 import "./a-box.css";
 const stores = /* @__PURE__ */ new WeakMap();
+const FADE_TRANSITION_MS = 140;
 const MODE_CLASS = /(?:^|\s)(?:dark|light)(?:\s|$)/;
 function hasModeClass(element) {
   return element.classList.contains("dark") || element.classList.contains("light");
@@ -200,21 +201,13 @@ function deviceSnapshot(navigator) {
     mobile: uaData.userAgentData?.mobile ?? /android|mobi|iphone|ipad|ipod/.test(source)
   };
 }
-function equal(a, b) {
-  if (a === b) return true;
-  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
-  const left = a;
-  const right = b;
-  const keys = Object.keys(left);
-  return keys.length === Object.keys(right).length && keys.every((key) => left[key] === right[key]);
-}
 function same(a, b) {
-  return a !== void 0 && Object.keys(b).every((key) => equal(a[key], b[key]));
+  return a !== void 0 && Object.keys(b).every((key) => isEqual(a[key], b[key]));
 }
 function changed(previous, current) {
   if (!previous) return { ...current };
   return Object.fromEntries(
-    Object.entries(current).filter(([key, value]) => !equal(previous[key], value))
+    Object.entries(current).filter(([key, value]) => !isEqual(previous[key], value))
   );
 }
 function px(value) {
@@ -264,7 +257,7 @@ function rounded(value) {
   return Math.round(value * 100) / 100;
 }
 class ABoxElement extends HTMLElementBase {
-  static observedAttributes = ["fade", "observe", "throttle"];
+  static observedAttributes = ["fade", "observe", "observe-offscreen", "throttle"];
   #internals = this.attachInternals?.();
   #store;
   #resizeObserver;
@@ -276,9 +269,10 @@ class ABoxElement extends HTMLElementBase {
   #measurementFields = /* @__PURE__ */ new Set();
   #watchContent = false;
   #watchScroll = false;
-  // Filtering and throttling compare against the last event, not the last read.
+  // Filtering compares against the last event, not the last read.
   #reportedMeasurement;
   #throttledReport;
+  #fadeMaskTimer;
   #context;
   #measuring = false;
   #clips = false;
@@ -298,6 +292,7 @@ class ABoxElement extends HTMLElementBase {
     this.#sync();
   }
   disconnectedCallback() {
+    this.#clearFadeMask();
     this.#stopMeasuring();
     this.#stopReportingContext();
     this.#store?.unobserveVisibility(this);
@@ -311,8 +306,9 @@ class ABoxElement extends HTMLElementBase {
      and the later connect would see the flags already set and skip it. */
   attributeChangedCallback(name, previous, current) {
     if (previous === current) return;
+    if (name === "fade" && current === null) this.#clearFadeMask();
     if (!this.#store) return;
-    if (name === "fade" || name === "observe") this.#sync();
+    if (name === "fade" || name === "observe" || name === "observe-offscreen") this.#sync();
     if (name === "throttle") this.#configureThrottle();
     if (name === "observe" || name === "throttle") this.#queueMeasurement();
   }
@@ -327,7 +323,7 @@ class ABoxElement extends HTMLElementBase {
   }
   /** Allows a nested `Tooltip truncatedOnly` to use Box's clipping decision. */
   get isTruncated() {
-    const measurement = this.#readMeasurement();
+    const measurement = this.#readMeasurement(false);
     return measurement.clippedX || measurement.clippedY;
   }
   /** Called by the per-window context cache. It is intentionally not a JSX prop. */
@@ -355,11 +351,12 @@ class ABoxElement extends HTMLElementBase {
     this.#watchContent = this.hasAttribute("fade") || content;
     this.#watchScroll = this.hasAttribute("fade") || scroll;
     const wantsMeasurement = this.hasAttribute("fade") || fields.size > 0;
-    const measure = this.isConnected && wantsMeasurement && (this.#visible ?? this.hasAttribute("fade"));
+    const offscreen = this.hasAttribute("observe-offscreen");
+    const measure = this.isConnected && wantsMeasurement && (offscreen || (this.#visible ?? this.hasAttribute("fade")));
     if (measure) this.#startMeasuring();
     else this.#stopMeasuring();
     if (this.#measuring) this.#syncMeasurementSources();
-    if (this.isConnected && wantsMeasurement) this.#store?.observeVisibility(this);
+    if (this.isConnected && wantsMeasurement && !offscreen) this.#store?.observeVisibility(this);
     else this.#store?.unobserveVisibility(this);
     if (this.isConnected && wantsContext) this.#startReportingContext();
     else this.#stopReportingContext();
@@ -391,7 +388,7 @@ class ABoxElement extends HTMLElementBase {
     this.#resizeObserver = new this.view.ResizeObserver(this.#queueMeasurement);
     this.#resizeObserver.observe(this);
     this.doc.fonts?.addEventListener("loadingdone", this.#queueMeasurement);
-    this.#measurement = this.#readMeasurement();
+    this.#measurement = this.#readMeasurement(false);
     this.#setMeasurementStates(this.#measurement);
     this.#syncChildObservation();
     this.#initialMeasurement = true;
@@ -488,7 +485,8 @@ class ABoxElement extends HTMLElementBase {
     this.#frame = this.view.requestAnimationFrame(() => {
       this.#frame = void 0;
       if (!this.#measuring) return;
-      this.#reportMeasurement();
+      if (this.#throttledReport) this.#throttledReport();
+      else this.#reportMeasurement();
     });
   };
   #queueContext = () => {
@@ -502,7 +500,30 @@ class ABoxElement extends HTMLElementBase {
       this.#reportContext(initial);
     });
   };
-  #readMeasurement() {
+  #readRects(rect) {
+    let rects = [];
+    const selector = this.getAttribute("include-rects-for");
+    if (selector) {
+      try {
+        const boxRect = rect ?? this.getBoundingClientRect();
+        rects = Array.from(this.querySelectorAll(selector), (element) => {
+          const target = element.getBoundingClientRect();
+          return {
+            top: rounded(target.top - boxRect.top),
+            right: rounded(target.right - boxRect.left),
+            bottom: rounded(target.bottom - boxRect.top),
+            left: rounded(target.left - boxRect.left),
+            width: rounded(target.width),
+            height: rounded(target.height)
+          };
+        });
+      } catch (error) {
+        if (!(error instanceof this.view.DOMException) || error.name !== "SyntaxError") throw error;
+      }
+    }
+    return rects;
+  }
+  #readMeasurement(includeRects = true) {
     const rect = this.getBoundingClientRect();
     const clientWidth = this.clientWidth;
     const clientHeight = this.clientHeight;
@@ -524,6 +545,7 @@ class ABoxElement extends HTMLElementBase {
     return {
       width: rounded(rect.width),
       height: rounded(rect.height),
+      rects: includeRects ? this.#readRects(rect) : [],
       clientWidth,
       clientHeight,
       scrollWidth,
@@ -559,7 +581,7 @@ class ABoxElement extends HTMLElementBase {
     this.#throttledReport = void 0;
     const interval = Number(this.getAttribute("throttle"));
     if (this.#measuring && Number.isFinite(interval) && interval > 0) {
-      this.#throttledReport = throttle(this.#emitMeasurement, Math.min(interval, 2147483647));
+      this.#throttledReport = throttle(() => this.#reportMeasurement(), Math.min(interval, 2147483647));
     }
   }
   #hasMeasurementChange(current) {
@@ -572,27 +594,22 @@ class ABoxElement extends HTMLElementBase {
     return false;
   }
   #reportMeasurement() {
-    const current = this.#readMeasurement();
+    const current = this.#readMeasurement(false);
     this.#measurement = current;
     this.#setMeasurementStates(current);
     this.#syncChildObservation();
     if (!this.#hasMeasurementChange(current)) return;
-    if (this.#throttledReport) this.#throttledReport();
-    else this.#emitMeasurement();
-  }
-  #emitMeasurement = () => {
-    const current = this.#measurement;
-    if (!this.#measuring || !current || !this.#hasMeasurementChange(current)) return;
+    const snapshot = { ...current, rects: this.#readRects() };
     const initial = this.#initialMeasurement;
     const previous = this.#reportedMeasurement;
     this.#initialMeasurement = false;
-    this.#reportedMeasurement = current;
+    this.#reportedMeasurement = snapshot;
     const detail = {
-      changed: initial ? { ...current } : changed(previous, current),
-      current
+      changed: changed(initial ? void 0 : previous, snapshot),
+      current: snapshot
     };
     this.dispatchEvent(new this.view.CustomEvent("measurechange", { detail }));
-  };
+  }
   #reportContext(initial) {
     const current = this.#readContext();
     const previous = this.#context;
@@ -620,6 +637,31 @@ class ABoxElement extends HTMLElementBase {
     this.#setState("hidden-end-x", measurement.hiddenEndX);
     this.#setState("hidden-start-y", measurement.hiddenStartY);
     this.#setState("hidden-end-y", measurement.hiddenEndY);
+    this.#syncFadeMask(measurement);
+  }
+  #syncFadeMask(measurement) {
+    const hidden = measurement.hiddenStartX || measurement.hiddenEndX || measurement.hiddenStartY || measurement.hiddenEndY;
+    if (hidden && this.hasAttribute("fade")) {
+      if (this.#fadeMaskTimer !== void 0) this.view.clearTimeout(this.#fadeMaskTimer);
+      this.#fadeMaskTimer = void 0;
+      this.#setState("fade-mask-active", true);
+      return;
+    }
+    if (!this.hasAttribute("fade")) {
+      this.#clearFadeMask();
+      return;
+    }
+    if (!this.#internals?.states?.has("fade-mask-active") || this.#fadeMaskTimer !== void 0) return;
+    if (this.view.matchMedia("(prefers-reduced-motion: reduce)").matches) {
+      this.#clearFadeMask();
+      return;
+    }
+    this.#fadeMaskTimer = this.view.setTimeout(() => this.#clearFadeMask(), FADE_TRANSITION_MS);
+  }
+  #clearFadeMask() {
+    if (this.#fadeMaskTimer !== void 0) this.view.clearTimeout(this.#fadeMaskTimer);
+    this.#fadeMaskTimer = void 0;
+    this.#setState("fade-mask-active", false);
   }
   #setState(name, active) {
     if (active) this.#internals?.states?.add(name);