@shadng/sng-ui 1.0.0

package/src/lib/menu/sng-menu-label.ts

@@ -0,0 +1,47 @@
+import {
+  Component,
+  ChangeDetectionStrategy,
+  input,
+  computed,
+  booleanAttribute,
+} from '@angular/core';
+import { cn } from './cn';
+
+/**
+ * Non-interactive label for grouping or describing menu sections.
+ *
+ * @example
+ * ```html
+ * <sng-menu>
+ *   <sng-menu-label>Actions</sng-menu-label>
+ *   <sng-menu-item>Edit</sng-menu-item>
+ *   <sng-menu-item>Delete</sng-menu-item>
+ * </sng-menu>
+ * ```
+ */
+@Component({
+  selector: 'sng-menu-label',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  host: {
+    '[class]': 'hostClasses()',
+  },
+  template: `<ng-content />`,
+})
+export class SngMenuLabel {
+  /** Custom CSS classes. */
+  class = input<string>('');
+
+  /**
+   * Whether to add left padding for alignment with checkbox/radio items.
+   */
+  inset = input(false, { transform: booleanAttribute });
+
+  hostClasses = computed(() =>
+    cn(
+      'px-2 py-1.5 text-sm font-semibold text-foreground',
+      this.inset() && 'pl-8',
+      this.class()
+    )
+  );
+}

package/src/lib/menu/sng-menu-radio-group.ts

@@ -0,0 +1,38 @@
+import {
+  Component,
+  ChangeDetectionStrategy,
+  model,
+} from '@angular/core';
+
+/**
+ * Container for radio menu items. Manages single-selection state.
+ *
+ * @example
+ * ```html
+ * <sng-menu>
+ *   <sng-menu-radio-group [(value)]="selectedTheme">
+ *     <sng-menu-radio-item value="light">Light</sng-menu-radio-item>
+ *     <sng-menu-radio-item value="dark">Dark</sng-menu-radio-item>
+ *     <sng-menu-radio-item value="system">System</sng-menu-radio-item>
+ *   </sng-menu-radio-group>
+ * </sng-menu>
+ * ```
+ */
+@Component({
+  selector: 'sng-menu-radio-group',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  host: {
+    'role': 'group',
+  },
+  template: `<ng-content />`,
+})
+export class SngMenuRadioGroup {
+  /** The currently selected value. Supports two-way binding. */
+  value = model<string>('');
+
+  /** @internal Called by child radio items to select a value. */
+  _selectValue(newValue: string) {
+    this.value.set(newValue);
+  }
+}

package/src/lib/menu/sng-menu-radio-item.ts

