@edsis/ui 0.0.2

package/combobox/README.md

@@ -0,0 +1,198 @@
+# Combobox
+
+Searchable single-select surface built from a button trigger, a CDK overlay,
+and the shared [Command](../command/README.md) list primitives.
+
+Use Combobox when users need type-to-filter selection from a medium-sized list
+without leaving the current form, settings screen, or dashboard panel.
+
+## Import
+
+```ts
+import { ComboboxComponent, type ComboboxOption } from '@edsis/ui/combobox';
+```
+
+## Composition
+
+The Angular structure maps the combobox idea onto the existing library stack:
+
+```text
+ui-combobox
+├── button[role="combobox"]
+└── CDK overlay
+    └── ui-command
+        ├── input[ui-command-input]
+        └── ui-command-list
+            └── button[ui-command-item]
+```
+
+This differs from the current shadcn Base UI page, which documents an input-first
+combobox. The Angular library currently ships the common searchable single-select
+pattern on top of Button + Command + CDK Overlay.
+
+## Basic usage
+
+Bind `[(value)]` when a signal or parent component should own the selected value.
+Pass width or layout utilities through the host `class`; the trigger fills that
+host width.
+
+```ts
+frameworkOptions: ComboboxOption<string>[] = [
+  { value: 'angular', label: 'Angular' },
+  { value: 'nextjs', label: 'Next.js' },
+  { value: 'astro', label: 'Astro' },
+];
+
+selectedFramework = signal<string | null>(null);
+```
+
+```html
+<ui-combobox
+  class="w-80"
+  [options]="frameworkOptions"
+  [(value)]="selectedFramework"
+  placeholder="Select framework"
+  searchPlaceholder="Search frameworks..." />
+```
+
+## Common patterns
+
+### Object-backed values
+
+Option values can be full domain objects, not only strings.
+
+```ts
+type Country = {
+  code: string;
+  label: string;
+  region: string;
+  currency: string;
+};
+
+countryOptions: ComboboxOption<Country>[] = [
+  {
+    value: { code: 'ca', label: 'Canada', region: 'North America', currency: 'CAD' },
+    label: 'Canada',
+  },
+  {
+    value: { code: 'jp', label: 'Japan', region: 'Asia', currency: 'JPY' },
+    label: 'Japan',
+  },
+];
+
+selectedCountry = signal<Country | null>(countryOptions[0]?.value ?? null);
+```
+
+```html
+<ui-combobox
+  class="w-full max-w-sm"
+  [options]="countryOptions"
+  [(value)]="selectedCountry"
+  placeholder="Select country"
+  searchPlaceholder="Search countries..." />
+```
+
+### Disabled options and empty states
+
+Mark options with `disabled: true` when they should stay visible but unavailable.
+Tune `searchPlaceholder` and `emptyText` so large lists feel intentional.
+
+```ts
+feedOptions: ComboboxOption<string>[] = [
+  { value: 'release-notes', label: 'Release notes' },
+  { value: 'beta-api', label: 'Beta API access', disabled: true },
+  { value: 'status-page', label: 'Status page' },
+];
+```
+
+```html
+<ui-combobox
+  class="w-full max-w-sm"
+  [options]="feedOptions"
+  placeholder="Choose a feed"
+  searchPlaceholder="Search feeds..."
+  emptyText="No feeds matched your query." />
+```
+
+### Reactive forms
+
+The component implements `ControlValueAccessor`, so it also works with Angular
+reactive forms.
+
+```ts
+readonly form = new FormGroup({
+  framework: new FormControl<string | null>(null),
+});
+```
+
+```html
+<form [formGroup]="form">
+  <ui-combobox
+    class="w-80"
+    formControlName="framework"
+    [options]="frameworkOptions"
+    placeholder="Select framework"
+    searchPlaceholder="Search frameworks..." />
+</form>
+```
+
+## API reference
+
+| Input or model      | Type                               | Default               |
+| ------------------- | ---------------------------------- | --------------------- |
+| `options`           | `ReadonlyArray<ComboboxOption<T>>` | `[]`                  |
+| `value`             | `T \| null`                        | `null`                |
+| `placeholder`       | `string`                           | `'Select…'`           |
+| `searchPlaceholder` | `string`                           | `'Search…'`           |
+| `emptyText`         | `string`                           | `'No results found.'` |
+| `disabled`          | `boolean`                          | `false`               |
+| `class`             | `string`                           | `''`                  |
+
+Output: `valueChange: T | null`.
+
+### `ComboboxOption<T>`
+
+```ts
+interface ComboboxOption<T = unknown> {
+  value: T;
+  label: string;
+  disabled?: boolean;
+}
+```
+
+## Styling and theming
+
+- Pass `class` to the host element for width and layout. The trigger fills the host width.
+- Trigger uses the shared `outline` button variant.
+- Overlay panel class is `ui-combobox-panel`.
+- Overlay width tracks the trigger with `--ui-combobox-trigger-width`.
+
+## Accessibility
+
+- Trigger exposes `role="combobox"`, `aria-expanded`, `aria-controls`, and `aria-haspopup="listbox"`.
+- Panel content is powered by `ui-command`, which provides the filter input and listbox roles.
+- Escape and outside click close the panel; focus returns to the trigger.
+- Keep a visible label or surrounding explanatory copy when placeholder text alone is not enough context.
+
+## Keyboard interactions
+
+- Enter or Space opens the trigger because it is a native button.
+- Arrow keys move between filtered command items once the search input is focused.
+- Enter selects the active option, and Escape closes the surface.
+- Tab leaves the combobox in normal DOM order.
+
+## Angular notes
+
+- `[(value)]` is the simplest signal-friendly binding for standalone components.
+- Because the component implements `ControlValueAccessor`, it also works with reactive forms.
+- Object-backed selections rely on strict equality. Reuse the same object instances from the bound `options` array.
+
+## Source parity
+
+The current shadcn combobox docs also cover grouped collections, popup triggers,
+clear buttons, invalid styling, input add-ons, and multi-select chips. Those
+variants are not exposed by `ui-combobox` yet.
+
+This README documents the supported Angular surface today and calls out the
+upstream shadcn page as a reference for future expansion, not as a promise that
+every upstream example already exists in this package.

