@semantic-components/ui-lab 0.62.0 → 0.63.0

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

@@ -0,0 +1,205 @@
+# Drawer
+
+A mobile-friendly slide-in panel that can be opened from any edge of the screen. Ideal for navigation menus, forms, and quick actions on touch devices.
+
+## Architecture
+
+The components follow a dependency injection (DI) pattern where child components inject the parent `ScDrawerProvider` to access shared state. `ScDrawerProvider` owns all overlay lifecycle logic (CDK overlay, backdrop, focus trap). The `ScDrawerPortal` directive marks the lazy content template that gets portaled into the overlay.
+
+```
+ScDrawerProvider (root wrapper - manages open state + overlay lifecycle)
+├── ScDrawerTrigger (button that opens drawer)
+└── ng-template[scDrawerPortal] (lazy content, portaled to CDK overlay)
+    └── ScDrawer (drawer directive - slides from configured direction)
+        ├── ScDrawerHandle (optional drag indicator)
+        ├── ScDrawerHeader
+        │   ├── ScDrawerTitle
+        │   └── ScDrawerDescription
+        ├── (user content)
+        └── ScDrawerFooter
+            └── ScDrawerClose
+```
+
+## Components
+
+| Component             | Selector                      | Description                                        |
+| --------------------- | ----------------------------- | -------------------------------------------------- |
+| `ScDrawerProvider`    | `div[sc-drawer-provider]`     | Root wrapper, manages open state + overlay         |
+| `ScDrawerTrigger`     | `button[sc-drawer-trigger]`   | Button that opens the drawer                       |
+| `ScDrawerPortal`      | `ng-template[scDrawerPortal]` | Directive marking lazy content for the overlay     |
+| `ScDrawer`            | `div[sc-drawer]`              | Drawer directive with directional slide animations |
+| `ScDrawerHeader`      | `div[sc-drawer-header]`       | Header section container                           |
+| `ScDrawerTitle`       | `h2[sc-drawer-title]`         | Drawer title (aria-labelledby)                     |
+| `ScDrawerDescription` | `p[sc-drawer-description]`    | Drawer description (aria-describedby)              |
+| `ScDrawerHandle`      | `div[sc-drawer-handle]`       | Visual drag handle indicator                       |
+| `ScDrawerFooter`      | `div[sc-drawer-footer]`       | Footer section for actions                         |
+| `ScDrawerClose`       | `button[sc-drawer-close]`     | Close button (sets `type="button"` automatically)  |
+
+## Usage
+
+### Basic Drawer
+
+```html
+<div sc-drawer-provider direction="bottom" [(open)]="isOpen">
+  <button sc-drawer-trigger>Open Drawer</button>
+  <ng-template scDrawerPortal>
+    <div sc-drawer>
+      <div sc-drawer-handle></div>
+      <div sc-drawer-header>
+        <h2 sc-drawer-title>Drawer Title</h2>
+        <p sc-drawer-description>Drawer description text.</p>
+      </div>
+      <div class="p-4">
+        <!-- Main content -->
+      </div>
+      <div sc-drawer-footer>
+        <button sc-drawer-close>Cancel</button>
+        <button sc-drawer-close>Submit</button>
+      </div>
+    </div>
+  </ng-template>
+</div>
+```
+
+### Controlled Drawer
+
+You can control the drawer state programmatically using the `open` model:
+
+```typescript
+@Component({
+  template: `
+    <div sc-drawer-provider direction="bottom" [(open)]="isOpen">
+      <button sc-drawer-trigger>Open</button>
+      <ng-template scDrawerPortal>
+        <div sc-drawer>
+          <!-- content -->
+        </div>
+      </ng-template>
+    </div>
+  `,
+})
+export class MyComponent {
+  isOpen = signal(false);
+
+  openDrawer() {
+    this.isOpen.set(true);
+  }
+
+  closeDrawer() {
+    this.isOpen.set(false);
+  }
+}
+```
+
+## Direction
+
+The drawer can slide in from any edge of the screen. The `direction` input is set on the provider:
+
+```html
+<!-- Bottom (default) -->
+<div sc-drawer-provider direction="bottom">
+  <button sc-drawer-trigger>Open</button>
+  <ng-template scDrawerPortal>
+    <div sc-drawer>...</div>
+  </ng-template>
+</div>
+
+<!-- Top -->
+<div sc-drawer-provider direction="top">...</div>
+
+<!-- Left -->
+<div sc-drawer-provider direction="left">...</div>
+
+<!-- Right -->
+<div sc-drawer-provider direction="right">...</div>
+```
+
+## Keyboard Navigation
+
+| Key      | Action                 |
+| -------- | ---------------------- |
+| `Escape` | Close drawer           |
+| `Tab`    | Navigate within drawer |
+
+## How It Works
+
+### State Management
+
+`ScDrawerProvider` uses a `model` signal for the `open` state:
+
+```typescript
+readonly open = model<boolean>(false);
+```
+
+Child components inject `ScDrawerProvider` to read or modify this state:
+
+```typescript
+// ScDrawerTrigger
+openDrawer(): void {
+  this.drawerProvider.open.set(true);
+}
+
+// ScDrawerClose
+closeDrawer(): void {
+  this.drawerProvider.open.set(false);
+}
+```
+
+### Overlay Management
+
+`ScDrawerProvider` creates a CDK overlay and attaches/detaches the `scDrawerPortal` template based on state:
+
+```typescript
+effect(() => {
+  if (this.overlayOpen()) {
+    this.attachDrawer();
+  } else {
+    this.detachDrawer();
+  }
+});
+```
+
+The `scDrawerPortal` directive marks the `ng-template` whose content is lazily instantiated into the overlay only when the drawer opens.
+
+### Animations
+
+`ScDrawer` uses directional slide animations with a two-state model:
+
+| State    | Data Attribute        | Description                                   |
+| -------- | --------------------- | --------------------------------------------- |
+| `open`   | `data-state="open"`   | Entry animation (fade + slide from direction) |
+| `closed` | `data-state="closed"` | Exit animation (fade + slide to direction)    |
+
+On `animationend`, the `closed` state triggers overlay cleanup via `onDrawerAnimationComplete()`.
+
+## Accessibility
+
+- `role="dialog"` on the drawer
+- `aria-modal="true"` for modal behavior
+- `aria-labelledby` linked to `ScDrawerTitle`
+- `aria-describedby` linked to `ScDrawerDescription`
+- `aria-haspopup="dialog"` on the trigger
+- `aria-expanded` reflects open state on trigger
+- Focus trapped within the drawer
+- Escape key closes the drawer (via CDK overlay keydown events)
+- Backdrop click closes the drawer (via CDK overlay backdrop click)
+
+## Customization
+
+All components accept a `class` input for custom styling:
+
+```html
+<div sc-drawer class="max-h-[80vh]">
+  <!-- constrained height drawer -->
+</div>
+
+<div sc-drawer-footer class="flex-row-reverse">
+  <!-- reversed button order -->
+</div>
+```
+
+## Dependencies
+
+- Angular CDK Overlay (`@angular/cdk/overlay`)
+- Angular CDK Portal (`@angular/cdk/portal`)
+- Angular CDK A11y (`@angular/cdk/a11y`)

