@semantic-components/ui-lab 0.62.0 → 0.63.0

package/src/lib/components/toggle-group/toggle-group.ts

@@ -0,0 +1,53 @@
+import { computed, Directive, input, model } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+export type ToggleGroupType = 'single' | 'multiple';
+export type ToggleGroupVariant = 'default' | 'outline';
+export type ToggleGroupSize = 'default' | 'sm' | 'lg';
+
+@Directive({
+  selector: 'div[sc-toggle-group]',
+  host: {
+    'data-slot': 'toggle-group',
+    role: 'group',
+    '[class]': 'class()',
+  },
+})
+export class ScToggleGroup {
+  readonly classInput = input<string>('', { alias: 'class' });
+  readonly type = input<ToggleGroupType>('single');
+  readonly value = model<string | string[] | null>(null);
+  readonly disabled = input<boolean>(false);
+  readonly variant = input<ToggleGroupVariant>('default');
+  readonly size = input<ToggleGroupSize>('default');
+
+  protected readonly class = computed(() =>
+    cn('flex items-center justify-center gap-1', this.classInput()),
+  );
+
+  isSelected(itemValue: string): boolean {
+    const currentValue = this.value();
+    if (this.type() === 'single') {
+      return currentValue === itemValue;
+    }
+    return Array.isArray(currentValue) && currentValue.includes(itemValue);
+  }
+
+  toggle(itemValue: string): void {
+    if (this.disabled()) return;
+
+    if (this.type() === 'single') {
+      this.value.set(this.value() === itemValue ? null : itemValue);
+    } else {
+      const currentValue = this.value();
+      const arr = Array.isArray(currentValue) ? [...currentValue] : [];
+      const index = arr.indexOf(itemValue);
+      if (index === -1) {
+        arr.push(itemValue);
+      } else {
+        arr.splice(index, 1);
+      }
+      this.value.set(arr);
+    }
+  }
+}

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

@@ -0,0 +1,76 @@
+# Toolbar
+
+A container for grouping a set of controls, such as toggle buttons. Built on `@angular/aria/toolbar` primitives with full keyboard navigation and ARIA support.
+
+## Components
+
+| Component              | Selector                       | Description                                                                        |
+| ---------------------- | ------------------------------ | ---------------------------------------------------------------------------------- |
+| `ScToolbar`            | `div[sc-toolbar]`              | Root toolbar container. Wraps `Toolbar` from `@angular/aria/toolbar`.              |
+| `ScToolbarWidget`      | `button[sc-toolbar-widget]`    | A toggleable button within the toolbar. Wraps `ToolbarWidget`.                     |
+| `ScToolbarWidgetGroup` | `div[sc-toolbar-widget-group]` | Groups related widgets together. Wraps `ToolbarWidgetGroup`.                       |
+| `ScToolbarSeparator`   | `div[sc-toolbar-separator]`    | A visual divider between widget groups. Auto-determines perpendicular orientation. |
+
+## Usage
+
+```html
+<div sc-toolbar [values]="['bold']">
+  <div sc-toolbar-widget-group>
+    <button sc-toolbar-widget value="bold" aria-label="Bold">B</button>
+    <button sc-toolbar-widget value="italic" aria-label="Italic">I</button>
+    <button sc-toolbar-widget value="underline" aria-label="Underline">U</button>
+  </div>
+
+  <div sc-toolbar-separator></div>
+
+  <div sc-toolbar-widget-group>
+    <button sc-toolbar-widget value="align-left" aria-label="Align left">L</button>
+    <button sc-toolbar-widget value="align-center" aria-label="Align center">C</button>
+    <button sc-toolbar-widget value="align-right" aria-label="Align right">R</button>
+  </div>
+</div>
+```
+
+## API
+
+### ScToolbar
+
+| Input          | Type                         | Default        | Description                                   |
+| -------------- | ---------------------------- | -------------- | --------------------------------------------- |
+| `orientation`  | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout direction of the toolbar.              |
+| `disabled`     | `boolean`                    | `false`        | Disables all widgets in the toolbar.          |
+| `softDisabled` | `boolean`                    | `true`         | When true, disabled widgets remain focusable. |
+| `wrap`         | `boolean`                    | `true`         | Whether keyboard navigation wraps around.     |
+| `values`       | `string[]`                   | `[]`           | Currently selected widget values.             |
+
+| Output         | Type       | Description                        |
+| -------------- | ---------- | ---------------------------------- |
+| `valuesChange` | `string[]` | Emits when selected values change. |
+
+### ScToolbarWidget
+
+| Input      | Type      | Default        | Description                           |
+| ---------- | --------- | -------------- | ------------------------------------- |
+| `value`    | `string`  | **(required)** | Unique value identifying this widget. |
+| `disabled` | `boolean` | `false`        | Disables this widget.                 |
+
+### ScToolbarWidgetGroup
+
+| Input      | Type      | Default | Description                                               |
+| ---------- | --------- | ------- | --------------------------------------------------------- |
+| `disabled` | `boolean` | `false` | Disables all widgets in this group.                       |
+| `multi`    | `boolean` | `false` | Allows multiple widgets to be selected within this group. |
+
+### ScToolbarSeparator
+
+No inputs. Automatically renders perpendicular to the parent toolbar's orientation.
+
+## Keyboard Navigation
+
+| Key                | Action                                           |
+| ------------------ | ------------------------------------------------ |
+| `Arrow Left/Right` | Move focus between widgets (horizontal toolbar). |
+| `Arrow Up/Down`    | Move focus between widgets (vertical toolbar).   |
+| `Home`             | Move focus to the first widget.                  |
+| `End`              | Move focus to the last widget.                   |
+| `Enter` / `Space`  | Toggle the focused widget.                       |

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

