@malva-ui/core 0.1.12

package/docs/ai/date-range-picker.md

@@ -0,0 +1,101 @@
+name: libs-date-range-picker
+description: Documentation for the @malva-ui/core/date-range-picker library — date range selection input
+type: project
+---
+
+# Library: date-range-picker
+
+## Overview
+
+The Date Range Picker library (`@malva-ui/core/date-range-picker`) provides a date range selection input combining two `mlv-calendar` instances inside a `mlv-popup` overlay.
+
+**Features:**
+
+- Trigger button showing formatted date range or placeholder
+- Two side-by-side calendar panels (left = month M, right = M+1) with coordinated range selection
+- First click sets start date, second click sets end date
+- Hover preview shows the potential range while selecting
+- Clear and Apply buttons in the footer
+- Full signal, reactive, and template-driven forms integration producing `MlvDateRangePickerValue<D> | null`
+- Keyboard accessible: trigger opens popup, Escape closes, Tab navigates between calendars
+- Modal focus management: the **inner panel** carries `role="dialog"` + `aria-modal="true"` + `cdkTrapFocus` (the single dialog role for this surface — the wrapping `mlv-popup` stays roleless/non-modal to avoid nesting a second dialog). On open, focus moves into the panel (first tabbable element, falling back to the `tabindex="-1"` panel container); Tab is trapped within; on close, focus returns to the trigger. Wired via the popup's `(afterOpened)="_onPanelOpened()"` / `(afterClosed)="_onPanelClosed()"`, `cdkTrapFocus` (`A11yModule`), and `MlvTabbableElementService` from `@malva-ui/cdk/accessibility`.
+- State variants: `default`, `success`, `warning`, `error`, `info`
+
+## Public API
+
+Exported from `@malva-ui/core/date-range-picker`:
+
+| Export                       | Kind      | Description                                                                          |
+| ---------------------------- | --------- | ------------------------------------------------------------------------------------ |
+| `MlvDateRangePicker`         | Component | `mlv-date-range-picker`                                                              |
+| `MlvDateRangePickerValue<D>` | Interface | `{ start: D \| null; end: D \| null }`                                               |
+| `MlvDateRangePickerState`    | Type      | `'default' \| 'success' \| 'warning' \| 'error' \| 'info'` (alias of `MlvFormState`) |
+
+## Component: `MlvDateRangePicker` (`mlv-date-range-picker`)
+
+### Inputs
+
+| Input         | Type                                                   | Default               | Description                                                        |
+| ------------- | ------------------------------------------------------ | --------------------- | ------------------------------------------------------------------ |
+| `placeholder` | `string`                                               | `'Select date range'` | Placeholder text when no range is selected                         |
+| `disabled`    | `BooleanInput`                                         | `false`               | Disables the trigger                                               |
+| `state`       | `MlvDateRangePickerState`                              | `'default'`           | Validation state for border color                                  |
+| `min`         | `D \| MlvDateRangePickerValue<D> \| null \| undefined` | `null`                | Minimum date; signal-form range constraints use their `start` date |
+| `max`         | `D \| MlvDateRangePickerValue<D> \| null \| undefined` | `null`                | Maximum date; signal-form range constraints use their `end` date   |
+
+### Outputs
+
+| Output        | Type                                    | Description    |
+| ------------- | --------------------------------------- | -------------- |
+| `rangeChange` | `MlvDateRangePickerValue<Date> \| null` | Emits on Apply |
+
+### Forms contract
+
+- Produces `MlvDateRangePickerValue<Date> | null`
+- External `value` model writes populate the trigger display and pending range without user-change feedback.
+- Implements Angular's signal-control contract and remains compatible with `[formControl]`, `formControlName`, and `ngModel`.
+
+## SCSS / BEM
+
+Block: `mlv-date-range-picker`
+
+| Class                                  | Description                           |
+| -------------------------------------- | ------------------------------------- |
+| `.mlv-date-range-picker`               | Host element                          |
+| `.mlv-date-range-picker__trigger`      | Clickable trigger button/div          |
+| `.mlv-date-range-picker__value`        | Formatted range text                  |
+| `.mlv-date-range-picker__placeholder`  | Placeholder text when no range        |
+| `.mlv-date-range-picker__separator`    | Arrow between start/end dates         |
+| `.mlv-date-range-picker__trigger-icon` | Calendar icon                         |
+| `.mlv-date-range-picker__panel`        | Popup panel container                 |
+| `.mlv-date-range-picker__calendars`    | Flex row wrapping two calendars       |
+| `.mlv-date-range-picker__divider`      | Vertical divider between calendars    |
+| `.mlv-date-range-picker__footer`       | Clear/Apply action row                |
+| `--open` modifier                      | When popup is open                    |
+| `--disabled` modifier                  | Disabled state                        |
+| `--selecting` modifier                 | After start date chosen, awaiting end |
+| `--state-*` modifiers                  | Validation state border color         |
+
+## Dependencies
+
+- `@malva-ui/core/calendar` — `mlv-calendar` with `[range]="true"` mode
+- `@malva-ui/core/popup` — `mlv-popup` for the floating panel overlay
+- `@malva-ui/core/form-utils` — `MlvSignalFormControlBase` signal-control base class
+- `@malva-ui/cdk/utils` — theme/utility injection tokens
+- `@malva-ui/cdk/accessibility` — `MlvTabbableElementService` for moving focus into the popup panel on open
+- `@angular/cdk/a11y` — `A11yModule` / `cdkTrapFocus` for trapping Tab within the `role="dialog"` panel
+
+## Notes
+
+- Pending range (in-popup selection) is separate from committed range (form control value); Apply commits, Clear resets.
+- `_isSelecting` computed flag drives the `--selecting` modifier when start is chosen but end is not yet.
+- **Mobile fullscreen:** the `mlv-popup` opts into `mobileMode="auto"` (`[mobileTitle]="label() || _i18n().selectDateRange"`), so below the `md` breakpoint (< 768px) both calendars open in a full-screen sheet with a header + close button and scroll-locked page. Because the **inner** panel already carries `role="dialog"` + `cdkTrapFocus`, the inner trap is disabled while the sheet is full-screen via `[cdkTrapFocus]="!rangePopup.isFullscreen()"` (reading the popup's public `isFullscreen` signal through the `#rangePopup` ref) so the outer full-screen trap is the only active one — the close button in the sheet header stays reachable. `_onPanelOpened()` / `_onPanelClosed()` focus-in/restore are unchanged. See `libs-popup.md` → _Mobile fullscreen inputs_.
+
+---
+
+## Field surface (2026-08)
+
+- Inherited `required` renders the `mlv-label` marker and sets `aria-required` on the trigger.
+- Inherited `ariaLabel` names the `role="button"` trigger.
+- Inherited `description` renders `<mlv-description>` below the control; `aria-describedby` is the base's `_describedBy()`.
+- The public `messageId` computed is gone — `<mlv-message>` carries the base's `_messageId()`.

package/docs/ai/day-picker.md

@@ -0,0 +1,135 @@
+# Library: day-picker
+
+## Overview
+
+The Day Picker library (`@malva-ui/core/day-picker`) provides a date selection component with a calendar popup. It is a signal forms control that also works with reactive and template-driven forms. Supports date range validation (min/max), custom date formatting, and multiple validation states.
+
+## Public API
+
+Exported from `@malva-ui/core/day-picker`:
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `MlvDayPicker` | Component | Date picker input — `mlv-day-picker` |
+| `MlvDayPickerState` | Type | `'default' \| 'success' \| 'info' \| 'warning' \| 'error'` (alias of `MlvFormState`) |
+
+---
+
+## Components
+
+### `MlvDayPicker`
+
+- **Selector:** `mlv-day-picker`
+- **Change Detection:** `OnPush`
+- **Extends:** `MlvSignalFormControlBase<D | null>` (`FormValueControl` contract)
+
+#### Model (two-way binding)
+
+| Name    | Type           | Default |
+| ------- | -------------- | ------- |
+| `value` | `Date \| null` | `null`  |
+
+#### Inputs
+
+| Name          | Type                | Default            | Description                 |
+| ------------- | ------------------- | ------------------ | --------------------------- |
+| `placeholder` | `string`            | `'Select date...'` | Shown when no date selected |
+| `state`       | `MlvDayPickerState` | `'default'`        | Visual/validation state     |
+| `disabled`    | `boolean`           | `false`            | Disables date selection     |
+| `label`       | `string`            | `''`               | Optional label              |
+| `message`     | `string`            | `''`               | Validation/error message    |
+| `min`         | `Date \| null`      | `null`             | Minimum selectable date     |
+| `max`         | `Date \| null`      | `null`             | Maximum selectable date     |
+| `dateFormat`  | `string`            | `'yyyy-MM-dd'`     | Display format string       |
+
+#### Internal Signals
+
+- `isOpen: signal(false)` — popup visibility
+- `displayValue` — formatted date string or `''`
+- `inputId` — auto-generated unique ID
+
+#### Host Bindings
+
+```ts
+host: {
+  'class': 'mlv-day-picker',
+  '[class.mlv-day-picker--disabled]': 'disabled()',
+}
+```
+
+#### Key Methods
+
+- `toggleDropdown()` — open/close calendar popup
+- `onDateSelected(date: Date | null)` — handle date selection; closes popup
+- External form writes update the public `value` model without emitting a user interaction.
+
+#### Template Summary
+
+Optional label → `MlvPopupContainer` with trigger (displays `displayValue` or placeholder + calendar icon, `role="combobox"`) → `MlvPopup` containing `MlvCalendar` (bound to `value`, `min`, `max`). Optional message display.
+
+Keyboard: Enter/Space opens, Escape closes.
+
+---
+
+## Usage Examples
+
+```html
+<!-- Basic -->
+<mlv-day-picker [(value)]="selectedDate" label="Date" />
+
+<!-- With constraints -->
+<mlv-day-picker [(value)]="date" [min]="minDate" [max]="maxDate" />
+
+<!-- Error state -->
+<mlv-day-picker [(value)]="date" state="error" message="Required" />
+
+<!-- Reactive forms -->
+<mlv-day-picker [formControl]="dateCtrl" label="Birth Date" />
+
+<!-- Disabled -->
+<mlv-day-picker [(value)]="date" [disabled]="true" />
+```
+
+---
+
+## Dependencies
+
+- `@angular/forms/signals` — `FormValueControl` contract and `[formField]` binding
+- `@malva-ui/core/popup` — `MlvPopup`, `MlvPopupContent`, `MlvPopupContainer`
+- `@malva-ui/core/calendar` — `MlvCalendar`
+- `@lucide/angular` — `LucideCalendar` icon
+
+---
+
+## Accessibility notes (updated)
+
+- The calendar popup is a modal dialog: `mlv-popup` is configured with `panelRole="dialog"` + `[modal]="true"` + `[ariaLabel]` (focus trap + `aria-modal`).
+- On open, focus moves into the calendar; on close, focus is restored to the trigger.
+- The trigger's `aria-controls` targets the calendar region id (`{id}-popup`), `tabindex` is `-1` when disabled, `aria-disabled` renders only when disabled, and the visible label is linked via `aria-labelledby` (a `<label for>` cannot name the `<div role="combobox">` trigger).
+
+## Mobile fullscreen
+
+The calendar `mlv-popup` opts into `mobileMode="auto"` (`[mobileTitle]="label() || _resolvedPlaceholder()"`), so below the `md` breakpoint (< 768px) the calendar opens as a full-screen sheet with a header bar + close button, scroll-locked page, and slide-up animation; on larger viewports it stays anchored to the trigger (unchanged). The existing `panelRole="dialog"` + `[modal]="true"` focus trap composes with the full-screen sheet, and `_onPopupOpened()` / `_onPopupClosed()` (focus-into-calendar / focus-restore) keep working. See `libs-popup.md` → _Mobile fullscreen inputs_.
+
+---
+
+## `@angular/aria` integration — evaluated, NOT adopted (2026-07-20)
+
+Phase 3 of the aria migration listed `day-picker → ngCombobox + ngComboboxDialog recipe; calendar stays manual`. This was **spike-evaluated and rejected**; the manual `<div role="combobox">` trigger + CDK-overlay `mlv-popup` implementation is kept. Reasons (empirical, aria 22.0.5):
+
+1. **`ngComboboxDialog` does not exist in aria 22.0.5.** The only combobox directives are `ngCombobox`, `ngComboboxPopup`, `ngComboboxWidget`. "dialog" is merely a `popupType` string value (`'listbox' | 'tree' | 'grid' | 'dialog'`) on `ComboboxPopup`.
+2. **`popupType="dialog"` produces no native `<dialog>` element and no modal/centering behavior.** A spike (`[ngCombobox]` trigger + `ng-template[ngComboboxPopup] popupType="dialog"`) rendered the popup inline via aria's `DeferredContent`, in-flow inside the component subtree (`nativeDialogElementProduced: false`); the only effect on the trigger is `aria-haspopup="dialog"` — which the manual trigger already sets. The premise that a native dialog's default modal centering might change the positioning calculus does not apply.
+3. **aria's popup rendering conflicts with the mandated CDK-overlay positioning** (same conflict documented for `select` Task 2.5 and `combobox` Task 2.7). `Combobox extends DeferredContentAware` and `ComboboxPopup` is a structural directive bound to aria's own `DeferredContent`, so the popup cannot be handed to `mlv-popup` (CDK overlay) for anchored-under-trigger positioning without fighting aria.
+4. **Uniquely decisive here: the popup content is a calendar, which stays manual by plan.** aria's combobox coordination expects an aria popup _widget_ (`ngListbox`/`ngTree`/`ngGrid`) inside `ngComboboxWidget` to relay navigation keys / active-descendant to. A calendar is none of these, so `[ngCombobox]` on the trigger would have no aria widget to coordinate with — zero semantic gain, only added complexity and risk to the working focus-in/focus-restore + focus-trap contract.
+5. **The existing manual trigger already satisfies the full a11y contract** (role=combobox, aria-haspopup=dialog, aria-expanded, aria-controls, aria-labelledby, disabled tabindex, Enter/Space open, Escape close, focus-into-calendar on open, focus-restore on close, `aria-modal` focus-trap via `mlv-popup`).
+
+Decision: keep manual. No public API, template, or spec changes. This is the plan's sanctioned fallback ("if a pattern doesn't fit, keep the manual implementation").
+
+---
+
+## Field surface (2026-08)
+
+- Inherited `required` renders the `mlv-label` marker and sets `aria-required` on the `role="combobox"` trigger.
+- Inherited `ariaLabel` names the trigger when no visible `label` is set (a visible label still wins through `aria-labelledby`).
+- Inherited `description` renders `<mlv-description>` below the control; the trigger's `aria-describedby` is the base's `_describedBy()`.
+- The public `messageId` computed is gone — `<mlv-message>` now carries the base's `_messageId()`, which previously had no id at all on some paths.