package/command/README.md

@@ -0,0 +1,275 @@
+# Command
+
+Searchable command palette primitive for quick actions, navigation, and settings.
+
+Use Command inline for filterable action lists, or compose it with Dialog to recreate shadcn's `CommandDialog` pattern. The same primitive also powers [Combobox](../combobox/README.md).
+
+## Import
+
+Import the command parts directly from the component package.
+
+```ts
+import {
+  CommandComponent,
+  CommandEmptyComponent,
+  CommandGroupComponent,
+  CommandInputComponent,
+  CommandItemComponent,
+  CommandListComponent,
+  CommandSeparatorComponent,
+  CommandShortcutComponent,
+} from '@edsis/ui/command';
+```
+
+When you want a palette launcher like shadcn's `CommandDialog`, add Button and Dialog primitives as well.
+
+```ts
+import { ButtonComponent } from '@edsis/ui/button';
+import {
+  DialogComponent,
+  DialogDescriptionComponent,
+  DialogHeaderComponent,
+  DialogTitleComponent,
+} from '@edsis/ui/dialog';
+```
+
+## Composition
+
+The Angular composition mirrors shadcn's structure while keeping overlay behavior separate.
+
+```text
+ui-command
+├── input[ui-command-input]
+└── ui-command-list
+    ├── ui-command-empty
+    ├── ui-command-group
+    │   ├── button[ui-command-item]
+    │   └── button[ui-command-item]
+    ├── ui-command-separator
+    └── ui-command-group
+        ├── button[ui-command-item]
+        └── button[ui-command-item]
+```
+
+## Basic usage
+
+Build the searchable surface from the root, input, list, and grouped items. Add `span[ui-command-shortcut]` when an item should expose a trailing keyboard hint.
+
+```html
+<ui-command class="max-w-md rounded-lg border border-border">
+  <input ui-command-input placeholder="Type a command or search..." />
+  <ui-command-list>
+    <ui-command-empty>No results found.</ui-command-empty>
+
+    <ui-command-group heading="Suggestions">
+      <button type="button" ui-command-item value="Calendar" (selected)="open('calendar')">Calendar</button>
+      <button type="button" ui-command-item value="Search Emoji" (selected)="open('emoji')">Search Emoji</button>
+    </ui-command-group>
+
+    <ui-command-separator />
+
+    <ui-command-group heading="Settings">
+      <button type="button" ui-command-item value="Profile" (selected)="open('profile')">
+        Profile
+        <span ui-command-shortcut>⌘P</span>
+      </button>
+    </ui-command-group>
+  </ui-command-list>
+</ui-command>
+```
+
+## Common patterns
+
+### Command palette dialog
+
+shadcn ships a dedicated `CommandDialog` helper. In this Angular library, compose `ui-dialog` with `ui-command` instead.
+
+```ts
+const commandOpen = signal(false);
+```
+
+```html
+<button type="button" ui-button variant="outline" (click)="commandOpen.set(true)">Open menu</button>
+
+<ui-dialog [(open)]="commandOpen">
+  <ui-dialog-header>
+    <ui-dialog-title>Command palette</ui-dialog-title>
+    <ui-dialog-description> Search for navigation, billing, or settings actions. </ui-dialog-description>
+  </ui-dialog-header>
+
+  <ui-command class="mt-4 rounded-lg border border-border">
+    <input ui-command-input placeholder="Type a command or search..." />
+    <ui-command-list>
+      <ui-command-empty>No results found.</ui-command-empty>
+      <ui-command-group heading="Suggestions">
+        <button type="button" ui-command-item value="Calendar" (selected)="commandOpen.set(false)">Calendar</button>
+      </ui-command-group>
+    </ui-command-list>
+  </ui-command>
+</ui-dialog>
+```
+
+### Shortcuts
+
+Use `span[ui-command-shortcut]` for keyboard hints aligned to the trailing edge of each row.
+
+```html
+<ui-command class="max-w-md rounded-lg border border-border">
+  <input ui-command-input placeholder="Search shortcuts..." />
+  <ui-command-list>
+    <ui-command-group heading="Quick actions">
+      <button type="button" ui-command-item value="Profile">
+        Profile
+        <span ui-command-shortcut>⌘P</span>
+      </button>
+      <button type="button" ui-command-item value="Billing">
+        Billing
+        <span ui-command-shortcut>⌘B</span>
+      </button>
+    </ui-command-group>
+  </ui-command-list>
+</ui-command>
+```
+
+### Scrollable command lists
+
+The list container defaults to a scrollable max height. Override it with `class` when the palette needs to expose many groups.
+
+```html
+<ui-command class="max-w-xl rounded-lg border border-border">
+  <input ui-command-input placeholder="Jump to a tool or action..." />
+  <ui-command-list class="max-h-56">
+    <ui-command-empty>No results found.</ui-command-empty>
+    <ui-command-group heading="Navigation">...</ui-command-group>
+    <ui-command-separator />
+    <ui-command-group heading="Actions">...</ui-command-group>
+    <ui-command-separator />
+    <ui-command-group heading="Tools">...</ui-command-group>
+  </ui-command-list>
+</ui-command>
+```
+
+### Controlled query
+
+Two-way bind the query when the parent needs to inspect, reset, or prefill the current search string.
+
+```ts
+const query = signal('');
+```
+
+```html
+<ui-command [(query)]="query" class="max-w-md rounded-lg border border-border">
+  <input ui-command-input placeholder="Filter actions..." />
+  <ui-command-list>...</ui-command-list>
+</ui-command>
+```
+
+### RTL
+
+For right-to-left interfaces, apply `dir="rtl"` to the wrapper and input.
+
+```html
+<section dir="rtl" lang="ar" class="max-w-md text-right">
+  <ui-command class="rounded-lg border border-border">
+    <input ui-command-input placeholder="اكتب أمرًا أو ابحث..." dir="rtl" />
+    <ui-command-list>
+      <ui-command-empty>لم يتم العثور على نتائج.</ui-command-empty>
+      <ui-command-group heading="اقتراحات">...</ui-command-group>
+      <ui-command-separator />
+      <ui-command-group heading="الإعدادات">...</ui-command-group>
+    </ui-command-list>
+  </ui-command>
+</section>
+```
+
+## API reference
+
+### `CommandComponent`
+
+| Input / Model | Type     | Default |
+| ------------- | -------- | ------- |
+| `query`       | `string` | `''`    |
+| `class`       | `string` | `''`    |
+
+### `CommandInputComponent`
+
+| Input         | Type     | Default                       |
+| ------------- | -------- | ----------------------------- |
+| `placeholder` | `string` | `Type a command or search...` |
+| `class`       | `string` | `''`                          |
+
+Behavior:
+
+- Uses `role="combobox"` and `aria-autocomplete="list"`.
+- Arrow Down and Arrow Up move the active item.
+- Enter selects the active visible item.
+
+### `CommandListComponent`
+
+| Input   | Type     | Default |
+| ------- | -------- | ------- |
+| `class` | `string` | `''`    |
+
+Behavior: renders the listbox region and scroll container.
+
+### `CommandGroupComponent`
+
+| Input     | Type             | Default |
+| --------- | ---------------- | ------- |
+| `heading` | `string \| null` | `null`  |
+| `class`   | `string`         | `''`    |
+
+### `CommandItemComponent`
+
+| Input / Output | Type                          | Default              |
+| -------------- | ----------------------------- | -------------------- |
+| `value`        | `string`                      | `''`                 |
+| `disabled`     | `boolean`                     | `false`              |
+| `class`        | `string`                      | `''`                 |
+| `selected`     | `MouseEvent \| KeyboardEvent` | emitted on selection |
+
+Behavior:
+
+- Uses `role="option"`.
+- Hides automatically when the current query does not match its `value` or text content.
+- Skips selection when `disabled` is `true`.
+
+### Auxiliary parts
+
+- `ui-command-empty` appears only when no visible items match the query.
+- `ui-command-separator` renders a divider between groups.
+- `span[ui-command-shortcut]` aligns trailing shortcut text with `ml-auto` styling.
+
+## Styling and theming
+
+Pass `class` to the root and parts to tune borders, width, list height, and embedded dialog layouts.
+
+The primitive already applies shared theme tokens such as `bg-popover`, `text-popover-foreground`, `border-border`, and active-row accent styles. Typical overrides include:
+
+- `rounded-lg border border-border` on the root for shadcn-like cards.
+- `max-h-*` on `ui-command-list` for taller or shorter scroll regions.
+- Additional spacing or layout classes on items when an app supplies inline badges or icons.
+
+## Accessibility
+
+- The input uses combobox semantics while the list exposes listbox-style options.
+- Items expose `aria-selected`, `data-active`, and disabled state markers.
+- Disabled items remain visible for discoverability but are skipped by keyboard selection.
+- Keep item labels descriptive and avoid deeply nested interactive content inside a command item.
+
+## Keyboard interactions
+
+- Arrow Down and Arrow Up move the active option through visible items.
+- Enter selects the active item.
+- Typing filters items by the configured `value` or fallback text content.
+
+## Angular notes
+
+- The root exposes a signal-backed `query` model, so `[(query)]` works naturally in standalone components.
+- `button[ui-command-item]` is the most practical item host because it preserves native semantics for click and keyboard handlers.
+- `ComboboxComponent` already builds on this primitive, so keep command examples action-oriented instead of mixing them with form-specific behavior.
+- This primitive intentionally stays presentational. Compose it with higher-level surfaces such as Dialog rather than coupling it to overlay infrastructure.
+
+## Source parity
+
+This Angular implementation follows shadcn's Command information architecture and `cmdk` mental model while translating the dialog helper into existing `ui-dialog` primitives and Angular selectors.