@@ -0,0 +1,94 @@
+import {
+  Component,
+  ChangeDetectionStrategy,
+  ViewEncapsulation,
+  inject,
+  input,
+  computed,
+  booleanAttribute,
+} from '@angular/core';
+import { cn } from './cn';
+import { SngMenuRadioGroup } from './sng-menu-radio-group';
+import { SNG_MENU_PANEL, MENU_ITEM_BASE_CLASSES } from './sng-menu-tokens';
+
+/**
+ * A radio menu item within a radio group.
+ *
+ * @example
+ * ```html
+ * <sng-menu-radio-group [(value)]="theme">
+ *   <sng-menu-radio-item value="light">Light</sng-menu-radio-item>
+ *   <sng-menu-radio-item value="dark">Dark</sng-menu-radio-item>
+ * </sng-menu-radio-group>
+ * ```
+ */
+@Component({
+  selector: 'sng-menu-radio-item',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    '[class]': 'hostClasses()',
+    '[attr.data-state]': 'isChecked() ? "checked" : "unchecked"',
+    '[attr.data-disabled]': 'resolvedDisabled() ? "" : null',
+    '[attr.aria-checked]': 'isChecked()',
+    '[attr.tabindex]': 'resolvedDisabled() ? -1 : 0',
+    'role': 'menuitemradio',
+    '(click)': 'select()',
+  },
+  template: `
+    <span class="flex h-4 w-4 items-center justify-center mr-2">
+      @if (isChecked()) {
+        <svg class="h-2 w-2 fill-current" viewBox="0 0 8 8">
+          <circle cx="4" cy="4" r="4" />
+        </svg>
+      }
+    </span>
+    <ng-content />
+  `,
+})
+export class SngMenuRadioItem {
+  private radioGroup = inject(SngMenuRadioGroup, { optional: true });
+  private panel = inject(SNG_MENU_PANEL, { optional: true });
+
+  /** Custom CSS classes. */
+  class = input<string>('');
+
+  /** The value associated with this radio item. */
+  value = input.required<string>();
+
+  /** Whether the radio item is disabled. */
+  disabled = input(false, { transform: booleanAttribute });
+
+  /** Legacy disabled input name. */
+  isDisabled = input<unknown>(undefined);
+
+  /** Whether to close the menu when this item is selected. Uses parent menu's setting when not specified. */
+  isCloseOnSelect = input<boolean | undefined>(undefined);
+
+  resolvedDisabled = computed(() => {
+    const legacyValue = this.isDisabled();
+    return legacyValue === undefined ? this.disabled() : booleanAttribute(legacyValue);
+  });
+
+  /** Whether this item is currently checked. */
+  isChecked = computed(() => this.radioGroup?.value() === this.value());
+
+  hostClasses = computed(() =>
+    cn(
+      ...MENU_ITEM_BASE_CLASSES,
+      this.class()
+    )
+  );
+
+  /** Select this radio item. */
+  select() {
+    if (!this.resolvedDisabled() && this.radioGroup) {
+      this.radioGroup._selectValue(this.value());
+      const shouldClose = this.isCloseOnSelect() ?? this.panel?.closeOnSelect() ?? true;
+      if (shouldClose) {
+        this.panel?.close();
+      }
+    }
+  }
+}

package/src/lib/menu/sng-menu-separator.ts

@@ -0,0 +1,27 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+
+/**
+ * Visual divider line between groups of menu items.
+ *
+ * @example
+ * ```html
+ * <sng-menu>
+ *   <sng-menu-item>Undo</sng-menu-item>
+ *   <sng-menu-item>Redo</sng-menu-item>
+ *   <sng-menu-separator />
+ *   <sng-menu-item>Cut</sng-menu-item>
+ *   <sng-menu-item>Copy</sng-menu-item>
+ * </sng-menu>
+ * ```
+ */
+@Component({
+  selector: 'sng-menu-separator',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  host: {
+    'class': 'block bg-border -mx-1 my-1 h-px',
+    'role': 'separator',
+  },
+  template: '',
+})
+export class SngMenuSeparator {}

package/src/lib/menu/sng-menu-shortcut.ts

@@ -0,0 +1,25 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+
+/**
+ * Displays a shortcut hint aligned to the right side of a menu item.
+ *
+ * @example
+ * ```html
+ * <sng-menu>
+ *   <sng-menu-item>
+ *     Save
+ *     <sng-menu-shortcut>Ctrl+S</sng-menu-shortcut>
+ *   </sng-menu-item>
+ * </sng-menu>
+ * ```
+ */
+@Component({
+  selector: 'sng-menu-shortcut',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  host: {
+    'class': 'ml-auto text-xs tracking-widest text-muted-foreground',
+  },
+  template: `<ng-content />`,
+})
+export class SngMenuShortcut {}

package/src/lib/menu/sng-menu-sub-content.ts

