@edsis/ui 0.0.2

package/kbd/README.md

@@ -0,0 +1,139 @@
+# Kbd
+
+Keyboard key primitive for shortcuts, inline command hints, and compact keycap groups.
+
+Use Kbd when the UI needs to display the key or shortcut that triggers an action, not to capture keyboard input itself.
+
+## Import
+
+```ts
+import { KbdComponent, KbdGroupComponent } from '@edsis/ui/kbd';
+```
+
+## Composition
+
+The Angular structure mirrors shadcn's `Kbd` and `KbdGroup` composition while keeping the host choice flexible.
+
+```text
+kbd[ui-kbd] or ui-kbd
+ui-kbd-group or [ui-kbd-group]
+├── kbd[ui-kbd] or ui-kbd
+└── kbd[ui-kbd] or ui-kbd
+```
+
+## Basic usage
+
+Prefer a native `<kbd>` host when you want built-in keyboard-input semantics in the DOM.
+
+```html
+<p class="inline-flex items-center gap-2 text-sm text-muted-foreground">
+  Press <kbd ui-kbd>Ctrl</kbd> <kbd ui-kbd>K</kbd> to open search.
+</p>
+```
+
+## Common patterns
+
+### Key groups
+
+Use `ui-kbd-group` when several keycaps should read as one shortcut cluster or one family of related commands.
+
+```html
+<ui-kbd-group>
+  <kbd ui-kbd>Ctrl + B</kbd>
+  <kbd ui-kbd>Ctrl + K</kbd>
+</ui-kbd-group>
+```
+
+### Button companion
+
+Use Kbd inside the button label when the shortcut is part of the visible affordance.
+
+```html
+<button ui-button type="button" variant="outline">
+  Accept
+  <kbd ui-kbd class="translate-x-0.5">⏎</kbd>
+</button>
+```
+
+### Input group shortcut hint
+
+Pair Kbd with the existing input-group primitives for launcher shortcuts and command-palette patterns.
+
+```html
+<ui-input-group class="max-w-sm">
+  <input ui-input-group-input placeholder="Search..." />
+  <ui-input-group-addon>
+    <span aria-hidden="true">⌕</span>
+  </ui-input-group-addon>
+  <ui-input-group-addon align="inline-end">
+    <ui-kbd-group>
+      <kbd ui-kbd>⌘</kbd>
+      <kbd ui-kbd>K</kbd>
+    </ui-kbd-group>
+  </ui-input-group-addon>
+</ui-input-group>
+```
+
+### Tooltip mapping
+
+The local tooltip primitive is a thin string-based wrapper around `matTooltip`, so rich tooltip content with embedded Kbd chips maps to plain tooltip text plus optional visible shortcut chips in adjacent markup.
+
+```html
+<button ui-button type="button" variant="outline" [uiTooltip]="'Save changes (S)'">Save</button>
+<button ui-button type="button" variant="outline" [uiTooltip]="'Print document (Ctrl + P)'">Print</button>
+```
+
+### RTL
+
+Set `dir="rtl"` on an ancestor container when the shortcut rows live in a right-to-left layout.
+
+```html
+<div dir="rtl" lang="ar" class="flex flex-col items-center gap-4">
+  <ui-kbd-group>
+    <kbd ui-kbd>⌘</kbd>
+    <kbd ui-kbd>⇧</kbd>
+    <kbd ui-kbd>⌥</kbd>
+    <kbd ui-kbd>⌃</kbd>
+  </ui-kbd-group>
+
+  <ui-kbd-group>
+    <kbd ui-kbd>Ctrl</kbd>
+    <span aria-hidden="true">+</span>
+    <kbd ui-kbd>B</kbd>
+  </ui-kbd-group>
+</div>
+```
+
+## API reference
+
+| Primitive           | Input   | Type     | Default | Notes                                         |
+| ------------------- | ------- | -------- | ------- | --------------------------------------------- |
+| `KbdComponent`      | `class` | `string` | `''`    | Extra Tailwind classes merged onto the keycap |
+| `KbdGroupComponent` | `class` | `string` | `''`    | Extra Tailwind classes merged onto the group  |
+
+## Styling and theming
+
+`ui-kbd` uses `border-border`, `bg-background`, `text-foreground`, and the shared `rounded-md` radius token so it stays aligned with buttons, inputs, and tooltip surfaces.
+
+The default typography is mono, compact, and non-selectable to match shadcn's keycap treatment without introducing a separate icon or badge variant system.
+
+## Accessibility
+
+- Prefer `<kbd ui-kbd>` when you want native keyboard-input semantics in the markup.
+- Keep decorative separators such as `+` or `/` `aria-hidden` when the surrounding sentence already communicates the shortcut clearly.
+- Kbd is presentational. The actionable control still needs the accessible name, tooltip text, and focus behavior.
+
+## Keyboard interactions
+
+Kbd and KbdGroup do not add keyboard behavior. Buttons, links, inputs, tooltip triggers, and menu items composed with them keep their native keyboard model.
+
+## Angular notes
+
+- There is no React-style `data-icon="inline-end"` API. Use the normal `class` input for spacing or alignment adjustments.
+- Import neighboring primitives such as Button, Input Group, or Tooltip separately. The Kbd entrypoint stays intentionally focused.
+
+## Source parity
+
+This Angular slice covers the shadcn Kbd preview, grouped keycaps, button companion usage, input-group shortcut hints, RTL examples, and API/accessibility guidance.
+
+The upstream tooltip example uses rich tooltip content with embedded keycaps. In this repo that maps to the existing string-based tooltip directive, so the shortcut lives in the tooltip message instead of projected tooltip markup.

