@edsis/ui 0.0.2

package/dialog/README.md

@@ -0,0 +1,237 @@
+# Dialog
+
+Displays a modal surface over the current page, traps focus while open, and restores focus to the previously active element when it closes.
+
+Use Dialog for confirmation flows, compact forms, link sharing, and long-form review tasks that should keep the user in the current context.
+
+## Import
+
+```ts
+import { ButtonComponent } from '@edsis/ui/button';
+import {
+  DialogCloseDirective,
+  DialogComponent,
+  DialogContentComponent,
+  DialogDescriptionComponent,
+  DialogFooterComponent,
+  DialogHeaderComponent,
+  DialogTitleComponent,
+} from '@edsis/ui/dialog';
+import { InputComponent } from '@edsis/ui/input';
+import { LabelComponent } from '@edsis/ui/label';
+```
+
+## Composition
+
+The Angular composition tracks the shadcn structure, with one intentional mapping difference: shadcn `DialogTrigger` becomes any external control that toggles the `open` signal.
+
+```text
+button[ui-button] (external trigger; sets the open signal)
+ui-dialog
+├── built-in close button (optional)
+├── ui-dialog-header
+│   ├── ui-dialog-title
+│   └── ui-dialog-description
+├── ui-dialog-content (optional body wrapper)
+└── ui-dialog-footer
+    └── button[ui-dialog-close] (optional custom close action)
+```
+
+## Basic usage
+
+Use an external button or link to toggle the `open` signal, then declare the dialog structure inside `ui-dialog`.
+
+```html
+<button type="button" ui-button variant="outline" (click)="open.set(true)">Edit profile</button>
+
+<ui-dialog [(open)]="open" aria-labelledby="dialog-title" aria-describedby="dialog-description" class="sm:max-w-sm">
+  <ui-dialog-header>
+    <ui-dialog-title id="dialog-title">Edit profile</ui-dialog-title>
+    <ui-dialog-description id="dialog-description">
+      Make changes to your profile here. Click save when you are done.
+    </ui-dialog-description>
+  </ui-dialog-header>
+
+  <ui-dialog-content class="grid gap-4 py-2">
+    <div class="grid gap-2">
+      <label ui-label for="name">Name</label>
+      <input ui-input id="name" value="Pedro Duarte" />
+    </div>
+    <div class="grid gap-2">
+      <label ui-label for="username">Username</label>
+      <input ui-input id="username" value="@peduarte" />
+    </div>
+  </ui-dialog-content>
+
+  <ui-dialog-footer>
+    <button type="button" ui-button variant="outline" ui-dialog-close>Cancel</button>
+    <button type="button" ui-button (click)="open.set(false)">Save changes</button>
+  </ui-dialog-footer>
+</ui-dialog>
+```
+
+## Common patterns
+
+### Destructive confirmation
+
+Use a short title, short body copy, and explicit cancel/confirm actions for destructive flows.
+
+```html
+<button type="button" ui-button variant="destructive" (click)="confirmOpen.set(true)">Delete project</button>
+
+<ui-dialog [(open)]="confirmOpen">
+  <ui-dialog-header>
+    <ui-dialog-title>Delete this project?</ui-dialog-title>
+    <ui-dialog-description>
+      This action cannot be undone. This permanently deletes your project.
+    </ui-dialog-description>
+  </ui-dialog-header>
+  <ui-dialog-footer>
+    <button type="button" ui-button variant="outline" ui-dialog-close>Cancel</button>
+    <button type="button" ui-button variant="destructive" (click)="confirmOpen.set(false)">Delete</button>
+  </ui-dialog-footer>
+</ui-dialog>
+```
+
+### Custom close button
+
+Hide the built-in corner close control with `[showCloseButton]="false"` and place `button[ui-dialog-close]` wherever dismissal should live.
+
+```html
+<ui-dialog [(open)]="shareOpen" [showCloseButton]="false" class="sm:max-w-md">
+  <ui-dialog-header>
+    <ui-dialog-title>Share link</ui-dialog-title>
+    <ui-dialog-description> Anyone who has this link can view this workspace. </ui-dialog-description>
+  </ui-dialog-header>
+  <ui-dialog-content class="grid gap-4 py-2">
+    <div class="grid gap-2">
+      <label ui-label for="share-link">Link</label>
+      <input ui-input id="share-link" readonly value="https://ui.shadcn.com/docs/components/radix/dialog" />
+    </div>
+  </ui-dialog-content>
+  <ui-dialog-footer class="sm:justify-start">
+    <button type="button" ui-button ui-dialog-close>Close</button>
+  </ui-dialog-footer>
+</ui-dialog>
+```
+
+### No close button
+
+Use `[showCloseButton]="false"` without an internal close action when Escape and backdrop dismissal are enough.
+
+```html
+<ui-dialog [(open)]="noCloseOpen" [showCloseButton]="false">
+  <ui-dialog-header>
+    <ui-dialog-title>No Close Button</ui-dialog-title>
+    <ui-dialog-description>
+      Dismiss this dialog with Escape, the backdrop, or another action you control.
+    </ui-dialog-description>
+  </ui-dialog-header>
+</ui-dialog>
+```
+
+### Sticky footer for long content
+
+Move the scroll region into `ui-dialog-content` and keep the footer outside that overflow container so primary actions remain visible.
+
+```html
+<ui-dialog [(open)]="stickyOpen" [showCloseButton]="false" class="max-h-[85vh] overflow-hidden p-0 sm:max-w-lg">
+  <ui-dialog-header class="px-6 pt-6">
+    <ui-dialog-title>Sticky Footer</ui-dialog-title>
+    <ui-dialog-description>Keep actions visible while the content scrolls.</ui-dialog-description>
+  </ui-dialog-header>
+  <ui-dialog-content class="max-h-[45vh] overflow-y-auto px-6 pb-6">
+    <!-- long content -->
+  </ui-dialog-content>
+  <ui-dialog-footer class="border-t border-border bg-background px-6 py-4 sm:justify-start">
+    <button type="button" ui-button variant="outline" ui-dialog-close>Close</button>
+    <button type="button" ui-button (click)="stickyOpen.set(false)">Save changes</button>
+  </ui-dialog-footer>
+</ui-dialog>
+```
+
+### RTL
+
+Wrap the trigger and dialog in a `dir="rtl"` container or set direction globally in the app shell.
+
+```html
+<div dir="rtl" lang="ar" class="text-right">
+  <button type="button" ui-button variant="outline" (click)="rtlOpen.set(true)">فتح الحوار</button>
+
+  <ui-dialog [(open)]="rtlOpen" [showCloseButton]="false" class="sm:max-w-sm">
+    <ui-dialog-header>
+      <ui-dialog-title>تعديل الملف الشخصي</ui-dialog-title>
+      <ui-dialog-description> قم بإجراء تغييرات على ملفك الشخصي هنا. انقر فوق حفظ عند الانتهاء. </ui-dialog-description>
+    </ui-dialog-header>
+    <ui-dialog-content class="grid gap-4 py-2">
+      <div class="grid gap-2">...</div>
+      <div class="grid gap-2">...</div>
+    </ui-dialog-content>
+    <ui-dialog-footer>
+      <button type="button" ui-button variant="outline" ui-dialog-close>إلغاء</button>
+      <button type="button" ui-button (click)="rtlOpen.set(false)">حفظ التغييرات</button>
+    </ui-dialog-footer>
+  </ui-dialog>
+</div>
+```
+
+## API reference
+
+### `DialogComponent`
+
+| Input                  | Type             | Default   |
+| ---------------------- | ---------------- | --------- |
+| `open` (model)         | `boolean`        | `false`   |
+| `closeOnEscape`        | `boolean`        | `true`    |
+| `closeOnBackdropClick` | `boolean`        | `true`    |
+| `showCloseButton`      | `boolean`        | `true`    |
+| `closeButtonLabel`     | `string`         | `'Close'` |
+| `aria-labelledby`      | `string \| null` | `null`    |
+| `aria-describedby`     | `string \| null` | `null`    |
+| `class`                | `string`         | `''`      |
+
+Output: `openedChange: boolean`. Method: `close()`.
+
+### Parts
+
+| Part                      | Purpose                                                  |
+| ------------------------- | -------------------------------------------------------- |
+| `ui-dialog-header`        | Title and description wrapper                            |
+| `ui-dialog-title`         | Primary dialog label                                     |
+| `ui-dialog-description`   | Supporting copy announced by assistive tech              |
+| `ui-dialog-content`       | Optional body wrapper for forms, grids, and scroll areas |
+| `ui-dialog-footer`        | Action row                                               |
+| `button[ui-dialog-close]` | Custom close action mapped to shadcn `DialogClose`       |
+
+Lower-level behavior is based on the Radix Dialog pattern: <https://www.radix-ui.com/primitives/docs/components/dialog#api-reference>.
+
+## Styling and theming
+
+The dialog surface uses the shared theme tokens for background, border, foreground, and ring colors. Pass `class` to `ui-dialog` when you need to adjust width, max height, overflow strategy, or padding for a specific modal pattern.
+
+Use `ui-dialog-content` and `ui-dialog-footer` classes to create scroll regions, sticky action rows, or wider content layouts without forking the primitive.
+
+## Accessibility
+
+- The surface renders with `role="dialog"` and `aria-modal="true"`.
+- Focus is trapped inside with `FocusTrap` from `@angular/cdk/a11y`.
+- Focus returns to the previously active element when the dialog closes.
+- Escape and backdrop dismissal are enabled by default but can be disabled for stricter flows.
+- Keep titles and descriptions concise so screen readers announce useful context immediately.
+
+## Keyboard interactions
+
+- `Tab` and `Shift+Tab` stay inside the dialog while it is open.
+- `Escape` closes the dialog unless `closeOnEscape` is disabled.
+- Native button activation handles `Enter` and `Space` for dialog actions.
+
+## Angular notes
+
+- This implementation intentionally maps shadcn `DialogTrigger` to an external control that owns the `open` signal.
+- `button[ui-dialog-close]` is the Angular-friendly equivalent of shadcn `DialogClose` for internal dismissal actions.
+- Seed open state with a signal in the owning component and keep the dialog content declarative.
+- Hide the built-in close affordance with `[showCloseButton]="false"` when the footer or body owns dismissal explicitly.
+
+## Source parity
+
+This Angular implementation follows the shadcn Dialog information architecture and examples while translating the interaction model to Angular selectors, signal-driven state, and explicit ownership of the trigger outside the modal content.