@@ -0,0 +1,4 @@
+export { ScToolbar } from './toolbar';
+export { ScToolbarWidget } from './toolbar-widget';
+export { ScToolbarWidgetGroup } from './toolbar-widget-group';
+export { ScToolbarSeparator } from './toolbar-separator';

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

@@ -0,0 +1,32 @@
+import { Toolbar } from '@angular/aria/toolbar';
+import { computed, Directive, inject, input } from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Directive({
+  selector: 'div[sc-toolbar-separator]',
+  host: {
+    'data-slot': 'toolbar-separator',
+    role: 'separator',
+    '[attr.aria-orientation]': 'separatorOrientation()',
+    '[attr.data-orientation]': 'separatorOrientation()',
+    '[class]': 'class()',
+  },
+})
+export class ScToolbarSeparator {
+  private readonly toolbar = inject(Toolbar);
+
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly separatorOrientation = computed(() =>
+    this.toolbar.orientation() === 'horizontal' ? 'vertical' : 'horizontal',
+  );
+
+  protected readonly class = computed(() => {
+    const isVertical = this.separatorOrientation() === 'vertical';
+    return cn(
+      'shrink-0 bg-border',
+      isVertical ? 'mx-1 h-full w-px' : 'my-1 h-px w-full',
+      this.classInput(),
+    );
+  });
+}

package/src/lib/components/toolbar/toolbar-widget-group.ts