@@ -0,0 +1,267 @@
+import {
+  Component,
+  ChangeDetectionStrategy,
+  ViewEncapsulation,
+  input,
+  computed,
+  inject,
+  Injector,
+  effect,
+  contentChildren,
+  forwardRef,
+  TemplateRef,
+  viewChild,
+  ViewContainerRef,
+  OnDestroy,
+  afterNextRender,
+} from '@angular/core';
+import { Overlay, type OverlayRef, type ConnectedPosition } from '@angular/cdk/overlay';
+import { TemplatePortal } from '@angular/cdk/portal';
+import { cn } from './cn';
+import { SNG_MENU_PANEL, type MenuPanel, animateOverlayClose, focusMenuContent } from './sng-menu-tokens';
+import { SngMenu } from './sng-menu';
+import { SngMenuSub, type MenuContentCoordinator } from './sng-menu-sub';
+
+const SUB_POSITIONS: ConnectedPosition[] = [
+  { originX: 'end', originY: 'top', overlayX: 'start', overlayY: 'top', offsetX: 4 },
+  { originX: 'start', originY: 'top', overlayX: 'end', overlayY: 'top', offsetX: -4 },
+];
+
+/**
+ * Container for submenu items. Uses CDK Overlay for viewport-aware positioning.
+ *
+ * @example
+ * ```html
+ * <sng-menu-sub>
+ *   <sng-menu-sub-trigger>More</sng-menu-sub-trigger>
+ *   <sng-menu-sub-content>
+ *     <sng-menu-item>Nested Item 1</sng-menu-item>
+ *   </sng-menu-sub-content>
+ * </sng-menu-sub>
+ * ```
+ */
+@Component({
+  selector: 'sng-menu-sub-content',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  providers: [
+    { provide: SNG_MENU_PANEL, useExisting: SngMenuSubContent },
+  ],
+  styles: [`
+    .sng-menu-sub-panel[data-state=open] { animation: sng-menu-sub-enter 150ms ease both; }
+    .sng-menu-sub-panel[data-state=closed] { animation: sng-menu-sub-exit 150ms ease both; }
+    @keyframes sng-menu-sub-enter { from { opacity: 0; transform: scale(0.95) translateX(-0.5rem); } }
+    @keyframes sng-menu-sub-exit { to { opacity: 0; transform: scale(0.95); } }
+  `],
+  template: `
+    <ng-template #subTemplate>
+      <div
+        [class]="contentClasses()"
+        [attr.data-state]="parentSub.isOpen() ? 'open' : 'closed'"
+        role="menu"
+        tabindex="-1">
+        <ng-content />
+      </div>
+    </ng-template>
+  `,
+})
+export class SngMenuSubContent implements MenuPanel, MenuContentCoordinator, OnDestroy {
+  /** @internal */
+  parentSub = inject(SngMenuSub);
+  private rootPanel = inject(SNG_MENU_PANEL, { skipSelf: true });
+  private rootMenu = inject(SngMenu);
+  private overlay = inject(Overlay);
+  private injector = inject(Injector);
+  private viewContainerRef = inject(ViewContainerRef);
+
+  private subTemplate = viewChild<TemplateRef<unknown>>('subTemplate');
+  private overlayRef: OverlayRef | null = null;
+  private _closing = false;
+  private _hoverEnterHandler: ((e: Event) => void) | null = null;
+  private _hoverLeaveHandler: ((e: Event) => void) | null = null;
+
+  /** @internal Track nested submenus for coordination. */
+  private nestedSubs = contentChildren(forwardRef(() => SngMenuSub), { descendants: true });
+
+  /** @internal Currently open nested submenu. */
+  private openSubmenu: SngMenuSub | null = null;
+
+  /** Custom CSS classes. */
+  class = input<string>('');
+
+  /** Inherits closeOnSelect from the root menu. */
+  get closeOnSelect() { return this.rootPanel.closeOnSelect; }
+
+  contentClasses = computed(() =>
+    cn(
+      'z-[9999] min-w-[8rem] rounded-md border border-border bg-popover py-1 text-popover-foreground shadow-lg',
+      'flex flex-col sng-menu-sub-panel',
+      this.class()
+    )
+  );
+
+  constructor() {
+    // Register with root menu for synchronous cleanup on close
+    this.rootMenu._subContentOverlays.add(this);
+
+    // Register cascade-dispose callback so parent can synchronously tear us down
+    this.parentSub._contentDispose = () => this._cascadeDispose();
+
+    // Register as coordinator for nested submenus
+    effect(() => {
+      const subs = this.nestedSubs();
+      subs.forEach(sub => { sub._parentCoordinator = this; });
+    });
+
+    // React to parent sub open/close
+    effect(() => {
+      const isOpen = this.parentSub.isOpen();
+      if (isOpen) {
+        this.openOverlay();
+      } else {
+        this.closeOverlay();
+      }
+    });
+  }
+
+  /** Close the entire menu tree. */
+  close() {
+    this.rootPanel.close();
+  }
+
+  /** @internal */
+  _requestSubOpen(sub: SngMenuSub): void {
+    if (this.openSubmenu && this.openSubmenu !== sub) {
+      // Cascade-dispose any nested overlays synchronously before closing the sibling
+      this.openSubmenu._contentDispose?.();
+      this.openSubmenu.closeImmediate();
+    }
+    this.openSubmenu = sub;
+  }
+
+  /** @internal */
+  _notifySubClosed(sub: SngMenuSub): void {
+    if (this.openSubmenu === sub) {
+      this.openSubmenu = null;
+    }
+  }
+
+  /** @internal */
+  _shouldOpenImmediately(sub: SngMenuSub): boolean {
+    return this.openSubmenu !== null && this.openSubmenu !== sub;
+  }
+
+  /** @internal Reset all state when root menu closes. */
+  _resetOnMenuClose() {
+    this.parentSub._reset();
+    if (this.openSubmenu) {
+      this.openSubmenu._contentDispose?.();
+      this.openSubmenu._reset();
+      this.openSubmenu = null;
+    }
+    this._closing = false;
+    this._disposeOverlay();
+  }
+
+  /** @internal Cancel pending close on this submenu and all ancestor submenus. */
+  _keepAncestorChainOpen() {
+    this.parentSub.scheduleOpen();
+    const coord = this.parentSub._parentCoordinator;
+    if (coord instanceof SngMenuSubContent) {
+      coord._keepAncestorChainOpen();
+    }
+  }
+
+  /** @internal Synchronously tear down this overlay and all nested child overlays. */
+  _cascadeDispose() {
+    // Cascade down: dispose any open nested submenu's overlay first
+    if (this.openSubmenu) {
+      this.openSubmenu._contentDispose?.();
+      this.openSubmenu._reset();
+      this.openSubmenu = null;
+    }
+    this._closing = false;
+    this._disposeOverlay();
+  }
+
+  ngOnDestroy() {
+    this.parentSub._contentDispose = null;
+    this.rootMenu._subContentOverlays.delete(this);
+    // Force-dispose: bypass _closing guard since the component is being destroyed
+    this._closing = false;
+    this._disposeOverlay();
+  }
+
+  private openOverlay() {
+    const template = this.subTemplate();
+    const triggerEl = this.parentSub._subTrigger()?._elementRef.nativeElement;
+    if (!template || !triggerEl) return;
+
+    this._disposeOverlay();
+
+    const positionStrategy = this.overlay.position()
+      .flexibleConnectedTo(triggerEl)
+      .withPositions(SUB_POSITIONS)
+      .withPush(true)
+      .withViewportMargin(8);
+
+    this.overlayRef = this.overlay.create({
+      positionStrategy,
+      scrollStrategy: this.overlay.scrollStrategies.reposition(),
+    });
+
+    const portal = new TemplatePortal(template, this.viewContainerRef);
+    this.overlayRef.attach(portal);
+
+    // Keep submenu open when mouse is over the overlay panel
+    const overlayEl = this.overlayRef.overlayElement;
+    this._hoverEnterHandler = () => this._keepAncestorChainOpen();
+    this._hoverLeaveHandler = (e: Event) => {
+      const related = (e as MouseEvent).relatedTarget as HTMLElement | null;
+      // If mouse went back to the parent sng-menu-sub, don't close
+      if (related?.closest('sng-menu-sub') === this.parentSub._hostEl) return;
+      // If mouse went to a deeper nested submenu panel, don't close
+      if (related?.closest('.sng-menu-sub-panel')) return;
+      this.parentSub.scheduleClose();
+    };
+    overlayEl.addEventListener('mouseenter', this._hoverEnterHandler);
+    overlayEl.addEventListener('mouseleave', this._hoverLeaveHandler);
+
+    afterNextRender(() => {
+      const panel = this.overlayRef?.overlayElement.querySelector('[role="menu"]') as HTMLElement | null;
+      if (panel) {
+        focusMenuContent(panel);
+      }
+    }, { injector: this.injector });
+  }
+
+  private closeOverlay() {
+    if (!this.overlayRef || this._closing) return;
+    this._closing = true;
+    // Synchronously cascade-close all nested overlays before animating this one
+    if (this.openSubmenu) {
+      this.openSubmenu._contentDispose?.();
+      this.openSubmenu._reset();
+      this.openSubmenu = null;
+    }
+    animateOverlayClose(this.overlayRef, () => this._disposeOverlay());
+  }
+
+  /** @internal */ _disposeOverlay() {
+    this._closing = false;
+    if (this.overlayRef) {
+      const overlayEl = this.overlayRef.overlayElement;
+      if (this._hoverEnterHandler) {
+        overlayEl.removeEventListener('mouseenter', this._hoverEnterHandler);
+        this._hoverEnterHandler = null;
+      }
+      if (this._hoverLeaveHandler) {
+        overlayEl.removeEventListener('mouseleave', this._hoverLeaveHandler);
+        this._hoverLeaveHandler = null;
+      }
+      this.overlayRef.dispose();
+      this.overlayRef = null;
+    }
+  }
+}