package/src/lib/components/drawer/drawer-close.ts

@@ -0,0 +1,18 @@
+import { Directive, inject } from '@angular/core';
+import { ScDrawerProvider } from './drawer-provider';
+
+@Directive({
+  selector: 'button[sc-drawer-close]',
+  host: {
+    'data-slot': 'drawer-close',
+    type: 'button',
+    '(click)': 'closeDrawer()',
+  },
+})
+export class ScDrawerClose {
+  private readonly drawer = inject(ScDrawerProvider);
+
+  protected closeDrawer(): void {
+    this.drawer.open.set(false);
+  }
+}

package/src/lib/components/drawer/drawer-description.ts

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

package/src/lib/components/drawer/drawer-footer.ts

@@ -0,0 +1,17 @@
+import { computed, Directive, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Directive({
+  selector: 'div[sc-drawer-footer]',
+  host: {
+    'data-slot': 'drawer-footer',
+    '[class]': 'class()',
+  },
+})
+export class ScDrawerFooter {
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn('mt-auto flex flex-col gap-2 p-4', this.classInput()),
+  );
+}

package/src/lib/components/drawer/drawer-handle.ts

@@ -0,0 +1,17 @@
+import { computed, Directive, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Directive({
+  selector: 'div[sc-drawer-handle]',
+  host: {
+    'data-slot': 'drawer-handle',
+    '[class]': 'class()',
+  },
+})
+export class ScDrawerHandle {
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn('mx-auto mt-4 h-2 w-[100px] rounded-full bg-muted', this.classInput()),
+  );
+}

package/src/lib/components/drawer/drawer-header.ts

@@ -0,0 +1,17 @@
+import { computed, Directive, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Directive({
+  selector: 'div[sc-drawer-header]',
+  host: {
+    'data-slot': 'drawer-header',
+    '[class]': 'class()',
+  },
+})
+export class ScDrawerHeader {
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn('grid gap-1.5 p-4 text-center sm:text-left', this.classInput()),
+  );
+}

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

