@malva-ui/core 0.1.12

package/docs/ai/button.md

@@ -0,0 +1,306 @@
+# Library: button
+
+## Overview
+
+The Button library (`@malva-ui/core/button`) provides accessible button primitives: styled native buttons, close buttons, connected button groups, split-button layouts, and two-state toggle buttons. Groups, split buttons, and toggles can provide a shared visual variant so consumers do not have to repeat it on every child button.
+
+> **Sizing is density-driven — there is no `size` input.** Button height/padding/font-size come from the `@malva-ui/cdk/density` system (`mlvDensity` host directive → `density-tight | density-compact | density-comfortable | density-spacious | density-airy`). A vestigial `size`/`ButtonSize` input existed but was never wired to any class or style (it silently did nothing) and was **removed**. Use `mlvDensity` to size a button (e.g. `<button mlvButton mlvDensity="compact">`), or set density on an ancestor.
+
+## Public API
+
+Exported from `@malva-ui/core/button`:
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `MlvButton` | Component | Main button with disabled and loading states — selector `button[mlvButton], a[mlvButton]` |
+| `MlvButtonClose` | Component | X-icon close action with transparent/circle defaults and standard density support — selector `mlv-button-close` |
+| `MlvButtonGroup` | Component | Connected set of related buttons — selector `mlv-button-group` |
+| `MlvButtonSplit` | Component | Joined primary action and related trigger — selector `mlv-button-split` |
+| `MlvButtonToggle` | Component | Two-state button with `aria-pressed` and two-way `pressed` state — selector `mlv-button-toggle` |
+| `MlvButtonVariant` | Type | `'primary' \| 'secondary' \| 'outlined' \| 'accent' \| 'transparent' \| 'elevated' \| 'error' \| 'warning' \| 'info'` |
+| `MlvButtonShape` | Type | `'default' \| 'circle' \| 'square' \| 'pill'` |
+| `MlvButtonVariantAccessor` | Interface | Contract used by button containers to provide an inherited variant |
+| `MLV_BUTTON_VARIANT` | Injection token | Optional ancestor-provided button variant context |
+| `MlvButtonBefore` | Directive | Template slot rendered before button text |
+| `MlvButtonAfter` | Directive | Template slot rendered after button text |
+| `MlvButtonIcon` | Directive | Marks a projected icon (`[mlvButtonIcon]` → `.mlv-button__icon`); optional since icon-only buttons are also inferred |
+
+---
+
+## Components
+
+### `MlvButton`
+
+- **Selector:** `button[mlvButton], a[mlvButton]` — applies to native `<button>` and `<a>` elements
+- **Change Detection:** `OnPush`
+- **Encapsulation:** `None`
+- 
+- 
+- **Imports:** `NgTemplateOutlet`
+
+#### Inputs
+
+| Name       | Type                            | Default     | Description                                                                                                                                              |
+| ---------- | ------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `variant`  | `MlvButtonVariant \| undefined` | `undefined` | Local variant; inherits from a button container, then falls back to `secondary` for the icon-only `square`/`circle` shapes and `primary` for the rest    |
+| `shape`    | `MlvButtonShape`                | `'default'` | Shape variant; `pill` keeps content width with a fully rounded stadium radius (`--mlv-radius-full`), matching the pill action bar and pill form controls |
+| `disabled` | `BooleanInput`                  | `false`     | Disables the button; coerced to boolean                                                                                                                  |
+| `loading`  | `BooleanInput`                  | `false`     | Shows a spinner, exposes busy state, and prevents duplicate activation                                                                                   |
+
+#### Content Children (protected)
+
+| Name        | Directive         | Description                              |
+| ----------- | ----------------- | ---------------------------------------- |
+| `beforeRef` | `MlvButtonBefore` | Template rendered before the button text |
+| `afterRef`  | `MlvButtonAfter`  | Template rendered after the button text  |
+
+#### Host Bindings
+
+```ts
+host: {
+  'class': 'mlv-button',
+  '[class]': '"mlv-button--variant-" + effectiveVariant() + " mlv-button--shape-" + shape()',
+  '[class.mlv-button--disabled]': 'disabled()',
+  '[class.mlv-button--loading]': 'loading()',
+  '[class.mlv-button--icon-only]': '_iconOnly()',
+  '[attr.disabled]': '(disabled() || loading()) || null',
+  '[attr.aria-disabled]': '(disabled() || loading()) || null',
+  '[attr.aria-busy]': 'loading() || null',
+}
+```
+
+> **Outlined / transparent label colour** — these two variants set
+> `--mlv-btn-text-color: var(--mlv-text-action)` (theme-aware: primary-600 in
+> light, primary-400 in dark). A previously hardcoded `primary-500` was not
+> theme-aware and failed WCAG AA contrast (3.59:1) on dark surfaces.
+
+#### Template Structure (`button.html`)
+
+```html
+@if (loading()) {
+<mlv-loader variant="circle" color="currentColor" indeterminate [size]="20" [strokeWidth]="2" />
+} @else if (beforeRef()) {
+<ng-container [ngTemplateOutlet]="beforeRef()!.templateRef" />
+}
+<span class="mlv-button__text"><ng-content /></span>
+@if (!loading() && afterRef()) {
+<ng-container [ngTemplateOutlet]="afterRef()!.templateRef" />
+}
+```
+
+The loading state keeps the projected text visible, replaces optional before/after
+content with an indeterminate `MlvLoader`, disables native button activation, and blocks
+anchor activation through the component click guard. Consumers remain responsible
+for changing the action label when a more specific in-progress label is useful.
+
+#### Styles Summary (`button.scss`)
+
+- Base: `display: inline-flex; align-items: center; gap: 0.25rem`
+- `appearance: none; cursor: pointer; transition: 0.2s`
+- Focus: 2px outline via `--mlv-focus-ring-color`
+- Size presets (padding, height, font scale):
+  - `xs`: xs padding, xs height, body-xs font
+  - `s`: s padding, s height, body-s font
+  - `m`: m padding, m height, body-m font
+  - `l`: l padding, l height, body-l font
+  - `xl`: xl padding, xl height, body-xl font
+- Variant styles:
+  - `primary`: `accent-1` background
+  - `secondary`: `neutral-1` background
+  - `accent`: `accent-2` background
+  - `transparent`: no background, neutral hover
+  - `outlined`: transparent with border
+- Shape styles:
+  - `default`: standard rectangular with radius
+  - `square`: `padding: 0.25rem; width = height`
+  - `circle`: `border-radius: 100%`
+- Disabled: `opacity` reduced, `cursor: not-allowed`, `pointer-events: none`
+- Loading: current-colour `MlvLoader`, wait cursor, blocked pointer interaction, and inherited reduced-motion support
+- Pressed: `[aria-pressed='true']` fills with `--mlv-btn-bg-active` and adds a `--mlv-stroke-width` inset `--mlv-border-normal` ring
+
+> **Pressed state** — any `button[mlvButton]` carrying `aria-pressed="true"`
+> gets the visible treatment, not just `mlv-button-toggle`. Toggles that render
+> the attribute on a plain `mlvButton` — every editor toolbar command button —
+> previously announced their state to assistive technology while looking
+> identical to an inactive control. The rule pins `--mlv-btn-bg-hover` as well,
+> because `.mlv-button:hover` has the same specificity and would otherwise
+> decide the background by Sass emission order. It writes
+> `--mlv-btn-box-shadow` rather than `box-shadow`, keeping the base
+> `box-shadow: var(--mlv-btn-box-shadow, none)` the single place the property
+> is set. `--mlv-background-neutral-1-active` backs it in both themes, so a
+> pressed control reads against light and dark toolbar surfaces alike.
+> targeting and all three declarations.
+
+> **Icon-only inference & the shape-aware default variant** — see
+> [docs/migrations/2026-08-button-icon-only-default-variant.md](../../docs/migrations/2026-08-button-icon-only-default-variant.md).
+>
+> - `.mlv-button--icon-only` no longer requires `mlvButtonIcon`. `_iconOnly()` is true when
+>   `shape` is `square`/`circle` **and** either a `[mlvButtonIcon]` is projected **or** the
+>   default slot renders no non-whitespace text. The slot is projected content, so its text
+>   is read back from `.mlv-button__text` (view child `#textRef`) inside an
+>   `afterRenderEffect` that re-runs on `shape`, `loading`, and `mlvButtonIcon` changes.
+>   `_hasProjectedText` starts `true`, so SSR (where `afterRenderEffect` never runs) keeps
+>   the directive-only behaviour. Text that appears/disappears inside an already-rendered
+>   button is **not** observed — annotate the icon for that case.
+> - `button.scss` sizes `.mlv-button--icon-only .mlv-button__text > svg:only-child` to
+>   `var(--mlv-icon-font-size)`, so an unannotated Lucide icon stops rendering at its
+>   intrinsic `24px` and overflowing the square at tight/compact density.
+
+The public `effectiveVariant` computed signal resolves the local `variant`, the closest `MLV_BUTTON_VARIANT` provider, and finally a shape-aware fallback — `secondary` for `square`/`circle`, `primary` for everything else — in that order. Because `mlv-button-group`, `mlv-button-split`, and `mlv-button-toggle` always provide `MLV_BUTTON_VARIANT` (falling back to `primary` themselves), the shape-aware default only applies to a standalone button.
+
+### `MlvButtonClose`
+
+- **Selector:** `mlv-button-close`
+- Renders an inner native `<button type="button">` using `MlvButton`
+- **Inputs:** `variant` (`transparent` by default), `shape` (`circle` by default), and required `ariaLabel`
+- Attaches the standard `MlvDensityDirective` as a host directive and supports `tight`, `compact`, `comfortable`, `spacious`, and `airy`
+- Forwards the directive's resolved density to the inner button, so dimensions match a regular icon-only `mlvButton` at every density
+- Applies `ariaLabel` to the inner native button; the role-less custom-element host is not an accessible-name target
+- For the transparent variant, uses `--mlv-text-secondary` at rest and `--mlv-text-primary` on hover/active, adapting automatically to light and dark themes
+- Retains regular button background, focus, active, and motion behavior
+- Pins its own `:focus-visible` ring (`.mlv-button--close.mlv-button:focus-visible { outline-color: var(--mlv-border-focus) }`). The base `.mlv-button` neutralises the UA outline and only the per-variant rules restore a colour, so the close button previously depended entirely on the variant it happened to render with; the qualified selector also outranks those equally specific variant rules regardless of stylesheet order. Width/offset stay on the shared base so the ring matches every other button.
+
+### `MlvButtonGroup`
+
+- **Selector:** `mlv-button-group`
+- **Role:** `group`; name it with native `aria-label` or `aria-labelledby` when surrounding context is insufficient
+- **Input:** `variant?: MlvButtonVariant`
+- Projects ordinary `button[mlvButton]` and/or `mlv-button-toggle` children
+- Joins adjacent corners and keeps focused buttons above their neighbors
+- Provides its resolved variant through `MLV_BUTTON_VARIANT`; a child's local `variant` wins
+
+### `MlvButtonSplit`
+
+- **Selector:** `mlv-button-split`
+- **Role:** `group`
+- **Input:** `variant?: MlvButtonVariant`
+- Projects the primary action first and its related trigger second
+- Owns connected layout, a vertically centered separator that is `0.25rem` shorter than the buttons, and shared variant injection; popup/menu behavior stays with the projected trigger
+
+### `MlvButtonToggle`
+
+- **Selector:** `mlv-button-toggle`
+- Renders an inner native `<button type="button">` using `MlvButton`
+- **Inputs:** `variant?`, `shape`, `disabled`, `mlvDensity?`, `ariaLabel?`, `ariaLabelledBy?`
+- **Model:** `pressed` (two-way bindable with `[(pressed)]`)
+- Reflects state through native `aria-pressed` and a visible pressed treatment
+- Forwards `mlvDensity` to the inner button
+- Inherits a group/split variant when its local `variant` is omitted, then provides that resolved value to its inner button
+
+---
+
+## Directives
+
+All defined in *(internal)*.
+
+### `MlvStructural` (abstract base, from `@malva-ui/cdk/utils`)
+
+Base class extended by `MlvButtonBefore` and `MlvButtonAfter`. Provides `templateRef = inject(TemplateRef)`. It lives in `@malva-ui/cdk/utils`, not in this barrel.
+
+### `MlvButtonBefore`
+
+- **Selector:** `[mlvButtonBefore]`
+- **Purpose:** Template slot for content rendered **before** the button text label.
+- Use with `<ng-template mlvButtonBefore>` inside a button.
+
+### `MlvButtonAfter`
+
+- **Selector:** `[mlvButtonAfter]`
+- **Purpose:** Template slot for content rendered **after** the button text label.
+- Use with `<ng-template mlvButtonAfter>` inside a button.
+
+---
+
+## Services
+
+None.
+
+---
+
+## Usage Examples
+
+```html
+<!-- Primary button (default) -->
+<button mlvButton>Click me</button>
+
+<!-- Variants -->
+<button mlvButton variant="secondary">Secondary</button>
+<button mlvButton variant="outlined">Outlined</button>
+<button mlvButton variant="accent">Accent</button>
+<button mlvButton variant="transparent">Transparent</button>
+<button mlvButton variant="error">Error</button>
+<button mlvButton variant="warning">Warning</button>
+<button mlvButton variant="info">Info</button>
+
+<!-- Sizing via density -->
+<button mlvButton mlvDensity="compact">Small</button>
+<button mlvButton mlvDensity="spacious">Large</button>
+
+<!-- Close action; all five standard density values are supported -->
+<mlv-button-close ariaLabel="Close dialog" mlvDensity="compact" />
+
+<!-- Icon before text -->
+<button mlvButton>
+  <ng-template mlvButtonBefore>
+    <svg><!-- search icon --></svg>
+  </ng-template>
+  Search
+</button>
+
+<!-- Icon after text -->
+<button mlvButton variant="primary">
+  Continue
+  <ng-template mlvButtonAfter><span>→</span></ng-template>
+</button>
+
+<!-- Circle icon button — icon-only sizing and the neutral `secondary` default
+     are inferred; `mlvButtonIcon` is optional -->
+<button mlvButton shape="circle" aria-label="Add">
+  <svg lucidePlus />
+</button>
+
+<!-- Explicit variant still wins over the shape-aware default -->
+<button mlvButton shape="circle" variant="primary" aria-label="Add">
+  <svg lucidePlus mlvButtonIcon />
+</button>
+
+<!-- Disabled -->
+<button mlvButton [disabled]="true">Disabled</button>
+
+<!-- Loading -->
+<button mlvButton [loading]="saving()">{{ saving() ? 'Saving…' : 'Save changes' }}</button>
+
+<!-- Link button -->
+<a mlvButton href="/page" variant="transparent">Go to page</a>
+
+<!-- One shared variant for a connected group -->
+<mlv-button-group variant="secondary" aria-label="Text alignment">
+  <button mlvButton>Left</button>
+  <button mlvButton>Center</button>
+  <button mlvButton>Right</button>
+</mlv-button-group>
+
+<!-- Split primary action and related trigger -->
+<mlv-button-split variant="primary" aria-label="Save options">
+  <button mlvButton>Save</button>
+  <button mlvButton shape="square" aria-label="More save options">…</button>
+</mlv-button-split>
+
+<!-- Two-way toggle state; both toggles inherit the group variant -->
+<mlv-button-group variant="secondary" aria-label="Formatting">
+  <mlv-button-toggle [(pressed)]="bold">Bold</mlv-button-toggle>
+  <mlv-button-toggle [(pressed)]="italic">Italic</mlv-button-toggle>
+</mlv-button-group>
+```
+
+---
+
+## Dependencies
+
+- `@angular/core` ^22.0.0
+- `@angular/common` — `NgTemplateOutlet`
+- `@angular/cdk/coercion` — `BooleanInput`, `coerceBooleanProperty`
+- `@lucide/angular` — close icon
+- `@malva-ui/cdk/density` — standard five-level density directive
+- `@malva-ui/core/loader` — indeterminate loading indicator
+- Malva UI CSS design tokens (`--mlv-*`)