package/src/lib/menu/sng-menu-sub-trigger.ts

@@ -0,0 +1,68 @@
+import {
+  Component,
+  ChangeDetectionStrategy,
+  ViewEncapsulation,
+  ElementRef,
+  input,
+  inject,
+  computed,
+} from '@angular/core';
+import { cn } from './cn';
+
+/**
+ * Trigger element for a submenu. Displays a chevron icon indicating
+ * a nested menu is available on hover.
+ *
+ * @example
+ * ```html
+ * <sng-menu-sub>
+ *   <sng-menu-sub-trigger>Share</sng-menu-sub-trigger>
+ *   <sng-menu-sub-content>
+ *     <sng-menu-item>Email</sng-menu-item>
+ *   </sng-menu-sub-content>
+ * </sng-menu-sub>
+ * ```
+ */
+@Component({
+  selector: 'sng-menu-sub-trigger',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    '[class]': 'hostClasses()',
+    'role': 'menuitem',
+    'aria-haspopup': 'menu',
+    'tabindex': '0',
+  },
+  template: `
+    <ng-content />
+    <svg
+      class="ml-auto h-4 w-4"
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+    >
+      <path d="m9 18 6-6-6-6"/>
+    </svg>
+  `,
+})
+export class SngMenuSubTrigger {
+  /** @internal Element ref for overlay positioning. */
+  _elementRef = inject(ElementRef);
+
+  /** Custom CSS classes. */
+  class = input<string>('');
+
+  hostClasses = computed(() =>
+    cn(
+      'flex cursor-default select-none items-center justify-between gap-4 whitespace-nowrap rounded-sm px-2 py-1.5 text-sm outline-none',
+      'hover:bg-accent hover:text-accent-foreground',
+      'focus-visible:bg-accent focus-visible:text-accent-foreground',
+      this.class()
+    )
+  );
+}