package/label/README.md

@@ -0,0 +1,136 @@
+# Label
+
+Renders accessible labels for native form controls and provides the wrapper-label pattern for checkbox, radio, and switch rows where the entire copy block should toggle the control.
+
+Use `ui-label` when a lightweight visible label is enough. For richer form-field layouts with descriptions, grouped sections, and generated id wiring, use the `form` entrypoint and `label[ui-form-label]` instead.
+
+## Import
+
+```ts
+import { LabelComponent } from '@edsis/ui/label';
+```
+
+## Composition
+
+The label primitive supports three common structures:
+
+```text
+ui-label[for] + native control[id]
+label[ui-label] + native control[id]
+label[ui-label]
+├── ui-checkbox | ui-radio | ui-switch
+└── descriptive copy
+```
+
+For full form-field composition, map the shadcn `Field` guidance to `ui-form-field`, `label[ui-form-label]`, and `[uiFormControl]` from `@edsis/ui/form`.
+
+## Basic usage
+
+Use `for` when the target control exposes a stable native `id`, such as an input or textarea.
+
+```html
+<div class="grid gap-2">
+  <ui-label for="email">Email address</ui-label>
+  <input ui-input id="email" type="email" placeholder="you@example.com" />
+</div>
+```
+
+You can also decorate a native label host when that fits the surrounding markup more naturally.
+
+```html
+<label ui-label for="email">Email address</label>
+<input ui-input id="email" type="email" placeholder="you@example.com" />
+```
+
+## Common patterns
+
+### Checkbox, radio, and switch rows
+
+When the entire row should toggle the control, wrap the control and copy in `label[ui-label]`. This is the closest Angular equivalent to the upstream shadcn checkbox-plus-label preview.
+
+```html
+<label ui-label class="inline-flex max-w-md items-start gap-3 rounded-xl border border-border p-4">
+  <ui-checkbox class="mt-0.5" />
+  <span class="grid gap-1 leading-none">
+    <span>Email me product updates</span>
+    <span class="text-sm font-normal leading-5 text-muted-foreground">
+      Wrap checkbox, radio, and switch rows in label[ui-label] when the whole row should toggle the control.
+    </span>
+  </span>
+</label>
+```
+
+### Label in Field
+
+The shadcn docs route richer field composition to `Field`. In this library, use the `form` entrypoint instead.
+
+```html
+<ui-form-field class="max-w-md">
+  <label ui-form-label>Email address</label>
+  <input ui-input uiFormControl type="email" placeholder="you@example.com" />
+  <p ui-form-description>We will only use this address for account updates.</p>
+</ui-form-field>
+```
+
+`label[ui-form-label]` automatically targets the generated control id from `[uiFormControl]`, so helper text and invalid state remain synchronized without manual `for` wiring.
+
+### RTL
+
+The label primitive is direction-agnostic. Apply `dir="rtl"` on a wrapper and reverse the row layout when the label and control should read from right to left.
+
+```html
+<div dir="rtl" lang="ar" class="max-w-md text-right">
+  <label ui-label class="flex flex-row-reverse items-start gap-3">
+    <ui-checkbox class="mt-0.5" />
+    <span class="grid gap-1 leading-none">
+      <span>قبول الشروط والأحكام</span>
+      <span class="text-sm font-normal leading-5 text-muted-foreground">
+        يظل نمط التسمية نفسه، فقط ضع الصف داخل حاوية تدعم الاتجاه من اليمين إلى اليسار.
+      </span>
+    </span>
+  </label>
+</div>
+```
+
+## API reference
+
+### `LabelComponent`
+
+| Input   | Type             | Default |
+| ------- | ---------------- | ------- |
+| `for`   | `string \| null` | `null`  |
+| `class` | `string`         | `''`    |
+
+Selectors: `ui-label`, `label[ui-label]`
+
+Related mapping: for shadcn `FieldLabel`, use `label[ui-form-label]` from `@edsis/ui/form`.
+
+## Styling and theming
+
+Base classes: `text-sm font-medium leading-none text-foreground`.
+
+- Pass `class` to tune spacing, layout, or typography for a specific label row.
+- `peer-disabled:cursor-not-allowed peer-disabled:opacity-70` dims the label when a peer-marked control is disabled.
+- Standard library theme tokens such as `text-foreground`, `text-muted-foreground`, `border-border`, and spacing utilities compose cleanly with the label host.
+
+## Accessibility
+
+- Set `for` only when the target control exposes a real native id.
+- Wrap checkbox, radio, and switch rows in `label[ui-label]` instead of relying on `for` to reach an internal input element.
+- Inside `ui-form-field`, prefer `label[ui-form-label]` so helper text and invalid state stay synchronized with `[uiFormControl]`.
+- Keep label text specific so screen readers and voice-control software announce useful control names.
+
+## Keyboard interactions
+
+- Labels themselves are not the main keyboard target; focus moves to the associated control in normal tab order.
+- Once the control has focus, keyboard behavior belongs to that control, such as `Space` toggling a checkbox.
+
+## Angular notes
+
+- Use `ui-label` or `label[ui-label]` for lightweight labeling only.
+- Use the `form` entrypoint when the surface also needs descriptions, errors, grouped sections, or generated `for` wiring.
+- The checkbox, radio, and switch families work best with wrapper labels because those controls own their internal focusable element.
+
+## Source parity
+
+This Angular slice keeps the shadcn Label guidance around installation, usage, field composition, RTL behavior, and API shape while mapping the upstream `Field` recommendation to the local `form` entrypoint and expressing checkbox-like examples with a wrapper-label pattern that fits the existing Angular primitives.

