@antadesign/anta 0.3.30 → 0.3.32

package/docs/components/box.md

@@ -10,6 +10,10 @@ pixels; strings accept CSS lengths. `padding` and `margin` also accept CSS
 shorthand, such as `padding="8px 16px"` or `margin="0 auto"`. Omission adds no
 spacing styles. A bare `round` fully rounds the corners.
 
+Box uses `position: relative` by default. Absolutely positioned descendants
+use it as their containing block. Set `position: static` on the Box if they
+should use another positioned ancestor.
+
 ```tsx
 <Box round={8} padding={10}><span /></Box>
 <Box display="flex" round={8} gap={6} padding={10}><span /></Box>
@@ -44,8 +48,10 @@ edges hide content while scrolling. `fade` enables both automatically.
 
 ### Fading a clipped edge
 
-`fade` masks edges with hidden content and removes the mask as scrolling reveals
-them. `fadeSize` sets its depth. It measures on connection, even off screen.
+`fade` masks edges with hidden content and eases the mask as scrolling reveals
+them. The mask is removed after the last edge fades out, preserving shadows and
+focus rings at rest. `fadeSize` sets its depth. It measures on connection, even
+off screen.
 
 ```tsx
 const TAGS = ['frontend', 'design-system', 'a11y', 'performance']
@@ -64,8 +70,9 @@ const TAGS = ['frontend', 'design-system', 'a11y', 'performance']
 .fade-demo a-tag { flex: 0 0 auto; }
 ```
 
-The mask clips to the padding box. It preserves the Box border, shadows, and
-focus ring when no edge is hidden.
+The fade affects the padding box. The mask remains through its exit transition,
+then disappears so shadows and focus rings are visible at rest. The easing is
+disabled when reduced motion is requested.
 
 To style hidden edges without `fade`, use `observe="edges"` and the
 `hidden-start-x`, `hidden-end-x`, `hidden-start-y`, or `hidden-end-y` CSS states.
@@ -91,9 +98,14 @@ const TAGS = ['frontend', 'design-system', 'a11y', 'performance']
 ## Measurements
 
 By default, `onMeasureChange` reports one frame after observation starts, then when
-the border-box `width` or `height` changes. `changed` contains all fields changed
-since the last event; `current` is the full snapshot. Reporting pauses off screen
-and resumes with a fresh snapshot when Box returns.
+the border-box `width` or `height` changes. `changed` contains fields
+changed since the last event; `current` is the full snapshot. Reporting pauses
+off screen and resumes with a fresh snapshot when Box returns.
+
+Pass `observeOffscreen` when a virtualized layout needs measurement events or
+clipping states while the Box is outside the viewport. It keeps the selected
+observers active. Use `throttle` to limit reads when offscreen content changes
+often.
 
 `observe` accepts one of the eight selections below, or a typed array combining
 them. `observe={['size', 'edges']}` and `observe={['edges', 'size']}` select the
@@ -134,19 +146,35 @@ When no measurement is selected, `onMeasureChange` adds `size`;
 Passing both handlers observes size and context without enabling scroll events.
 Without handlers or `fade`, omitting `observe` keeps Box idle.
 
-Set `throttle` to a minimum interval in milliseconds. The first report has no
-added delay; subsequent reports include a trailing update with the latest values.
-Omit it or pass `0` for frame-based reporting. Negative or non-finite values use
-`0`. The interval applies to `onMeasureChange`; context events are not throttled.
-Throttling limits event delivery; it does not reduce observer reads.
-`edges`, `scroll`, and `fade` continue measuring during scrolling so their
-CSS states remain current.
+Set `throttle` to a minimum interval in milliseconds. The initial measurement
+is immediate; later activity gets a trailing read with the latest values. Omit
+it or pass `0` for frame-based updates. Negative or non-finite values use `0`.
+The interval limits measurement reads, CSS state updates, and
+`onMeasureChange` events; context events are not throttled. The
+`box.measurement` getter still reads fresh values on demand.
 
 `Tooltip truncatedOnly` reads Box's clipping on demand. It works without
 `observe` or `onMeasureChange` and does not enable continuous observation.
 
-This readout observes `['size', 'overflow', 'edges', 'scroll']` with `throttle={100}`.
-Resize or scroll the Box to update it.
+Pass `includeRectsFor` to add matching descendants to each measurement snapshot.
+`current.rects` contains their border boxes in document order, with `top`,
+`left`, `right`, and `bottom` measured from the Box's top-left border edge, plus
+each match's `width` and `height`.
+
+The selector does not start observation or add event triggers. Box reads the
+rects when an existing `observe` selection reports a change. `current.rects`
+always contains the latest array; `changed.rects` appears only when that array
+differs from the previous report. For a fresh read at any time, use
+`box.measurement.rects`.
+
+With `observe="scroll"` and no throttle, Box can query, measure, and compare
+every matching descendant on each reported frame. Keep the selector focused or
+set `throttle` when many descendants match. A larger interval also delays the
+fade as the reader reaches an edge.
+
+This readout observes `['size', 'overflow', 'edges', 'scroll']` with `throttle={100}`
+and `fade`. It includes the first content row in `rects`. Resize or scroll the
+Box to update the values and edge mask.
 
 ```tsx title="measurechange"
 const [measurement, setMeasurement] = useState<BoxMeasurement | null>(null)
