wally-ui 1.13.1 → 1.14.1

package/playground/showcase/src/app/components/selection-popover/selection-popover.ts

@@ -0,0 +1,269 @@
+import { AfterViewInit, Component, computed, ElementRef, HostListener, output, OutputEmitterRef, signal, ViewChild, WritableSignal } from '@angular/core';
+
+/**
+ * Selection Popover Component
+ *
+ * Displays a floating action toolbar above selected text (similar to Medium, Notion, Google Docs).
+ * Uses Selection API for text detection and supports custom actions via content projection.
+ *
+ * @example
+ * ```html
+ * <wally-selection-popover (textSelected)="onTextSelected($event)">
+ *   <div popoverActions>
+ *     <button>Custom Action</button>
+ *   </div>
+ *   <article>Selectable content...</article>
+ * </wally-selection-popover>
+ * ```
+ */
+@Component({
+  selector: 'wally-selection-popover',
+  standalone: true,
+  imports: [],
+  templateUrl: './selection-popover.html',
+  styleUrl: './selection-popover.css'
+})
+export class SelectionPopover implements AfterViewInit {
+  /** Reference to the popover element for positioning calculations */
+  @ViewChild('popover') popoverElement!: ElementRef<HTMLDivElement>;
+
+  /** Reference to custom actions slot for detecting projected content */
+  @ViewChild('customActionsSlot', { read: ElementRef }) customActionsSlot?: ElementRef;
+
+  /** Emits when text is selected (fallback action only) */
+  textSelected: OutputEmitterRef<string> = output<string>();
+
+  /** Current popover position (top, left in pixels) */
+  popoverPosition: WritableSignal<{ top: number; left: number; }> = signal<{ top: number; left: number; }>({ top: 0, left: 0 });
+
+  /** Whether custom actions are projected */
+  hasCustomActionsSignal: WritableSignal<boolean> = signal<boolean>(false);
+
+  /** Whether popover should be rendered in DOM */
+  isVisible: WritableSignal<boolean> = signal<boolean>(false);
+
+  /** Whether popover is positioned correctly (controls opacity) */
+  isPositioned: WritableSignal<boolean> = signal<boolean>(false);
+
+  /** Currently selected text */
+  selectedText: WritableSignal<string> = signal<string>('');
+
+  /**
+   * Detects if user is on mobile device
+   */
+  isMobile = computed(() => {
+    if (typeof window === 'undefined') return false;
+
+    return 'ontouchstart' in window ||
+      navigator.maxTouchPoints > 0 ||
+      window.innerWidth < 768;
+  });
+
+  /**
+   * Computes adjusted position with viewport constraints
+   * Prevents popover from overflowing screen edges
+   * Mobile-aware: accounts for virtual keyboard and smaller screens
+   */
+  adjustedPosition = computed(() => {
+    const position = this.popoverPosition();
+    const viewportWidth = window.innerWidth;
+    const viewportHeight = window.innerHeight;
+
+    // Get real popover dimensions if available, otherwise estimate
+    const popoverWidth = this.popoverElement?.nativeElement?.offsetWidth || 200;
+    const popoverHeight = this.popoverElement?.nativeElement?.offsetHeight || 50;
+
+    let left = position.left;
+    let top = position.top;
+
+    // Horizontal adjustment
+    if (left + popoverWidth > viewportWidth) {
+      left = viewportWidth - popoverWidth - 10;
+    }
+    if (left < 10) {
+      left = 10;
+    }
+
+    // Vertical adjustment for mobile (avoid keyboard and screen edges)
+    if (this.isMobile()) {
+      // If too close to top, position below selection instead
+      if (top < 80) {
+        const selection = window.getSelection();
+        if (selection && selection.rangeCount > 0) {
+          const range = selection.getRangeAt(0);
+          const rect = range.getBoundingClientRect();
+          top = rect.bottom + 10; // 10px below selection
+        }
+      }
+
+      // If too close to bottom (virtual keyboard area), keep visible
+      if (top + popoverHeight > viewportHeight - 100) {
+        top = viewportHeight - popoverHeight - 100;
+      }
+    }
+
+    return { top, left };
+  });
+
+  /**
+   * Handles both mouse and touch selection events
+   * Mobile: touchend after long-press selection
+   * Desktop: mouseup after click-drag selection
+   */
+  @HostListener('mouseup', ['$event'])
+  @HostListener('touchend', ['$event'])
+  onMouseUp(event: MouseEvent | TouchEvent): void {
+    const isMobile = 'ontouchstart' in window;
+    const delay = isMobile ? 100 : 10;
+
+    setTimeout(() => {
+      this.handleTextSelection();
+    }, delay);
+  }
+
+  /**
+   * Closes popover when clicking outside
+   * @param event - Mouse event from document click
+   */
+  @HostListener('document:mousedown', ['$event'])
+  onDocumentClick(event: MouseEvent): void {
+    if (this.isVisible() && this.popoverElement) {
+      const clickedInside = this.popoverElement.nativeElement.contains(event.target as Node);
+
+      if (!clickedInside) {
+        this.hide();
+      }
+    }
+  }
+
+  /**
+   * Closes popover when ESC key is pressed
+   */
+  @HostListener('document:keydown.escape')
+  onEscape(): void {
+    this.hide();
+  }
+
+  /**
+  * Prevents native mobile selection menu from appearing
+  * This ensures only our custom popover is shown
+  */
+  @HostListener('selectionchange')
+  onNativeSelectionChange() {
+    const selection = window.getSelection();
+
+    if (selection && selection.toString().trim().length >= 3) {
+      // Prevent native menu only if valid selection exists
+      // and our popover will appear
+      event?.preventDefault?.();
+    }
+  }
+
+  /**
+   * Prevents scroll when touching the popover on mobile
+   * Ensures users can interact with actions without accidentally scrolling
+   */
+  @HostListener('touchmove', ['$event'])
+  onTouchMove(event: TouchEvent): void {
+    if (this.isVisible() && this.popoverElement) {
+      const target = event.target as Node;
+      const isPopoverTouch = this.popoverElement.nativeElement.contains(target);
+
+      if (isPopoverTouch) {
+        event.preventDefault();
+      }
+    }
+  }
+
+  /**
+   * Handles text selection and shows popover
+   *
+   * Two-step positioning algorithm to prevent visual "flash":
+   * 1. Render popover invisible (opacity: 0) at selection center
+   * 2. Wait for DOM render to get real popover width
+   * 3. Recalculate centered position with actual width
+   * 4. Fade in popover (opacity: 100) at correct position
+   *
+   * Uses position: fixed + getBoundingClientRect() for viewport-relative positioning
+   * No window.scrollY needed - stays in place during scroll
+   */
+  handleTextSelection(): void {
+    const selection = window.getSelection();
+
+    if (!selection || selection.toString().trim().length < 3) {
+      this.hide();
+      return;
+    }
+
+    const text = selection.toString().trim();
+    const range = selection.getRangeAt(0);
+    const rect = range.getBoundingClientRect();
+
+    this.selectedText.set(text);
+
+    // Calculate selection center point
+    const selectionCenterX = rect.left + (rect.width / 2);
+    const selectionTop = rect.top;
+
+    // Step 1: Render invisible for width calculation
+    this.isVisible.set(true);
+    this.isPositioned.set(false); // opacity: 0
+
+    // Step 2: Recalculate position with real popover width
+    setTimeout(() => {
+      if (this.popoverElement?.nativeElement) {
+        const popoverWidth = this.popoverElement.nativeElement.offsetWidth;
+
+        // Center popover above selection (60px offset)
+        this.popoverPosition.set({
+          top: selectionTop - 60,
+          left: selectionCenterX - (popoverWidth / 2)
+        });
+
+        // Fade in at correct position
+        this.isPositioned.set(true); // opacity: 100
+      }
+
+      // Detect projected custom actions
+      if (this.customActionsSlot?.nativeElement) {
+        const slot = this.customActionsSlot.nativeElement;
+        const firstChild = slot.children[0] as HTMLElement;
+        const hasContent = firstChild && firstChild.children.length > 0;
+        this.hasCustomActionsSignal.set(hasContent);
+      }
+    }, 0);
+  }
+
+  /**
+   * Hides popover and clears browser text selection
+   */
+  hide(): void {
+    this.isVisible.set(false);
+    this.isPositioned.set(false);
+
+    window.getSelection()?.removeAllRanges();
+  }
+
+  /**
+   * Handles any click inside the popover
+   * Emits selected text and closes popover
+   * This allows both custom actions and fallback button to work
+   */
+  onPopoverClick() {
+    const text = this.selectedText();
+    this.textSelected.emit(text);
+    this.hide();
+  }
+
+  /**
+   * Lifecycle hook - detects custom actions on component init
+   */
+  ngAfterViewInit(): void {
+    if (this.customActionsSlot?.nativeElement) {
+      const slot = this.customActionsSlot.nativeElement;
+      const firstChild = slot.children[0] as HTMLElement;
+      const hasContent = firstChild && firstChild.children.length > 0;
+      this.hasCustomActionsSignal.set(hasContent);
+    }
+  }
+}