package/menubar/README.md

@@ -0,0 +1,269 @@
+# Menubar
+
+Persistent desktop-style command strip with horizontal roving focus for top-level triggers and explicit projected menu content.
+
+This Angular implementation follows the shadcn Menubar information architecture while intentionally reusing the existing dropdown-menu content primitives for rows, checkbox items, radio groups, labels, shortcuts, and nested submenu triggers.
+
+## Import
+
+```ts
+import {
+  MenubarComponent,
+  MenubarContentDirective,
+  MenubarMenuComponent,
+  MenubarTriggerDirective,
+} from '@edsis/ui/menubar';
+import {
+  MenuCheckboxItemComponent,
+  MenuContentDirective,
+  MenuGroupComponent,
+  MenuItemComponent,
+  MenuLabelComponent,
+  MenuRadioGroupComponent,
+  MenuRadioItemComponent,
+  MenuSeparatorComponent,
+  MenuShortcutComponent,
+  MenuSurfaceComponent,
+  MenuTriggerDirective,
+} from '@edsis/ui/dropdown-menu';
+```
+
+## Structure
+
+```text
+ui-menubar
+├── ui-menubar-menu
+│   ├── button[uiMenubarTrigger]
+│   └── ng-template[uiMenubarContent]
+│       └── ui-menu-surface
+│           ├── ui-menu-group
+│           │   ├── 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]
+└── ui-menubar-menu
+    ├── button[uiMenubarTrigger]
+    └── ng-template[uiMenubarContent]
+```
+
+## Basic usage
+
+```html
+<ui-menubar>
+  <ui-menubar-menu>
+    <button type="button" [uiMenubarTrigger]="fileMenu">File</button>
+    <ng-template uiMenubarContent #fileMenu="uiMenubarContent">
+      <ui-menu-surface class="w-56">
+        <ui-menu-group>
+          <button ui-menu-item type="button">
+            New Tab
+            <span ui-menu-shortcut>⌘T</span>
+          </button>
+          <button ui-menu-item type="button" [uiMenuTrigger]="shareMenu" side="right" align="start">
+            Share
+            <span class="ml-auto text-xs text-muted-foreground">›</span>
+          </button>
+        </ui-menu-group>
+      </ui-menu-surface>
+    </ng-template>
+  </ui-menubar-menu>
+</ui-menubar>
+```
+
+## Common patterns
+
+### Basic command strip
+
+Use one `ui-menubar-menu` per top-level trigger. The root owns horizontal roving focus, so only one trigger participates in tab order at a time.
+
+```html
+<ui-menubar>
+  <ui-menubar-menu>
+    <button type="button" [uiMenubarTrigger]="basicFileMenu">File</button>
+    <ng-template uiMenubarContent #basicFileMenu="uiMenubarContent">
+      <ui-menu-surface class="w-48">
+        <button ui-menu-item type="button">New Tab</button>
+        <button ui-menu-item type="button">Open Recent</button>
+        <button ui-menu-item type="button" [disabled]="true">Import from iCloud</button>
+      </ui-menu-surface>
+    </ng-template>
+  </ui-menubar-menu>
+</ui-menubar>
+```
+
+### Checkbox and radio rows
+
+The top-level strip stays on `menubar`, while toggleable content rows remain on the dropdown-menu primitives that already own those semantics.
+
+```ts
+const showSidebar = signal(true);
+const editorTheme = signal<'light' | 'dark' | 'system'>('system');
+```
+
+```html
+<ui-menubar>
+  <ui-menubar-menu>
+    <button type="button" [uiMenubarTrigger]="viewMenu">View</button>
+    <ng-template uiMenubarContent #viewMenu="uiMenubarContent">
+      <ui-menu-surface class="w-56">
+        <ui-menu-group>
+          <button ui-menu-checkbox-item type="button" [(checked)]="showSidebar">Sidebar</button>
+        </ui-menu-group>
+        <ui-menu-separator />
+        <ui-menu-label [inset]="true">Theme</ui-menu-label>
+        <ui-menu-radio-group [(value)]="editorTheme">
+          <button ui-menu-radio-item type="button" value="light">Light</button>
+          <button ui-menu-radio-item type="button" value="dark">Dark</button>
+          <button ui-menu-radio-item type="button" value="system">System</button>
+        </ui-menu-radio-group>
+      </ui-menu-surface>
+    </ng-template>
+  </ui-menubar-menu>
+</ui-menubar>
+```
+
+### Submenus
+
+Map shadcn `MenubarSub` to `[uiMenuTrigger]` on a `button[ui-menu-item]`. This keeps overlay ownership explicit and lets the shared menu trigger keep submenu keyboard behavior in one place.
+
+```html
+<ng-template uiMenuContent #findMenu="uiMenuContent">
+  <ui-menu-surface class="w-44">
+    <button ui-menu-item type="button">Search the web</button>
+    <button ui-menu-item type="button">Find...</button>
+    <button ui-menu-item type="button">Find Next</button>
+  </ui-menu-surface>
+</ng-template>
+
+<ui-menubar>
+  <ui-menubar-menu>
+    <button type="button" [uiMenubarTrigger]="editMenu">Edit</button>
+    <ng-template uiMenubarContent #editMenu="uiMenubarContent">
+      <ui-menu-surface class="w-56">
+        <button ui-menu-item type="button" [uiMenuTrigger]="findMenu" side="right" align="start">
+          Find
+          <span class="ml-auto text-xs text-muted-foreground">›</span>
+        </button>
+      </ui-menu-surface>
+    </ng-template>
+  </ui-menubar-menu>
+</ui-menubar>
+```
+
+### Icons and shortcuts
+
+Project inline icons and shortcut hints directly into the row content.
+
+```html
+<ui-menu-surface class="w-56">
+  <button ui-menu-item type="button">
+    <ui-nav-icon name="description" [size]="16" class="text-muted-foreground" />
+    New File
+    <span ui-menu-shortcut>⌘N</span>
+  </button>
+  <button ui-menu-item type="button" variant="destructive">
+    <ui-nav-icon name="delete" [size]="16" class="text-current" />
+    Delete
+  </button>
+</ui-menu-surface>
+```
+
+### RTL
+
+The root menubar respects computed direction for left and right movement. Apply `dir="rtl"` directly to the projected menu surface when the content itself should render right-to-left.
+
+```html
+<section dir="rtl" lang="ar" class="text-right">
+  <ui-menubar>
+    <ui-menubar-menu>
+      <button type="button" [uiMenubarTrigger]="rtlFileMenu">ملف</button>
+      <ng-template uiMenubarContent #rtlFileMenu="uiMenubarContent">
+        <ui-menu-surface dir="rtl" lang="ar" class="w-56 text-right">
+          <button ui-menu-item type="button">تبويب جديد <span ui-menu-shortcut>⌘T</span></button>
+          <button ui-menu-item type="button">نافذة جديدة <span ui-menu-shortcut>⌘N</span></button>
+        </ui-menu-surface>
+      </ng-template>
+    </ui-menubar-menu>
+  </ui-menubar>
+</section>
+```
+
+## API Reference
+
+### `MenubarComponent`
+
+| Input   | Type      | Default |
+| ------- | --------- | ------- |
+| `class` | `string`  | `''`    |
+| `loop`  | `boolean` | `true`  |
+
+Role: `menubar`.
+
+### `MenubarMenuComponent`
+
+Structural wrapper for one top-level trigger plus its `uiMenubarContent` template.
+
+### `MenubarTriggerDirective`
+
+| Input              | Type                           | Default   |
+| ------------------ | ------------------------------ | --------- |
+| `uiMenubarTrigger` | `MenubarContentDirective`      | required  |
+| `align`            | `'start' \| 'center' \| 'end'` | `'start'` |
+| `disabled`         | `boolean`                      | `false`   |
+
+Output: `openedChange: boolean`.
+
+Methods: `open()`, `close()`, `toggle()`, `focus()`.
+
+### `MenubarContentDirective`
+
+Projected overlay template for a top-level menubar trigger.
+
+### Dropdown-menu parts reused in content
+
+Import these from `@edsis/ui/dropdown-menu`:
+
+- `MenuSurfaceComponent`
+- `MenuItemComponent`
+- `MenuCheckboxItemComponent`
+- `MenuRadioGroupComponent`
+- `MenuRadioItemComponent`
+- `MenuLabelComponent`
+- `MenuSeparatorComponent`
+- `MenuShortcutComponent`
+- `MenuTriggerDirective`
+- `MenuContentDirective`
+
+## Styling and theming
+
+- Pass `class` to `ui-menubar` when the root needs width, border, or layout changes.
+- Style content surfaces on `ui-menu-surface`, not on the root menubar strip.
+- Use shared theme tokens such as `border-border`, `bg-background`, `bg-accent`, and `text-muted-foreground` for visual consistency.
+
+## Accessibility
+
+- Top-level triggers expose `role="menuitem"`, `aria-haspopup="menu"`, and `aria-expanded`.
+- The root menubar keeps one active tab stop, matching desktop menubar behavior.
+- Projected content rows keep the accessible menu, checkbox, and radio roles from dropdown-menu.
+- Disabled rows stay visible, announce their disabled state, and are skipped by roving focus.
+
+## Keyboard interactions
+
+- `ArrowLeft` and `ArrowRight` move across top-level triggers.
+- `Home` and `End` jump to the first and last top-level trigger.
+- `ArrowDown` opens the active menu and focuses its first enabled item.
+- `ArrowRight` opens right-side submenu rows built with `[uiMenuTrigger] side="right"`.
+
+## Angular Notes
+
+- Menubar is intentionally split across two entrypoints: `menubar` for the persistent strip, `dropdown-menu` for the shared content rows.
+- This avoids duplicating the same menu item semantics in two packages while still exposing a dedicated shadcn-style top-level component.
+- Use native buttons for triggers so keyboard activation and disabled behavior stay predictable.
+
+## Source parity
+
+This slice keeps the shadcn Menubar command patterns, examples, keyboard expectations, and RTL guidance while making Angular overlay ownership explicit through `uiMenubarContent` and the existing dropdown-menu primitives.