@semantic-components/ui-lab 0.62.0 → 0.63.0

package/src/lib/components/masonry-grid/README.md

@@ -0,0 +1,204 @@
+# Masonry Grid
+
+A Pinterest-style layout component that arranges items in columns with varying heights.
+
+## Installation
+
+Import the components from the masonry-grid module:
+
+```typescript
+import { ScMasonryGrid, ScMasonryItem } from '@/ui/masonry-grid';
+```
+
+## Usage
+
+### Basic Usage
+
+```html
+<sc-masonry-grid [columns]="4" [gap]="16">
+  @for (item of items; track item.id) {
+  <sc-masonry-item>
+    <div class="card">
+      <!-- Your content -->
+    </div>
+  </sc-masonry-item>
+  }
+</sc-masonry-grid>
+```
+
+### Image Gallery
+
+```html
+<sc-masonry-grid [columns]="3" [gap]="12">
+  @for (image of images; track image.id) {
+  <sc-masonry-item>
+    <img [src]="image.url" [alt]="image.title" class="w-full rounded-lg" />
+  </sc-masonry-item>
+  }
+</sc-masonry-grid>
+```
+
+### Custom Breakpoints
+
+```html
+<sc-masonry-grid
+  [columns]="4"
+  [gap]="16"
+  [breakpoints]="[
+    { minWidth: 0, columns: 1 },
+    { minWidth: 640, columns: 2 },
+    { minWidth: 1024, columns: 4 }
+  ]"
+>
+  <!-- items -->
+</sc-masonry-grid>
+```
+
+### Absolute Positioning Mode
+
+```html
+<sc-masonry-grid [columns]="3" [gap]="16" layoutMode="absolute">
+  <!-- items -->
+</sc-masonry-grid>
+```
+
+### Programmatic Relayout
+
+```typescript
+import { viewChild } from '@angular/core';
+import { ScMasonryGrid } from '@/ui/masonry-grid';
+
+readonly masonryGrid = viewChild(ScMasonryGrid);
+
+onContentChange(): void {
+  // Trigger manual relayout after content changes
+  this.masonryGrid()?.relayout();
+}
+```
+
+## API Reference
+
+### ScMasonryGrid
+
+The main container component for the masonry layout.
+
+#### Inputs
+
+| Input         | Type                      | Default               | Description                 |
+| ------------- | ------------------------- | --------------------- | --------------------------- |
+| `columns`     | `number`                  | `4`                   | Default number of columns   |
+| `gap`         | `number`                  | `16`                  | Gap between items in pixels |
+| `breakpoints` | `MasonryBreakpoint[]`     | `DEFAULT_BREAKPOINTS` | Responsive breakpoints      |
+| `layoutMode`  | `'columns' \| 'absolute'` | `'columns'`           | Layout algorithm to use     |
+| `class`       | `string`                  | `''`                  | Additional CSS classes      |
+
+#### Public Methods
+
+| Method       | Description                             |
+| ------------ | --------------------------------------- |
+| `relayout()` | Manually trigger a layout recalculation |
+
+### ScMasonryItem
+
+Wrapper component for each item in the grid.
+
+#### Outputs
+
+| Output       | Type                | Description                    |
+| ------------ | ------------------- | ------------------------------ |
+| `sizeChange` | `{ width, height }` | Emitted when item size changes |
+
+#### Public Methods
+
+| Method         | Returns       | Description                |
+| -------------- | ------------- | -------------------------- |
+| `getElement()` | `HTMLElement` | Get the native DOM element |
+| `getHeight()`  | `number`      | Get the element's height   |
+
+## Type Definitions
+
+### MasonryBreakpoint
+
+```typescript
+interface MasonryBreakpoint {
+  minWidth: number; // Minimum viewport width
+  columns: number; // Number of columns at this breakpoint
+}
+```
+
+### MasonryConfig
+
+```typescript
+interface MasonryConfig {
+  columns?: number;
+  gap?: number;
+  breakpoints?: MasonryBreakpoint[];
+}
+```
+
+### MasonryLayoutMode
+
+```typescript
+type MasonryLayoutMode = 'columns' | 'absolute';
+```
+
+## Default Breakpoints
+
+```typescript
+const DEFAULT_BREAKPOINTS: MasonryBreakpoint[] = [
+  { minWidth: 0, columns: 1 }, // Mobile
+  { minWidth: 640, columns: 2 }, // sm
+  { minWidth: 768, columns: 3 }, // md
+  { minWidth: 1024, columns: 4 }, // lg
+  { minWidth: 1280, columns: 5 }, // xl
+];
+```
+
+## Layout Modes
+
+### columns (default)
+
+Uses CSS `column-count` for layout. This is the most performant option:
+
+- **Pros**: Native browser layout, no JavaScript calculations, smooth animations
+- **Cons**: Items flow top-to-bottom then left-to-right (not shortest-column-first)
+- **Best for**: Most use cases, image galleries, card layouts
+
+### absolute
+
+Uses JavaScript-calculated absolute positioning:
+
+- **Pros**: Items placed in shortest column first, better space utilization
+- **Cons**: Requires JavaScript calculations, may need manual relayout
+- **Best for**: When precise shortest-column placement is required
+
+## Features
+
+- **CSS Columns Layout**: Uses native CSS columns for optimal performance
+- **Responsive**: Configurable breakpoints for different screen sizes
+- **Flexible Gap**: Customizable spacing between items
+- **Dynamic Content**: Handles varying item heights automatically
+- **Two Layout Modes**: CSS columns or absolute positioning
+- **Manual Relayout**: Trigger recalculation when content changes
+- **ResizeObserver**: Automatically responds to container size changes
+
+## Styling
+
+The component uses CSS columns for layout. Each item automatically:
+
+- Breaks inside avoid (prevents items from splitting across columns)
+- Has margin-bottom equal to the gap
+
+Custom styling can be applied via the `class` input or by styling the content within `sc-masonry-item`.
+
+## Performance Tips
+
+1. **Use `columns` mode** (default) for best performance
+2. **Add `loading="lazy"`** to images for better initial load
+3. **Use `track` in `@for`** loops for efficient DOM updates
+4. **Call `relayout()`** sparingly, only when necessary
+
+## Browser Support
+
+- CSS Columns: Supported in all modern browsers
+- ResizeObserver: Supported in all modern browsers (polyfill available for older browsers)

