@semantic-components/ui-lab 0.62.0 → 0.63.0

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

@@ -0,0 +1,248 @@
+# ScSheet Components
+
+A set of Angular components for creating accessible side panels (drawers) with shadcn/ui styling.
+
+## Architecture
+
+The components follow a dependency injection (DI) pattern where child components inject the parent `ScSheetProvider` to access shared state. `ScSheetProvider` owns all overlay lifecycle logic (CDK overlay, backdrop, focus trap). The `ScSheetPortal` directive marks the lazy content template that gets portaled into the overlay.
+
+```
+ScSheetProvider (root wrapper - manages open state, side + overlay lifecycle)
+├── ScSheetTrigger (button that opens sheet)
+└── ng-template[scSheetPortal] (lazy content, portaled to CDK overlay)
+    └── ScSheet (dialog panel with slide animations)
+        ├── ScSheetClose (close button)
+        ├── ScSheetHeader
+        │   ├── ScSheetTitle
+        │   └── ScSheetDescription
+        ├── (user content)
+        └── ScSheetFooter
+```
+
+## Components
+
+| Component            | Selector                     | Description                                    |
+| -------------------- | ---------------------------- | ---------------------------------------------- |
+| `ScSheetProvider`    | `div[sc-sheet-provider]`     | Root wrapper, manages open state + overlay     |
+| `ScSheetTrigger`     | `button[sc-sheet-trigger]`   | Button that opens the sheet                    |
+| `ScSheetPortal`      | `ng-template[scSheetPortal]` | Directive marking lazy content for the overlay |
+| `ScSheet`            | `div[sc-sheet]`              | Dialog panel with slide animations             |
+| `ScSheetHeader`      | `div[sc-sheet-header]`       | Header section container                       |
+| `ScSheetTitle`       | `h2[sc-sheet-title]`         | Sheet title (aria-labelledby)                  |
+| `ScSheetDescription` | `p[sc-sheet-description]`    | Sheet description (aria-describedby)           |
+| `ScSheetFooter`      | `div[sc-sheet-footer]`       | Footer section for actions                     |
+| `ScSheetClose`       | `button[sc-sheet-close]`     | Button that closes the sheet                   |
+
+## Usage
+
+### Basic Sheet (Right Side)
+
+```html
+<div sc-sheet-provider>
+  <button sc-sheet-trigger>Open Sheet</button>
+  <ng-template scSheetPortal>
+    <div sc-sheet>
+      <button sc-sheet-close>
+        <svg><!-- X icon --></svg>
+        <span class="sr-only">Close</span>
+      </button>
+      <div sc-sheet-header>
+        <h2 sc-sheet-title>Sheet Title</h2>
+        <p sc-sheet-description>Sheet description goes here.</p>
+      </div>
+      <!-- Your content -->
+      <div sc-sheet-footer>
+        <button>Cancel</button>
+        <button>Save</button>
+      </div>
+    </div>
+  </ng-template>
+</div>
+```
+
+### Different Sides
+
+```html
+<!-- Left side -->
+<div sc-sheet-provider side="left">
+  <button sc-sheet-trigger>Open Left</button>
+  <ng-template scSheetPortal>
+    <div sc-sheet>
+      <!-- content -->
+    </div>
+  </ng-template>
+</div>
+
+<!-- Top side -->
+<div sc-sheet-provider side="top">
+  <button sc-sheet-trigger>Open Top</button>
+  <ng-template scSheetPortal>
+    <div sc-sheet>
+      <!-- content -->
+    </div>
+  </ng-template>
+</div>
+
+<!-- Bottom side -->
+<div sc-sheet-provider side="bottom">
+  <button sc-sheet-trigger>Open Bottom</button>
+  <ng-template scSheetPortal>
+    <div sc-sheet>
+      <!-- content -->
+    </div>
+  </ng-template>
+</div>
+```
+
+### Controlled Sheet
+
+```typescript
+@Component({
+  template: `
+    <div sc-sheet-provider [(open)]="isOpen" side="right">
+      <button sc-sheet-trigger>Open</button>
+      <ng-template scSheetPortal>
+        <div sc-sheet>
+          <!-- content -->
+        </div>
+      </ng-template>
+    </div>
+  `,
+})
+export class MyComponent {
+  isOpen = signal(false);
+
+  openSheet() {
+    this.isOpen.set(true);
+  }
+
+  closeSheet() {
+    this.isOpen.set(false);
+  }
+}
+```
+
+### Navigation Sheet
+
+```html
+<div sc-sheet-provider side="left">
+  <button sc-sheet-trigger>Menu</button>
+  <ng-template scSheetPortal>
+    <div sc-sheet>
+      <button sc-sheet-close>X</button>
+      <div sc-sheet-header>
+        <h2 sc-sheet-title>Navigation</h2>
+      </div>
+      <nav class="flex flex-col gap-2">
+        <a href="#">Home</a>
+        <a href="#">Products</a>
+        <a href="#">About</a>
+        <a href="#">Contact</a>
+      </nav>
+    </div>
+  </ng-template>
+</div>
+```
+
+## Keyboard Navigation
+
+| Key      | Action                |
+| -------- | --------------------- |
+| `Escape` | Close sheet           |
+| `Tab`    | Navigate within sheet |
+
+## Side Options
+
+| Side     | Description                    |
+| -------- | ------------------------------ |
+| `right`  | Slides in from right (default) |
+| `left`   | Slides in from left            |
+| `top`    | Slides down from top           |
+| `bottom` | Slides up from bottom          |
+
+## How It Works
+
+### State Management
+
+`ScSheetProvider` uses a `model` signal for the `open` state and an `input` for the `side`:
+
+```typescript
+readonly side = input<SheetSide>('right');
+readonly open = model<boolean>(false);
+```
+
+Child components inject `ScSheetProvider` to read or modify this state:
+
+```typescript
+// ScSheetTrigger
+openSheet(): void {
+  this.sheetProvider.open.set(true);
+}
+
+// ScSheetClose
+closeSheet(): void {
+  this.sheetProvider.open.set(false);
+}
+```
+
+### Overlay Management
+
+`ScSheetProvider` creates a CDK overlay and attaches/detaches the `scSheetPortal` template based on state:
+
+```typescript
+effect(() => {
+  if (this.overlayOpen()) {
+    this.attachSheet();
+  } else {
+    this.detachSheet();
+  }
+});
+```
+
+The `scSheetPortal` directive marks the `ng-template` whose content is lazily instantiated into the overlay only when the sheet opens.
+
+### Slide Animations
+
+`ScSheet` applies different transform classes based on the side and open state:
+
+```typescript
+const sideClosedClasses: Record<SheetSide, string> = {
+  top: '-translate-y-full',
+  right: 'translate-x-full',
+  bottom: 'translate-y-full',
+  left: '-translate-x-full',
+};
+
+const sideOpenClasses: Record<SheetSide, string> = {
+  top: 'translate-y-0',
+  right: 'translate-x-0',
+  bottom: 'translate-y-0',
+  left: 'translate-x-0',
+};
+```
+
+## Accessibility
+
+- `role="dialog"` on `ScSheet`
+- `aria-modal="true"` for modal behavior
+- `aria-labelledby` linked to `ScSheetTitle`
+- `aria-describedby` linked to `ScSheetDescription`
+- `aria-haspopup="dialog"` on the trigger
+- `aria-expanded` reflects open state on trigger
+- Focus trapped within the sheet via `cdkTrapFocus`
+- Escape key closes the sheet (via CDK overlay keydown events)
+- Click outside (backdrop) closes the sheet (via CDK overlay backdrop click)
+
+## Customization
+
+All components accept a `class` input for custom styling:
+
+```html
+<div sc-sheet class="w-[400px]">
+  <!-- custom width -->
+</div>
+
+<div sc-sheet-footer class="flex-row-reverse">
+  <!-- reversed button order -->
+</div>
+```

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