package/playground/showcase/src/app/pages/documentation/chat-sdk/chat-sdk.html

@@ -22,7 +22,7 @@
     </header>
 
     <!-- Live Demo -->
-    <section id="live-demo" class="mb-12" aria-labelledby="demo-heading">
+    <section id="live-demo" class="mb-12 font-sans" aria-labelledby="demo-heading">
       <h2 id="demo-heading" class="text-[10px] sm:text-xs text-neutral-500 dark:text-neutral-500 uppercase tracking-wider mb-4">
         [ Live Demo ]
       </h2>

package/playground/showcase/src/app/pages/documentation/components/button-docs/button-docs.examples.ts

@@ -79,7 +79,7 @@ export const ButtonCodeExamples = {
     <wally-button
       variant="secondary"
       type="button"
-      (click)="goToSignUp()">
+      (buttonClick)="goToSignUp()">
       Create Account
     </wally-button>
   </div>
@@ -109,14 +109,14 @@ export const ButtonCodeExamples = {
   <div class="flex gap-2 justify-end">
     <wally-button
       variant="ghost"
-      (click)="closeModal()">
+      (buttonClick)="closeModal()">
       Cancel
     </wally-button>
 
     <wally-button
       variant="destructive"
       [loading]="isDeleting()"
-      (click)="confirmDelete()">
+      (buttonClick)="confirmDelete()">
       Delete Account
     </wally-button>
   </div>
@@ -125,7 +125,7 @@ export const ButtonCodeExamples = {
   // Dashboard Actions
   dashboardExample: `<!-- Dashboard Actions -->
 <div class="dashboard-header">
-  <wally-button variant="outline" (click)="exportData()">
+  <wally-button variant="outline" (buttonClick)="exportData()">
     Export
     <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24"
          stroke-width="1.5" stroke="currentColor" class="size-5">
@@ -134,7 +134,7 @@ export const ButtonCodeExamples = {
     </svg>
   </wally-button>
 
-  <wally-button (click)="createNew()">
+  <wally-button (buttonClick)="createNew()">
     Create New
     <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24"
          stroke-width="2" stroke="currentColor" class="size-5">
@@ -162,7 +162,7 @@ export const ButtonCodeExamples = {
 
   // === EVENTS ===
 
-  clickTemplate: `<wally-button (click)="handleClick()">Click Me</wally-button>`,
+  clickTemplate: `<wally-button (buttonClick)="handleClick()">Click Me</wally-button>`,
 
   clickMethod: `handleClick(): void {
   console.log('Button clicked!');
@@ -263,7 +263,7 @@ export const ButtonCodeExamples = {
 </wally-button>
 
 <!-- Programmatic navigation -->
-<wally-button (click)="navigateToProfile()">
+<wally-button (buttonClick)="navigateToProfile()">
   View Profile
 </wally-button>`,
 
@@ -312,18 +312,18 @@ export class MyComponent {
 <wally-button
   [loading]="isLoading()"
   [disabled]="isDisabled()"
-  (click)="handleSubmit()">
+  (buttonClick)="handleSubmit()">
   Submit
 </wally-button>`,
 
   // Button vs type="button"
   buttonTypeExplained: `<!-- GOOD: Explicit type prevents accidental form submission -->
-<wally-button type="button" (click)="openModal()">
+<wally-button type="button" (buttonClick)="openModal()">
   Open
 </wally-button>
 
 <!-- CAUTION: Default type="button" is safe, but explicit is better -->
-<wally-button (click)="openModal()">Open</wally-button>
+<wally-button (buttonClick)="openModal()">Open</wally-button>
 
 <!-- GOOD: Use type="submit" for form submission -->
 <form (ngSubmit)="save()">

package/playground/showcase/src/app/pages/documentation/components/button-docs/button-docs.html

@@ -484,7 +484,7 @@
       <div class="p-8 border-2 border-neutral-300 dark:border-neutral-700 bg-white dark:bg-[#0a0a0a]" role="img"
         aria-label="Live preview of button click event handling with feedback message">
         <div class="flex flex-col gap-2 text-center">
-          <wally-button (click)="handleClick()">Click Me</wally-button>
+          <wally-button (buttonClick)="handleClick()">Click Me</wally-button>
           @if (clickMessage()) {
           <p class="text-sm text-green-600 dark:text-green-400 font-medium">
             {{ clickMessage() }}
@@ -753,7 +753,7 @@
               </thead>
               <tbody>
                 <tr>
-                  <td class="p-4 font-mono text-blue-600 dark:text-blue-400">click</td>
+                  <td class="p-4 font-mono text-blue-600 dark:text-blue-400">buttonClick</td>
                   <td class="p-4 font-mono text-purple-600 dark:text-purple-400">void</td>
                   <td class="p-4 text-gray-700 dark:text-gray-300">Emitted when button is clicked. Also handles
                     navigation for link variant</td>

package/playground/showcase/src/app/pages/documentation/components/components.html

@@ -181,6 +181,33 @@
         </article>
 
 
+        <!-- Selection Popover Component -->
+        <article class="group border-b-2 border-neutral-300 dark:border-neutral-700 last:border-b-0" role="article"
+          aria-labelledby="selection-popover-heading">
+          <a href="/documentation/components/selection-popover"
+            class="block px-4 py-4 sm:py-5 bg-white dark:bg-[#0a0a0a] hover:bg-[#0a0a0a] dark:hover:bg-white transition-all duration-150 cursor-pointer"
+            aria-label="Navigate to Selection Popover component documentation with text selection detection, viewport-aware positioning, and zero-flash rendering">
+            <div class="flex flex-col sm:flex-row sm:items-start sm:justify-between gap-3">
+              <div class="flex-1">
+                <div class="flex items-center gap-3 mb-2">
+                  <h3 id="selection-popover-heading"
+                    class="text-base sm:text-lg font-bold text-[#0a0a0a] dark:text-white group-hover:text-white dark:group-hover:text-[#0a0a0a] uppercase tracking-wide transition-colors duration-150">
+                    <span aria-hidden="true">&gt;_ </span>Selection Popover
+                  </h3>
+                  <span class="text-[10px] font-bold bg-blue-500 text-white px-2 py-1 uppercase tracking-wider"
+                    aria-label="Status: New Component">
+                    NEW
+                  </span>
+                </div>
+                <p
+                  class="text-xs sm:text-sm text-neutral-600 dark:text-neutral-400 group-hover:text-neutral-300 dark:group-hover:text-neutral-600 transition-colors duration-150">
+                  Floating action toolbar that appears above selected text (Medium/Notion-style). Features Selection API integration, viewport-aware positioning, zero-flash rendering, and custom actions via content projection.
+                </p>
+              </div>
+            </div>
+          </a>
+        </article>
+
         <!-- Tooltip Component -->
         <article class="group border-b-2 border-neutral-300 dark:border-neutral-700 last:border-b-0" role="article"
           aria-labelledby="tooltip-heading">

package/playground/showcase/src/app/pages/documentation/components/components.routes.ts

@@ -28,5 +28,9 @@ export const componentsRoutes: Routes = [
     {
         path: 'dropdown-menu',
         loadComponent: () => import('./dropdown-menu-docs/dropdown-menu-docs').then(m => m.DropdownMenuDocs)
+    },
+    {
+        path: 'selection-popover',
+        loadComponent: () => import('./selection-popover-docs/selection-popover-docs').then(m => m.SelectionPopoverDocs)
     }
 ];

package/playground/showcase/src/app/pages/documentation/components/selection-popover-docs/selection-popover-docs.css

@@ -0,0 +1 @@
+/* Selection Popover Documentation Styles */