@acronis-platform/ui-react 5.5.9 → 7.0.0

package/dist/llms/chart-state.md

@@ -1,6 +1,6 @@
 # ChartState
 
-> A shared loading / empty / error placeholder for the chart types, rendered in place of the chart inside the same sized slot. A compact status block — a leading glyph over a centered label, with an optional retry action for the error state. The `empty` state draws the silhouette the design defines for each chart type (`variant`), plus an optional "Widget description" line; `loading` and `error` share one treatment. Distinct from `WidgetPlaceholder`, which is the composable skeleton for a widget that isn't a chart — see behavior.md.
+> Shared loading / empty / warning / error / number visuals for a chart slot. Empty, warning, and error use the Breakpoints visual treatment: a 64px status circle with a 24px glyph and centered message. Number shows a centered KPI value; loading uses the shared spinner. Consumers select the state and may localize its content through `description`. Distinct from `WidgetPlaceholder`, which is the composable skeleton for a non-chart widget.
 
 **Status:** draft · **Category:** data-display · **Since:** v0.58.0
 
@@ -14,190 +14,107 @@ import { ChartState } from '@acronis-platform/ui-react'
 
 ```tsx
 <ChartState state="loading" />
-<ChartState state="empty" variant="bar" description="No results for the selected range" />
-<ChartState
-  state="error"
-  action={<Button variant="ghost" onClick={refetch}>Try again</Button>}
-/>
+<ChartState state="empty" description={t('chart.noData')} />
+<ChartState state="warning" description={t('chart.partialData')} />
+<ChartState state="error" description={t('chart.loadError')} />
+<ChartState state="number" description="0 GB" />
 ```
 
-A shared loading / empty / error placeholder for the chart types. Render it in
-place of a chart — inside the same sized slot — while data is loading, when
-there is nothing to plot, or when the fetch failed.
+A shared visual state for one chart slot. Use it while chart data is loading,
+missing, incomplete, or has failed, or when a KPI should show its numeric empty
+value. Empty, warning, and error share the Breakpoints state circles; number
+uses the centered disabled-style KPI value; loading uses the shared spinner.
 
-> **Design-pending v1.** Ported from the Figma InputSelect dropdown states (the
-> reference node for this task) and kept visually in step with the shipped
-> `InputSelectStatus`. There is no `--ui-chart-*` token tier yet, so it themes
-> from existing semantic tokens directly.
-
-## When to use
-
-- A chart cannot render yet (data in flight), has no data to plot, or failed to
-  load — swap the chart for the matching `ChartState`.
-- You want the same placeholder across every chart type, rather than each chart
-  hand-rolling its own.
-
-## When not to use
-
-- A full-page empty state (illustration, title, description, primary action) —
-  use the larger `Empty` component instead.
-- A bare loading indicator with no surrounding message — use `Spinner` directly.
-
-## Example
+Consumers select the semantic state and pass localized or context-specific
+content through `description`. `ChartState` does not infer the state from data.
 
 ```tsx
-import { ChartState, ChartContainer, Button } from '@acronis-platform/ui-react';
-
-function Sales({ status, data, config, refetch }) {
-  if (status === 'loading') return <ChartState state="loading" />;
-  if (status === 'error')
-    return (
-      <ChartState
-        state="error"
-        action={
-          <Button variant="ghost" onClick={refetch}>
-            Try again
-          </Button>
-        }
-      />
-    );
-  if (!data.length) return <ChartState state="empty" />;
-
-  return (
-    <ChartContainer config={config} className="h-[300px] w-[500px]">
-      {/* …the chart… */}
-    </ChartContainer>
-  );
-}
+import { ChartState } from '@acronis-platform/ui-react';
+
+if (status === 'loading') return <ChartState state="loading" />;
+if (status === 'warning')
+  return <ChartState state="warning" description={t('chart.partialData')} />;
+if (status === 'error')
+  return <ChartState state="error" description={t('chart.loadError')} />;
+if (isEmptyKpi) return <ChartState state="number" description="0 GB" />;
+if (!data.length)
+  return <ChartState state="empty" description={t('chart.noData')} />;
 ```
 
-The three states share one compact layout: a leading glyph (spinner / inbox /
-warning) over a centered label. Pass `description` to override a state's default
-label, and `action` to add a retry affordance to the error state. Long unbroken
-error descriptions (CTI paths, API URLs) wrap at word boundaries and scroll
-vertically when they exceed the slot height.
+`ChartState` fills the chart's slot. It does not own the containing widget card
+or dashboard composition; see `ChartWidget` for a single chart card.
 
 ## Props
 
 | Prop | Type | Default | Required | Description |
 |------|------|---------|----------|-------------|
