@semantic-components/ui-lab 0.62.0 → 0.63.0

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

@@ -0,0 +1,175 @@
+# Select Components
+
+A set of components for building accessible select dropdowns following the Single Responsibility Principle.
+
+## Features
+
+- Full keyboard navigation support
+- ARIA-compliant accessibility
+- Automatic scroll-to-active on keyboard navigation
+- Overlay positioning with CDK
+- Customizable styling via `class` input
+
+## Components
+
+| Component               | Selector                        | Responsibility                                                  |
+| ----------------------- | ------------------------------- | --------------------------------------------------------------- |
+| `ScSelect`              | `div[sc-select]`                | Root container, wraps `Combobox` from `@angular/aria`           |
+| `ScSelectTrigger`       | `div[sc-select-trigger]`        | Trigger button styling, exposes overlay origin                  |
+| `ScSelectInput`         | `input[sc-select-input]`        | Hidden input, wraps `ComboboxInput` from `@angular/aria`        |
+| `ScSelectValue`         | `span[sc-select-value]`         | Display selected value with styling                             |
+| `ScSelectIcon`          | `svg[sc-select-icon]`           | Chevron icon styling (use with `@semantic-icons/lucide-icons`)  |
+| `ScSelectPortal`        | `div[sc-select-portal]`         | Overlay positioning & combobox popup container (infrastructure) |
+| `ScSelectList`          | `div[sc-select-list]`           | Content container, wraps `Listbox` from `@angular/aria`         |
+| `ScSelectItem`          | `div[sc-select-item]`           | Option item styling, wraps `Option` from `@angular/aria`        |
+| `ScSelectItemIndicator` | `svg[sc-select-item-indicator]` | Checkmark icon for selected state                               |
+
+## Basic Usage
+
+### Template
+
+```html
+<div sc-select>
+  <div sc-select-trigger>
+    <span sc-select-value>{{ displayValue() }}</span>
+    <input sc-select-input aria-label="Select" placeholder="Select an option" />
+    <svg sc-select-icon si-chevron-down-icon aria-hidden="true"></svg>
+  </div>
+  <div sc-select-portal>
+    <div sc-select-list>
+      @for (option of options; track option.value) {
+      <div sc-select-item [value]="option.value" [label]="option.label">
+        {{ option.label }}
+        <svg sc-select-item-indicator si-check-icon aria-hidden="true"></svg>
+      </div>
+      }
+    </div>
+  </div>
+</div>
+```
+
+### Component
+
+```typescript
+import { ChangeDetectionStrategy, Component, computed, viewChild } from '@angular/core';
+import { SiCheckIcon, SiChevronDownIcon } from '@semantic-icons/lucide-icons';
+import { ScSelect, ScSelectList, ScSelectIcon, ScSelectInput, ScSelectItem, ScSelectItemIndicator, ScSelectPortal, ScSelectTrigger, ScSelectValue } from '@app/ui/select';
+
+@Component({
+  selector: 'app-example',
+  imports: [ScSelect, ScSelectList, ScSelectIcon, ScSelectInput, ScSelectItem, ScSelectItemIndicator, ScSelectPortal, ScSelectTrigger, ScSelectValue, SiCheckIcon, SiChevronDownIcon],
+  template: `
+    ...
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ExampleComponent {
+  private readonly select = viewChild.required(ScSelect);
+
+  displayValue = computed(() => {
+    const values = this.select().values();
+    return values.length ? values[0] : 'Select an option';
+  });
+
+  options = [
+    { value: 'option1', label: 'Option 1' },
+    { value: 'option2', label: 'Option 2' },
+    { value: 'option3', label: 'Option 3' },
+  ];
+}
+```
+
+## Accessing Selected Values
+
+Use `viewChild` to query `ScSelect` and access the `values()` signal:
+
+```typescript
+private readonly select = viewChild.required(ScSelect);
+
+selectedValues = computed(() => this.select().values());
+```
+
+## Keyboard Navigation
+
+The select component supports full keyboard navigation:
+
+| Key               | Action                                |
+| ----------------- | ------------------------------------- |
+| `Enter` / `Space` | Open dropdown / Select focused option |
+| `ArrowDown`       | Move focus to next option             |
+| `ArrowUp`         | Move focus to previous option         |
+| `Home`            | Move focus to first option            |
+| `End`             | Move focus to last option             |
+| `Escape`          | Close dropdown                        |
+| `Tab`             | Close dropdown and move focus         |
+
+When navigating with keyboard, the dropdown automatically scrolls to keep the active option visible.
+
+## Accessibility
+
+The select components are built with accessibility in mind:
+
+- Uses `@angular/aria/combobox` and `@angular/aria/listbox` for proper ARIA roles
+- `aria-label` on the input for screen reader support
+- `aria-hidden="true"` on decorative icons
+- Visual focus indicators for keyboard navigation
+- Selected state indicated via `aria-selected`
+
+### Required Accessibility Attributes
+
+```html
+<!-- Always provide an accessible label -->
+<input sc-select-input aria-label="Select a fruit" />
+
+<!-- Hide decorative icons from screen readers -->
+<svg sc-select-icon si-chevron-down-icon aria-hidden="true"></svg>
+<svg sc-select-item-indicator si-check-icon aria-hidden="true"></svg>
+```
+
+## API Reference
+
+### ScSelect
+
+| Property   | Type     | Description                       |
+| ---------- | -------- | --------------------------------- |
+| `class`    | `string` | Additional CSS classes            |
+| `values()` | `signal` | Signal containing selected values |
+
+### ScSelectItem
+
+| Property | Type     | Description                        |
+| -------- | -------- | ---------------------------------- |
+| `value`  | `any`    | The value of the option            |
+| `label`  | `string` | The label displayed for the option |
+| `class`  | `string` | Additional CSS classes             |
+
+### All Components
+
+All components accept a `class` input for custom styling:
+
+```html
+<div sc-select class="w-64">
+  <div sc-select-trigger class="bg-slate-100">...</div>
+</div>
+```
+
+## Architecture
+
+```
+ScSelect (root, wraps Combobox)
+├── ScSelectTrigger (trigger + overlay origin)
+│   ├── ScSelectValue (display value)
+│   ├── ScSelectInput (wraps ComboboxInput)
+│   └── ScSelectIcon (chevron icon)
+└── ScSelectPortal (overlay infrastructure)
+    └── ScSelectList (wraps Listbox)
+        └── ScSelectItem (wraps Option)
+            └── ScSelectItemIndicator (checkmark icon)
+```
+
+## Dependencies
+
+- `@angular/aria/combobox` - Combobox behavior
+- `@angular/aria/listbox` - Listbox and option behavior
+- `@angular/cdk/overlay` - Overlay positioning
+- `@semantic-icons/lucide-icons` - Icon library

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

@@ -0,0 +1,9 @@
+export { ScSelect } from './select';
+export { ScSelectTrigger } from './select-trigger';
+export { ScSelectInput } from './select-input';
+export { ScSelectValue } from './select-value';
+export { ScSelectIcon } from './select-icon';
+export { ScSelectPortal } from './select-portal';
+export { ScSelectList } from './select-list';
+export { ScSelectItem } from './select-item';
+export { ScSelectItemIndicator } from './select-item-indicator';

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

@@ -0,0 +1,20 @@
+import { computed, Directive, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Directive({
+  selector: 'svg[sc-select-icon]',
+  host: {
+    'data-slot': 'select-icon',
+    '[class]': 'class()',
+  },
+})
+export class ScSelectIcon {
+  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/select/select-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-select-input]',
+  imports: [],
+  template: ``,
+  hostDirectives: [ComboboxInput],
+  host: {
+    'data-slot': 'select-input',
+    '[class]': 'class()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScSelectInput {
+  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/select/select-item-indicator.ts

@@ -0,0 +1,20 @@
+import { computed, Directive, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Directive({
+  selector: 'svg[sc-select-item-indicator]',
+  host: {
+    'data-slot': 'select-item-indicator',
+    '[class]': 'class()',
+  },
+})
+export class ScSelectItemIndicator {
+  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/select/select-item.ts

@@ -0,0 +1,48 @@
+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-select-item]',
+  hostDirectives: [
+    {
+      directive: Option,
+      inputs: ['value', 'label'],
+    },
+  ],
+  host: {
+    'data-slot': 'select-item',
+    '[class]': 'class()',
+  },
+})
+export class ScSelectItem {
+  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',
+      this.classInput(),
+    ),
+  );
+}

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

@@ -0,0 +1,42 @@
+import { Combobox } from '@angular/aria/combobox';
+import { Listbox } from '@angular/aria/listbox';
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  inject,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Component({
+  selector: 'div[sc-select-list]',
+  imports: [],
+  template: `
+    <ng-content />
+  `,
+  hostDirectives: [Listbox],
+  host: {
+    'data-slot': 'select-list',
+    '[class]': 'class()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScSelectList {
+  readonly listbox = inject(Listbox);
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  private readonly combobox = inject(Combobox);
+
+  protected readonly class = computed(() =>
+    cn(
+      'bg-popover text-popover-foreground z-50 mt-1 flex w-full max-h-44 min-w-[8rem] flex-col gap-0.5 overflow-auto rounded-md border p-1 shadow-md',
+      this.combobox.expanded()
+        ? 'opacity-100 visible transition-[max-height,opacity,visibility] duration-150 ease-out'
+        : 'max-h-0 opacity-0 invisible transition-[max-height,opacity,visibility] duration-150 ease-in [transition-delay:0s,0s,150ms]',
+      this.classInput(),
+    ),
+  );
+}

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

@@ -0,0 +1,48 @@
+import { ComboboxPopupContainer } from '@angular/aria/combobox';
+import { OverlayModule } from '@angular/cdk/overlay';
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  inject,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { ScSelect } from './select';
+import { cn } from '@semantic-components/ui';
+
+@Component({
+  selector: 'div[sc-select-portal]',
+  imports: [ComboboxPopupContainer, OverlayModule],
+  template: `
+    <ng-template ngComboboxPopupContainer>
+      @if (origin(); as origin) {
+        <ng-template
+          [cdkConnectedOverlay]="{
+            origin,
+            usePopover: 'inline',
+            matchWidth: true,
+          }"
+          [cdkConnectedOverlayOpen]="true"
+        >
+          <ng-content />
+        </ng-template>
+      }
+    </ng-template>
+  `,
+  host: {
+    'data-slot': 'select-portal',
+    '[class]': 'class()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScSelectPortal {
+  private readonly select = inject(ScSelect);
+
+  protected readonly origin = computed(() => this.select.origin());
+
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() => cn('', this.classInput()));
+}

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

@@ -0,0 +1,36 @@
+import { CdkOverlayOrigin } from '@angular/cdk/overlay';
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  inject,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Component({
+  selector: 'div[sc-select-trigger]',
+  imports: [],
+  template: `
+    <ng-content />
+  `,
+  hostDirectives: [CdkOverlayOrigin],
+  host: {
+    'data-slot': 'select-trigger',
+    '[class]': 'class()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScSelectTrigger {
+  readonly overlayOrigin = inject(CdkOverlayOrigin);
+  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/select/select-value.ts

@@ -0,0 +1,32 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Component({
+  selector: 'span[sc-select-value]',
+  imports: [],
+  template: `
+    <ng-content />
+  `,
+  host: {
+    'data-slot': 'select-value',
+    '[class]': 'class()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScSelectValue {
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn(
+      'pointer-events-none absolute left-3 flex items-center gap-2 truncate',
+      this.classInput(),
+    ),
+  );
+}

package/src/lib/components/select/select.ts

@@ -0,0 +1,57 @@
+import { Combobox } from '@angular/aria/combobox';
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  contentChild,
+  effect,
+  inject,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { SIGNAL, signalSetFn } from '@angular/core/primitives/signals';
+import { cn } from '@semantic-components/ui';
+import { ScSelectList } from './select-list';
+import { ScSelectTrigger } from './select-trigger';
+
+@Component({
+  selector: 'div[sc-select]',
+  imports: [Combobox],
+  hostDirectives: [
+    {
+      directive: Combobox,
+    },
+  ],
+  template: `
+    <ng-content />
+  `,
+  host: {
+    'data-slot': 'select',
+    '[class]': 'class()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScSelect {
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  private readonly trigger = contentChild(ScSelectTrigger);
+  private readonly content = contentChild(ScSelectList, {
+    descendants: true,
+  });
+
+  readonly origin = computed(() => this.trigger()?.overlayOrigin);
+  readonly values = computed(() => this.content()?.listbox.values() ?? []);
+  readonly displayValue = computed(() => {
+    const vals = this.values();
+    return vals.length > 0 ? String(vals[0]) : '';
+  });
+
+  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/separator/README.md

@@ -0,0 +1,59 @@
+# Separator
+
+Visually or semantically separates content.
+
+## Components
+
+- `ScSeparator` - A visual divider with horizontal or vertical orientation
+
+## Usage
+
+### Horizontal Separator (default)
+
+```html
+<div sc-separator></div>
+```
+
+### Vertical Separator
+
+```html
+<div class="flex h-5 items-center space-x-4">
+  <div>Item 1</div>
+  <div sc-separator orientation="vertical"></div>
+  <div>Item 2</div>
+  <div sc-separator orientation="vertical"></div>
+  <div>Item 3</div>
+</div>
+```
+
+## Inputs
+
+| Input         | Type                         | Default        | Description            |
+| ------------- | ---------------------------- | -------------- | ---------------------- |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Separator orientation  |
+| `decorative`  | `boolean`                    | `false`        | If true, purely visual |
+| `class`       | `string`                     | `''`           | Additional CSS classes |
+
+## Styling
+
+The separator uses the `bg-border` color by default. Override with custom classes:
+
+```html
+<div sc-separator class="bg-red-500"></div>
+```
+
+Custom thickness:
+
+```html
+<!-- Thicker horizontal separator -->
+<div sc-separator class="h-0.5"></div>
+
+<!-- Thicker vertical separator -->
+<div sc-separator orientation="vertical" class="w-0.5"></div>
+```
+
+## Accessibility
+
+- Uses `role="separator"` for semantic meaning
+- `aria-orientation` attribute indicates the orientation
+- Set `decorative` to `true` if the separator is purely visual

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

@@ -0,0 +1 @@
+export * from './separator';

package/src/lib/components/separator/separator.ts

@@ -0,0 +1,29 @@
+import { computed, Directive, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+export type SeparatorOrientation = 'horizontal' | 'vertical';
+
+@Directive({
+  selector: 'div[sc-separator]',
+  host: {
+    'data-slot': 'separator',
+    role: 'separator',
+    '[attr.aria-orientation]': 'orientation()',
+    '[attr.data-orientation]': 'orientation()',
+    '[class]': 'class()',
+  },
+})
+export class ScSeparator {
+  readonly classInput = input<string>('', { alias: 'class' });
+  readonly orientation = input<SeparatorOrientation>('horizontal');
+  readonly decorative = input<boolean>(false);
+
+  protected readonly class = computed(() => {
+    const isHorizontal = this.orientation() === 'horizontal';
+    return cn(
+      'shrink-0 bg-border',
+      isHorizontal ? 'h-px w-full' : 'h-full w-px',
+      this.classInput(),
+    );
+  });
+}