package/drawer/README.md

@@ -0,0 +1,145 @@
+# Drawer
+
+Bottom-first modal drawer built on the local Sheet overlay primitive. It mirrors the shadcn Drawer composition while using Angular signals and explicit standalone imports.
+
+## Import
+
+```ts
+import { ButtonComponent } from '@edsis/ui/button';
+import {
+  DrawerCloseDirective,
+  DrawerComponent,
+  DrawerContentComponent,
+  DrawerDescriptionComponent,
+  DrawerFooterComponent,
+  DrawerHeaderComponent,
+  DrawerTitleComponent,
+} from '@edsis/ui/drawer';
+```
+
+## Usage
+
+```ts
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { ButtonComponent } from '@edsis/ui/button';
+import {
+  DrawerCloseDirective,
+  DrawerComponent,
+  DrawerDescriptionComponent,
+  DrawerFooterComponent,
+  DrawerHeaderComponent,
+  DrawerTitleComponent,
+} from '@edsis/ui/drawer';
+
+@Component({
+  selector: 'app-drawer-example',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [
+    ButtonComponent,
+    DrawerCloseDirective,
+    DrawerComponent,
+    DrawerDescriptionComponent,
+    DrawerFooterComponent,
+    DrawerHeaderComponent,
+    DrawerTitleComponent,
+  ],
+  template: `
+    <button type="button" ui-button variant="outline" (click)="open.set(true)">Open Drawer</button>
+
+    <ui-drawer [(open)]="open" aria-labelledby="drawer-title" aria-describedby="drawer-description">
+      <div class="mx-auto w-full max-w-sm">
+        <ui-drawer-header>
+          <ui-drawer-title id="drawer-title">Move Goal</ui-drawer-title>
+          <ui-drawer-description id="drawer-description">Set your daily activity goal.</ui-drawer-description>
+        </ui-drawer-header>
+        <ui-drawer-footer>
+          <button type="button" ui-button>Submit</button>
+          <button type="button" ui-button variant="outline" ui-drawer-close>Cancel</button>
+        </ui-drawer-footer>
+      </div>
+    </ui-drawer>
+  `,
+})
+export class DrawerExampleComponent {
+  protected readonly open = signal(false);
+}
+```
+
+## Common Patterns
+
+### Sides
+
+Drawer defaults to `bottom`, matching the common shadcn and Vaul pattern. Set `side` when the drawer should enter from a different edge.
+
+```html
+<ui-drawer [(open)]="open" side="right" aria-labelledby="drawer-side-title">
+  <ui-drawer-header>
+    <ui-drawer-title id="drawer-side-title">Scrollable Content</ui-drawer-title>
+  </ui-drawer-header>
+  <ui-drawer-content class="max-h-[50vh] overflow-y-auto px-1">
+    <!-- long content -->
+  </ui-drawer-content>
+</ui-drawer>
+```
+
+### Responsive Dialog
+
+Use a desktop breakpoint in the owning component and render Dialog for larger viewports, Drawer for smaller viewports. Keep both surfaces bound to the same `open` signal so trigger and submit actions stay consistent.
+
+```html
+@if (isDesktop()) {
+<ui-dialog [(open)]="open">...</ui-dialog>
+} @else {
+<ui-drawer [(open)]="open">...</ui-drawer>
+}
+```
+
+## API Reference
+
+### DrawerComponent
+
+| Input                  | Type                                     | Default                    |
+| ---------------------- | ---------------------------------------- | -------------------------- |
+| `open`                 | `boolean` model                          | `false`                    |
+| `side`                 | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` for `ui-drawer` |
+| `closeOnEscape`        | `boolean`                                | `true`                     |
+| `closeOnBackdropClick` | `boolean`                                | `true`                     |
+| `aria-labelledby`      | `string \| null`                         | `null`                     |
+| `aria-describedby`     | `string \| null`                         | `null`                     |
+| `class`                | `string`                                 | empty string               |
+
+### Parts
+
+| Part                                            | Purpose                                                                              |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `ui-drawer-header`                              | Title and description wrapper.                                                       |
+| `ui-drawer-title`                               | Accessible title. Provide an `id` and connect it with `aria-labelledby`.             |
+| `ui-drawer-description`                         | Supporting text. Provide an `id` and connect it with `aria-describedby` when useful. |
+| `ui-drawer-content`                             | Optional scroll/body region inside the surface.                                      |
+| `ui-drawer-footer`                              | Action row.                                                                          |
+| `button[ui-drawer-close]`, `a[ui-drawer-close]` | Projected close action equivalent to shadcn `DrawerClose`.                           |
+
+## Styling And Theming
+
+The drawer uses the same theme tokens as Sheet: `bg-background`, `border-border`, `text-foreground`, and `text-muted-foreground`. Pass `class` to tune dimensions such as `max-h-[85vh]`, `sm:max-w-md`, or side-specific scroll behavior.
+
+## Accessibility
+
+- The surface renders with `role="dialog"` and `aria-modal="true"`.
+- Focus is trapped inside the CDK overlay while open and restored to the previously focused element on close.
+- Provide `aria-labelledby` and `aria-describedby` when the drawer contains a title and description.
+- Use native buttons for open, submit, and close actions.
+
+## Keyboard Interactions
+
+- `Tab` and `Shift+Tab` move within the focus-trapped drawer content.
+- `Escape` closes the drawer when `closeOnEscape` is `true`.
+- Enter and Space activate native buttons, including `button[ui-drawer-close]`.
+
+## Angular Notes
+
+The Angular Drawer deliberately uses an external trigger button and `[(open)]` signal binding instead of a `DrawerTrigger` component. This keeps ownership of state explicit and avoids hidden context wiring across overlay portals. `DrawerComponent` is exported as an alias over the same implementation as `SheetComponent`, so fixes to focus management, backdrop dismissal, and edge positioning are shared.
+
+## Source Parity
+
+shadcn Drawer is built on Vaul and includes drag gestures and scale-background options. This Angular version maps the core modal drawer behavior to CDK Overlay and FocusTrap: bottom-first direction, side selection, focus trapping, Escape/backdrop dismissal, close actions, scrollable content, responsive dialog composition, and RTL-friendly content. It does not implement Vaul drag gestures.

package/dropdown-menu/README.md

@@ -0,0 +1,311 @@
+# Dropdown Menu
+
+Accessible menu rendered in a CDK overlay with keyboard navigation (arrow keys,
+Home/End, type-ahead, Escape).
+
+This Angular implementation follows the shadcn Dropdown Menu information architecture while mapping the React root
+component to an explicit trigger directive and projected menu template.
+
+## Import
+
+```ts
+import {
+  MenuCheckboxItemComponent,
+  MenuTriggerDirective,
+  MenuContentDirective,
+  MenuGroupComponent,
+  MenuSurfaceComponent,
+  MenuItemComponent,
+  MenuRadioGroupComponent,
+  MenuRadioItemComponent,
+  MenuSeparatorComponent,
+  MenuLabelComponent,
+  MenuShortcutComponent,
+} from '@edsis/ui/dropdown-menu';
+```
+
+## Usage
+
+```html
+<button
+  ui-button
+  type="button"
+  variant="outline"
+  #accountTrigger="uiMenuTrigger"
+  [uiMenuTrigger]="menu"
+  side="bottom"
+  align="end">
+  Open
+</button>
+
+<ng-template uiMenuContent #menu="uiMenuContent">
+  <ui-menu-surface class="w-56">
+    <ui-menu-group>
+      <ui-menu-label>My account</ui-menu-label>
+      <button ui-menu-item type="button" (selected)="onProfile(); accountTrigger.close()">
+        Profile
+        <span ui-menu-shortcut>⌘P</span>
+      </button>
+      <button ui-menu-item type="button" (selected)="onSettings(); accountTrigger.close()">Settings</button>
+    </ui-menu-group>
+    <ui-menu-separator />
+    <ui-menu-group>
+      <button ui-menu-item type="button" disabled>Disabled</button>
+      <button ui-menu-item type="button" variant="destructive" (selected)="onSignOut(); accountTrigger.close()">
+        Sign out
+      </button>
+    </ui-menu-group>
+  </ui-menu-surface>
+</ng-template>
+```
+
+Use the trigger export when a standard command row should dismiss the overlay. Checkbox and radio rows can stay open so
+the user can adjust multiple settings in one pass.
+
+## Composition
+
+```text
+button[ui-button][uiMenuTrigger]
+└── ng-template[uiMenuContent]
+    └── ui-menu-surface
+        ├── ui-menu-group
+        │   ├── ui-menu-label
+        │   ├── button[ui-menu-item]
+        │   └── button[ui-menu-item][uiMenuTrigger]
+        │       └── ng-template[uiMenuContent]
+        │           └── ui-menu-surface
+        ├── ui-menu-separator
+        ├── button[ui-menu-checkbox-item]
+        └── ui-menu-radio-group
+            └── button[ui-menu-radio-item]
+```
+
+## Common patterns
+
+### Basic account menu
+
+```html
+<button ui-button type="button" variant="outline" #menuTrigger="uiMenuTrigger" [uiMenuTrigger]="menu">Open</button>
+
+<ng-template uiMenuContent #menu="uiMenuContent">
+  <ui-menu-surface class="w-56">
+    <ui-menu-group>
+      <ui-menu-label>My Account</ui-menu-label>
+      <button ui-menu-item type="button" (selected)="menuTrigger.close()">Profile</button>
+      <button ui-menu-item type="button" (selected)="menuTrigger.close()">Billing</button>
+      <button ui-menu-item type="button" (selected)="menuTrigger.close()">Settings</button>
+    </ui-menu-group>
+    <ui-menu-separator />
+    <ui-menu-group>
+      <button ui-menu-item type="button" (selected)="menuTrigger.close()">GitHub</button>
+      <button ui-menu-item type="button" (selected)="menuTrigger.close()">Support</button>
+      <button ui-menu-item type="button" [disabled]="true">API</button>
+    </ui-menu-group>
+  </ui-menu-surface>
+</ng-template>
+```
+
+### Submenu
+
+Map shadcn `DropdownMenuSub` to `uiMenuTrigger` on a `button[ui-menu-item]`.
+
+```html
+<ng-template uiMenuContent #inviteUsersMenu="uiMenuContent">
+  <ui-menu-surface class="w-48">
+    <button ui-menu-item type="button">Email</button>
+    <button ui-menu-item type="button">Message</button>
+    <button ui-menu-item type="button">Calendar invite</button>
+  </ui-menu-surface>
+</ng-template>
+
+<ui-menu-surface class="w-56">
+  <ui-menu-group>
+    <button ui-menu-item type="button">Team</button>
+    <button ui-menu-item type="button" [uiMenuTrigger]="inviteUsersMenu" side="right" align="start">
+      Invite users
+      <span class="ml-auto text-xs text-muted-foreground">›</span>
+    </button>
+  </ui-menu-group>
+</ui-menu-surface>
+```
+
+### Checkboxes
+
+Use checkbox rows when the menu exposes independent toggles.
+
+```ts
+const showStatusBar = signal(true);
+const showActivityBar = signal(false);
+const showPanel = signal(false);
+```
+
+```html
+<ui-menu-surface class="w-44">
+  <ui-menu-group>
+    <ui-menu-label>Appearance</ui-menu-label>
+    <button ui-menu-checkbox-item type="button" [(checked)]="showStatusBar">Status Bar</button>
+    <button ui-menu-checkbox-item type="button" [(checked)]="showActivityBar">Activity Bar</button>
+    <button ui-menu-checkbox-item type="button" [(checked)]="showPanel">Panel</button>
+  </ui-menu-group>
+</ui-menu-surface>
+```
+
+### Radio group
+
+Use a radio group for one exclusive choice.
+
+```ts
+const panelPosition = signal<'top' | 'bottom' | 'right'>('bottom');
+```
+
+```html
+<ui-menu-surface class="w-44">
+  <ui-menu-label [inset]="true">Panel Position</ui-menu-label>
+  <ui-menu-radio-group [(value)]="panelPosition">
+    <button ui-menu-radio-item type="button" value="top">Top</button>
+    <button ui-menu-radio-item type="button" value="bottom">Bottom</button>
+    <button ui-menu-radio-item type="button" value="right">Right</button>
+  </ui-menu-radio-group>
+</ui-menu-surface>
+```
+
+### Shortcuts and icons
+
+Project shortcut text and inline icons directly into the row content.
+
+```html
+<ui-menu-surface class="w-56">
+  <button ui-menu-item type="button">
+    <svg aria-hidden="true" class="size-4" viewBox="0 0 24 24">...</svg>
+    Profile
+    <span ui-menu-shortcut>⇧⌘P</span>
+  </button>
+  <button ui-menu-item type="button">
+    <svg aria-hidden="true" class="size-4" viewBox="0 0 24 24">...</svg>
+    Billing
+    <span ui-menu-shortcut>⌘B</span>
+  </button>
+</ui-menu-surface>
+```
+
+### Avatar trigger composition
+
+Also import the avatar entrypoint when the trigger should be an account avatar.
+
+```ts
+import { AvatarComponent, AvatarFallbackComponent, AvatarImageComponent } from '@edsis/ui/avatar';
+```
+
+```html
+<button
+  ui-button
+  type="button"
+  variant="ghost"
+  size="icon"
+  class="h-10 w-10 rounded-full p-0"
+  [uiMenuTrigger]="accountMenu"
+  align="end">
+  <ui-avatar>
+    <ui-avatar-image src="https://github.com/shadcn.png" alt="Ada Lovelace" />
+    <ui-avatar-fallback>AL</ui-avatar-fallback>
+  </ui-avatar>
+</button>
+```
+
+### RTL
+
+Set `dir="rtl"` and `lang` on the surface, and prefer `side="left"` when nested content should open toward the visual
+start edge.
+
+```html
+<ng-template uiMenuContent #rtlAccountMenu="uiMenuContent">
+  <ui-menu-surface dir="rtl" lang="ar" class="w-44 text-right">
+    <button ui-menu-item type="button">الملف الشخصي</button>
+    <button ui-menu-item type="button">الفوترة</button>
+  </ui-menu-surface>
+</ng-template>
+
+<ui-menu-surface dir="rtl" lang="ar" class="w-56 text-right">
+  <button ui-menu-item type="button" [uiMenuTrigger]="rtlAccountMenu" side="left" align="start">
+    الحساب
+    <span class="mr-auto text-xs text-muted-foreground">‹</span>
+  </button>
+</ui-menu-surface>
+```
+
+## API
+
+### `[uiMenuTrigger]`
+
+| Input           | Type                                     | Default    |
+| --------------- | ---------------------------------------- | ---------- |
+| `uiMenuTrigger` | `MenuContentDirective`                   | _required_ |
+| `side`          | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` |
+| `align`         | `'start' \| 'center' \| 'end'`           | `'start'`  |
+| `disabled`      | `boolean`                                | `false`    |
+
+Output: `openedChange: boolean`. Methods: `open()`, `close()`, `toggle()`.
+
+### `ng-template[uiMenuContent]`
+
+Projected template wrapper for the menu surface that is consumed by `[uiMenuTrigger]`.
+
+### `ui-menu-surface`
+
+Container with `role="menu"` and arrow key navigation wired through
+`FocusKeyManager` (wrapping + type-ahead). Emits `closeRequested` on Tab.
+
+### `ui-menu-item`
+
+`role="menuitem"`. Inputs: `disabled`, `inset`, `class`. Output: `selected`.
+
+### `ui-menu-checkbox-item`
+
+`role="menuitemcheckbox"`. Inputs: `[(checked)]`, `disabled`, `variant`, `class`.
+
+### `ui-menu-radio-group` and `ui-menu-radio-item`
+
+Use `[(value)]` on the group and `value` on each radio row. Radio items expose `role="menuitemradio"`.
+
+### Auxiliary
+
+- `ui-menu-group` → structural wrapper with `role="group"`.
+- `ui-menu-separator` → `role="separator"`.
+- `ui-menu-label` — non-interactive label row.
+- `ui-menu-shortcut` — right-aligned shortcut badge.
+
+## Styling and theming
+
+Pass `class` to the surface or individual rows to control width, spacing, and emphasis. Borders and separators use the
+shared theme border tokens, destructive rows use the destructive palette, and projected icons inherit the current text
+color.
+
+## Accessibility
+
+- Trigger: `aria-haspopup="menu"`, `aria-expanded` reflects state.
+- Surface: `role="menu"`, items receive `role="menuitem"`, disabled items get
+  `aria-disabled="true"`.
+- Checkbox and radio items expose `aria-checked` semantics through the relevant menuitem roles.
+- Close on outside click, Escape, or Tab. Focus returns to the trigger.
+
+## Keyboard interactions
+
+- Enter, Space, and ArrowDown on the trigger open the menu.
+- Arrow Up and Arrow Down move between enabled rows; Home and End jump to the first or last row.
+- Typeahead matches the row label text.
+- Enter and Space activate the focused row.
+
+## Angular notes
+
+- There is no React-style `DropdownMenu` root component; the root behavior is handled by `uiMenuTrigger` and
+  `ng-template[uiMenuContent]`.
+- Reuse `uiMenuTrigger` on `button[ui-menu-item]` when you need a submenu.
+- Standard command rows can dismiss the overlay explicitly through a `#menuTrigger="uiMenuTrigger"` template reference,
+  while checkbox and radio rows can stay open for multi-step preference changes.
+
+## Source parity
+
+This Angular entrypoint keeps the main shadcn dropdown-menu patterns: grouped commands, shortcuts, icons, nested menus,
+checkbox items, radio groups, avatar triggers, destructive rows, and RTL guidance. The shadcn page includes additional
+permutations such as checkbox-icons, radio-icons, and a very large complex menu; the local demos cover the same
+primitives through representative compositions instead of duplicating every permutation one-to-one.