-| `state` | `'loading' | 'empty' | 'error'` | — | yes | Which placeholder to show. Drives the leading artwork and the default label (loading → spinner + "Data is loading…"; empty → variant silhouette or no artwork + "No data found"; error → warning glyph + "Something went wrong"). |
-| `variant` | `'area' | 'bar' | 'line' | 'donut' | 'radial' | 'funnel' | 'radar' | 'sankey' | 'scatter' | 'treemap' | 'table' | 'text'` | — | no | Which chart the slot holds. The `empty` state then draws that type's silhouette instead of the generic inbox glyph — the design defines one per chart type. `donut` and `radial` share a ring. Ignored by `loading` and `error`, which share one treatment. |
-| `description` | `ReactNode` | — | no | Text shown below the illustration or glyph. Defaults to `"Data is loading…"` / `"No data found"` / `"Something went wrong"` based on `state`. Pass a value to override for any state. |
-| `action` | `ReactNode` | — | no | Trailing action rendered for the `error` state only (e.g. a "Try again" button). |
+| `state` | `'loading' | 'empty' | 'warning' | 'error' | 'number'` | — | yes | Which state to show. Loading uses the shared spinner; empty, warning, and error use the shared circular status icon; number shows a centered disabled-style KPI value. Error is an assertive alert; other states are polite status messages. |
+| `description` | `ReactNode` | — | no | Localized or context-specific content. For `number`, this is the numeric readout. Defaults to "Data is loading…", "No data found", "Data may be incomplete", "Something went wrong", or "0". |
 
 ## Behavior
 
 ### Rendering per state
 
 - **Given** `state="loading"`, **when** rendered, **then** it shows the shared
-  `Spinner` (lg) above the label "Data is loading…" and announces the label via
-  its `role="status"` live region (no `aria-busy`, which could defer that
-  announcement).
-- **Given** `state="empty"`, **when** rendered, **then** it shows the label
-  "No data found" (no artwork unless a `variant` is passed).
-- **Given** `state="error"`, **when** rendered, **then** it shows the warning
-  glyph above the label "Something went wrong" and announces as an alert.
-
-### Label override
-
-- **Given** a `description` prop, **when** rendered in any state, **then** the
-  supplied text replaces that state's default label.
-
-### Action
-
-- **Given** an `action` node, **when** `state="error"`, **then** the action is
-  rendered after the label (e.g. a "Try again" button).
-- **Given** an `action` node, **when** `state` is `loading` or `empty`, **then**
-  the action is **not** rendered.
-
-### Layout
-
-- **Given** any state, **when** placed in a sized slot (the same box a chart
-  would occupy), **then** the block fills it (`size-full`) with a `min-h-32`
-  floor so it stays legible in an unsized parent.
-- **Given** `state="loading"` or `state="empty"`, **when** rendered, **then**
-  the content is vertically centered in the slot (`justify-center`).
-- **Given** `state="error"`, **when** the description is short enough to fit,
-  **then** the content is vertically centered via auto margins (`my-auto`).
-- **Given** `state="error"` with a long unbroken `description` (e.g. CTI error
-  paths, API URLs), **when** the text overflows the slot height, **then** the
-  auto margins collapse and the icon stays anchored at the top, with vertical
-  scroll (`overflow-y: auto`) so the full diagnostic text is accessible. Long
-  unbroken strings wrap at word boundaries (`overflow-wrap: break-word`),
-  breaking mid-word only when a single token cannot fit on one line.
-  `overflow-x: hidden` prevents any horizontal scrollbar.
-
-### Per-type empty states
-
-`empty` is the one state the design draws per chart type: an area silhouette for
-an area chart, a ring for a donut, a funnel for a funnel. An empty widget then
-still says what it _would_ have shown, which a single generic glyph can't.
-
-`variant` selects it. `donut` and `radial` share one ring — a radial-bar widget
-with no data has nothing to tell it apart. Without a `variant` the empty state
-shows no artwork — just the text.
-
-The geometry is exported from the Figma instances rather than redrawn, and every
-path is `currentColor`: the tone is set once on the container, so brand and theme
-overrides reach the artwork. Two of the eleven silhouettes use a second, fainter
-tone (the table and metric-list ones tint their header row darker than the body
-rows); that hierarchy is kept as `fill-opacity` on the same colour rather than a
-second token.
-
-The caption is **one line, in one style**. Figma styles it `body/default` on
-`text/onSurface/primary` — 14/24, centred, _not_ muted — which is what the root
-already applies, so the description and the fallback status label read
-identically. For a per-type empty state that line is the `description`: the mockups draw the silhouette over "Widget description" with no
-status label, because the artwork already says "no data" and the sentence worth
-the space is what the widget _would_ show. With no `description` it falls back to
-the status label, so a caller that only sets `variant` still reads sensibly.
-
-`loading` and `error` deliberately keep one shared treatment — the design only
-redesigned `empty`.
-
-### Not `WidgetPlaceholder`
-
-Two components, two jobs, and they are not interchangeable:
-
-- **`ChartState`** is the placeholder _inside_ a chart's slot. It fills whatever
-  gives the slot its height, renders one of three states, and is what a chart
-  widget swaps in for its plot.
-- **`WidgetPlaceholder`** is a composable skeleton with its own header, footer
-  and action parts, plus an `interactive` affordance — for a dashboard widget
-  that isn't a chart, or a whole tile that is still being set up.
-
-`WidgetPlaceholder` predates the per-type empty states and is used by consuming
-MFEs, so it stays.
+  large `Spinner` and the default message "Data is loading…".
+- **Given** `state="empty"`, **when** rendered, **then** it shows the neutral
+  circle with the `CircleMinusGray` glyph and the default message "No data
+  found".
+- **Given** `state="warning"`, **when** rendered, **then** it shows the warning
+  circle with the `TriangleWarningYellow` glyph and the default message "Data
+  may be incomplete".
+- **Given** `state="error"`, **when** rendered, **then** it shows the critical
+  circle with the `DiamondWarningRed` glyph and the default message "Something
+  went wrong".
+- **Given** `state="number"`, **when** rendered, **then** it shows the centered
+  disabled-style numeric value "0" without a state icon.
+- **Given** empty, warning, or error, **when** rendered, **then** the group is
+  centered and uses a 64px state circle, a 24px glyph, 12px separation, and
+  centered 14px / 24px text.
+
+### Copy
+
+- **Given** a `description`, **when** rendered in any state, **then** the supplied
+  content replaces that state's fallback message. Consumers provide localized
+  or context-specific copy.
+
+### Layout and overflow
+
+- **Given** any state, **when** placed in a chart slot, **then** the block fills
+  the slot without forcing a minimum height beyond its content.
+- **Given** loading, empty, or warning, **when** rendered, **then** the content
+  is centered in the slot.
+- **Given** `state="error"` with a short message, **when** rendered, **then**
+  the icon and message are vertically centered.
+- **Given** an error with a long message, **when** it exceeds the slot height,
+  **then** the icon remains fully visible, the state scrolls vertically, and
+  unbroken strings wrap within the available width.
+
+### Composition boundary
+
+`ChartState` controls the state visuals inside one chart slot. It does not set
+the chart-widget card border or arrange a group of widgets; those belong to
+their respective component or consuming application.
 
 ## Accessibility
 