package/src/lib/menu/sng-menu-sub.ts

@@ -0,0 +1,124 @@
+import {
+  Component,
+  ChangeDetectionStrategy,
+  OnDestroy,
+  ElementRef,
+  inject,
+  signal,
+  contentChild,
+} from '@angular/core';
+import { Subscription, timer } from 'rxjs';
+import { SngMenuSubTrigger } from './sng-menu-sub-trigger';
+
+/** Interface for parent content to coordinate sibling submenus. */
+export interface MenuContentCoordinator {
+  _requestSubOpen(sub: SngMenuSub): void;
+  _notifySubClosed(sub: SngMenuSub): void;
+  _shouldOpenImmediately(sub: SngMenuSub): boolean;
+}
+
+/**
+ * Container for a nested submenu within a menu.
+ * Opens on hover and contains a trigger and content.
+ *
+ * @example
+ * ```html
+ * <sng-menu-sub>
+ *   <sng-menu-sub-trigger>More Options</sng-menu-sub-trigger>
+ *   <sng-menu-sub-content>
+ *     <sng-menu-item>Option A</sng-menu-item>
+ *   </sng-menu-sub-content>
+ * </sng-menu-sub>
+ * ```
+ */
+@Component({
+  selector: 'sng-menu-sub',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  host: {
+    'class': 'block relative',
+    '[attr.data-state]': 'isOpen() ? "open" : "closed"',
+    '(mouseenter)': 'scheduleOpen()',
+    '(mouseleave)': 'onMouseLeave($event)',
+  },
+  template: `<ng-content />`,
+})
+export class SngMenuSub implements OnDestroy {
+  private hoverTimerSubscription: Subscription | null = null;
+
+  /** @internal Host element reference. */
+  _hostEl = inject(ElementRef).nativeElement;
+
+  /** @internal The sub-trigger child for positioning. */
+  _subTrigger = contentChild(SngMenuSubTrigger);
+
+  /** @internal Set by parent content for sibling coordination. */
+  _parentCoordinator: MenuContentCoordinator | null = null;
+
+  /** @internal Dispose callback set by content for cascade close. */
+  _contentDispose: (() => void) | null = null;
+
+  isOpen = signal(false);
+
+  open() {
+    if (this.isOpen()) return;
+    this.clearTimeout();
+    this.isOpen.set(true);
+    this._parentCoordinator?._requestSubOpen(this);
+  }
+
+  close() {
+    if (!this.isOpen()) return;
+    this.isOpen.set(false);
+    this._parentCoordinator?._notifySubClosed(this);
+  }
+
+  /** Immediately close without animation — used when switching between submenus. */
+  closeImmediate() {
+    this.clearTimeout();
+    this.isOpen.set(false);
+  }
+
+  scheduleOpen() {
+    this.clearTimeout();
+    if (this._parentCoordinator?._shouldOpenImmediately(this)) {
+      this.open();
+    } else {
+      this.hoverTimerSubscription = timer(100).subscribe(() => {
+        this.hoverTimerSubscription = null;
+        this.open();
+      });
+    }
+  }
+
+  /** @internal */
+  onMouseLeave(event: MouseEvent) {
+    const related = event.relatedTarget as HTMLElement | null;
+    // If mouse moved into the submenu overlay panel, don't close
+    if (related?.closest('.sng-menu-sub-panel')) return;
+    this.scheduleClose();
+  }
+
+  scheduleClose() {
+    this.clearTimeout();
+    this.hoverTimerSubscription = timer(100).subscribe(() => {
+      this.hoverTimerSubscription = null;
+      this.close();
+    });
+  }
+
+  /** @internal Reset all state when root menu closes. */
+  _reset() {
+    this.clearTimeout();
+    this.isOpen.set(false);
+  }
+
+  private clearTimeout() {
+    this.hoverTimerSubscription?.unsubscribe();
+    this.hoverTimerSubscription = null;
+  }
+
+  ngOnDestroy() {
+    this.clearTimeout();
+  }
+}