@semantic-components/ui-lab 0.62.0 → 0.63.0

package/src/lib/components/combobox/README.md

@@ -0,0 +1,166 @@
+# Combobox
+
+Autocomplete input and command palette with a list of suggestions. Built on `@angular/aria` primitives using a composable, nested combobox pattern.
+
+## Architecture
+
+Uses a **nested combobox** pattern:
+
+1. **Outer combobox** (`ScCombobox`, readonly) — acts as trigger, opens/closes dialog
+2. **ComboboxDialog** (inside `ScComboboxPortal`) — native `<dialog>` popup
+3. **Inner combobox** (inside `ScComboboxPortal`, `filterMode="manual"`, `alwaysExpanded`) — handles search + keyboard navigation
+4. **Listbox + Option** (`ScComboboxList` + `ScComboboxItem`) — the actual options list
+
+The search input is **built into** `ScComboboxPortal`'s template (not projected). This is required because the search `ComboboxInput` must be in the inner `Combobox`'s DI context.
+
+## Components
+
+| Component                 | Selector                          | Aria Primitive                                                                   | Purpose                                 |
+| ------------------------- | --------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------- |
+| `ScCombobox`              | `div[sc-combobox]`                | `Combobox` (hostDirective, readonly)                                             | Root container                          |
+| `ScComboboxTrigger`       | `div[sc-combobox-trigger]`        | —                                                                                | Styling wrapper for trigger             |
+| `ScComboboxInput`         | `input[sc-combobox-input]`        | `ComboboxInput` (hostDirective)                                                  | Invisible input (opens dropdown)        |
+| `ScComboboxIcon`          | `svg[sc-combobox-icon]`           | —                                                                                | Chevron icon with rotation on expand    |
+| `ScComboboxPortal`        | `div[sc-combobox-portal]`         | `ComboboxPopupContainer` + `ComboboxDialog` + inner `Combobox` + `ComboboxInput` | Dialog popup with built-in search input |
+| `ScComboboxList`          | `div[sc-combobox-list]`           | `Listbox` (hostDirective)                                                        | Scrollable options list                 |
+| `ScComboboxItem`          | `div[sc-combobox-item]`           | `Option` (hostDirective)                                                         | Individual option                       |
+| `ScComboboxItemIndicator` | `svg[sc-combobox-item-indicator]` | —                                                                                | Checkmark (visible when selected)       |
+| `ScComboboxEmpty`         | `div[sc-combobox-empty]`          | —                                                                                | Empty state message                     |
+
+### ScComboboxPortal
+
+**Inputs:**
+
+| Input               | Type     | Default       | Description              |
+| ------------------- | -------- | ------------- | ------------------------ |
+| `searchPlaceholder` | `string` | `'Search...'` | Search input placeholder |
+| `class`             | `string` | `''`          | Additional CSS classes   |
+
+**Two-way Bindings:**
+
+| Binding       | Type     | Description                |
+| ------------- | -------- | -------------------------- |
+| `searchValue` | `string` | Current search/filter text |
+
+### ScComboboxList
+
+Exposes from `Listbox` hostDirective:
+
+| Input/Output | Type       | Description               |
+| ------------ | ---------- | ------------------------- |
+| `[(values)]` | `string[]` | Selected values           |
+| `[multi]`    | `boolean`  | Enable multiple selection |
+
+### ScComboboxItem
+
+Exposes from `Option` hostDirective:
+
+| Input        | Type      | Description                |
+| ------------ | --------- | -------------------------- |
+| `[value]`    | `string`  | Option value (required)    |
+| `[label]`    | `string`  | Option label for typeahead |
+| `[disabled]` | `boolean` | Disable this option        |
+
+## Usage
+
+### Single Select
+
+```html
+<div sc-combobox class="w-[200px]">
+  <div sc-combobox-trigger>
+    <span class="pointer-events-none absolute left-3 truncate">{{ displayValue() }}</span>
+    <input sc-combobox-input />
+    <svg sc-combobox-icon xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <path d="m7 15 5 5 5-5" />
+      <path d="m7 9 5-5 5 5" />
+    </svg>
+  </div>
+  <div sc-combobox-portal searchPlaceholder="Search..." [(searchValue)]="search">
+    @if (filteredOptions().length === 0) {
+    <div sc-combobox-empty>No results found.</div>
+    }
+    <div sc-combobox-list [(values)]="selectedValues">
+      @for (option of filteredOptions(); track option.value) {
+      <div sc-combobox-item [value]="option.value" [label]="option.label">
+        <span>{{ option.label }}</span>
+        <svg sc-combobox-item-indicator xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <path d="M20 6 9 17l-5-5" />
+        </svg>
+      </div>
+      }
+    </div>
+  </div>
+</div>
+```
+
+```typescript
+readonly search = signal('');
+readonly selectedValues = signal<string[]>([]);
+
+readonly options = [
+  { value: 'next', label: 'Next.js' },
+  { value: 'angular', label: 'Angular' },
+];
+
+readonly filteredOptions = computed(() => {
+  const query = this.search().toLowerCase();
+  if (!query) return this.options;
+  return this.options.filter((o) => o.label.toLowerCase().includes(query));
+});
+
+readonly displayValue = computed(() => {
+  const vals = this.selectedValues();
+  if (vals.length === 0) return 'Select...';
+  const option = this.options.find((o) => o.value === vals[0]);
+  return option?.label ?? 'Select...';
+});
+
+constructor() {
+  // Auto-close on single select + clear search
+  afterRenderEffect(() => {
+    if (this.selectedValues().length > 0) this.search.set('');
+  });
+}
+```
+
+### Multiple Selection
+
+```html
+<div sc-combobox-list [multi]="true" [(values)]="selectedValues">
+  <!-- same item template -->
+</div>
+```
+
+### Disabled Options
+
+```html
+<div sc-combobox-item [value]="option.value" [label]="option.label" [disabled]="true">
+  <!-- content -->
+</div>
+```
+
+## Consumer Responsibilities
+
+The composable API puts the consumer in control of:
+
+- **Display text** — compute from `selectedValues()` and your options array
+- **Filtering** — filter your options array using `searchValue` model
+- **Selected values** — manage via `[(values)]` on `ScComboboxList` (always `string[]`)
+- **Auto-close** — for single-select, use `afterRenderEffect` to close after selection
+
+## Features
+
+- Search/filter with built-in search input inside the dialog
+- Single and multiple selection via Listbox `multi` input
+- Disabled options via Option `disabled` input
+- Checkmark indicator for selected options
+- Full keyboard navigation via `@angular/aria` primitives
+- Dialog positioning anchored below the trigger
+
+## Accessibility
+
+- `@angular/aria` `Combobox`, `ComboboxInput`, `ComboboxDialog`, `Listbox`, and `Option` directives handle all ARIA attributes
+- Keyboard navigation (arrow keys, enter, escape) managed by aria primitives
+- Focus management between trigger and dialog
+- `aria-selected` on options, `aria-expanded` on trigger
+- Native `<dialog>` element for proper focus trapping

