@acronis-platform/ui-react 3.0.0 → 4.1.0

package/dist/llms/calendar.md

@@ -0,0 +1,188 @@
+# Calendar
+
+> A day-grid built on react-day-picker: single / range / multiple date selection across one or more months side by side, with prev/next navigation at the outer edges of the month row. Design-pending v1 ported from ui-legacy — themed off the shared semantic tokens (no `--ui-calendar-*` tier yet).
+
+**Status:** draft · **Category:** forms · **Since:** v0.56.0
+
+## Import
+
+```tsx
+import { Calendar } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+const [selected, setSelected] = React.useState<Date>();
+
+<Calendar mode="single" selected={selected} onSelect={setSelected} />
+
+{/* Two-month range */}
+<Calendar
+  mode="range"
+  numberOfMonths={2}
+  selected={range}
+  onSelect={setRange}
+/>
+```
+
+A day-grid for picking dates, built on
+[`react-day-picker`](https://daypicker.dev/) and re-themed to the Acronis UI Kit's
+semantic tokens.
+
+> **Design-pending v1.** Ported from `@acronis-platform/shadcn-uikit` before a
+> "ready for dev" Figma node exists. It is themed off the shared semantic
+> vocabulary (no `--ui-calendar-*` token tier yet); reconcile against the real
+> design with `/figma-component Calendar <url> --update` once mockups land.
+
+## When to use
+
+- Selecting a single date, a set of dates, or a start–end range in place.
+- As the grid inside a date-field popover (see `DateRangePicker`, `InputDatePicker`).
+
+## When not to use
+
+- For a compact date **field** with a popover trigger, compose `InputDatePicker`
+  (single) or `DateRangePicker` (range) instead of embedding the bare grid.
+
+## Examples
+
+```tsx
+import { Calendar } from '@acronis-platform/ui-react';
+
+// Single date
+const [date, setDate] = React.useState<Date>();
+<Calendar mode="single" selected={date} onSelect={setDate} />;
+
+// Two-month range
+<Calendar
+  mode="range"
+  numberOfMonths={2}
+  selected={range}
+  onSelect={setRange}
+/>;
+
+// Disabled weekends + specific dates
+<Calendar
+  mode="single"
+  disabled={[{ dayOfWeek: [0, 6] }, new Date(2026, 6, 4)]}
+/>;
+```
+
+## Parts
+
+| Part      | Element             | Notes                                          |
+| --------- | ------------------- | ---------------------------------------------- |
+| `nav`     | `<button>` pair     | Previous / next, at the outer edges of the row |
+| `caption` | `<div>`             | "Month Year" label per month                   |
+| `weekday` | `<div>`             | Weekday column header                          |
+| `grid`    | `<table role=grid>` | One per month                                  |
+| `day`     | `<button>`          | Selectable day                                 |
+| `outside` | `<button>`          | Adjacent-month filler day (optional)           |
+
+Selection mode, month count, and every other `react-day-picker` prop pass through.
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `mode` | `'single' | 'multiple' | 'range'` | `single` | no | Selection mode — a single date, a set of dates, or a start–end range. |
+| `selected` | `Date | Date[] | DateRange` | — | no | The current selection (controlled). Shape depends on `mode`: a `Date` for single, `Date[]` for multiple, `{ from, to }` for range. |
+| `number-of-months` | `number` | `1` | no | How many months to render side by side. |
+| `show-outside-days` | `boolean` | `true` | no | Show days from the previous/next month to fill the first/last week. |
+| `caption-layout` | `'label' | 'dropdown' | 'dropdown-months' | 'dropdown-years'` | `label` | no | How the month/year caption is rendered (plain label or dropdowns). |
+| `disabled` | `Matcher | Matcher[]` | — | no | Day(s) that cannot be selected. Accepts a date, a range, a predicate, a day-of-week matcher, or `true` to disable all days. |
+| `default-month` | `Date` | — | no | The month rendered first (uncontrolled navigation). |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `select` | `selected` | Fired when the selection changes (React: `onSelect`). The payload matches the `selected` shape for the current `mode`. |
+
+## Behavior
+
+Design-pending v1 ported from `@acronis-platform/shadcn-uikit`'s `calendar`.
+Behavior is provided by `react-day-picker`'s `DayPicker`; this component only
+re-themes the grid.
+
+### Single selection
+
+- **Given** `mode="single"`, **when** the user clicks a day, **then** `onSelect`
+  fires with that `Date` and the day paints the brand fill
+  (`--ui-background-brand-primary` / `--ui-glyph-on-brand-primary`).
+- **Given** a selected day, **when** the user clicks it again, **then** the
+  selection clears (`onSelect` fires with `undefined`).
+
+### Range selection
+
+- **Given** `mode="range"`, **when** the user clicks a first day, **then**
+  `onSelect` fires with `{ from }` and that day becomes the range start.
+- **When** the user clicks a second day, **then** `onSelect` fires with
+  `{ from, to }`; the start and end days paint the brand fill and the days between
+  them get the range-middle band (`--ui-background-surface-hover`).
+
+### Multiple months
+
+- **Given** `numberOfMonths={2}`, **then** two month grids render side by side and
+  a single previous / next button pair sits at the outer edges of the row (not one
+  pair per month). Clicking next advances **both** months.
+
+### Navigation
+
+- **When** the user clicks the previous / next button, **then** the displayed
+  month(s) shift by one. A nav button at the edge of the allowed range is disabled
+  and paints `--ui-text-on-surface-disabled`.
+
+### Disabled days
+
+- **Given** a `disabled` matcher, **then** matched days are non-interactive
+  (`disabled` attribute) and paint `--ui-text-on-surface-disabled`; clicking them
+  does not fire `onSelect`.
+
+### Today & outside days
+
+- The current day is decorated with a bold, underlined label (no color
+  dependency); the underline is dropped when the day is also selected.
+- With `showOutsideDays` (default), leading/trailing days from the adjacent months
+  fill the grid and render in `--ui-text-on-surface-secondary`.
+
+## Accessibility
+
+Accessibility is provided by `react-day-picker`, which follows the ARIA
+[grid pattern](https://www.w3.org/WAI/ARIA/apg/patterns/grid/) for the day grid.
+
+## Roles & structure
+
+- The root is a calendar application region; each month renders as a
+  `<table role="grid">` with column headers for the weekdays.
+- Each day is a `<button>` inside a grid cell. Selected days expose
+  `aria-selected`; disabled days set the `disabled` attribute.
+- The previous / next controls are labelled buttons; a control that would move
+  past the allowed range is `aria-disabled`.
+
+## Keyboard
+
+| Key                   | Action                                          |
+| --------------------- | ----------------------------------------------- |
+| `Arrow Left/Right`    | Move focus to the previous / next day           |
+| `Arrow Up/Down`       | Move focus to the same weekday of the adj. week |
+| `Home` / `End`        | First / last day of the week                    |
+| `PageUp` / `PageDown` | Previous / next month                           |
+| `Shift+PageUp/Down`   | Previous / next year                            |
+| `Enter` / `Space`     | Select the focused day                          |
+
+Roving focus: only the active day is in the tab order; arrow keys move focus and
+auto-advance the visible month when crossing a boundary.
+
+## Focus
+
+- The focused day shows a 3px `--ui-focus-primary` ring, raised above its
+  neighbours (`z-10`) so the ring is never clipped by an adjacent selected fill.
+
+## Contrast
+
+- Selected days pair `--ui-background-brand-primary` with
+  `--ui-glyph-on-brand-primary`; idle days use `text-foreground` on the calendar
+  surface. Outside/disabled days use the secondary/disabled text tokens, which are
+  intentionally lower-emphasis but remain within the palette's contrast budget.

package/dist/llms/card-filter.md

@@ -0,0 +1,214 @@
+# CardFilter
+
+> A compact stat/filter card: a caption label above a prominent value, with an optional leading icon. Three variants — `static` (presentational), `static-empty` (presentational placeholder with an em-dash), and `clickable` (an interactive filter that renders a button with hover / active / focus states).
+
+**Status:** ready · **Category:** data-display · **Since:** v0.26.0
+
+## Import
+
+```tsx
+import { CardFilter } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+<CardFilter variant="static" label="Total assets" value="125" icon={<CircleInfoIcon />} />
+
+{/* Clickable filter, selected is controlled */}
+<CardFilter
+  variant="clickable"
+  label="Active filters"
+  value="3"
+  selected={selected}
+  onClick={() => setSelected((prev) => !prev)}
+/>
+
+{/* Polymorphic: render as a link */}
+<CardFilter variant="clickable" label="Alerts" value="12" render={<a href="/alerts" />} />
+```
+
+A compact stat/filter card: a caption label above a prominent value, with an
+optional leading icon. Use it for dashboard metrics and for clickable filter
+chips that summarize a count.
+
+## When to use
+
+- Surfacing a single metric or count with a short label (e.g. "Active filters 3").
+- A clickable summary that applies or navigates to a filtered view
+  (`variant="clickable"`).
+- An empty/placeholder metric slot (`variant="static-empty"`).
+
+## When not to use
+
+- For rich, multi-field content — use a general Card/Panel instead.
+- For a primary call to action — use `Button` / `ButtonMenu`.
+
+## Variants
+
+| variant        | Interactive | Value color                                | Notes                          |
+| -------------- | ----------- | ------------------------------------------ | ------------------------------ |
+| `static`       | no          | `--ui-card-filter-static-value-color-idle` | Default presentational card.   |
+| `static-empty` | no          | `…-static-value-color-disabled`            | No icon; shows an em-dash `–`. |
+| `clickable`    | yes         | `--ui-card-filter-clickable-value-color`   | Renders a `<button>`.          |
+
+## Examples
+
+```tsx
+import { CardFilter } from '@acronis-platform/ui-react';
+import { CircleInfoIcon } from '@acronis-platform/icons-react/stroke-mono';
+
+// Static metric
+<CardFilter label="Total assets" value="125" icon={<CircleInfoIcon />} />;
+
+// Empty placeholder
+<CardFilter variant="static-empty" label="Pending" />;
+
+// Clickable filter
+<CardFilter
+  variant="clickable"
+  label="Active filters"
+  value="3"
+  icon={<CircleInfoIcon />}
+  onClick={applyFilter}
+/>;
+
+// Polymorphic: render as a link
+<CardFilter
+  variant="clickable"
+  label="Alerts"
+  value="12"
+  render={<a href="/alerts" />}
+/>;
+```
+
+## Parts
+
+| Part    | Element              | Description                                      |
+| ------- | -------------------- | ------------------------------------------------ |
+| `root`  | `<button>` / `<div>` | Card surface; interactive only for `clickable`.  |
+| `label` | `<span>`             | Caption above the value (12px).                  |
+| `icon`  | `<svg>`              | Optional 16px leading glyph (hidden when empty). |
+| `value` | `<span>`             | Prominent value (24px); colored per variant.     |
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `variant` | `'static' | 'static-empty' | 'clickable'` | `'static'` | no | Visual style and interactivity. `static` is presentational with a default value color; `static-empty` is a presentational placeholder (no icon, a muted em-dash); `clickable` renders an interactive `<button>` with a link-colored value and hover / active / focus states. Per the design, only `clickable` has states beyond idle. |
+| `selected` | `boolean` | — | no | `clickable` only. Controlled — applies the selected (active) styling and exposes the card as a pressed toggle (`aria-pressed`/`data-selected`). The consumer owns the state and flips it in the `click` handler; there is no internal state and no uncontrolled default. |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `click` | `MouseEvent` | Fired on activation (pointer or keyboard) of the `clickable` variant. Typically applies the filter the card represents. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `label` | The caption shown above the value. Plain text or inline nodes. |
+| `value` | The prominent value. Ignored for `static-empty` (which shows an em-dash placeholder). |
+| `icon` | Optional leading glyph (16px) rendered before the value. Hidden for `static-empty`. |
+
+## Behavior
+
+### Rendering
+
+**Given** a CardFilter with `label` and `value`
+**When** it renders with the default `variant="static"`
+**Then** the label appears above the value, the value uses the static idle color,
+and the card is a presentational `<div>` (no interaction states).
+
+**Given** `variant="static-empty"`
+**When** it renders
+**Then** no icon is shown and the value is a muted em-dash (`–`) regardless of the
+`value` prop — the empty-state placeholder.
+
+**Given** an `icon`
+**When** the variant is `static` or `clickable`
+**Then** the icon (16px) is rendered before the value with an 8px gap. The icon is
+ignored for `static-empty`.
+
+### Interaction (clickable only)
+
+**Given** `variant="clickable"`
+**When** it renders
+**Then** the card is a native `<button>`, the value uses the link color, and the
+card exposes hover, active, and focus-visible treatments.
+
+**Given** a clickable CardFilter
+**When** the pointer hovers / presses it
+**Then** the container fill and border shift to their `*-hover` / `*-active` tokens.
+
+**Given** a clickable CardFilter
+**When** it receives keyboard focus
+**Then** a 3px `--ui-focus-primary` ring is painted flush to the edge and the
+border takes its focused token; the ring is suppressed for pointer focus.
+
+**Given** a clickable CardFilter
+**When** it is activated (click, Enter, or Space)
+**Then** a `click` event fires.
+
+**Constraint:** `static` and `static-empty` are non-interactive — they have no
+state other than idle (mirrors the Figma constraint).
+
+### Selection (clickable only)
+
+**Given** a clickable CardFilter with `selected={false}`
+**When** it renders
+**Then** `aria-pressed="false"` and no `data-selected` attribute is present; the
+card shows its idle/hover/active treatments only.
+
+**Given** a clickable CardFilter with `selected={true}`
+**When** it renders
+**Then** `aria-pressed="true"` and `data-selected="true"` are set, and the
+container fill/border switch to the active tokens even without pointer hover or
+press. The `hover:` and `data-[selected=true]:` utilities are equal-specificity
+Tailwind selectors; the selected styling wins on hover only because
+`data-[selected=true]:*` is declared after `hover:*` in the `clickable` variant
+string, not because of any inherent precedence — reordering that string would
+flip the result. No story or test currently exercises the selected+hover
+combination; treat this as source-order-dependent until one does.
+
+**Constraint:** `aria-pressed` (and `type="button"`) apply only to the default
+`<button>` root. When composed via `render` onto a non-button element (e.g.
+`render={<a href="/alerts" />}`), they are omitted — that ARIA/HTML pairing
+would be invalid on a link or other element. `data-selected` is a pure styling
+hook and is still set regardless of the rendered element.
+
+**Given** a clickable CardFilter
+**When** the user activates it
+**Then** the card only fires `click` — `selected` does not change on its own. The
+consumer flips `selected` in its `onClick` handler (the component is controlled
+only; there is no internal selected state).
+
+### Composition
+
+**Given** a `render` prop (e.g. `<a href>`)
+**When** the CardFilter renders
+**Then** it renders as that element with the card's classes and props merged on —
+e.g. a clickable filter that navigates as a link.
+
+## Accessibility
+
+- **Role:** `clickable` renders a native `<button>` (implicit `role="button"`);
+  `static` / `static-empty` render a presentational `<div>`. The `render` prop can
+  swap the element (e.g. a native `<a>` for a link filter).
+- **Accessible name:** for the `clickable` variant the name comes from the card's
+  text content (label + value). If that is not descriptive enough, pass an explicit
+  `aria-label`.
+- **Keyboard (clickable):** Enter and Space activate (native button). Tab focuses;
+  the static variants are not focusable.
+- **Focus visible:** keyboard focus shows a 3px ring in `--ui-focus-primary` flush
+  to the card edge (no offset), via `:focus-visible`; suppressed for pointer focus.
+- **Pressed state (clickable):** `aria-pressed` reflects the controlled `selected`
+  prop (`"true"`/`"false"`), exposing the card as a toggle button; `data-selected`
+  mirrors it for styling.
+- **Static content:** `static` / `static-empty` are presentational; they convey a
+  value but are not interactive and are not in the tab order.
+- **Contrast:** label / value / surface pairs come from the design tokens, authored
+  to meet WCAG contrast. The `static-empty` placeholder uses a muted token.
+- **WCAG:** 2.1.1 (keyboard), 2.4.7 (focus visible), 1.4.3 / 1.4.11 (contrast),
+  4.1.2 (name/role/value).