package/src/lib/components/masonry-grid/index.ts

@@ -0,0 +1,4 @@
+export { ScMasonryGrid, type MasonryLayoutMode } from './masonry-grid';
+export { ScMasonryItem } from './masonry-item';
+export { DEFAULT_BREAKPOINTS, DEFAULT_CONFIG } from './masonry-types';
+export type { MasonryBreakpoint, MasonryConfig } from './masonry-types';

package/src/lib/components/masonry-grid/masonry-grid.ts

@@ -0,0 +1,178 @@
+import {
+  afterNextRender,
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  contentChildren,
+  DestroyRef,
+  ElementRef,
+  inject,
+  input,
+  signal,
+  viewChild,
+  ViewEncapsulation,
+} from '@angular/core';
+import { cn } from '@semantic-components/ui';
+import { ScMasonryItem } from './masonry-item';
+import { DEFAULT_BREAKPOINTS, type MasonryBreakpoint } from './masonry-types';
+
+export type MasonryLayoutMode = 'columns' | 'absolute';
+
+@Component({
+  selector: 'sc-masonry-grid',
+  template: `
+    <div
+      #container
+      [class]="containerClass()"
+      [style.column-count]="
+        layoutMode() === 'columns' ? currentColumns() : null
+      "
+      [style.column-gap.px]="layoutMode() === 'columns' ? gap() : null"
+      [style.position]="layoutMode() === 'absolute' ? 'relative' : null"
+      [style.height.px]="layoutMode() === 'absolute' ? containerHeight() : null"
+    >
+      <ng-content />
+    </div>
+  `,
+  styles: `
+    :host {
+      display: block;
+    }
+
+    :host ::ng-deep sc-masonry-item {
+      margin-bottom: var(--masonry-gap, 16px);
+    }
+  `,
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScMasonryGrid {
+  private readonly elementRef = inject(ElementRef<HTMLElement>);
+  private readonly destroyRef = inject(DestroyRef);
+  private resizeObserver: ResizeObserver | null = null;
+
+  readonly containerRef = viewChild<ElementRef<HTMLDivElement>>('container');
+  readonly items = contentChildren(ScMasonryItem);
+
+  readonly columns = input(4);
+  readonly gap = input(16);
+  readonly breakpoints = input<MasonryBreakpoint[]>(DEFAULT_BREAKPOINTS);
+  readonly layoutMode = input<MasonryLayoutMode>('columns');
+  readonly class = input<string>('');
+
+  protected readonly containerWidth = signal(0);
+  protected readonly containerHeight = signal(0);
+
+  protected readonly currentColumns = computed(() => {
+    const width = this.containerWidth();
+    const bps = [...this.breakpoints()].sort((a, b) => b.minWidth - a.minWidth);
+
+    for (const bp of bps) {
+      if (width >= bp.minWidth) {
+        return bp.columns;
+      }
+    }
+
+    return this.columns();
+  });
+
+  protected readonly containerClass = computed(() =>
+    cn('w-full', this.class()),
+  );
+
+  constructor() {
+    // Set CSS variable for gap
+    this.elementRef.nativeElement.style.setProperty(
+      '--masonry-gap',
+      `${this.gap()}px`,
+    );
+
+    afterNextRender(() => {
+      this.observeResize();
+      this.updateContainerWidth();
+
+      if (this.layoutMode() === 'absolute') {
+        this.calculateLayout();
+      }
+    });
+  }
+
+  private observeResize(): void {
+    if (typeof ResizeObserver === 'undefined') return;
+
+    this.resizeObserver = new ResizeObserver(() => {
+      this.updateContainerWidth();
+      if (this.layoutMode() === 'absolute') {
+        this.calculateLayout();
+      }
+    });
+
+    const container = this.containerRef()?.nativeElement;
+    if (container) {
+      this.resizeObserver.observe(container);
+    }
+
+    this.destroyRef.onDestroy(() => {
+      this.resizeObserver?.disconnect();
+    });
+  }
+
+  private updateContainerWidth(): void {
+    const container = this.containerRef()?.nativeElement;
+    if (container) {
+      this.containerWidth.set(container.offsetWidth);
+      // Update gap CSS variable
+      this.elementRef.nativeElement.style.setProperty(
+        '--masonry-gap',
+        `${this.gap()}px`,
+      );
+    }
+  }
+
+  private calculateLayout(): void {
+    const container = this.containerRef()?.nativeElement;
+    const itemsList = this.items();
+
+    if (!container || itemsList.length === 0) return;
+
+    const cols = this.currentColumns();
+    const gapSize = this.gap();
+    const containerW = this.containerWidth();
+    const columnWidth = (containerW - (cols - 1) * gapSize) / cols;
+
+    // Track height of each column
+    const columnHeights = new Array(cols).fill(0);
+
+    itemsList.forEach((item) => {
+      const element = item.getElement();
+
+      // Find the shortest column
+      const shortestColumn = columnHeights.indexOf(Math.min(...columnHeights));
+
+      // Calculate position
+      const left = shortestColumn * (columnWidth + gapSize);
+      const top = columnHeights[shortestColumn];
+
+      // Apply styles
+      element.style.position = 'absolute';
+      element.style.left = `${left}px`;
+      element.style.top = `${top}px`;
+      element.style.width = `${columnWidth}px`;
+
+      // Update column height
+      const itemHeight = element.offsetHeight;
+      columnHeights[shortestColumn] += itemHeight + gapSize;
+    });
+
+    // Set container height
+    this.containerHeight.set(Math.max(...columnHeights) - gapSize);
+  }
+
+  /** Recalculate the layout manually */
+  relayout(): void {
+    this.updateContainerWidth();
+    if (this.layoutMode() === 'absolute') {
+      this.calculateLayout();
+    }
+  }
+}

package/src/lib/components/masonry-grid/masonry-item.ts

@@ -0,0 +1,66 @@
+import {
+  afterNextRender,
+  ChangeDetectionStrategy,
+  Component,
+  DestroyRef,
+  ElementRef,
+  inject,
+  input,
+  output,
+  ViewEncapsulation,
+} from '@angular/core';
+
+@Component({
+  selector: 'sc-masonry-item',
+  template: `
+    <ng-content />
+  `,
+  styles: `
+    :host {
+      display: block;
+      break-inside: avoid;
+    }
+  `,
+  encapsulation: ViewEncapsulation.None,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class ScMasonryItem {
+  private readonly elementRef = inject(ElementRef<HTMLElement>);
+  private readonly destroyRef = inject(DestroyRef);
+  private resizeObserver: ResizeObserver | null = null;
+
+  readonly class = input<string>('');
+
+  readonly sizeChange = output<{ width: number; height: number }>();
+
+  constructor() {
+    afterNextRender(() => {
+      this.observeSize();
+    });
+  }
+
+  private observeSize(): void {
+    if (typeof ResizeObserver === 'undefined') return;
+
+    this.resizeObserver = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        const { width, height } = entry.contentRect;
+        this.sizeChange.emit({ width, height });
+      }
+    });
+
+    this.resizeObserver.observe(this.elementRef.nativeElement);
+
+    this.destroyRef.onDestroy(() => {
+      this.resizeObserver?.disconnect();
+    });
+  }
+
+  getElement(): HTMLElement {
+    return this.elementRef.nativeElement;
+  }
+
+  getHeight(): number {
+    return this.elementRef.nativeElement.offsetHeight;
+  }
+}

package/src/lib/components/masonry-grid/masonry-types.ts

@@ -0,0 +1,24 @@
+export interface MasonryBreakpoint {
+  minWidth: number;
+  columns: number;
+}
+
+export interface MasonryConfig {
+  columns?: number;
+  gap?: number;
+  breakpoints?: MasonryBreakpoint[];
+}
+
+export const DEFAULT_BREAKPOINTS: MasonryBreakpoint[] = [
+  { minWidth: 0, columns: 1 },
+  { minWidth: 640, columns: 2 },
+  { minWidth: 768, columns: 3 },
+  { minWidth: 1024, columns: 4 },
+  { minWidth: 1280, columns: 5 },
+];
+
+export const DEFAULT_CONFIG: MasonryConfig = {
+  columns: 4,
+  gap: 16,
+  breakpoints: DEFAULT_BREAKPOINTS,
+};

package/src/lib/components/mention-input/README.md

@@ -0,0 +1,122 @@
+# Mention Input
+
+Text input with @mention support for users, channels, or custom entities.
+
+## Components
+
+- `ScMentionInput` - Textarea with mention autocomplete
+
+## Usage
+
+### Basic Usage
+
+```html
+<sc-mention-input [(value)]="message" [(mentions)]="mentionedUsers" [users]="availableUsers" placeholder="Type @ to mention someone..." />
+```
+
+### Custom Trigger Character
+
+```html
+<sc-mention-input [users]="channels" trigger="#" placeholder="Type # to mention a channel..." />
+```
+
+## API
+
+### ScMentionInput
+
+| Input         | Type            | Default                          | Description              |
+| ------------- | --------------- | -------------------------------- | ------------------------ |
+| `class`       | `string`        | `''`                             | Additional CSS classes   |
+| `placeholder` | `string`        | `'Type @ to mention someone...'` | Placeholder text         |
+| `disabled`    | `boolean`       | `false`                          | Disable the input        |
+| `rows`        | `number`        | `3`                              | Number of visible rows   |
+| `users`       | `MentionUser[]` | `[]`                             | Available users/entities |
+| `trigger`     | `string`        | `'@'`                            | Trigger character        |
+
+| Output          | Type            | Description                      |
+| --------------- | --------------- | -------------------------------- |
+| `value`         | `string`        | Two-way binding for text value   |
+| `mentions`      | `MentionUser[]` | Two-way binding for mentions     |
+| `mentionSelect` | `MentionUser`   | Emits when a mention is selected |
+
+| Method            | Returns         | Description        |
+| ----------------- | --------------- | ------------------ |
+| `focus()`         | `void`          | Focus the textarea |
+| `getMentions()`   | `MentionUser[]` | Get all mentions   |
+| `clearMentions()` | `void`          | Clear all mentions |
+
+## MentionUser Interface
+
+```typescript
+interface MentionUser {
+  id: string;
+  name: string;
+  username: string;
+  avatar?: string;
+}
+```
+
+## Features
+
+- **Trigger Detection**: Activates when typing the trigger character (default: @)
+- **Search Filtering**: Filters users by name or username as you type
+- **Keyboard Navigation**: Use Arrow keys to navigate, Enter/Tab to select, Escape to close
+- **Avatar Support**: Display user avatars in the suggestion list
+- **Duplicate Prevention**: Already mentioned users are filtered from suggestions
+- **Custom Triggers**: Use any character as a trigger (e.g., # for channels)
+
+## Examples
+
+### Chat Application
+
+```typescript
+@Component({
+  template: `
+    <sc-mention-input [(value)]="message" [(mentions)]="mentions" [users]="teamMembers" placeholder="Type a message..." [rows]="2" />
+    <button (click)="sendMessage()">Send</button>
+  `,
+})
+export class ChatInput {
+  message = signal('');
+  mentions = signal<MentionUser[]>([]);
+  teamMembers: MentionUser[] = [
+    { id: '1', name: 'John Doe', username: 'johndoe' },
+    { id: '2', name: 'Jane Smith', username: 'janesmith' },
+  ];
+
+  sendMessage() {
+    console.log('Message:', this.message());
+    console.log('Mentioned:', this.mentions());
+  }
+}
+```
+
+### With Avatars
+
+```typescript
+const users: MentionUser[] = [
+  { id: '1', name: 'Sarah', username: 'sarah', avatar: 'https://example.com/sarah.jpg' },
+  { id: '2', name: 'Mike', username: 'mike', avatar: 'https://example.com/mike.jpg' },
+];
+```
+
+### Channel Mentions
+
+```html
+<sc-mention-input [users]="channels" trigger="#" placeholder="Mention a channel with #..." />
+```
+
+```typescript
+const channels: MentionUser[] = [
+  { id: '1', name: 'General', username: 'general' },
+  { id: '2', name: 'Engineering', username: 'engineering' },
+  { id: '3', name: 'Design', username: 'design' },
+];
+```
+
+## Accessibility
+
+- Dropdown has `role="listbox"` for screen readers
+- Options have `role="option"` and `aria-selected`
+- Keyboard navigation support (Arrow keys, Enter, Tab, Escape)
+- Focus management when selecting mentions

package/src/lib/components/mention-input/index.ts

@@ -0,0 +1,2 @@
+export { ScMentionInput } from './mention-input';
+export type { MentionUser } from './mention-input';