-- The root is a **live region** so a screen reader announces the state change
-  when a chart swaps its content in:
-  - `loading` / `empty` → `role="status"` with `aria-live="polite"`.
-  - `error` → `role="alert"` with `aria-live="assertive"`.
-- On `loading` the shared `Spinner` is rendered `aria-hidden` so the root's own
-  live region (with the label) announces once, rather than the Spinner's
-  `role="status"` + sr-only "Loading…" nesting inside it and double-announcing.
-- The root does **not** carry `aria-busy`. It is itself the live region, and some
-  screen readers defer announcing a busy region's content until `aria-busy`
-  clears; because this placeholder is unmounted (swapped for the chart) rather
-  than un-busied, a busy flag would risk swallowing the "Data is loading…"
-  announcement. Put `aria-busy` on the chart-slot **container** instead if a busy
-  signal is needed (same guidance as `Skeleton`).
-- The live-region attributes (`role` / `aria-live`) are applied after the prop
-  spread, so the state's a11y contract is not clobbered by a consumer-passed
-  attribute.
-- The label text is a real `<p>`, so the state message is always in the
-  accessible tree — the glyph is decorative and does not need its own label.
-- **Do not rely on the glyph color alone** to convey the state — the label
-  carries the meaning. Icon colors (`--ui-glyph-on-status-info` /
-  `--ui-glyph-on-status-warning`) and the label (`--ui-text-on-surface-primary`)
-  resolve to semantic tokens that meet contrast in both themes.
-- If the error state offers a retry, pass an actual interactive control as
-  `action` (a `Button`) so it is focusable and keyboard-operable.
+- The root is the live region: loading, empty, warning, and number use
+  `role="status"` with `aria-live="polite"`; error uses `role="alert"` with
+  `aria-live="assertive"`.
+- The root live-region attributes are applied after the prop spread, so the
+  selected state's announcement semantics cannot be overwritten by consumer
+  props.
+- The loading Spinner and state glyphs are decorative. The displayed content
+  supplies the state meaning independently of icon color.
+- The root does not carry `aria-busy`. This placeholder is unmounted when the
+  chart replaces it, and some screen readers defer announcements inside a busy
+  region. Put `aria-busy` on the chart-slot container if a busy signal is needed.
+- Long error text can scroll vertically, and long unbroken strings wrap within
+  the available width.
 
 ## Contrast
 
