@edsis/ui 0.0.2

package/composer/README.md

@@ -0,0 +1,235 @@
+# Composer
+
+Configurable prompt composer for chat, AI, and message surfaces.
+
+This Angular implementation takes conceptual inspiration from Flux Composer, but the API, styling, and composition model follow the shadcn-style patterns already established in this library.
+
+## Import
+
+```ts
+import {
+  ComposerActionsLeadingComponent,
+  ComposerActionsTrailingComponent,
+  ComposerComponent,
+  ComposerFooterComponent,
+  ComposerHeaderComponent,
+  ComposerInputComponent,
+  ComposerTextareaComponent,
+} from '@edsis/ui/composer';
+```
+
+## Composition
+
+```text
+ui-composer
+├── ui-composer-header (optional)
+├── ui-composer-actions-leading (optional)
+├── textarea[ui-composer-input] or ui-composer-input
+├── ui-composer-actions-trailing (optional)
+└── ui-composer-footer (optional)
+```
+
+Use `textarea[ui-composer-input]` when you want native textarea behavior, template-driven forms, or reactive forms.
+Use `ui-composer-input` when you want to project a custom rich-text surface or editor shell.
+
+## Basic Usage
+
+```html
+<form (ngSubmit)="send()">
+  <ui-composer (submitRequested)="send()">
+    <textarea
+      ui-composer-input
+      rows="2"
+      maxRows="6"
+      placeholder="How can I help you today?"
+      [(ngModel)]="prompt"
+      name="prompt"></textarea>
+
+    <ui-composer-actions-trailing>
+      <button ui-button type="submit" size="icon-sm" aria-label="Send prompt">Send</button>
+    </ui-composer-actions-trailing>
+  </ui-composer>
+</form>
+```
+
+## With Header
+
+Use the header slot for file previews, avatars, upload summaries, or compact context cards.
+
+```html
+<ui-composer>
+  <ui-composer-header>
+    <div class="flex items-center gap-3 rounded-lg border border-border bg-muted/40 px-3 py-2">
+      <img src="/avatar.png" alt="Uploaded file owner" class="size-10 rounded-md object-cover" />
+      <div class="min-w-0">
+        <p class="truncate text-sm font-medium">profile-shot.png</p>
+        <p class="text-xs text-muted-foreground">2.1 MB</p>
+      </div>
+    </div>
+  </ui-composer-header>
+
+  <textarea ui-composer-input rows="2" maxRows="6" placeholder="Ask about this asset..."></textarea>
+
+  <ui-composer-actions-trailing>
+    <button ui-button type="button" size="sm">Send</button>
+  </ui-composer-actions-trailing>
+</ui-composer>
+```
+
+## Inline Layout
+
+Set `inline` when actions and input should share a compact single-row shell.
+
+```html
+<ui-composer inline submit="enter">
+  <ui-composer-actions-leading>
+    <button ui-button type="button" variant="ghost" size="icon-sm" aria-label="Add attachment">+</button>
+  </ui-composer-actions-leading>
+
+  <textarea ui-composer-input rows="1" maxRows="4" placeholder="Reply..."></textarea>
+
+  <ui-composer-actions-trailing>
+    <button ui-button type="button" variant="secondary" size="icon-sm" aria-label="Voice input">Mic</button>
+    <button ui-button type="submit" size="icon-sm" aria-label="Send reply">Send</button>
+  </ui-composer-actions-trailing>
+</ui-composer>
+```
+
+## Input Variant
+
+Set `variant="input"` when the composer should align more closely with the radius and density of other input surfaces.
+
+```html
+<ui-composer variant="input">
+  <textarea ui-composer-input rows="2" maxRows="5" placeholder="What's on your mind?"></textarea>
+</ui-composer>
+```
+
+## Height And Autosize
+
+`rows` sets the initial height of the native textarea surface.
+`maxRows` caps autosize growth before the textarea begins scrolling.
+
+```html
+<ui-composer>
+  <textarea ui-composer-input rows="3" maxRows="8" placeholder="Write a longer prompt..."></textarea>
+</ui-composer>
+```
+
+## Submit Behavior
+
+By default, keyboard submission uses `cmd-enter`, which means `Cmd+Enter` on macOS and `Ctrl+Enter` on Windows/Linux.
+
+Use `submit="enter"` when pressing `Enter` should submit immediately. `Shift+Enter` still inserts a new line.
+
+```html
+<ui-composer submit="enter" (submitRequested)="send()">
+  <textarea ui-composer-input rows="1" maxRows="4" placeholder="Quick reply..."></textarea>
+</ui-composer>
+```
+
+When `submitForm` stays `true`, the composer also calls the nearest native `form.requestSubmit()` after emitting `submitRequested`.
+
+## Rich Text Slot
+
+Project a custom editor shell through `ui-composer-input` when you want a richer surface without changing the composer container API.
+
+```html
+<ui-composer>
+  <ui-composer-input>
+    <div
+      contenteditable="true"
+      role="textbox"
+      aria-multiline="true"
+      class="min-h-20 w-full rounded-sm bg-transparent px-2 py-2 outline-none">
+      Draft a richer message...
+    </div>
+  </ui-composer-input>
+
+  <ui-composer-actions-leading>
+    <button ui-button type="button" variant="ghost" size="icon-sm" aria-label="Insert file">+</button>
+  </ui-composer-actions-leading>
+
+  <ui-composer-actions-trailing>
+    <button ui-button type="button" size="icon-sm" aria-label="Send rich text message">Send</button>
+  </ui-composer-actions-trailing>
+</ui-composer>
+```
+
+## Disabled And Invalid
+
+Use the root inputs for shared composer state.
+
+```html
+<ui-composer [disabled]="isSending" [invalid]="promptInvalid">
+  <textarea ui-composer-input rows="2" maxRows="6"></textarea>
+</ui-composer>
+```
+
+For native textarea integrations, `aria-invalid` can still be supplied directly on `textarea[ui-composer-input]` when state comes from another layer.
+
+## API Reference
+
+### `ComposerComponent`
+
+| Input        | Type                     | Default       | Notes                                                                 |
+| ------------ | ------------------------ | ------------- | --------------------------------------------------------------------- |
+| `variant`    | `'default' \| 'input'`   | `'default'`   | Controls shell radius and density.                                    |
+| `inline`     | `boolean`                | `false`       | Places leading actions, input, and trailing actions in a compact row. |
+| `disabled`   | `boolean`                | `false`       | Applies shared disabled treatment and prevents keyboard submit.       |
+| `invalid`    | `boolean`                | `false`       | Applies destructive border and ring treatment.                        |
+| `submit`     | `'cmd-enter' \| 'enter'` | `'cmd-enter'` | Controls keyboard submit behavior.                                    |
+| `submitForm` | `boolean`                | `true`        | Requests native form submission after `submitRequested`.              |
+| `class`      | `string`                 | `''`          | Appends classes to the composer host.                                 |
+
+### `ComposerComponent` output
+
+| Output            | Type            | Notes                                                                 |
+| ----------------- | --------------- | --------------------------------------------------------------------- |
+| `submitRequested` | `KeyboardEvent` | Emitted when keyboard submission is triggered from the input surface. |
+
+### `ComposerTextareaComponent`
+
+| Input          | Type             | Default | Notes                                               |
+| -------------- | ---------------- | ------- | --------------------------------------------------- |
+| `rows`         | `number`         | `2`     | Initial line count.                                 |
+| `maxRows`      | `number \| null` | `null`  | Maximum autosize line count before scrolling.       |
+| `disabled`     | `boolean`        | `false` | Disables the textarea even if the root is enabled.  |
+| `aria-invalid` | `boolean`        | `false` | Applies invalid styling on the textarea input slot. |
+| `class`        | `string`         | `''`    | Appends classes to the textarea host.               |
+
+### Slot Components
+
+`ComposerHeaderComponent`, `ComposerFooterComponent`, `ComposerActionsLeadingComponent`, `ComposerActionsTrailingComponent`, and `ComposerInputComponent` each accept a single `class` input.
+
+## Accessibility
+
+- Pair `textarea[ui-composer-input]` with an accessible label from surrounding copy, `aria-label`, or form-field composition.
+- Give icon-only buttons inside action slots explicit `aria-label` values.
+- Keep meaningful supporting text in `ui-composer-footer` or nearby description content.
+- Use `submit="enter"` carefully in multiline experiences so users still understand `Shift+Enter` for a new line.
+- When projecting a custom editor through `ui-composer-input`, provide `role="textbox"`, `aria-multiline="true"`, and clear keyboard handling in the editor surface itself.
+
+## Keyboard Interactions
+
+- `Cmd+Enter` or `Ctrl+Enter` submits by default.
+- `Enter` submits when `submit="enter"`.
+- `Shift+Enter` keeps inserting new lines in `submit="enter"` mode.
+- Standard textarea editing, selection, clipboard, and IME behavior remain native when using `textarea[ui-composer-input]`.
+
+## Styling And Theming
+
+The composer uses the shared `border-input`, `bg-background`, `ring-ring`, `text-foreground`, and `placeholder:text-muted-foreground` tokens.
+
+Override layout and density by passing `class` to the root or individual slot components.
+Keep the projected input surface transparent so the composer shell remains the visible boundary.
+
+## Angular Notes
+
+- `textarea[ui-composer-input]` remains a native textarea surface and autosizes without replacing native browser editing behavior.
+- `ui-composer-input` is intentionally presentational. It is meant for custom editor projection, not as a built-in rich-text editor.
+- The composer shell is presentational and does not import layout or theme services, which keeps the entrypoint compatible with the library's component-layer rules.
+
+## Source Inspiration
+
+This component borrows the high-level idea of a structured prompt composer from Flux Composer, but the Angular API, slot names, styling tokens, keyboard behavior contract, and examples are implemented specifically for this library's shadcn-style component system.