@@ -0,0 +1,10 @@
+export { ScSheetProvider } from './sheet-provider';
+export type { SheetSide } from './sheet-provider';
+export { ScSheetTrigger } from './sheet-trigger';
+export { ScSheetPortal } from './sheet-portal';
+export { ScSheet } from './sheet';
+export { ScSheetHeader } from './sheet-header';
+export { ScSheetTitle } from './sheet-title';
+export { ScSheetDescription } from './sheet-description';
+export { ScSheetFooter } from './sheet-footer';
+export { ScSheetClose } from './sheet-close';

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

@@ -0,0 +1,32 @@
+import { computed, Directive, inject, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { ScSheetProvider } from './sheet-provider';
+import { buttonVariants, ScButtonVariants } from '@semantic-components/ui';
+
+@Directive({
+  selector: 'button[sc-sheet-close]',
+  host: {
+    'data-slot': 'sheet-close',
+    '[class]': 'class()',
+    '(click)': 'closeSheet()',
+  },
+})
+export class ScSheetClose {
+  private readonly sheetProvider = inject(ScSheetProvider);
+
+  readonly classInput = input<string>('', { alias: 'class' });
+  readonly variant = input<ScButtonVariants['variant']>('ghost');
+  readonly size = input<ScButtonVariants['size']>('icon-sm');
+
+  protected readonly class = computed(() =>
+    cn(
+      buttonVariants({ variant: this.variant(), size: this.size() }),
+      'absolute top-3 right-3 z-10',
+      this.classInput(),
+    ),
+  );
+
+  protected closeSheet(): void {
+    this.sheetProvider.open.set(false);
+  }
+}

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

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

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

@@ -0,0 +1,20 @@
+import { computed, Directive, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Directive({
+  selector: 'div[sc-sheet-footer]',
+  host: {
+    'data-slot': 'sheet-footer',
+    '[class]': 'class()',
+  },
+})
+export class ScSheetFooter {
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn(
+      'flex flex-col-reverse gap-2 sm:flex-row sm:justify-end',
+      this.classInput(),
+    ),
+  );
+}

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

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

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

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

package/src/lib/components/sheet/sheet-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 { ScSheetPortal } from './sheet-portal';
+
+export type SheetSide = 'top' | 'right' | 'bottom' | 'left';
+
+@Component({
+  selector: 'div[sc-sheet-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]="sheetPortal().templateRef" />
+      </div>
+    </ng-template>
+  `,
+  host: {
+    'data-slot': 'sheet-provider',
+    '[class]': 'class()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScSheetProvider {
+  private readonly overlay = inject(Overlay);
+  private readonly viewContainerRef = inject(ViewContainerRef);
+
+  readonly classInput = input<string>('', { alias: 'class' });
+  readonly side = input<SheetSide>('right');
+
+  private readonly overlayTemplate =
+    viewChild.required<TemplateRef<unknown>>('overlayTemplate');
+
+  protected readonly sheetPortal = contentChild.required(ScSheetPortal);
+
+  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.attachSheet();
+      } else {
+        this.detachSheet();
+      }
+    });
+  }
+
+  onSheetAnimationComplete(): 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.closeSheet());
+      this.overlayRef.keydownEvents().subscribe((event) => {
+        if (event.key === 'Escape') this.closeSheet();
+      });
+    }
+    return this.overlayRef;
+  }
+
+  private attachSheet(): void {
+    const ref = this.getOverlayRef();
+    if (!ref.hasAttached()) {
+      const portal = new TemplatePortal(
+        this.overlayTemplate(),
+        this.viewContainerRef,
+      );
+      ref.attach(portal);
+    }
+  }
+
+  private detachSheet(): void {
+    if (this.overlayRef?.hasAttached()) {
+      this.overlayRef.detach();
+    }
+  }
+
+  private closeSheet(): void {
+    this.open.set(false);
+  }
+}

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

@@ -0,0 +1,20 @@
+import { computed, Directive, inject, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { ScSheet } from './sheet';
+
+@Directive({
+  selector: 'h2[sc-sheet-title]',
+  host: {
+    'data-slot': 'sheet-title',
+    '[id]': 'sheet.titleId',
+    '[class]': 'class()',
+  },
+})
+export class ScSheetTitle {
+  readonly sheet = inject(ScSheet);
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn('text-lg font-semibold text-foreground', this.classInput()),
+  );
+}

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

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

package/src/lib/components/sheet/sheet.ts

@@ -0,0 +1,92 @@
+import { _IdGenerator } from '@angular/cdk/a11y';
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  effect,
+  ElementRef,
+  inject,
+  input,
+  signal,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { ScSheetProvider, SheetSide } from './sheet-provider';
+
+type ScSheetState = 'open' | 'closed';
+
+const sidePositionClasses: Record<SheetSide, string> = {
+  top: 'inset-x-0 top-0 border-b',
+  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',
+  left: 'inset-y-0 left-0 h-full w-3/4 border-r sm:max-w-sm',
+};
+
+const sideAnimationClasses: Record<SheetSide, 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',
+};
+
+@Component({
+  selector: 'div[sc-sheet]',
+  template: `
+    <ng-content />
+  `,
+  host: {
+    'data-slot': 'sheet',
+    role: 'dialog',
+    'aria-modal': 'true',
+    '[attr.aria-labelledby]': 'titleId',
+    '[attr.aria-describedby]': 'descriptionId',
+    '[attr.data-state]': 'state()',
+    '[class]': 'class()',
+    '[tabindex]': '-1',
+    '(animationend)': 'onAnimationEnd($event)',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScSheet {
+  private readonly elementRef = inject(ElementRef<HTMLElement>);
+
+  readonly sheetProvider = inject(ScSheetProvider);
+  readonly classInput = input<string>('', { alias: 'class' });
+  readonly state = signal<ScSheetState>('closed');
+
+  readonly sheetId = inject(_IdGenerator).getId('sc-sheet-');
+  readonly titleId = `${this.sheetId}-title`;
+  readonly descriptionId = `${this.sheetId}-description`;
+
+  protected readonly class = computed(() => {
+    const side = this.sheetProvider.side();
+
+    return cn(
+      'bg-background fixed z-50 flex flex-col gap-4 p-6 shadow-lg',
+      sidePositionClasses[side],
+      'animate-in fade-in-0 duration-300',
+      sideAnimationClasses[side],
+      '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.sheetProvider.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.sheetProvider.onSheetAnimationComplete();
+    }
+  }
+}