-Label and glyph colors resolve to semantic `--ui-*` tokens that meet contrast on
-the surface in both light and dark themes.
+Message text uses `--ui-text-on-surface-primary`. The state glyphs are the
+multi-color design assets, placed on semantic neutral, warning, and critical
+background tokens. The textual message communicates meaning without relying on
+color.

package/dist/llms/chart-widget.md

@@ -1,6 +1,6 @@
 # ChartWidget
 
-> The dashboard card a chart sits in: a `Card` with the standard widget header (title, optional filter chip and the ⋯ actions menu) and an optional metric readout above the plot. Adds the one thing a `Card` doesn't know about — the body's loading / empty / error placeholder — and re-implements nothing else: its `header` is `CardHeaderProps`, spread. It declares no size: the grid sizes the card and the widget passes that height down, so a `size-full` chart fills whatever the header leaves. The per-type chart components stay card-less, so a chart is still usable outside a widget.
+> The dashboard card a chart sits in: a `Card` with the standard widget header (title, optional filter chip and the ⋯ actions menu) and an optional metric readout above the plot. Adds the one thing a `Card` doesn't know about — the body's loading / empty / warning / error / number state — and re-implements nothing else. The consumer selects the state explicitly; the widget does not infer it from chart data. its `header` is `CardHeaderProps`, spread. It declares no size: the grid sizes the card and the widget passes that height down, so a `size-full` chart fills whatever the header leaves. The per-type chart components stay card-less, so a chart is still usable outside a widget.
 
 **Status:** draft · **Category:** data-display · **Since:** v2.1.0
 
@@ -35,10 +35,11 @@ readout, then the plot. `ChartWidget` is that composition — and only that.
 
 ## What it adds
 
-One thing a `Card` legitimately doesn't know about: **what the body shows while
-there is no plot.** `state="loading" | "empty" | "error"` renders `ChartState` in
-place of the chart, and `error` also gives the Card its error border — one prop,
-not two.
+One thing a `Card` legitimately doesn't know about: **what the body shows for
+an explicitly selected state.** `state="loading" | "empty" | "warning" |
+"error" | "number"` renders `ChartState` in place of the metric and chart. The
+consumer chooses the state; the widget does not infer it from data. Card chrome
+remains consistent for each state.
 
 ## What it doesn't add
 
@@ -63,7 +64,7 @@ the rest of the card. See `behavior.md`.
 | ------------------ | ------------------------------------------------------------------ |
 | `index.yaml`       | Identity, category, status, `since`.                               |
 | `api.yaml`         | The prop contract and the per-framework adapters.                  |
-| `anatomy.yaml`     | Parts, the schematic, and the four body states.                    |
+| `anatomy.yaml`     | Parts, the schematic, and the five widget states.                  |
 | `behavior.md`      | Composition, how the height reaches the plot, state, localization. |
 | `accessibility.md` | Roles, the placeholder's live region, header controls.             |
 | `tokens.yaml`      | The `--ui-*` tokens the widget references.                         |
@@ -87,12 +88,10 @@ chart.
 | `header` | `CardHeaderProps` | — | no | The card header, forwarded verbatim to `CardHeader` — `title`, `description`, `extras` (a filter chip), `actions` (the ⋯ menu), `isDraggable`, `isSwitchable`, `hasAvatar`, `hasRename`, `isCollapsible`. Omit for a header-less widget. |
 | `orientation` | `'vertical' | 'horizontal'` | `vertical` | no | How the `metric` and plot are arranged inside the card body. `vertical` (default) — metric above the plot, full width; the metric takes its natural height and the plot fills the rest. `horizontal` — metric and plot side by side, each `flex-1`; use for compact (sm/288px) widgets where vertical space is at a premium. |
 | `metric` | `ReactNode` | — | no | The readout beside or above the plot (depending on `orientation`), typically a `Metric`. |
-| `variant` | `'area' | 'bar' | 'line' | 'donut' | 'radial' | 'funnel' | 'radar' | 'sankey' | 'scatter' | 'treemap' | 'table' | 'text'` | — | no | Which chart the widget holds. Only used while `state="empty"`, to pick the silhouette for that chart type. Forwarded to `ChartState`. |
-| `state` | `'loading' | 'empty' | 'error'` | — | no | Renders `ChartState` in place of the plot, keeping the header. `error` additionally gives the Card its error border. |
-| `stateDescription` | `ReactNode` | — | no | Text below the placeholder illustration or glyph. Forwarded to `ChartState` as `description`. Defaults to the per-state built-in ("Data is loading…" / "No data found" / "Something went wrong"). |
-| `stateAction` | `ReactNode` | — | no | Trailing action on the `error` placeholder — e.g. a retry button. |
+| `state` | `'loading' | 'empty' | 'warning' | 'error' | 'number'` | — | no | Renders `ChartState` in place of the metric and plot, keeping the header. The consumer selects the state; no state is inferred from the data. Card chrome remains consistent for all states. |
+| `stateDescription` | `ReactNode` | — | no | Localized or context-specific content shown by `ChartState`. For `number`, pass the numeric value and unit. Defaults to per-state fallback content, including `0` for `number`. |
 | `bodyClassName` | `string` | — | no | Class for the card body. Rarely needed — the body already fills the card. For the case where neither the grid nor the content gives a height, e.g. a placeholder-only widget outside a sized cell. |