package/context-menu/README.md

@@ -0,0 +1,267 @@
+# Context Menu
+
+Displays a menu of actions triggered by a right click. The Angular version maps the
+shadcn `ContextMenuTrigger` to a directive on any focusable host and reuses the
+shared menu primitives from [Dropdown Menu](../dropdown-menu/README.md) for the
+overlay content.
+
+## Import
+
+```ts
+import { ContextMenuTriggerDirective } from '@edsis/ui/context-menu';
+import {
+  MenuCheckboxItemComponent,
+  MenuContentDirective,
+  MenuGroupComponent,
+  MenuItemComponent,
+  MenuLabelComponent,
+  MenuRadioGroupComponent,
+  MenuRadioItemComponent,
+  MenuSeparatorComponent,
+  MenuShortcutComponent,
+  MenuSurfaceComponent,
+  MenuTriggerDirective,
+} from '@edsis/ui/dropdown-menu';
+```
+
+## Composition
+
+The Angular composition stays close to shadcn while exposing the root behavior
+through directives and shared menu primitives.
+
+```text
+div[uiContextMenuTrigger]
+└── ng-template[uiMenuContent]
+    └── ui-menu-surface
+        ├── ui-menu-group
+        │   └── button[ui-menu-item]
+        ├── ui-menu-separator
+        ├── button[ui-menu-checkbox-item]
+        ├── ui-menu-label
+        ├── ui-menu-radio-group
+        │   └── button[ui-menu-radio-item]
+        └── button[ui-menu-item][uiMenuTrigger]
+            └── ng-template[uiMenuContent]
+                └── ui-menu-surface
+```
+
+## Basic usage
+
+Prefer a focusable trigger so pointer users can right-click and keyboard users can
+open the same menu with Shift+F10 or the context-menu key.
+
+```html
+<div
+  [uiContextMenuTrigger]="menu"
+  tabindex="0"
+  aria-label="Open file actions"
+  class="flex h-32 w-full max-w-sm items-center justify-center rounded-xl border border-dashed border-border">
+  Right-click here
+</div>
+
+<ng-template uiMenuContent #menu="uiMenuContent">
+  <ui-menu-surface class="w-56">
+    <ui-menu-group>
+      <button ui-menu-item>Profile</button>
+      <button ui-menu-item>Billing</button>
+      <button ui-menu-item>Team</button>
+    </ui-menu-group>
+  </ui-menu-surface>
+</ng-template>
+```
+
+## Common patterns
+
+### Browser-style actions
+
+Use grouped commands and shortcuts for browser or editor surfaces.
+
+```html
+<ui-menu-surface class="w-60">
+  <ui-menu-group>
+    <button ui-menu-item>
+      Back
+      <span ui-menu-shortcut>⌘[</span>
+    </button>
+    <button ui-menu-item [disabled]="true">
+      Forward
+      <span ui-menu-shortcut>⌘]</span>
+    </button>
+    <button ui-menu-item>
+      Reload
+      <span ui-menu-shortcut>⌘R</span>
+    </button>
+  </ui-menu-group>
+</ui-menu-surface>
+```
+
+### Nested tools menu
+
+Map shadcn `ContextMenuSub` to `uiMenuTrigger` on a menu item. This keeps submenu
+composition explicit and works with the same overlay primitive used by dropdown menus.
+
+```html
+<ng-template uiMenuContent #moreTools="uiMenuContent">
+  <ui-menu-surface class="w-48">
+    <button ui-menu-item>Save Page...</button>
+    <button ui-menu-item>Create Shortcut...</button>
+    <button ui-menu-item>Name Window...</button>
+  </ui-menu-surface>
+</ng-template>
+
+<ui-menu-surface class="w-56">
+  <button ui-menu-item [uiMenuTrigger]="moreTools" side="right" align="start">
+    More tools
+    <span class="ml-auto text-xs text-muted-foreground">›</span>
+  </button>
+</ui-menu-surface>
+```
+
+### Checkbox rows
+
+Use checkbox rows for independent toggles such as browser preferences.
+
+```ts
+const showBookmarks = signal(true);
+const showFullUrls = signal(false);
+```
+
+```html
+<ui-menu-surface class="w-56">
+  <ui-menu-group>
+    <button ui-menu-checkbox-item [(checked)]="showBookmarks">Show bookmarks</button>
+    <button ui-menu-checkbox-item [(checked)]="showFullUrls">Show full URLs</button>
+  </ui-menu-group>
+</ui-menu-surface>
+```
+
+### Radio groups
+
+Use `ui-menu-radio-group` when the menu exposes an exclusive choice.
+
+```ts
+const selectedTheme = signal<'light' | 'dark' | 'system'>('system');
+```
+
+```html
+<ui-menu-surface class="w-56">
+  <ui-menu-label [inset]="true">Theme</ui-menu-label>
+  <ui-menu-radio-group [(value)]="selectedTheme">
+    <button ui-menu-radio-item value="light">Light</button>
+    <button ui-menu-radio-item value="dark">Dark</button>
+    <button ui-menu-radio-item value="system">System</button>
+  </ui-menu-radio-group>
+</ui-menu-surface>
+```
+
+### Destructive rows
+
+Pass `variant="destructive"` when the row should read as irreversible.
+
+```html
+<ui-menu-surface class="w-56">
+  <ui-menu-group>
+    <button ui-menu-item>Edit</button>
+    <button ui-menu-item>Share</button>
+  </ui-menu-group>
+  <ui-menu-separator />
+  <ui-menu-group>
+    <button ui-menu-item variant="destructive">Delete</button>
+  </ui-menu-group>
+</ui-menu-surface>
+```
+
+### RTL
+
+Set `dir="rtl"` on the surface and prefer `side="left"` for nested menus so the
+submenu opens toward the visual start edge.
+
+```html
+<ng-template uiMenuContent #rtlTools="uiMenuContent">
+  <ui-menu-surface dir="rtl" lang="ar" class="w-44 text-right">
+    <button ui-menu-item>حفظ الصفحة...</button>
+    <button ui-menu-item>إنشاء اختصار...</button>
+  </ui-menu-surface>
+</ng-template>
+
+<ui-menu-surface dir="rtl" lang="ar" class="w-56 text-right">
+  <button ui-menu-item [uiMenuTrigger]="rtlTools" side="left" align="start">
+    المزيد من الأدوات
+    <span class="mr-auto text-xs text-muted-foreground">‹</span>
+  </button>
+</ui-menu-surface>
+```
+
+## API reference
+
+### `[uiContextMenuTrigger]`
+
+| Input                  | Type                   | Default    |
+| ---------------------- | ---------------------- | ---------- |
+| `uiContextMenuTrigger` | `MenuContentDirective` | _required_ |
+| `disabled`             | `boolean`              | `false`    |
+
+Output: `openedChange: boolean`
+
+Methods:
+
+- `openAt(x, y)` opens the projected surface at the given viewport coordinates.
+- `close()` closes the active overlay.
+
+### Shared menu parts
+
+| Part                            | Purpose                                                                                  |
+| ------------------------------- | ---------------------------------------------------------------------------------------- |
+| `ui-menu-surface`               | Overlay container with roving focus, typeahead, Escape close, and Tab-to-close behavior. |
+| `ui-menu-group`                 | Lightweight grouping wrapper for related rows.                                           |
+| `button[ui-menu-item]`          | Standard command row with optional `variant="destructive"`.                              |
+| `button[ui-menu-checkbox-item]` | Toggle row with `[(checked)]` and `role="menuitemcheckbox"`.                             |
+| `ui-menu-radio-group`           | Exclusive-selection container with signal-friendly `[(value)]`.                          |
+| `button[ui-menu-radio-item]`    | Exclusive option row with `role="menuitemradio"`.                                        |
+| `ui-menu-label`                 | Non-interactive label row.                                                               |
+| `ui-menu-shortcut`              | Right-aligned shortcut hint.                                                             |
+| `ui-menu-separator`             | Visual divider between command groups.                                                   |
+
+For lower-level behavior details, see the Radix Context Menu API reference:
+<https://www.radix-ui.com/docs/primitives/components/context-menu#api-reference>.
+
+## Styling and theming
+
+Pass `class` to `ui-menu-surface`, `ui-menu-group`, labels, and items to tune width,
+spacing, alignment, and emphasis. Destructive rows use the shared `destructive` theme
+tokens. Visible dividers and borders follow the shared border tokens rather than the
+current text color.
+
+## Accessibility
+
+- Make the trigger focusable if keyboard users need access to the menu.
+- Native `contextmenu` is captured and its default prevented.
+- Menu rows expose the expected `menuitem`, `menuitemcheckbox`, and `menuitemradio`
+  roles plus `aria-checked` and `aria-disabled` where appropriate.
+- Keep item labels short and descriptive, and avoid placing unrelated interactive
+  controls inside a menu row.
+
+## Keyboard interactions
+
+- Right click opens the menu at the pointer location.
+- Shift+F10 and the context-menu key open the menu at the trigger center when the
+  trigger is focusable.
+- Arrow Up and Arrow Down move between enabled items.
+- Home and End jump to the start or end of the list.
+- Typeahead matches row text.
+- Enter and Space activate the focused row.
+- Escape and Tab close the surface.
+
+## Angular notes
+
+- There is no dedicated `ui-context-menu` root component. The root behavior lives on the
+  `[uiContextMenuTrigger]` directive plus `ng-template[uiMenuContent]`.
+- Use signals with `[(checked)]` and `[(value)]` for checkbox and radio rows.
+- Reuse `uiMenuTrigger` when a submenu is needed.
+- Long-press support depends on the browser firing the native `contextmenu` event.
+
+## Source parity
+
+This implementation keeps the shadcn information architecture while mapping the trigger
+to Angular directives, submenu behavior to nested `uiMenuTrigger` composition, and
+checkbox or radio state to signal-friendly APIs.