@@ -155,19 +183,25 @@ const [measurement, setMeasurement] = useState<BoxMeasurement | null>(null)
   round={8}
   className="measure-probe-box"
   observe={['size', 'overflow', 'edges', 'scroll']}
+  fade
+  includeRectsFor=".measure-probe-target"
   throttle={100}
   onMeasureChange={(_, { current }) => setMeasurement(current)}
 >
   <Text size="small" priority="tertiary">Resize or scroll this Box.</Text>
-  <div className="measure-probe-wide">wide content, so both axes overflow</div>
+  <div className="measure-probe-wide measure-probe-target">wide content, so both axes overflow</div>
   <div className="measure-probe-wide">and a second line, so the vertical axis does too</div>
   <div className="measure-probe-wide">and a third</div>
 </Box>
 
 <div className="measure-probe-readout">
-  {Object.entries(measurement ?? {}).map(([field, value]) => (
-    <Tag key={field} size="small" label={field} value={String(value)} />
-  ))}
+  {Object.entries(measurement ?? {}).map(([field, value]) => field === 'rects' && Array.isArray(value)
+    ? <div key={field} className="measure-probe-rects">
+        <Tag size="small" label="rects" value={`${value.length} match${value.length === 1 ? '' : 'es'}`} />
+        <pre><code>{JSON.stringify(value, null, 2)}</code></pre>
+      </div>
+    : <Tag key={field} size="small" label={field} value={String(value)} />
+  )}
 </div>
 ```
 
@@ -184,6 +218,8 @@ const [measurement, setMeasurement] = useState<BoxMeasurement | null>(null)
 }
 .measure-probe-wide { inline-size: 520px; padding-block: 6px; }
 .measure-probe-readout { display: flex; flex-wrap: wrap; gap: 6px; }
+.measure-probe-rects { flex-basis: 100%; min-width: 0; }
+.measure-probe-rects pre { margin: 4px 0 0; padding: 8px; border: 1px solid var(--border-4); border-radius: 4px; background: var(--bg-2); white-space: pre-wrap; overflow-wrap: anywhere; }
 ```
 
 See the [measurement fields](#boxmeasurement). Overflow fields map to kebab-case
@@ -284,13 +320,15 @@ const canvasRef = useRef<HTMLCanvasElement>(null)
 | `fade?` | boolean | — | Fades out every edge that currently hides clipped content, and drops the fade from an edge once the reader scrolls to it. |
 | `fadeSize?` | number \| string | 24 | Depth of the `fade` gradient. A `number` is pixels; a string is any CSS length. |
 | `gap?` | number \| string | — | Gap between children, matching the CSS `gap` property. A `number` is pixels; a string is any CSS length or two-value gap (`'1rem'`, `'8px 16px'`). Applies while the Box is a flex or grid container. |
+| `includeRectsFor?` | 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. |
 | `margin?` | number \| string | — | Outer spacing, matching CSS `margin`. Numbers are pixels; strings accept CSS shorthand, `auto`, negative lengths, and custom properties. Omission adds no style. |
 | `observe?` | 'width' \| 'height' \| 'size' \| 'context' \| 'overflow' \| 'edges' \| 'scroll' \| 'all' \| readonly BoxObservation[] | — | One selection or an array of selections, in any order. `'size'` watches width and height; `'context'` watches rendering context; `'overflow'` watches content dimensions and clipping. `'edges'` reports which edges hide content; `'scroll'` reports offsets, potentially every frame; `'all'` selects everything. Selections are independent: use `['size', 'edges']` to combine them. A measurement handler implies `'size'` when no measurement is selected; a context handler adds `'context'`. Size skips content and scroll observers; overflow adds content observation; hidden edges and scroll add scroll reads. Without handlers or `fade`, omission stays idle. |
+| `observeOffscreen?` | boolean | — | Keeps measurement events and CSS clipping states current outside the viewport. Has no effect unless `observe` or `fade` selects measurement. |
 | `onContextChange?` | (event, detail) => void | — | Fired after Box's browser and local rendering context changes. `detail` contains the changed fields and a full current snapshot. |
-| `onMeasureChange?` | (event, detail) => void | — | Fired when a selected measurement field changes. `detail` contains all fields changed since the last event and a full current snapshot. |
+| `onMeasureChange?` | (event, detail) => void | — | 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. |
 | `padding?` | number \| string | — | Inner spacing, matching CSS `padding`. Numbers are pixels; strings accept CSS shorthand, percentages, and custom properties. Omission adds no style. |
 | `round?` | boolean \| number \| string | — | Fully-round corners (`border-radius: 999px`, clamped to the box). Pass a `number` (px) or a CSS length string (`'1rem'`) for a custom radius. Omit for square corners. |
-| `throttle?` | number | 0 | 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. |
+| `throttle?` | number | 0 | 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. |
 
 ### BoxMeasurement
 
@@ -307,6 +345,7 @@ const canvasRef = useRef<HTMLCanvasElement>(null)
 | `hiddenStartY` | boolean | — |  |
 | `overflowX` | boolean | — | Content exceeds the padding box on this axis, regardless of CSS overflow. |
 | `overflowY` | boolean | — |  |
+| `rects` | BoxRect[] | — | Matches for `includeRectsFor`, in document order. Empty when omitted. |
 | `scrollableX` | boolean | — | The exceeded content can be scrolled by the reader on this axis. |
 | `scrollableY` | boolean | — |  |
 | `scrollHeight` | number | — |  |
@@ -315,6 +354,19 @@ const canvasRef = useRef<HTMLCanvasElement>(null)
 | `scrollWidth` | number | — | Full scrollable-content dimensions, matching `scrollWidth` / `scrollHeight`. |
 | `width` | number | — | Border-box width and height in CSS pixels. |
 
+### BoxRect
+
+Coordinates and dimensions of a matched descendant's border box.
+
+| Field | Type | Default | Description |
+|------|------|---------|-------------|
+| `bottom` | number | — |  |
+| `height` | number | — |  |
+| `left` | number | — |  |
+| `right` | number | — |  |
+| `top` | number | — |  |
+| `width` | number | — |  |
+
 ### BoxContext
 
 | Field | Type | Default | Description |
@@ -381,7 +433,10 @@ Use `<a-box>` without JSX. Events are non-bubbling `CustomEvent`s with the same
 observation. Combine the eight selections with spaces, such as
 `observe="size edges"` or `observe="size scroll"`, in any order. Repeated tokens
 have no effect; unknown tokens are ignored. A bare `observe` means `"all"`.
-`throttle="100"` limits measurement events to a 100 ms interval.
+`throttle="100"` limits measurement reads, CSS state updates, and measurement
+events to a 100 ms interval.
+Add `observe-offscreen` to keep measurement observation active outside the
+viewport.
 
 ```html title="a-box"
 <a-box display="grid" gap="8px" round="12px" observe="all"
@@ -392,7 +447,9 @@ have no effect; unknown tokens are ignored. A bare `observe` means `"all"`.
 ```
 
 Import `@antadesign/anta/elements/a-box` to register the element. Listen for
-`measurechange` and `contextchange` with `addEventListener`.
+`measurechange` and `contextchange` with `addEventListener`. Set
+`include-rects-for=".marker"` to add matching descendant rects to each
+measurement without changing the observation triggers.
 `box.measurement`, `box.context`, and `box.isTruncated` read values synchronously.
 
 ## Styling