-| `children` | `ReactNode` | — | no | The chart. Replaced by the placeholder while `state` is set. |
+| `children` | `ReactNode` | — | no | The selected state replaces this chart and the metric while `state` is set. |
 | `render` | `useRender.RenderProp` | — | no | Replace the rendered `<div>` with another element or component (Base UI composition), forwarded to `Card`. How a dashboard gives each widget a landmark role — `render={<section aria-label="Sessions" />}` — which is the one thing the widget can't infer for itself. |
 
 ## Behavior
@@ -142,21 +141,23 @@ design constraint, and hard-coding them would have fought the grid.
 
 ### State
 
-`state` renders `ChartState` **instead of** `children`. The header stays.
+The consumer selects `state` explicitly; the widget does not infer it from chart
+data. When set, `ChartState` replaces both the `metric` and `children`. The
+header stays. The `number` state shows a centered numeric KPI value.
 
-`state="error"` also maps to `Card`'s `hasError`, so the error border and the
-error placeholder come from one prop. A caller can't get one without the other,
-which is what the mockups draw.
+The card surface and border remain the same for loading, empty, warning, error,
+and number. State-specific visuals are contained within `ChartState` in the
+body.
 
-`ChartState` owns the live-region contract (`role="status"` for loading/empty,
-`role="alert"` for error), so the announcement follows the placeholder rather
-than being re-declared on the widget.
+`ChartState` owns the live-region contract (`role="status"` for loading, empty,
+warning, and number; `role="alert"` for error), so the announcement follows
+the state rather than being re-declared on the widget.
 
 ### Localization
 
-Every string is the caller's: the header's `title` / `description`, the metric's
-own labels, `stateDescription`, and the label inside `stateAction`. The only
-literals are `ChartState`'s per-state defaults, which `stateDescription` overrides.
+The header's `title` / `description`, the metric's labels, and
+`stateDescription` can be supplied by the consumer. The `stateDescription`
+prop lets applications localize or contextualize the state content.
 
 ## Accessibility
 
@@ -187,7 +188,7 @@ name, so a chart inside should not repeat it in its own accessible name.
 ## The placeholder is the live region
 
 While `state` is set, `ChartState` is the live region — `role="status"`
-(`aria-live="polite"`) for loading and empty, `role="alert"`
+(`aria-live="polite"`) for loading, empty, warning, and number; `role="alert"`
 (`aria-live="assertive"`) for error. The widget deliberately does **not** add
 `aria-busy` around it: the placeholder is unmounted and replaced by the plot
 rather than un-busied, and some assistive tech defers announcing a busy region's
@@ -203,7 +204,8 @@ switch, rename button and collapse trigger each take a label prop with a
 default, and the `actions` slot is the caller's own control (an icon button
 needs its own `aria-label` — the mockups' ⋯ menu has no visible text).
 
-## Colour is not the only signal
+## State meaning
 
-`state="error"` changes the card's border colour, but the placeholder also
-carries an icon and a message, so the error is not conveyed by colour alone.
+The widget card border stays consistent across states. `ChartState` supplies a
+state icon and message (or the numeric KPI value), so meaning does not rely on
+color alone.

package/dist/llms/data-table.md

@@ -72,10 +72,12 @@ from it too (see **Server-driven usage** below).
 - **Infinite scroll** — set `paginationMode="infinite"` and pass the full
   accumulated `data`, `hasNextPage`, `isLoadingMore`, and an `onLoadMore`
   callback. DataTable renders a sentinel row that calls `onLoadMore` once it
-  scrolls into view, and a trailing loading row while `isLoadingMore` is true.
-  The sentinel needs at least one row already rendered — it can't drive an
-  empty table's very first fetch, so seed the first page yourself (e.g. on
-  mount). Pass `loadMoreRootMargin` (e.g. `'400px'`) to fire `onLoadMore`
+  scrolls into view. While `isLoadingMore` is true, it hides the sentinel and
+  shows a centered status row with "Loading more data..."; override
+  `loadingMoreLabel` to localize it. Loaded rows stay visible. The `skeleton`
+  prop remains the initial-load treatment. The sentinel needs at least one row
+  already rendered — it can't drive an empty table's very first fetch, so seed
+  the first page yourself (e.g. on mount). Pass `loadMoreRootMargin` (e.g. `'400px'`) to fire `onLoadMore`
   before the sentinel is literally visible, so the fetch has a head start on
   the user's scroll — tune it relative to your page size, since a large
   margin with small pages can trigger several `onLoadMore` calls back-to-back