package/date-picker/README.md

@@ -0,0 +1,177 @@
+# Date Picker
+
+Popup date input backed by Angular Material `MatDatepicker`, styled through the shared shadcn token bridge.
+
+The upstream shadcn Date Picker is composed from Popover and Calendar. This Angular library exposes `ui-date-picker` as the app-level wrapper while preserving the same product behavior: an input trigger, a calendar popup, selected state, and date constraints.
+
+## Requires a date adapter
+
+```ts
+import { provideNativeDateAdapter } from '@angular/material/core';
+
+export const appConfig = { providers: [provideNativeDateAdapter()] };
+```
+
+## Import
+
+```ts
+import { DatePickerComponent } from '@edsis/ui/date-picker';
+import { LabelComponent } from '@edsis/ui/label';
+```
+
+## Usage
+
+Pair the picker with a visible label through the `id` input, then bind the selected date through the signal model.
+
+```html
+<label ui-label for="date-picker-demo">Date</label>
+<ui-date-picker id="date-picker-demo" class="w-72" [(value)]="date" placeholder="Pick a date" />
+```
+
+The component also implements `ControlValueAccessor`, so it can be used with reactive forms or `ngModel`.
+
+## Common patterns
+
+### Basic
+
+```html
+<label ui-label for="date-picker-simple">Date</label>
+<ui-date-picker id="date-picker-simple" class="w-44" [(value)]="basicDate" placeholder="Pick a date" />
+```
+
+### Coordinated range
+
+Use two date pickers when the product needs a start and end date but does not need a dedicated range-calendar primitive.
+
+```html
+<div class="grid gap-4 sm:grid-cols-2">
+  <div class="grid gap-2">
+    <label ui-label for="date-range-start">Start date</label>
+    <ui-date-picker id="date-range-start" [(value)]="rangeStart" [max]="rangeEnd()" />
+  </div>
+  <div class="grid gap-2">
+    <label ui-label for="date-range-end">End date</label>
+    <ui-date-picker id="date-range-end" [(value)]="rangeEnd" [min]="rangeStart()" />
+  </div>
+</div>
+```
+
+### Date of birth
+
+Use `startView="multi-year"` and `startAt` for dates that are usually far away from the current month.
+
+```html
+<label ui-label for="date-picker-birth">Date of birth</label>
+<ui-date-picker
+  id="date-picker-birth"
+  class="w-48"
+  [(value)]="birthDate"
+  placeholder="Select date"
+  [startAt]="birthStartAt"
+  startView="multi-year" />
+```
+
+### Date plus time
+
+Pair the date picker with a native `input[type="time"]` for date-time forms.
+
+```html
+<div class="grid gap-4 sm:grid-cols-[minmax(0,12rem)_8rem]">
+  <div class="grid gap-2">
+    <label ui-label for="date-picker-time-date">Date</label>
+    <ui-date-picker id="date-picker-time-date" [(value)]="timeDate" />
+  </div>
+  <div class="grid gap-2">
+    <label ui-label for="date-picker-time-input">Time</label>
+    <input id="date-picker-time-input" ui-input type="time" step="1" [value]="timeValue()" />
+  </div>
+</div>
+```
+
+### Disabled dates
+
+Use `min`, `max`, and `dateFilter` to prevent invalid choices in the calendar before submit.
+
+```ts
+readonly minBookingDate = new Date(2026, 0, 1);
+readonly maxBookingDate = new Date(2026, 11, 31);
+readonly weekdayFilter = (date: Date | null): boolean => {
+  const day = date?.getDay();
+  return day !== 0 && day !== 6;
+};
+```
+
+```html
+<ui-date-picker
+  id="date-picker-subscription"
+  [(value)]="subscriptionDate"
+  [min]="minBookingDate"
+  [max]="maxBookingDate"
+  [dateFilter]="weekdayFilter" />
+```
+
+### RTL
+
+Set `dir="rtl"` on a wrapping container or at the application shell. The picker follows the surrounding direction.
+
+```html
+<div dir="rtl" lang="ar" class="grid max-w-xs gap-2 text-right">
+  <label ui-label for="date-picker-rtl">Date</label>
+  <ui-date-picker id="date-picker-rtl" [(value)]="rtlDate" placeholder="Pick a date" />
+</div>
+```
+
+## API reference
+
+| Input / Model     | Type                                | Default                 |
+| ----------------- | ----------------------------------- | ----------------------- |
+| `value`           | `Date \| null`                      | `null`                  |
+| `id`              | `string \| null`                    | `null`                  |
+| `placeholder`     | `string`                            | `'Pick a date'`         |
+| `required`        | `boolean`                           | `false`                 |
+| `min`             | `Date \| null`                      | `null`                  |
+| `max`             | `Date \| null`                      | `null`                  |
+| `startAt`         | `Date \| null`                      | `null`                  |
+| `startView`       | `'month' \| 'year' \| 'multi-year'` | `'month'`               |
+| `touchUi`         | `boolean`                           | `false`                 |
+| `dateFilter`      | `(date: Date \| null) => boolean`   | `null`                  |
+| `panelClass`      | `string \| string[]`                | `'ui-datepicker-panel'` |
+| `aria-label`      | `string \| null`                    | `null`                  |
+| `aria-labelledby` | `string \| null`                    | `null`                  |
+| `disabled`        | `boolean`                           | `false`                 |
+| `class`           | `string`                            | `''`                    |
+
+## Styling and theming
+
+The host accepts `class` for width and layout utilities. The inner Material form field is full width, so classes such as `w-44`, `w-72`, and `w-full` should be placed on `ui-date-picker`.
+
+The popup panel defaults to `ui-datepicker-panel`, and calendar colors come from the shared Material token bridge for popover, foreground, primary, and ring colors.
+
+## Accessibility
+
+- Pair the date picker with a visible label using the `id` input, or provide `aria-label` / `aria-labelledby`.
+- The input, toggle, popup focus management, calendar grid roles, and date keyboard navigation come from `MatDatepicker`.
+- Use constraints such as `min`, `max`, and `dateFilter` when dates are not selectable.
+- Keep the visible label specific, such as `Start date`, `End date`, or `Subscription date`.
+
+## Keyboard interactions
+
+- Tab moves focus to the date input and toggle button.
+- Enter or Space on the toggle opens the calendar popup.
+- Arrow keys navigate dates while the calendar is open.
+- Enter selects the focused date.
+- Escape closes the popup and returns focus to the trigger.
+
+## Angular notes
+
+- Provide a Material date adapter once at the application root.
+- Use `[(value)]` when binding to a signal-backed `Date | null` value.
+- Use the component as a CVA inside Angular forms when validation and form submission belong to a `FormControl`.
+- `startView="multi-year"` is useful for birthdays and other far-past dates.
+- For range selection today, coordinate two `ui-date-picker` instances with reciprocal `min` and `max` bindings.
+
+## Source parity
+
+This Angular implementation follows the current shadcn Date Picker information architecture while translating React Popover plus Calendar composition into the local Material-backed wrapper.
+
+The upstream Range Picker example is represented as two coordinated `ui-date-picker` controls rather than a single range-calendar API. The upstream Natural Language example can be built by parsing text into a `Date | null` value and binding that value to `ui-date-picker`.