@@ -0,0 +1,35 @@
+import { ToolbarWidgetGroup } from '@angular/aria/toolbar';
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Component({
+  selector: 'div[sc-toolbar-widget-group]',
+  hostDirectives: [
+    {
+      directive: ToolbarWidgetGroup,
+      inputs: ['disabled', 'multi'],
+    },
+  ],
+  template: `
+    <ng-content />
+  `,
+  host: {
+    'data-slot': 'toolbar-widget-group',
+    '[class]': 'class()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScToolbarWidgetGroup {
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn('flex items-center gap-1', this.classInput()),
+  );
+}

package/src/lib/components/toolbar/toolbar-widget.ts

@@ -0,0 +1,48 @@
+import { ToolbarWidget } from '@angular/aria/toolbar';
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  inject,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Component({
+  selector: 'button[sc-toolbar-widget]',
+  hostDirectives: [
+    {
+      directive: ToolbarWidget,
+      inputs: ['value', 'disabled'],
+    },
+  ],
+  template: `
+    <ng-content />
+  `,
+  host: {
+    'data-slot': 'toolbar-widget',
+    type: 'button',
+    '[attr.data-state]': 'widget.selected() ? "on" : "off"',
+    '[class]': 'class()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScToolbarWidget {
+  protected readonly widget = inject(ToolbarWidget);
+
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn(
+      'inline-flex items-center justify-center rounded-md text-sm font-medium ring-offset-background transition-colors',
+      'h-9 min-w-9 px-2.5',
+      'hover:bg-muted hover:text-muted-foreground',
+      'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
+      'disabled:pointer-events-none disabled:opacity-50',
+      'data-[state=on]:bg-accent data-[state=on]:text-accent-foreground',
+      this.classInput(),
+    ),
+  );
+}

package/src/lib/components/toolbar/toolbar.ts

@@ -0,0 +1,44 @@
+import { Toolbar } from '@angular/aria/toolbar';
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  inject,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+
+@Component({
+  selector: 'div[sc-toolbar]',
+  hostDirectives: [
+    {
+      directive: Toolbar,
+      inputs: ['orientation', 'disabled', 'wrap', 'values', 'softDisabled'],
+      outputs: ['valuesChange'],
+    },
+  ],
+  template: `
+    <ng-content />
+  `,
+  host: {
+    'data-slot': 'toolbar',
+    '[attr.data-orientation]': 'toolbar.orientation()',
+    '[class]': 'class()',
+  },
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScToolbar {
+  protected readonly toolbar = inject(Toolbar);
+
+  readonly classInput = input<string>('', { alias: 'class' });
+
+  protected readonly class = computed(() =>
+    cn(
+      'inline-flex items-center gap-1 rounded-lg border bg-background p-1',
+      this.toolbar.orientation() === 'vertical' && 'flex-col',
+      this.classInput(),
+    ),
+  );
+}

package/src/lib/components/tooltip/ANIMATIONS.md

@@ -0,0 +1,274 @@
+# Tooltip Animations
+
+This document explains how animations work in the tooltip component.
+
+## Overview
+
+The tooltip uses a state-based animation system that coordinates between the service and overlay component to provide smooth fade-in and fade-out effects.
+
+## Architecture
+
+### State Management
+
+The tooltip overlay has two states:
+
+```typescript
+type ScTooltipState = 'open' | 'closed';
+```
+
+The state is managed by a signal in `ScTooltip`:
+
+```typescript
+readonly state = signal<ScTooltipState>('open');
+```
+
+### State Attribute
+
+The state is exposed as a `data-state` attribute on the tooltip element:
+
+```typescript
+host: {
+  '[attr.data-state]': 'state()',
+}
+```
+
+This allows CSS to target different states:
+
+- `[data-state="open"]` - Tooltip is visible
+- `[data-state="closed"]` - Tooltip is closing
+
+## Animation Flow
+
+### 1. Show Animation (Fade In)
+
+When a tooltip is created:
+
+```typescript
+// ScTooltipManager.show()
+this.tooltipRef = this.overlayRef.attach(portal);
+```
+
+The overlay component initializes with `state = 'open'`, triggering CSS animations:
+
+```css
+.animate-in.fade-in-0.zoom-in-95
+```
+
+This creates a smooth fade-in with a subtle zoom effect.
+
+### 2. Hide Animation (Fade Out)
+
+When hiding a tooltip, the process is:
+
+**Step 1**: Trigger close state
+
+```typescript
+// ScTooltipManager.hide()
+this.tooltipRef.instance.close();
+```
+
+**Step 2**: Overlay component sets state to 'closed'
+
+```typescript
+// ScTooltip.close()
+close(): void {
+  this.state.set('closed');
+}
+```
+
+**Step 3**: CSS animations activate
+
+```css
+[data-state='closed'] {
+  /* Apply exit animations */
+  animation: fade-out, zoom-out;
+}
+```
+
+**Step 4**: Listen for animation completion
+
+```typescript
+// ScTooltip component listens to animationend event
+protected onAnimationEnd(event: AnimationEvent): void {
+  if (this.state() === 'closed' && event.target === this.elementRef.nativeElement) {
+    this.animationComplete.emit(); // Notify manager
+  }
+}
+
+// ScTooltipManager subscribes to animation complete
+this.animationSubscription = this.tooltipRef.instance.animationComplete.subscribe(() => {
+  this.disposeTooltip(); // Dispose after animation
+});
+```
+
+The animation completes automatically based on CSS animation duration (~200ms).
+
+## CSS Classes
+
+The tooltip uses Tailwind CSS utility classes for animations:
+
+### Entry Animations (data-state="open")
+
+```css
+animate-in          /* Base animation class */
+fade-in-0           /* Fade from opacity 0 */
+zoom-in-95          /* Zoom from 95% scale */
+```
+
+### Exit Animations (data-state="closed")
+
+```css
+data-[state=closed]:animate-out      /* Base exit animation */
+data-[state=closed]:fade-out-0       /* Fade to opacity 0 */
+data-[state=closed]:zoom-out-95      /* Zoom to 95% scale */
+```
+
+## Timing
+
+### Animation Duration
+
+The animation duration is defined as a static constant:
+
+```typescript
+private static readonly ANIMATION_DURATION = 200; // ms
+```
+
+This value must match your CSS animation duration for smooth transitions.
+
+### Show/Hide Delays
+
+Users can configure delays before showing or hiding tooltips:
+
+- **`tooltipDelay`** (default: 200ms) - Delay before showing
+- **`tooltipHideDelay`** (default: 0ms) - Delay before hiding
+
+These are separate from the animation duration and controlled by the directive.
+
+## Why This Approach?
+
+### 1. Smooth Exit Animations
+
+Simply disposing the overlay would cause an instant disappearance. By:
+
+1. Setting state to 'closed'
+2. Waiting for animation to complete
+3. Then disposing the overlay
+
+We ensure users see a smooth fade-out effect.
+
+### 2. No JavaScript Animations
+
+All animations are pure CSS, which:
+
+- Performs better (GPU accelerated)
+- Respects user's reduced motion preferences
+- Easier to customize with Tailwind classes
+
+### 3. Event-Driven Disposal
+
+The service listens to actual animation completion events, preventing:
+
+- Memory leaks from undisposed overlays
+- Visual glitches from early disposal
+- Timing mismatches between CSS and JavaScript
+- Issues with custom animation durations
+
+## Customizing Animations
+
+### Change Animation Duration
+
+Update your CSS animation duration:
+
+```css
+/* Change animation duration in your custom classes */
+.my-custom-tooltip {
+  animation-duration: 300ms !important;
+}
+```
+
+The manager automatically waits for the `animationend` event, so no timing constants need updating.
+
+### Custom Animation Classes
+
+Use the `tooltipClass` input to add custom animations:
+
+```html
+<button scTooltip="Hello" tooltipClass="custom-bounce">Click me</button>
+```
+
+```css
+.custom-bounce {
+  animation: bounce 0.3s ease-in-out;
+}
+```
+
+### Disable Animations
+
+Remove animation classes from `ScTooltip.hostClass`:
+
+```typescript
+protected readonly hostClass = computed(() =>
+  cn(
+    'bg-primary text-primary-foreground z-50 rounded-md px-3 py-1.5 text-xs max-w-xs',
+    // Remove these lines for no animations:
+    // 'animate-in fade-in-0 zoom-in-95',
+    // 'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
+    this.data.tooltipClass,
+  ),
+);
+```
+
+The component will still emit `animationComplete` even without animations.
+
+## Accessibility
+
+The animation system respects accessibility:
+
+- **Reduced Motion**: Tailwind's animation utilities automatically respect `prefers-reduced-motion`
+- **Screen Readers**: The `aria-live="polite"` attribute ensures content changes are announced smoothly
+- **No Motion Sickness**: The subtle zoom (95% scale) avoids dramatic movements
+
+## Debugging
+
+To debug animation issues:
+
+1. **Check State Transitions**
+
+   ```typescript
+   // Add logging in ScTooltip
+   close(): void {
+     console.log('Tooltip closing, state:', this.state());
+     this.state.set('closed');
+     console.log('Tooltip state after close:', this.state());
+   }
+   ```
+
+2. **Verify Animation Events**
+
+   ```typescript
+   // Add logging in ScTooltip
+   protected onAnimationEnd(event: AnimationEvent): void {
+     console.log('Animation ended:', event.animationName, 'State:', this.state());
+     if (this.state() === 'closed' && event.target === this.elementRef.nativeElement) {
+       console.log('Emitting animationComplete');
+       this.animationComplete.emit();
+     }
+   }
+   ```
+
+3. **Inspect DOM**
+   - Open DevTools while tooltip is closing
+   - Check the `data-state` attribute changes from `"open"` to `"closed"`
+   - Verify animation classes are present
+
+## Summary
+
+The tooltip animation system provides:
+
+- ✅ Smooth fade-in/fade-out with zoom effects
+- ✅ State-based animations using CSS
+- ✅ Coordinated timing between service and overlay
+- ✅ Accessible and performant
+- ✅ Easy to customize
+
+The key is the two-step hide process: set state to 'closed', then dispose after animation completes.

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

@@ -0,0 +1,100 @@
+# Tooltip
+
+A simple directive-based tooltip for displaying text hints on hover or focus.
+
+## Usage
+
+### Basic Usage
+
+```html
+<button scTooltipTrigger="Save changes">Save</button>
+```
+
+### With Position
+
+```html
+<button scTooltipTrigger="Save changes" tooltipPosition="right">Save</button>
+```
+
+Available positions: `top` (default), `right`, `bottom`, `left`
+
+### With Custom Delay
+
+```html
+<button scTooltipTrigger="Save changes" [tooltipDelay]="500">Save</button>
+```
+
+### With Hide Delay
+
+```html
+<button scTooltipTrigger="Save changes" [tooltipHideDelay]="200">Save</button>
+```
+
+### Disabled State
+
+```html
+<button scTooltipTrigger="Save changes" [tooltipDisabled]="isDisabled">Save</button>
+```
+
+### Custom Styling
+
+```html
+<button scTooltipTrigger="Save changes" tooltipClass="my-custom-tooltip">Save</button>
+```
+
+## API Reference
+
+### Inputs
+
+| Input              | Alias       | Type                                     | Default | Description                                     |
+| ------------------ | ----------- | ---------------------------------------- | ------- | ----------------------------------------------- |
+| `scTooltipTrigger` | -           | `string`                                 | -       | The tooltip text content (required)             |
+| `tooltipPosition`  | `position`  | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Position of the tooltip relative to the trigger |
+| `tooltipDelay`     | `showDelay` | `number`                                 | `200`   | Delay before showing the tooltip (ms)           |
+| `tooltipHideDelay` | `hideDelay` | `number`                                 | `0`     | Delay before hiding the tooltip (ms)            |
+| `tooltipDisabled`  | `disabled`  | `boolean`                                | `false` | Whether the tooltip is disabled                 |
+| `tooltipClass`     | `class`     | `string`                                 | `''`    | Custom CSS class for the tooltip                |
+
+## Accessibility
+
+- The tooltip has `role="tooltip"` for screen readers
+- The tooltip uses `aria-live="polite"` and `aria-atomic="true"` for dynamic content announcements
+- The trigger element has `aria-describedby` pointing to the tooltip when visible
+- Supports keyboard navigation (shows on focus, hides on blur)
+- Pressing `Escape` dismisses the tooltip
+- Unique IDs are generated using Angular CDK's `_IdGenerator` for proper ARIA references
+
+## Behavior
+
+- **Singleton**: Only one tooltip is visible at a time globally (managed by `ScTooltipManager`)
+- **Smart Positioning**: Automatically flips to the opposite side if there's not enough space using CDK Overlay
+- **Hover Support**: Shows on mouseenter, hides on mouseleave
+- **Focus Support**: Shows on focus, hides on blur
+- **Escape to Close**: Pressing Escape dismisses the tooltip
+- **Smooth Animations**: Fade in/out with zoom effects - see [ANIMATIONS.md](./ANIMATIONS.md) for details
+
+## When to Use
+
+Use **Tooltip** for:
+
+- Simple text hints
+- Icon button labels
+- Abbreviation explanations
+- Quick help text
+
+Use **Hovercard** instead for:
+
+- Rich content with HTML
+- Images or avatars
+- Interactive elements (buttons, links)
+- Complex formatted content
+
+## Architecture
+
+The tooltip consists of three main parts:
+
+- **`ScTooltipTrigger`** (directive) - Attaches to trigger elements, handles user interactions (used via `[scTooltipTrigger]` attribute)
+- **`ScTooltipManager`** (service) - Manages overlay lifecycle, ensures singleton behavior
+- **`ScTooltip`** (component) - The visual tooltip component with content and styling
+
+See [ANIMATIONS.md](./ANIMATIONS.md) for details on how animations work.

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

@@ -0,0 +1,3 @@
+export { ScTooltipTrigger } from './tooltip-trigger';
+export { ScTooltipManager } from './tooltip-manager';
+export type { ScTooltipPosition } from './tooltip-manager';