@@ -153,13 +155,13 @@ as `children` of the toolbar for per-column filtering.
 | `expand-label` | `string` | `'Expand row'` | no | On the expand-trigger part — accessible name while the row is collapsed. Override to localize. |
 | `collapse-label` | `string` | `'Collapse row'` | no | On the expand-trigger part — accessible name while the row is expanded. Override to localize. |
 | `sort-label` | `(title: string) => string` | `(title) => `Sort by ${title}`` | no | On the column-header part — builds the accessible label of the sort toggle from the column title. Override to localize. |
-| `table` | `Table<TData>` | — | no | Render from an externally-built TanStack `table` instance instead of DataTable's own — DataTable then owns no state. Makes the following no-ops (configure the equivalent on the external instance instead): columnVisibility, onColumnVisibilityChange, onColumnSizingChange, enableColumnResizing, getRowCanExpand, manualSorting, sorting, onSortingChange, paginationMode, onLoadMore, loadMoreRootMargin, hasNextPage, isLoadingMore. meta.pin-driven column pinning is also skipped — pin/unpin the external instance directly via TanStack's `column.pin()`. |
+| `table` | `Table<TData>` | — | no | Render from an externally-built TanStack `table` instance instead of DataTable's own — DataTable then owns no state. Makes the following no-ops (configure the equivalent on the external instance instead): columnVisibility, onColumnVisibilityChange, onColumnSizingChange, enableColumnResizing, getRowCanExpand, manualSorting, sorting, onSortingChange, paginationMode, onLoadMore, loadMoreRootMargin, hasNextPage, isLoadingMore, loadingMoreLabel. meta.pin-driven column pinning is also skipped — pin/unpin the external instance directly via TanStack's `column.pin()`. |
 | `getRowCanExpand` | `(row: Row<TData>) => boolean` | — | no | Enables row expansion for rows that return true. Pair with renderExpandedRow. |
 | `renderExpandedRow` | `(row: Row<TData>) => ReactNode` | — | no | Renders the detail content for an expanded row. |
 | `striped` | `boolean` | `false` | no | Alternating row backgrounds (borrowed from the Vue AvTable). |
 | `bordered` | `boolean` | `false` | no | Vertical borders between columns (rows already have horizontal borders). |
 | `highlightCurrentRow` | `boolean` | `false` | no | Highlight the row the user last clicked (the "current" row). |
