@ojiepermana/angular 22.1.11 → 22.1.12

package/component/combobox/README.md

@@ -0,0 +1,202 @@
+# 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 '@ojiepermana/angular/component/combobox';
+```
+
+## Composition
+
+The Angular structure maps the combobox idea onto the existing library stack:
+
+```text
+Combobox
+├── button[role="combobox"]
+└── CDK overlay
+    └── Command
+        ├── input[CommandInput]
+        └── CommandList
+            └── button[CommandItem]
+```
+
+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
+<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
+<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
+<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">
+  <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 `combobox-panel`.
+- Overlay width tracks the trigger with `--combobox-trigger-width`.
+
+## Accessibility
+
+- Trigger exposes `role="combobox"`, `aria-expanded`, `aria-controls`, and `aria-haspopup="listbox"`.
+- Panel content is powered by `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 closes the listbox, returns focus to the trigger, and lets the browser continue the tab sequence from there.
+
+## 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 `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/component/command/README.md

@@ -0,0 +1,287 @@
+# 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 '@ojiepermana/angular/component/command';
+```
+
+When you want a palette launcher like shadcn's `CommandDialog`, add Button and Dialog primitives as well.
+
+```ts
+import { ButtonComponent } from '@ojiepermana/angular/component/button';
+import {
+  DialogComponent,
+  DialogDescriptionComponent,
+  DialogHeaderComponent,
+  DialogTitleComponent,
+} from '@ojiepermana/angular/component/dialog';
+```
+
+## Composition
+
+The Angular composition mirrors shadcn's structure while keeping overlay behavior separate.
+
+```text
+Command
+├── input[CommandInput]
+└── CommandList
+    ├── CommandEmpty
+    ├── CommandGroup
+    │   ├── button[CommandItem]
+    │   └── button[CommandItem]
+    ├── CommandSeparator
+    └── CommandGroup
+        ├── button[CommandItem]
+        └── button[CommandItem]
+```
+
+## Basic usage
+
+Build the searchable surface from the root, input, list, and grouped items. Add `span[CommandShortcut]` when an item should expose a trailing keyboard hint.
+
+```html
+<command class="max-w-md rounded-lg border border-border">
+  <input CommandInput placeholder="Type a command or search..." />
+  <CommandList>
+    <CommandEmpty>No results found.</CommandEmpty>
+
+    <CommandGroup heading="Suggestions">
+      <button type="button" CommandItem value="Calendar" (selected)="open('calendar')">
+        Calendar
+      </button>
+      <button type="button" CommandItem value="Search Emoji" (selected)="open('emoji')">
+        Search Emoji
+      </button>
+    </CommandGroup>
+
+    <CommandSeparator />
+
+    <CommandGroup heading="Settings">
+      <button type="button" CommandItem value="Profile" (selected)="open('profile')">
+        Profile
+        <span CommandShortcut>⌘P</span>
+      </button>
+    </CommandGroup>
+  </CommandList>
+</command>
+```
+
+## Common patterns
+
+### Command palette dialog
+
+shadcn ships a dedicated `CommandDialog` helper. In this Angular library, compose `Dialog` with `Command` instead.
+
+```ts
+const commandOpen = signal(false);
+```
+
+```html
+<button type="button" Button variant="outline" (click)="commandOpen.set(true)">Open menu</button>
+
+<dialog [(open)]="commandOpen">
+  <DialogHeader>
+    <DialogTitle>Command palette</DialogTitle>
+    <DialogDescription> Search for navigation, billing, or settings actions. </DialogDescription>
+  </DialogHeader>
+
+  <command class="mt-4 rounded-lg border border-border">
+    <input CommandInput placeholder="Type a command or search..." />
+    <CommandList>
+      <CommandEmpty>No results found.</CommandEmpty>
+      <CommandGroup heading="Suggestions">
+        <button type="button" CommandItem value="Calendar" (selected)="commandOpen.set(false)">
+          Calendar
+        </button>
+      </CommandGroup>
+    </CommandList>
+  </command>
+</dialog>
+```
+
+### Shortcuts
+
+Use `span[CommandShortcut]` for keyboard hints aligned to the trailing edge of each row.
+
+```html
+<command class="max-w-md rounded-lg border border-border">
+  <input CommandInput placeholder="Search shortcuts..." />
+  <CommandList>
+    <CommandGroup heading="Quick actions">
+      <button type="button" CommandItem value="Profile">
+        Profile
+        <span CommandShortcut>⌘P</span>
+      </button>
+      <button type="button" CommandItem value="Billing">
+        Billing
+        <span CommandShortcut>⌘B</span>
+      </button>
+    </CommandGroup>
+  </CommandList>
+</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
+<command class="max-w-xl rounded-lg border border-border">
+  <input CommandInput placeholder="Jump to a tool or action..." />
+  <CommandList class="max-h-56">
+    <CommandEmpty>No results found.</CommandEmpty>
+    <CommandGroup heading="Navigation">...</CommandGroup>
+    <CommandSeparator />
+    <CommandGroup heading="Actions">...</CommandGroup>
+    <CommandSeparator />
+    <CommandGroup heading="Tools">...</CommandGroup>
+  </CommandList>
+</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
+<command [(query)]="query" class="max-w-md rounded-lg border border-border">
+  <input CommandInput placeholder="Filter actions..." />
+  <CommandList>...</CommandList>
+</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">
+  <command class="rounded-lg border border-border">
+    <input CommandInput placeholder="اكتب أمرًا أو ابحث..." dir="rtl" />
+    <CommandList>
+      <CommandEmpty>لم يتم العثور على نتائج.</CommandEmpty>
+      <CommandGroup heading="اقتراحات">...</CommandGroup>
+      <CommandSeparator />
+      <CommandGroup heading="الإعدادات">...</CommandGroup>
+    </CommandList>
+  </command>
+</section>
+```
+
+## API reference
+
+### `CommandComponent`
+
+| Input / Model / Output | Type     | Default                         |
+| ---------------------- | -------- | ------------------------------- |
+| `query`                | `string` | `''`                            |
+| `class`                | `string` | `''`                            |
+| `dismissed`            | `void`   | emitted on Escape with no query |
+
+`(dismissed)` fires when Escape arrives and there is nothing left to clear. A
+Command inside a dialog or popover can ignore it -- the overlay closes itself on
+Escape -- but a standalone one has no other way to be asked to close.
+
+### `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
+
+- `CommandEmpty` appears only when no visible items match the query.
+- `CommandSeparator` renders a divider between groups.
+- `span[CommandShortcut]` 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 `CommandList` 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, enabled items; disabled rows are never announced as the active descendant.
+- Enter selects the active item.
+- Typing filters items by the configured `value` or fallback text content.
+- Escape clears the query, and asks the container to dismiss (`(dismissed)`) once the query is already empty. Both consume the key's default action; only the clearing one stops propagating, so a Command inside a dialog does not close the dialog while clearing its search, but a second Escape does close it.
+
+## Angular notes
+
+- The root exposes a signal-backed `query` model, so `[(query)]` works naturally in standalone components.
+- `button[CommandItem]` 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 `Dialog` primitives and Angular selectors.