@@ -0,0 +1,8 @@
+import { Directive, inject, TemplateRef } from '@angular/core';
+
+@Directive({
+  selector: 'ng-template[scDrawerPortal]',
+})
+export class ScDrawerPortal {
+  readonly templateRef = inject(TemplateRef);
+}

package/src/lib/components/drawer/drawer-provider.ts

@@ -0,0 +1,142 @@
+import { NgTemplateOutlet } from '@angular/common';
+import { CdkTrapFocus } from '@angular/cdk/a11y';
+import { Overlay, OverlayModule, OverlayRef } from '@angular/cdk/overlay';
+import { TemplatePortal } from '@angular/cdk/portal';
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  contentChild,
+  effect,
+  inject,
+  input,
+  model,
+  signal,
+  TemplateRef,
+  viewChild,
+  ViewContainerRef,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { ScBackdrop } from '../backdrop';
+import { ScDrawerPortal } from './drawer-portal';
+
+export type DrawerDirection = 'top' | 'right' | 'bottom' | 'left';
+
+@Component({
+  selector: 'div[sc-drawer-provider]',
+  imports: [OverlayModule, ScBackdrop, CdkTrapFocus, NgTemplateOutlet],
+  template: `
+    <ng-content />
+    <ng-template #overlayTemplate>
+      <div
+        sc-backdrop
+        [open]="open()"
+        (animationComplete)="onBackdropAnimationComplete()"
+      ></div>
+      <div cdkTrapFocus [cdkTrapFocusAutoCapture]="true">
+        <ng-container [ngTemplateOutlet]="drawerPortal().templateRef" />
+      </div>
+    </ng-template>
+  `,
+  host: {
+    'data-slot': 'drawer-provider',
+    '[class]': 'class()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScDrawerProvider {
+  private readonly overlay = inject(Overlay);
+  private readonly viewContainerRef = inject(ViewContainerRef);
+
+  readonly classInput = input<string>('', { alias: 'class' });
+  readonly direction = input<DrawerDirection>('bottom');
+
+  private readonly overlayTemplate =
+    viewChild.required<TemplateRef<unknown>>('overlayTemplate');
+
+  protected readonly drawerPortal = contentChild.required(ScDrawerPortal);
+
+  readonly open = model<boolean>(false);
+  readonly overlayOpen = signal<boolean>(false);
+  private readonly animationsCompleted = signal<number>(0);
+  private overlayRef: OverlayRef | null = null;
+
+  protected readonly class = computed(() => cn('contents', this.classInput()));
+
+  constructor() {
+    effect(() => {
+      if (this.open()) {
+        this.overlayOpen.set(true);
+        this.animationsCompleted.set(0);
+      }
+    });
+
+    effect(() => {
+      const completed = this.animationsCompleted();
+      if (completed === 2 && !this.open()) {
+        this.overlayOpen.set(false);
+        this.animationsCompleted.set(0);
+      }
+    });
+
+    effect(() => {
+      if (this.overlayOpen()) {
+        this.attachDrawer();
+      } else {
+        this.detachDrawer();
+      }
+    });
+  }
+
+  onDrawerAnimationComplete(): void {
+    if (!this.open()) {
+      this.animationsCompleted.update((n) => n + 1);
+    }
+  }
+
+  onBackdropAnimationComplete(): void {
+    if (!this.open()) {
+      this.animationsCompleted.update((n) => n + 1);
+    }
+  }
+
+  private getOverlayRef() {
+    if (!this.overlayRef) {
+      this.overlayRef = this.overlay.create({
+        positionStrategy: this.overlay.position().global(),
+        hasBackdrop: true,
+        backdropClass: 'cdk-overlay-transparent-backdrop',
+        scrollStrategy: this.overlay.scrollStrategies.block(),
+      });
+
+      this.overlayRef.backdropClick().subscribe(() => this.closeDrawer());
+      this.overlayRef.keydownEvents().subscribe((event) => {
+        if (event.key === 'Escape') this.closeDrawer();
+      });
+    }
+    return this.overlayRef;
+  }
+
+  private attachDrawer(): void {
+    const ref = this.getOverlayRef();
+    if (!ref.hasAttached()) {
+      const portal = new TemplatePortal(
+        this.overlayTemplate(),
+        this.viewContainerRef,
+      );
+      ref.attach(portal);
+    }
+  }
+
+  private detachDrawer(): void {
+    if (this.overlayRef?.hasAttached()) {
+      this.overlayRef.detach();
+    }
+  }
+
+  private closeDrawer(): void {
+    this.open.set(false);
+  }
+}

package/src/lib/components/drawer/drawer-title.ts

@@ -0,0 +1,17 @@
+import { computed, Directive, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Directive({
+  selector: 'h2[sc-drawer-title]',
+  host: {
+    'data-slot': 'drawer-title',
+    '[class]': 'class()',
+  },
+})
+export class ScDrawerTitle {
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn('text-lg font-semibold leading-none tracking-tight', this.classInput()),
+  );
+}

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

@@ -0,0 +1,24 @@
+import { computed, Directive, inject, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { ScDrawerProvider } from './drawer-provider';
+
+@Directive({
+  selector: 'button[sc-drawer-trigger]',
+  host: {
+    'data-slot': 'drawer-trigger',
+    type: 'button',
+    '[class]': 'class()',
+    '[attr.aria-expanded]': 'drawer.open()',
+    '(click)': 'openDrawer()',
+  },
+})
+export class ScDrawerTrigger {
+  readonly drawer = inject(ScDrawerProvider);
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() => cn('', this.classInput()));
+
+  openDrawer(): void {
+    this.drawer.open.set(true);
+  }
+}

package/src/lib/components/drawer/drawer.ts

@@ -0,0 +1,77 @@
+import {
+  computed,
+  Directive,
+  effect,
+  ElementRef,
+  inject,
+  input,
+  signal,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { DrawerDirection, ScDrawerProvider } from './drawer-provider';
+
+type ScDrawerState = 'open' | 'closed';
+
+const directionBaseClasses: Record<DrawerDirection, string> = {
+  top: 'inset-x-0 top-0 border-b rounded-b-[10px]',
+  right: 'inset-y-0 right-0 h-full w-3/4 border-l sm:max-w-sm',
+  bottom: 'inset-x-0 bottom-0 border-t rounded-t-[10px]',
+  left: 'inset-y-0 left-0 h-full w-3/4 border-r sm:max-w-sm',
+};
+
+const directionAnimationClasses: Record<DrawerDirection, string> = {
+  top: 'slide-in-from-top data-[state=closed]:slide-out-to-top',
+  right: 'slide-in-from-right data-[state=closed]:slide-out-to-right',
+  bottom: 'slide-in-from-bottom data-[state=closed]:slide-out-to-bottom',
+  left: 'slide-in-from-left data-[state=closed]:slide-out-to-left',
+};
+
+@Directive({
+  selector: 'div[sc-drawer]',
+  host: {
+    'data-slot': 'drawer',
+    role: 'dialog',
+    'aria-modal': 'true',
+    '[attr.data-state]': 'state()',
+    '[class]': 'class()',
+    '(animationend)': 'onAnimationEnd($event)',
+  },
+})
+export class ScDrawer {
+  private readonly elementRef = inject(ElementRef<HTMLElement>);
+
+  readonly drawer = inject(ScDrawerProvider);
+  readonly classInput = input<string>('', { alias: 'class' });
+  readonly state = signal<ScDrawerState>('closed');
+
+  protected readonly class = computed(() => {
+    const direction = this.drawer.direction();
+
+    return cn(
+      'fixed z-50 flex flex-col bg-background',
+      directionBaseClasses[direction],
+      'animate-in fade-in-0 duration-300',
+      directionAnimationClasses[direction],
+      'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:duration-300',
+      this.classInput(),
+    );
+  });
+
+  constructor() {
+    // Sync state with provider's open signal
+    effect(() => {
+      const isOpen = this.drawer.open();
+      this.state.set(isOpen ? 'open' : 'closed');
+    });
+  }
+
+  protected onAnimationEnd(event: AnimationEvent): void {
+    // Only trigger cleanup when close animation completes
+    if (
+      this.state() === 'closed' &&
+      event.target === this.elementRef.nativeElement
+    ) {
+      this.drawer.onDrawerAnimationComplete();
+    }
+  }
+}

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

@@ -0,0 +1,11 @@
+export { ScDrawerProvider } from './drawer-provider';
+export type { DrawerDirection } from './drawer-provider';
+export { ScDrawer } from './drawer';
+export { ScDrawerTrigger } from './drawer-trigger';
+export { ScDrawerPortal } from './drawer-portal';
+export { ScDrawerHeader } from './drawer-header';
+export { ScDrawerFooter } from './drawer-footer';
+export { ScDrawerTitle } from './drawer-title';
+export { ScDrawerDescription } from './drawer-description';
+export { ScDrawerHandle } from './drawer-handle';
+export { ScDrawerClose } from './drawer-close';