@ojiepermana/angular 21.3.4 → 22.0.1

package/component/collapsible/README.md

@@ -0,0 +1,195 @@
+# Collapsible
+
+Displays an interactive disclosure region that expands and collapses inline content.
+
+Use Collapsible for settings drawers, detail rows, compact status cards, and nested explorers where content should stay in the same document flow.
+
+## Import
+
+```ts
+import {
+  CollapsibleComponent,
+  CollapsibleContentComponent,
+  CollapsibleTriggerDirective,
+} from '@ojiepermana/angular/component/collapsible';
+```
+
+## Composition
+
+The Angular composition follows the shadcn and Radix structure while using a root component, a trigger directive on a native button, and a content component.
+
+```text
+ui-collapsible
+├── button[ui-collapsible-trigger]
+└── ui-collapsible-content
+```
+
+## Basic usage
+
+Bind `[(open)]` when the parent should control the disclosure state or seed a default open panel.
+
+```ts
+readonly detailsOpen = signal(false);
+```
+
+```html
+<ui-collapsible [(open)]="detailsOpen" class="w-full max-w-md rounded-lg border border-border p-3">
+  <button
+    ui-collapsible-trigger
+    class="inline-flex w-full items-center justify-between gap-2 text-left text-sm font-medium">
+    Can I use this in my project?
+    <span aria-hidden="true">+</span>
+  </button>
+
+  <ui-collapsible-content class="pt-3 text-sm text-muted-foreground">
+    Yes. The trigger and content follow the disclosure ARIA pattern and stay in normal layout flow.
+  </ui-collapsible-content>
+</ui-collapsible>
+```
+
+## Common patterns
+
+### Controlled state
+
+Use a signal boolean with `[(open)]` when another control needs to observe or update the open state.
+
+```ts
+readonly isOpen = signal(false);
+
+toggleFromElsewhere(): void {
+  this.isOpen.update((value) => !value);
+}
+```
+
+### Button composition
+
+`button[ui-collapsible-trigger]` is a directive, so it can compose with the local button primitive on the same element.
+
+```html
+<ui-collapsible [(open)]="basicOpen" class="rounded-md border border-border p-2">
+  <button ui-button ui-collapsible-trigger variant="ghost" class="w-full justify-between px-2">
+    Product details
+    <svg aria-hidden="true" class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+      <polyline points="6 9 12 15 18 9" />
+    </svg>
+  </button>
+
+  <ui-collapsible-content class="px-2 pb-2 pt-1 text-sm text-muted-foreground">
+    This panel can reveal additional details without leaving the page.
+  </ui-collapsible-content>
+</ui-collapsible>
+```
+
+### Settings drawer
+
+Wrap the trigger and content inside a card-like surface when the disclosure belongs to a small settings editor.
+
+```html
+<ui-collapsible [(open)]="settingsOpen" class="rounded-lg border border-border p-4">
+  <div class="flex items-start gap-3">
+    <div class="grid flex-1 grid-cols-2 gap-2">
+      <input ui-input placeholder="Radius X" />
+      <input ui-input placeholder="Radius Y" />
+      <ui-collapsible-content class="col-span-full grid grid-cols-2 gap-2 pt-0">
+        <input ui-input placeholder="Blur" />
+        <input ui-input placeholder="Spread" />
+      </ui-collapsible-content>
+    </div>
+
+    <button ui-button ui-collapsible-trigger variant="outline" size="icon" aria-label="Toggle advanced fields">
+      <span aria-hidden="true">...</span>
+    </button>
+  </div>
+</ui-collapsible>
+```
+
+### Nested file tree
+
+Nested `ui-collapsible` roots work well for compact explorers and outline views.
+
+```html
+<ui-collapsible [(open)]="componentsOpen">
+  <button ui-collapsible-trigger class="inline-flex items-center gap-2 text-sm font-medium">components</button>
+
+  <ui-collapsible-content class="ml-5 mt-2 flex flex-col gap-1">
+    <ui-collapsible [(open)]="uiOpen">
+      <button ui-collapsible-trigger class="inline-flex items-center gap-2 text-sm font-medium">ui</button>
+      <ui-collapsible-content class="ml-5 mt-2 flex flex-col gap-1 text-sm text-muted-foreground">
+        <span>button.ts</span>
+        <span>collapsible.ts</span>
+      </ui-collapsible-content>
+    </ui-collapsible>
+  </ui-collapsible-content>
+</ui-collapsible>
+```
+
+### RTL
+
+For right-to-left interfaces, set `dir="rtl"` on a wrapping container or the collapsible root.
+
+```html
+<section dir="rtl" lang="ar" class="max-w-md text-right">
+  <ui-collapsible [(open)]="rtlOpen" class="flex flex-col gap-2">
+    <button ui-collapsible-trigger class="inline-flex items-center justify-between gap-2 text-sm font-medium">
+      تبديل التفاصيل
+    </button>
+    <ui-collapsible-content class="flex flex-col gap-2 text-sm">
+      <div class="rounded-md border border-border px-4 py-2">عنوان الشحن</div>
+      <div class="rounded-md border border-border px-4 py-2">2x سماعات الاستوديو</div>
+    </ui-collapsible-content>
+  </ui-collapsible>
+</section>
+```
+
+## API reference
+
+### `CollapsibleComponent`
+
+| Input          | Type      | Default |
+| -------------- | --------- | ------- |
+| `open` (model) | `boolean` | `false` |
+| `disabled`     | `boolean` | `false` |
+| `class`        | `string`  | `''`    |
+
+### `CollapsibleContentComponent`
+
+| Input        | Type      | Default |
+| ------------ | --------- | ------- |
+| `forceMount` | `boolean` | `false` |
+| `class`      | `string`  | `''`    |
+
+### Parts
+
+- `button[ui-collapsible-trigger]` is the interactive control. It manages `aria-expanded`, `aria-controls`, `data-state`, and root toggling.
+- `ui-collapsible-content` is the panel region. It applies `role="region"`, `aria-labelledby`, `data-state`, and optional persistent projection via `forceMount`.
+- Lower-level behavior follows the Radix Collapsible model: <https://www.radix-ui.com/primitives/docs/components/collapsible#api-reference>.
+
+## Styling and theming
+
+Pass `class` to the root or content, and use the native `class` attribute on the trigger button. The root and content expose `data-state="open" | "closed"` so surrounding styles or transitions can react to the current disclosure state.
+
+Use theme tokens such as `border-border`, `bg-card`, `text-muted-foreground`, and spacing utilities to match the rest of the library.
+
+## Accessibility
+
+- The primitive follows the disclosure WAI-ARIA pattern.
+- Trigger is a native button, so Enter and Space work without extra key handling.
+- Trigger receives `aria-controls` and `aria-expanded`; content receives `role="region"` and `aria-labelledby`.
+- `disabled` keeps the control visible while preventing interaction.
+
+## Keyboard interactions
+
+- `Enter` toggles the collapsible.
+- `Space` toggles the collapsible.
+- Tab order follows the DOM order of the trigger and any focusable controls inside the content.
+
+## Angular notes
+
+- `[(open)]` is the Angular equivalent of shadcn's `open` and `onOpenChange` props.
+- `button[ui-collapsible-trigger]` is a directive, not a component, so it can compose with `button[ui-button]` on the same element.
+- `forceMount` keeps projected content rendered even when the panel is closed, which is useful for measuring or animating content without re-creating it.
+- The local API intentionally does not add an `asChild` prop; Angular composition is handled through selectors and host directives instead.
+
+## Source parity
+
+This Angular implementation follows the shadcn Collapsible structure and examples while translating the API to standalone Angular imports, signal-backed state, button-directive composition, and Angular-friendly RTL guidance.

package/component/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 '@ojiepermana/angular/component/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/component/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 '@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
+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.