-| `skeleton` | `boolean` | `false` | no | Render placeholder skeleton rows instead of data (loading state). |
+| `skeleton` | `boolean` | `false` | no | Render shared Skeleton placeholders for initial loading, replacing the data rows while keeping the header visible. |
 | `skeletonRows` | `number` | `5` | no | Number of skeleton rows when skeleton is set. |
 | `enableColumnResizing` | `boolean` | `false` | no | Opt in to interactive column resizing — renders a drag handle at the trailing edge of each resizable header (TanStack's native `columnResizing`, `columnResizeMode: 'onChange'`). |
 | `enableColumnReordering` | `boolean` | `false` | no | Opt in to column reordering by dragging a header cell onto another one (native HTML5 drag-and-drop driving TanStack's `columnOrder`; the dragged header dims while the gesture is in flight). Pinned columns are excluded — they're anchored to a table edge by definition. Pointer-only: there is no keyboard equivalent yet. No-op when `table` is passed. |
@@ -188,9 +190,10 @@ as `children` of the toolbar for per-column filtering.
 | `renderRow` | `(row: Row<TData>, rowIndex: number) => ReactNode` | — | no | Renders a full row, bypassing DataTable's default per-cell `flexRender` path entirely. Use to swap in a custom, independently memoizable row component — the caller owns the row's markup and equality semantics. Reuse the exported `getCellStyle` / `getPinnedStyle` / `getColumnWidth` helpers to match DataTable's default cell styling if desired. Also bypasses `renderExpandedRow` — a row rendered via `renderRow` never gets an expanded-content row appended; read `row.getIsExpanded()` and render it yourself if needed. |
 | `renderEmptyState` | `(context: { hasFilters: boolean }) => ReactNode` | — | no | Renders a custom empty state instead of the default "No results." row. Receives `hasFilters` (whether any column filter is currently applied) so the caller can distinguish "no data at all" from "no matches" — the copy/wording/localization stays the caller's job. |
 | `paginationMode` | `'page' | 'infinite'` | `'page'` | no | `'page'` keeps today's client-paginated behavior. `'infinite'` omits the paginated row model — `data` is the full accumulated array the caller appends to on each `onLoadMore` — and renders a sentinel row that calls `onLoadMore` once it scrolls into view. The sentinel requires at least one row already rendered, so it cannot drive an empty table's very first fetch — seed the first page yourself (e.g. on mount) and use `onLoadMore` for subsequent pages. No-op when `table` is passed. Does not compose with virtualization; for a large accumulated list, virtualize the raw `Table` primitives yourself instead. |
-| `loadMoreRootMargin` | `string` | — | no | Expands the sentinel's `IntersectionObserver` root margin (native CSS margin syntax, e.g. "400px") so `onLoadMore` fires before the sentinel is literally visible, reducing how often the trailing loading row is seen. `paginationMode="infinite"` only; no-op when `table` is passed. How far this actually prefetches also depends on page size — a large margin with small pages can trigger several `onLoadMore` calls back-to-back as the user scrolls normally, which is expected; tune it relative to page size. |
+| `loadMoreRootMargin` | `string` | — | no | Expands the sentinel's `IntersectionObserver` root margin (native CSS margin syntax, e.g. "400px") so `onLoadMore` fires before the sentinel is literally visible, reducing how often the trailing loading status row is seen. `paginationMode="infinite"` only; no-op when `table` is passed. How far this actually prefetches also depends on page size — a large margin with small pages can trigger several `onLoadMore` calls back-to-back as the user scrolls normally, which is expected; tune it relative to page size. |
 | `hasNextPage` | `boolean` | `false` | no | Whether more rows are available to load. `paginationMode="infinite"` only. |
-| `isLoadingMore` | `boolean` | `false` | no | Whether a load is in flight — suppresses further `onLoadMore` calls and renders a trailing loading row. `paginationMode="infinite"` only. |
+| `isLoadingMore` | `boolean` | `false` | no | Whether a load is in flight — suppresses further `onLoadMore` calls and renders a centered status row with `loadingMoreLabel`. The observer sentinel is omitted while loading. `paginationMode="infinite"` only; no-op when `table` is passed. |
+| `loadingMoreLabel` | `string` | `'Loading more data...'` | no | Visible text in the infinite-scroll loading status row. Override to localize. `paginationMode="infinite"` only; no-op when `table` is passed. |
 
 ## Events
 
@@ -264,12 +267,18 @@ Scenario: Custom row rendering
 Scenario: Infinite scroll
   Given paginationMode="infinite" and hasNextPage is true
   And at least one row is already rendered
-  Then a sentinel row renders as the last row of the body
+  And isLoadingMore is false
+  Then an aria-hidden sentinel row renders after the loaded rows
   When the sentinel scrolls into view and isLoadingMore is false
   Then onLoadMore fires
   And no further onLoadMore calls fire while isLoadingMore is true
   When isLoadingMore is true
-  Then a trailing loading row renders below the sentinel
+  Then the sentinel is omitted
+  And a centered status row renders after the loaded rows
+  And the status row shows loadingMoreLabel (default "Loading more data...")
+  And the status row carries role="status" and aria-live="polite"
+  When isLoadingMore becomes false and hasNextPage is still true
+  Then the sentinel renders again
 ```
 
 ```gherkin
@@ -509,10 +518,11 @@ Scenario: Selection counts under an active filter — two deliberate scopes
   renders no tooltip.
 - Per-column filter fields live in a keyboard-navigable `FilterSearchFilters`
   popover; each applied-filter chip below the toolbar removes its own filter.
-- The infinite-scroll loading row (`paginationMode="infinite"`, `isLoadingMore`)
-  carries `role="status"`/`aria-live="polite"` with an `sr-only` "Loading more
-  rows…" text, so a screen-reader user is told a fetch is in flight without
-  having to notice the animated placeholder.
+- The infinite-scroll loading status row (`paginationMode="infinite"`,
+  `isLoadingMore`) visibly shows `loadingMoreLabel` (default "Loading more
+  data...") and carries `role="status"`/`aria-live="polite"`. Override
+  `loadingMoreLabel` to localize the message. The observer sentinel is omitted
+  while this status row is shown.
 
 ## Known limitations
 

package/dist/llms/dialog-root.md

@@ -58,19 +58,19 @@ decision. Composable from parts; built on the Base UI Dialog primitive.
 
 ## Parts
 
-| Part                             | Element (default)  | Purpose                                           |
-| -------------------------------- | ------------------ | ------------------------------------------------- |
-| `DialogRoot`                     | —                  | Root; owns the open state (Base UI `Root`).       |
-| `DialogTrigger`                  | `button`           | Opens the dialog.                                 |
-| `DialogContent`                  | `div[role=dialog]` | The portaled, centered popup (+ overlay).         |
-| `DialogHeaderRoot`               | `div`              | Top bar; holds the title and close button.        |
-| `DialogTitle`                    | `h2`               | Accessible dialog name (`aria-labelledby`).       |
-| `DialogCloseButton`              | `button`           | Icon button that dismisses the dialog.            |
-| `DialogBodyRoot`                 | `div`              | Scrollable content region.                        |
-| `DialogDescription`              | `p`                | Supporting copy (`aria-describedby`).             |
-| `DialogFooterRoot`               | `div`              | Right-aligned action bar.                         |
-| `DialogClose`                    | `button`           | Closes the dialog; wrap a Button via `render`.    |
-| `DialogOverlay` / `DialogPortal` | —                  | Lower-level parts (`DialogContent` renders them). |
+| Part                             | Element (default)  | Purpose                                                                                  |
+| -------------------------------- | ------------------ | ---------------------------------------------------------------------------------------- |
+| `DialogRoot`                     | —                  | Root; owns the open state (Base UI `Root`).                                              |
+| `DialogTrigger`                  | `button`           | Opens the dialog.                                                                        |
+| `DialogContent`                  | `div[role=dialog]` | The portaled popup (+ overlay); centered by default, or top-aligned via `verticalAlign`. |
+| `DialogHeaderRoot`               | `div`              | Top bar; holds the title and close button.                                               |
+| `DialogTitle`                    | `h2`               | Accessible dialog name (`aria-labelledby`).                                              |
+| `DialogCloseButton`              | `button`           | Icon button that dismisses the dialog.                                                   |
+| `DialogBodyRoot`                 | `div`              | Scrollable content region.                                                               |
+| `DialogDescription`              | `p`                | Supporting copy (`aria-describedby`).                                                    |
+| `DialogFooterRoot`               | `div`              | Right-aligned action bar.                                                                |
+| `DialogClose`                    | `button`           | Closes the dialog; wrap a Button via `render`.                                           |
+| `DialogOverlay` / `DialogPortal` | —                  | Lower-level parts (`DialogContent` renders them).                                        |
 
 ## Sizes
 
@@ -79,6 +79,12 @@ decision. Composable from parts; built on the Base UI Dialog primitive.
 `large` (832px) is a legacy backward-compatibility size with no design token,
 kept for existing call sites (see the public `Dialog` recipe's `wide` variant).
 
+## Placement
+
+`DialogContent` takes a `verticalAlign` prop: `center` (default) centers the
+popup in the viewport; `top` pins it 48px from the top edge, horizontally
+centered, keeping its content height (still capped at `100dvh - 96px`).
+
 ## Example (internal usage only)
 
 ```tsx
@@ -124,6 +130,7 @@ import { Button } from '../button';
 | `default-open` | `boolean` | `false` | no | Initial open state when uncontrolled. |
 | `modal` | `boolean | 'trap-focus'` | `true` | no | Modal behavior — traps focus and locks background scroll while open. `'trap-focus'` keeps the focus trap but allows background interaction. |
 | `size` | `'sm' | 'large'` | `'sm'` | no | Popup max-width (on the content part). `sm` (512px) has a Figma-defined token (`--ui-dialog-container-size-sm`); `large` (832px) is a legacy backward-compatibility size with no design token, kept for existing call sites (see the public `Dialog` recipe's `wide` variant). |
+| `verticalAlign` | `'center' | 'top'` | `'center'` | no | Vertical placement of the popup (on the content part). `center` (the default) centers it in the viewport; `top` pins it 48px from the top edge of the viewport instead, keeping its content height. A ui-react-only extension beyond the Figma contract, like `size="large"`. |
 | `portal` | `boolean` | `true` | no | Render the content inside a portal (the content part). Required by the underlying primitive for correct stacking; disable only when supplying your own portal ancestor. |
 | `render` | `RenderProp` | `undefined` | no | Composition prop available on the trigger, close, title, description, and other primitive parts — replaces the rendered element with another component (e.g. render the trigger as a Button) while merging props. React-only; other frameworks use their own polymorphism. |
 
@@ -205,6 +212,26 @@ Scenario: Modal locks the background (default)
   inside the dialog until it closes
 ```
 
+### Placement
+
+```gherkin
+Scenario: The popup is centered by default
+  Given a DialogRoot whose DialogContent has no verticalAlign (or
+  verticalAlign = "center")
+  When it opens
+  Then the popup is centered in the viewport, horizontally and vertically
+```
+
+```gherkin
+Scenario: verticalAlign = "top" pins the popup near the top edge
+  Given a DialogRoot whose DialogContent has verticalAlign = "top"
+  When it opens
+  Then the popup's top edge sits 48px below the top of the viewport
+  And it stays horizontally centered
+  And it keeps its content height (still capped at 100dvh - 96px), leaving
+  the viewport below it empty
+```
+
 ## Accessibility
 
 DialogRoot leans on the Base UI Dialog primitive for its modal semantics,