package/docs/ai/calendar.md

@@ -0,0 +1,237 @@
+# Library: calendar
+
+## Overview
+
+The Calendar library (`@malva-ui/core/calendar`) provides a fully accessible, keyboard-navigable date picker component with three view modes: **month**, **year**, and **multi-year**. It supports date constraints (min/max), custom disabled-date logic, single-date and range selection, and adapter-backed localization / date math.
+
+It also defines the shared Malva UI date-adapter contract used to abstract date math, localized labels, and formatting away from the native `Date` object. Applications can provide their own adapter implementation for libraries such as Luxon, Moment, or date-fns-based wrappers.
+
+## Public API
+
+Exported from `@malva-ui/core/calendar`:
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `MlvCalendar` | Component | The calendar UI — selector `mlv-calendar` |
+| `MlvCalendarView` | Type | `'month' \| 'year' \| 'multi-year'` |
+| `MlvCalendarRangeValue` | Type | `{ start: D \| null; end: D \| null }` for range mode |
+| `MlvDateAdapter` | Abstract class | Date manipulation and localization contract for calendar-aware components |
+| `MLV_DATE_ADAPTER` | InjectionToken | App-level token for providing a custom `MlvDateAdapter` implementation |
+| `MLV_DATE_LOCALE` | InjectionToken | App-level locale token consumed by date adapters |
+| `MlvNativeDateAdapter` | Service | Default adapter built on native `Date` and `Intl.DateTimeFormat` |
+| `provideMlvDateAdapter` | Provider helper | Registers a custom adapter class and optional locale for the app |
+
+---
+
+## Components
+
+### `MlvCalendar`
+
+- **Selector:** `mlv-calendar`
+- **Change Detection:** `OnPush`
+- 
+- 
+
+#### Model (two-way binding)
+
+| Name         | Type                                      | Default | Description                                                       |
+| ------------ | ----------------------------------------- | ------- | ----------------------------------------------------------------- |
+| `value`      | `Model<D \| null>`                        | `null`  | The currently selected date object produced by the active adapter |
+| `rangeValue` | `Model<MlvCalendarRangeValue<D> \| null>` | `null`  | Selected range when range mode is enabled                         |
+
+#### Inputs
+
+| Name             | Type                             | Default   | Description                                         |
+| ---------------- | -------------------------------- | --------- | --------------------------------------------------- |
+| `min`            | `D \| null`                      | `null`    | Minimum selectable date                             |
+| `max`            | `D \| null`                      | `null`    | Maximum selectable date                             |
+| `disabledDates`  | `((date: D) => boolean) \| null` | `null`    | Custom callback; return `true` to disable a date    |
+| `startView`      | `MlvCalendarView`                | `'month'` | Initial view when rendered                          |
+| `firstDayOfWeek` | `number`                         | `1`       | First day of the week (0 = Sunday, 1 = Monday)      |
+| `range`          | `boolean`                        | `false`   | Enables range selection mode backed by `rangeValue` |
+
+#### Internal State
+
+| Signal              | Type                              | Description                                                                                               |
+| ------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `activeDate`        | `WritableSignal<D>`               | Currently navigated-to date (not necessarily selected)                                                    |
+| `currentView`       | `WritableSignal<MlvCalendarView>` | Which view panel is shown                                                                                 |
+| `_rangePreviewDate` | `WritableSignal<D \| null>`       | Transient hover/focus endpoint while a range has a start but no committed end; never mutates `rangeValue` |
+
+#### Computed
+
+| Signal              | Type                                         | Description                                                                                             |
+| ------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `weekdays`          | `computed<string[]>`                         | Localized weekday labels from the active adapter, rotated by `firstDayOfWeek`                           |
+| `monthDays`         | `computed<CalendarDayCell<D>[]>`             | Day cells for month grid, including leading/trailing adjacent-period dates to fill each week row        |
+| `monthWeeks`        | `computed<CalendarDayCell<D>[][]>`           | `monthDays` grouped into week rows (chunks of 7) so the template can render each week as a `role="row"` |
+| `years`             | `computed<number[]>`                         | 24 years shown in multi-year view                                                                       |
+| `headerLabel`       | `computed<string>`                           | Localized display text for the header button                                                            |
+| `_displayRange`     | `computed<MlvCalendarRangeValue<D> \| null>` | Chronologically normalized committed range, or the start-to-preview interval while choosing an end date |
+| `isRangePreviewing` | `computed<boolean>`                          | Whether the calendar is displaying a transient range preview                                            |
+| `hasCompletedRange` | `computed<boolean>`                          | Whether both committed range endpoints are present                                                      |
+
+#### Methods
+
+| Method                | Signature                      | Description                                                                                                                                                                                        |
+| --------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `navigatePrev`        | `(): void`                     | Go to previous month / year / multi-year block while preserving free navigation in range mode                                                                                                      |
+| `navigateNext`        | `(): void`                     | Go to next month / year / multi-year block while preserving free navigation in range mode                                                                                                          |
+| `switchView`          | `(): void`                     | Cycle: month → year → multi-year → month                                                                                                                                                           |
+| `selectDate`          | `(date: D): void`              | Select a date; no-op if disabled                                                                                                                                                                   |
+| `selectMonth`         | `(month: number): void`        | Select month (0–11), switches to month view                                                                                                                                                        |
+| `selectYear`          | `(year: number): void`         | Select year, switches to year view                                                                                                                                                                 |
+| `isDateDisabled`      | `(date: D): boolean`           | Check min/max/disabledDates                                                                                                                                                                        |
+| `isToday`             | `(date: D): boolean`           | Check if date is today                                                                                                                                                                             |
+| `isSelected`          | `(date: D): boolean`           | Check if date matches `value`                                                                                                                                                                      |
+| `isDisplayRangeStart` | `(date: D): boolean`           | Check whether a date is the chronological start of the committed or previewed display range                                                                                                        |
+| `isDisplayRangeEnd`   | `(date: D): boolean`           | Check whether a date is the chronological end of the committed or previewed display range                                                                                                          |
+| `isInDisplayRange`    | `(date: D): boolean`           | Check whether a date belongs to the committed or previewed display range                                                                                                                           |
+| `previewRange`        | `(date: D): void`              | Preview a valid end date from the current start during hover or keyboard focus without committing the range                                                                                        |
+| `clearRangePreview`   | `(): void`                     | Clear the transient preview when focus or pointer leaves the date grid                                                                                                                             |
+| `onKeydown`           | `(event: KeyboardEvent): void` | Keyboard navigation handler                                                                                                                                                                        |
+| `focus`               | `(): void`                     | Focuses the active cell (the roving `tabindex="0"` day/month/year button). Public entry point for popup hosts (`mlv-day-picker`, `mlv-date-range-picker`) that want focus to land inside the grid. |
+
+#### Host Bindings
+
+```ts
+host: {
+  'class': 'mlv-calendar',
+  '(keydown)': 'onKeydown($event)',
+  // NOTE: the host is intentionally NOT focusable (no tabindex). Focus is
+  // owned by the active grid cell via the roving-tabindex pattern.
+}
+```
+
+#### Keyboard Navigation (month view)
+
+| Key                     | Action                  |
+| ----------------------- | ----------------------- |
+| `←` / `→`               | Move one day left/right |
+| `↑` / `↓`               | Move one week up/down   |
+| `Page Up` / `Page Down` | Previous/next month     |
+| `Home`                  | First day of month      |
+| `End`                   | Last day of month       |
+| `Enter` / `Space`       | Select the active date  |
+
+#### Template Structure (`calendar.html`)
+
+- **Header row:** circular prev/next `mlvButton` controls and a central header button wrapped in `mlvFade` so long localized month/year labels do not overflow
+- **Month view** (`@if currentView === 'month'`): valid `role="grid"` structure
+  - Weekday header row — `role="row"` containing `role="columnheader"` cells
+  - `div.mlv-calendar__days` is a `role="rowgroup"` holding one `div.mlv-calendar__week` per week (`role="row"`). Each week is grouped from `monthWeeks()` (chunks of 7 from `monthDays()`) and uses `display: contents` in CSS so its day cells still participate in the parent 7-column grid.
+  - Each day cell wrapper is a `role="gridcell"` (carrying `[attr.aria-selected]`) that contains a circular `button[mlvButton]`. The **button keeps native button semantics** (no `role="gridcell"` override) and carries the roving `[attr.tabindex]` (`0` for the active date, `-1` otherwise).
+  - Leading/trailing days from adjacent months are shown when needed to complete the week rows and are visually dimmed
+  - Single-date selection uses the `primary` button variant. An unfinished range previews the hovered/focused endpoint and every date between it and the selected start with directional caps; a committed range becomes one seamless primary-colored band.
+  - Range endpoints are normalized chronologically, so hovering before the selected start swaps that anchor to the trailing cap. Week-row boundaries receive their own visual caps without changing the selected values.
+- **Year view** (`@if currentView === 'year'`): `role="group"` (labelled) containing a 4-column grid of 12 circular `mlvButton` month selectors (plain buttons, no `role` override), disabled when a month contains no selectable date within min/max and custom disabled-date rules. `aria-pressed` + roving `[attr.tabindex]` mark the current month.
+- **Multi-year view** (`@if currentView === 'multi-year'`): `role="group"` containing a 4-column grid of 24 `mlvButton` year selectors with the same availability rules, `aria-pressed`, and roving `[attr.tabindex]`.
+
+All month labels, weekday labels, year labels, header labels, and day ARIA labels come from the active `MlvDateAdapter` rather than hardcoded native `Date` calls.
+
+#### Styles Summary (`calendar.scss`)
+
+- Host surface uses shared Malva UI tokens directly (`--mlv-elevation-bg-2`, `--mlv-border-subtle`, `--mlv-shadow-1`) rather than component-scoped alias variables for static values
+- Header is a raised neutral panel containing compact transparent Malva UI buttons and a faded title wrapper for long localized labels
+- Day cells use circular Malva UI buttons; selected states use the `primary` variant, idle states use `transparent`, adjacent-month days are dimmed, and today uses the shared focus border token
+- Range cells remove the column gap and expand to the full grid track: previews use pale accent interiors with primary endpoints, while completed ranges use a continuous primary background. Logical inline radii cap only range and week-row boundaries, including right-to-left layouts.
+- Month selection buttons are fixed-size circular controls so localized short month labels do not turn into oval buttons
+- Year selection buttons remain full-width within the 4-column grid and disable unavailable periods instead of allowing navigation into dead ranges
+
+---
+
+## Directives
+
+None.
+
+## Services
+
+### `MlvNativeDateAdapter`
+
+Default adapter shipped by the library. Uses native `Date` for date math and `Intl.DateTimeFormat` for localized labels, month names, weekday names, and accessible date strings.
+
+### `MlvDateAdapter<D>`
+
+Abstract contract for adapter-backed date operations. Key responsibilities:
+
+- clone / create / validate date instances
+- add calendar days, months, and years
+- compare dates without relying on native object identity
+- produce localized month names, weekday names, and formatted labels
+- deserialize unknown values into the adapter’s date type
+
+The calendar component itself only relies on this abstract contract for user-facing labels and calendar arithmetic.
+
+### Provider Tokens
+
+- `MLV_DATE_ADAPTER` — injects the active adapter instance
+- `MLV_DATE_LOCALE` — provides the app-level locale string
+- `provideMlvDateAdapter(AdapterClass, locale?)` — helper for app configuration
+
+---
+
+## Usage Examples
+
+```html
+<!-- Basic -->
+<mlv-calendar [(value)]="selectedDate" />
+
+<!-- Constrained range -->
+<mlv-calendar [(value)]="selectedDate" [min]="minDate" [max]="maxDate" />
+
+<!-- Custom disabled dates -->
+<mlv-calendar [(value)]="selectedDate" [disabledDates]="isWeekend" />
+
+<!-- Start in year view -->
+<mlv-calendar [(value)]="selectedDate" startView="year" />
+
+<!-- Sunday as first day -->
+<mlv-calendar [(value)]="selectedDate" [firstDayOfWeek]="0" />
+
+<!-- Range mode -->
+<mlv-calendar [range]="true" [(rangeValue)]="selectedRange" />
+```
+
+```ts
+export class MyComponent {
+  selectedDate = signal<Date | null>(null);
+  selectedRange = signal<MlvCalendarRangeValue<Date> | null>(null);
+  minDate = new Date(2020, 0, 1);
+  maxDate = new Date(2030, 11, 31);
+  isWeekend = (d: Date) => d.getDay() === 0 || d.getDay() === 6;
+}
+```
+
+```ts
+import { bootstrapApplication } from '@angular/platform-browser';
+import { MlvNativeDateAdapter, provideMlvDateAdapter } from '@malva-ui/core/calendar';
+
+bootstrapApplication(AppComponent, {
+  providers: [...provideMlvDateAdapter(MlvNativeDateAdapter, 'ro-RO')],
+});
+```
+
+---
+
+## Accessibility Notes
+
+- **Roving tabindex** (single tab stop per view): the host is **not** focusable. Exactly one grid cell button carries `tabindex="0"` (the active day / current month / current year); all others are `tabindex="-1"`. This replaces the previous model where the host was `tabindex="0"` and every day button was natively tabbable (~35 tab stops).
+- **Focus follows the active cell**: after arrow / Page / Home / End navigation changes `activeDate`, focus is moved to the newly-active cell via `afterNextRender` (scheduled only from the keyboard handlers, so programmatic `activeDate` changes never steal focus). Focus follows across month/year boundaries.
+- **`focus()` entry point**: consumers embedding the calendar in a popup can call `MlvCalendar.focus()` to move focus into the grid; it targets the roving `tabindex="0"` cell.
+- Full arrow-key navigation in month, year, and multi-year views; `Enter`/`Space` selects; `PageUp`/`PageDown` change month; `Home`/`End` jump to first/last.
+- Valid ARIA grid semantics for the month view: `role="grid"` → `role="row"` (weekday header + one `role="rowgroup"` of week `role="row"`s) → `role="gridcell"` (carrying `aria-selected`) → native `button`.
+- Year / multi-year selection grids are labelled `role="group"`s of plain buttons (no `role="listitem"` — the previous `aria-pressed` + `role="listitem"` combo was invalid); the current option is indicated with `aria-pressed` and the roving `tabindex`.
+- Day buttons carry `aria-disabled`, `aria-current="date"` for today, and localized `aria-label` attributes generated by the active adapter.
+- Range previews follow both pointer hover and keyboard focus. Because the preview is transient, `aria-selected` continues to describe only committed values until the user selects the second endpoint.
+- Header and month-selection labels use `mlvFade` where needed to avoid truncation breaking layout.
+
+---
+
+## Internationalization (i18n)
+
+Strings resolve through `MLV_CALENDAR_I18N` (`@malva-ui/i18n`): `previousPeriod`, `nextPeriod`, plus two ICU strings resolved via `MlvI18nResolverService` — `switchView` (`"Switch to {view, select, year {year} multiYear {multi-year} other {month}} view"`, exposed as the `_switchViewLabel` computed) and `selectMonthForYear` (`"Select month for {year}"`, used by `getYearViewLabel()`). Provide `provideMlvI18nTesting()` in specs.
+
+## Dependencies
+
+- `@angular/core` ^22.0.0 — signals, `computed()`, `model()`, `afterNextRender`, `ElementRef`, `Injector` (roving-focus management)
+- `@angular/common` — native control flow