package/src/lib/components/combobox/combobox-empty.ts

@@ -0,0 +1,17 @@
+import { computed, Directive, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Directive({
+  selector: 'div[sc-combobox-empty]',
+  host: {
+    'data-slot': 'combobox-empty',
+    '[class]': 'class()',
+  },
+})
+export class ScComboboxEmpty {
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn('py-6 text-center text-sm text-muted-foreground', this.classInput()),
+  );
+}

package/src/lib/components/combobox/combobox-icon.ts

@@ -0,0 +1,20 @@
+import { computed, Directive, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Directive({
+  selector: 'svg[sc-combobox-icon]',
+  host: {
+    'data-slot': 'combobox-icon',
+    '[class]': 'class()',
+  },
+})
+export class ScComboboxIcon {
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn(
+      'text-muted-foreground pointer-events-none absolute right-3 size-4 shrink-0 opacity-50 transition-transform duration-150 [[aria-expanded=true]~&]:rotate-180',
+      this.classInput(),
+    ),
+  );
+}

package/src/lib/components/combobox/combobox-input.ts

@@ -0,0 +1,32 @@
+import { ComboboxInput } from '@angular/aria/combobox';
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Component({
+  selector: 'input[sc-combobox-input]',
+  imports: [],
+  template: ``,
+  hostDirectives: [ComboboxInput],
+  host: {
+    'data-slot': 'combobox-input',
+    '[class]': 'class()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScComboboxInput {
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn(
+      'absolute inset-0 h-full w-full cursor-pointer border-none bg-transparent opacity-0 outline-none',
+      this.classInput(),
+    ),
+  );
+}

package/src/lib/components/combobox/combobox-item-indicator.ts

@@ -0,0 +1,20 @@
+import { computed, Directive, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Directive({
+  selector: 'svg[sc-combobox-item-indicator]',
+  host: {
+    'data-slot': 'combobox-item-indicator',
+    '[class]': 'class()',
+  },
+})
+export class ScComboboxItemIndicator {
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn(
+      'absolute right-2 size-4 opacity-0 [[aria-selected=true]>&]:opacity-100',
+      this.classInput(),
+    ),
+  );
+}

package/src/lib/components/combobox/combobox-item.ts

@@ -0,0 +1,49 @@
+import { Option } from '@angular/aria/listbox';
+import {
+  computed,
+  Directive,
+  effect,
+  ElementRef,
+  inject,
+  input,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Directive({
+  selector: 'div[sc-combobox-item]',
+  hostDirectives: [
+    {
+      directive: Option,
+      inputs: ['value', 'label', 'disabled'],
+    },
+  ],
+  host: {
+    'data-slot': 'combobox-item',
+    '[class]': 'class()',
+  },
+})
+export class ScComboboxItem {
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  private readonly option = inject(Option);
+  private readonly elementRef = inject<ElementRef<HTMLElement>>(ElementRef);
+
+  constructor() {
+    effect(() => {
+      if (this.option.active()) {
+        this.elementRef.nativeElement.scrollIntoView({ block: 'nearest' });
+      }
+    });
+  }
+
+  protected readonly class = computed(() =>
+    cn(
+      'relative flex min-h-9 cursor-pointer select-none items-center gap-2 rounded-sm px-2 py-1.5 pr-8 text-sm outline-none transition-colors',
+      'hover:bg-accent hover:text-accent-foreground',
+      'data-[active=true]:ring-2 data-[active=true]:ring-ring data-[active=true]:ring-offset-1',
+      'aria-selected:bg-accent/50 aria-selected:text-accent-foreground',
+      'aria-disabled:pointer-events-none aria-disabled:opacity-50',
+      this.classInput(),
+    ),
+  );
+}

package/src/lib/components/combobox/combobox-list.ts

@@ -0,0 +1,40 @@
+import { Listbox } from '@angular/aria/listbox';
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Component({
+  selector: 'div[sc-combobox-list]',
+  imports: [],
+  template: `
+    <ng-content />
+  `,
+  hostDirectives: [
+    {
+      directive: Listbox,
+      inputs: ['values', 'multi'],
+      outputs: ['valuesChange'],
+    },
+  ],
+  host: {
+    'data-slot': 'combobox-list',
+    '[class]': 'class()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScComboboxList {
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn(
+      'max-h-[300px] overflow-y-auto overflow-x-hidden p-1',
+      this.classInput(),
+    ),
+  );
+}

package/src/lib/components/combobox/combobox-portal.ts

@@ -0,0 +1,111 @@
+import {
+  Combobox,
+  ComboboxDialog,
+  ComboboxInput,
+  ComboboxPopupContainer,
+} from '@angular/aria/combobox';
+import {
+  afterRenderEffect,
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  ElementRef,
+  inject,
+  input,
+  model,
+  viewChild,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Component({
+  selector: 'div[sc-combobox-portal]',
+  imports: [ComboboxPopupContainer, ComboboxDialog, Combobox, ComboboxInput],
+  template: `
+    <ng-template ngComboboxPopupContainer>
+      <dialog #dialog ngComboboxDialog [class]="dialogClass()">
+        <div ngCombobox filterMode="manual" [alwaysExpanded]="true">
+          <div [class]="searchContainerClass()">
+            <svg
+              class="mr-2 size-4 shrink-0 opacity-50"
+              xmlns="http://www.w3.org/2000/svg"
+              width="24"
+              height="24"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="2"
+              stroke-linecap="round"
+              stroke-linejoin="round"
+              aria-hidden="true"
+            >
+              <circle cx="11" cy="11" r="8" />
+              <path d="m21 21-4.3-4.3" />
+            </svg>
+            <input
+              ngComboboxInput
+              type="text"
+              [class]="searchInputClass()"
+              [placeholder]="searchPlaceholder()"
+              [(value)]="searchValue"
+            />
+          </div>
+          <ng-template ngComboboxPopupContainer>
+            <ng-content />
+          </ng-template>
+        </div>
+      </dialog>
+    </ng-template>
+  `,
+  host: {
+    'data-slot': 'combobox-portal',
+    '[class]': 'class()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScComboboxPortal {
+  readonly classInput = input<string>('', { alias: 'class' });
+  readonly searchPlaceholder = input<string>('Search...');
+  readonly searchValue = model<string>('');
+
+  private readonly parentCombobox = inject(Combobox);
+  private readonly dialogRef =
+    viewChild<ElementRef<HTMLDialogElement>>('dialog');
+
+  protected readonly class = computed(() => cn('', this.classInput()));
+
+  protected readonly dialogClass = computed(() =>
+    cn(
+      'bg-popover text-popover-foreground m-0 w-full overflow-hidden rounded-md border p-0 shadow-md',
+    ),
+  );
+
+  protected readonly searchContainerClass = computed(() =>
+    cn('flex items-center border-b px-3'),
+  );
+
+  protected readonly searchInputClass = computed(() =>
+    cn(
+      'flex h-10 w-full rounded-md bg-transparent py-3 text-sm outline-none',
+      'placeholder:text-muted-foreground',
+      'disabled:cursor-not-allowed disabled:opacity-50',
+    ),
+  );
+
+  constructor() {
+    afterRenderEffect(() => {
+      const dialogEl = this.dialogRef()?.nativeElement;
+      if (!dialogEl) return;
+
+      const inputEl = this.parentCombobox.inputElement();
+      if (!inputEl) return;
+
+      const rect = inputEl.getBoundingClientRect();
+      dialogEl.style.position = 'fixed';
+      dialogEl.style.top = `${rect.bottom + 4}px`;
+      dialogEl.style.left = `${rect.left}px`;
+      dialogEl.style.width = `${rect.width}px`;
+    });
+  }
+}

package/src/lib/components/combobox/combobox-trigger.ts

@@ -0,0 +1,20 @@
+import { computed, Directive, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Directive({
+  selector: 'div[sc-combobox-trigger]',
+  host: {
+    'data-slot': 'combobox-trigger',
+    '[class]': 'class()',
+  },
+})
+export class ScComboboxTrigger {
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn(
+      'border-input bg-background relative flex h-9 w-full items-center rounded-md border px-3 text-sm shadow-xs transition-colors hover:bg-accent/50 focus-within:ring-2 focus-within:ring-ring focus-within:ring-offset-2 focus-within:ring-offset-background has-[[aria-disabled=true]]:cursor-not-allowed has-[[aria-disabled=true]]:opacity-50',
+      this.classInput(),
+    ),
+  );
+}

package/src/lib/components/combobox/combobox.ts

@@ -0,0 +1,42 @@
+import { Combobox } from '@angular/aria/combobox';
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  effect,
+  inject,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { SIGNAL, signalSetFn } from '@angular/core/primitives/signals';
+import { cn } from '@semantic-components/ui';
+
+@Component({
+  selector: 'div[sc-combobox]',
+  imports: [Combobox],
+  hostDirectives: [
+    {
+      directive: Combobox,
+    },
+  ],
+  template: `
+    <ng-content />
+  `,
+  host: {
+    'data-slot': 'combobox',
+    '[class]': 'class()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScCombobox {
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() => cn('relative', this.classInput()));
+
+  private readonly combobox = inject(Combobox);
+
+  constructor() {
+    effect(() => signalSetFn(this.combobox.readonly[SIGNAL], true));
+  }
+}

package/src/lib/components/combobox/index.ts

@@ -0,0 +1,9 @@
+export { ScCombobox } from './combobox';
+export { ScComboboxTrigger } from './combobox-trigger';
+export { ScComboboxInput } from './combobox-input';
+export { ScComboboxIcon } from './combobox-icon';
+export { ScComboboxPortal } from './combobox-portal';
+export { ScComboboxList } from './combobox-list';
+export { ScComboboxItem } from './combobox-item';
+export { ScComboboxItemIndicator } from './combobox-item-indicator';
+export { ScComboboxEmpty } from './combobox-empty';