agnosticui-core 2.0.0-alpha.2

package/src/components/Sidebar/core/_Sidebar.ts

@@ -0,0 +1,833 @@
+import { LitElement, html, css } from 'lit';
+import { property } from 'lit/decorators.js';
+import type { PropertyValues } from 'lit';
+
+/**
+ * Event to notify if the sidebar is open or closed
+ */
+export interface AgSidebarToggleEventDetail {
+  open: boolean;
+}
+
+/**
+ * Event to notify if the sidebar is collapsed (rail mode) or expanded (desktop mode)
+ */
+export interface AgSidebarCollapseEventDetail {
+  collapsed: boolean;
+}
+
+/**
+ * Prop definitions
+ */
+export interface AgSidebarProps {
+  /** Whether the sidebar is open or closed */
+  open?: boolean;
+  /** Whether the sidebar is collapsed (rail mode) or expanded (desktop mode) */
+  collapsed?: boolean;
+  /** Whether the sidebar is on the left or right */
+  position?: 'left' | 'right';
+  /** ARIA label for the sidebar */
+  ariaLabel?: string;
+
+  /** Variant of the sidebar */
+  variant?: 'default' | 'bordered' | 'elevated';
+  /** Whether to disable transitions */
+  noTransition?: boolean;
+  /** Width of the sidebar */
+  width?: string;
+  /** Whether to disable compact/rail mode. When true, sidebar is either full-width or hidden (no intermediate collapsed state) */
+  disableCompactMode?: boolean;
+  /** Whether to show the mobile toggle button */
+  showMobileToggle?: boolean;
+  /** Position of the mobile toggle button. Default: top-left */
+  mobileTogglePosition?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+  /** Whether to show the header toggle button */
+  showHeaderToggle?: boolean;
+  /** Callback function to handle toggle open/close events */
+  onToggle?: (event: AgSidebarToggleEvent) => void;
+  /** Callback function to handle expanded/collapsed events */
+  onCollapse?: (event: AgSidebarCollapseEvent) => void;
+}
+
+/**
+ * Event type aliases
+ */
+export type AgSidebarToggleEvent = CustomEvent<AgSidebarToggleEventDetail>;
+export type AgSidebarCollapseEvent = CustomEvent<AgSidebarCollapseEventDetail>;
+
+/**
+ * AgSidebar - A self-contained, accessible sidebar navigation component.
+ * 
+ * Provides a responsive sidebar with mobile overlay and desktop rail/collapse modes.
+ * Supports customizable header, navigation content, and footer sections with full
+ * keyboard navigation and focus management.
+ * 
+ * @element ag-sidebar
+ * 
+ * @slot header - Header content area for logo, title, or actions. When `collapsed` is true on desktop, content fades out but slot remains in DOM for accessibility. If provided, overrides composable header slots (header-start, header-end, header-toggle).
+ * @slot header-start - Left side of header for logo or title. Hidden when sidebar is collapsed. Ignored if `header` slot has content.
+ * @slot header-end - Right side of header for action buttons. Always visible, even when collapsed. Ignored if `header` slot has content.
+ * @slot header-toggle - Specific slot for custom toggle button in header. Auto-positioned at the end. Ignored if `header` slot has content.
+ * @slot - Default slot for main navigation content. Use `<ag-sidebar-nav>` component for structured navigation with proper aria attributes.
+ * @slot footer - Footer content area for copyright info, version numbers, or help links. Remains visible when sidebar is collapsed, content should be icon-only or very compact.
+ * @slot ag-toggle-icon - Customizes the floating mobile toggle button icon and header toggle icon. Must be an SVG element sized 18x18px. Falls back to built-in panel icon if not provided.
+ * 
+ * @fires ag-sidebar-toggle - Fired when sidebar open/close state changes (mobile overlay). Detail: `{ open: boolean }`
+ * @fires ag-sidebar-collapse - Fired when sidebar expanded/collapsed state changes (desktop rail). Detail: `{ collapsed: boolean }`
+ * 
+ * @csspart ag-sidebar-backdrop - The backdrop overlay shown on mobile when sidebar is open
+ * @csspart ag-sidebar-toggle-button - The floating toggle button shown on mobile (when `show-mobile-toggle` is true)
+ * @csspart ag-sidebar-container - The main sidebar container element (aside)
+ * @csspart ag-sidebar-header - The header section wrapper
+ * @csspart ag-sidebar-header-toggle - The collapse/expand toggle button in header (when `show-header-toggle` is true)
+ * @csspart ag-sidebar-content - The main content scrollable area
+ * @csspart ag-sidebar-footer - The footer section wrapper
+ * 
+ * @cssprop --ag-sidebar-width - Width of expanded sidebar. Default: `18rem`
+ * @cssprop --ag-sidebar-width-collapsed - Width of collapsed sidebar (rail mode). Default: `3rem`
+ * @cssprop --ag-sidebar-padding - Internal padding for content area. Default: `0.5rem`
+ * @cssprop --ag-sidebar-background - Background color of sidebar. Default: `#ffffff`
+ * @cssprop --ag-sidebar-border - Border color. Default: `#e5e7eb`
+ * @cssprop --ag-sidebar-transition-duration - Animation duration for state changes. Default: `200ms`
+ * @cssprop --ag-sidebar-transition-easing - Animation easing function. Default: `ease-in-out`
+ * @cssprop --ag-sidebar-z-index - Z-index for sidebar container on mobile. Default: `1000`
+ * @cssprop --ag-sidebar-backdrop-z-index - Z-index for backdrop overlay on mobile. Default: `999`
+ * @cssprop --ag-sidebar-toggle-z-index - Z-index for floating toggle button. Default: `1001`
+
+ * 
+ * @example
+ * ```html
+ * <ag-sidebar>
+ *   <div slot="header">
+ *     <h1>My App</h1>
+ *   </div>
+ *   
+ *   <ag-sidebar-nav>
+ *     <ag-sidebar-nav-item href="/">Home</ag-sidebar-nav-item>
+ *     <ag-sidebar-nav-item href="/about">About</ag-sidebar-nav-item>
+ *   </ag-sidebar-nav>
+ *   
+ *   <div slot="footer">
+ *     <p>© 2024 Company</p>
+ *   </div>
+ * </ag-sidebar>
+ * ```
+ * 
+ * @example
+ * ```html
+ * <!-- Composable header slots (automatic layout) -->
+ * <ag-sidebar>
+ *   <h2 slot="header-start">My App</h2>
+ *   <button slot="header-end">Settings</button>
+ *   <button slot="header-toggle" @click=${handleToggle}>
+ *     ${PanelIcon()}
+ *   </button>
+ * </ag-sidebar>
+ * ```
+ * 
+ * @example
+ * ```html
+ * <!-- Custom toggle icon -->
+ * <ag-sidebar show-header-toggle>
+ *   <svg slot="ag-toggle-icon" width="18" height="18" viewBox="0 0 18 18">
+ *     <path d="M3 9h12M3 5h12M3 13h12" stroke="currentColor"/>
+ *   </svg>
+ *   <div slot="header">Navigation</div>
+ * </ag-sidebar>
+ * ```
+ */
+export class AgSidebar extends LitElement implements AgSidebarProps {
+  static styles = css`
+    :host {
+      display: block;
+      position: relative;
+      --ag-sidebar-width: 18rem;
+      --ag-sidebar-width-collapsed: 3rem;
+      --ag-sidebar-padding: var(--ag-space-2, 0.5rem);
+      --ag-sidebar-background: var(--ag-background-primary, #ffffff);
+      --ag-sidebar-border: var(--ag-border, #e5e7eb);
+      --ag-sidebar-transition-duration: var(--ag-motion-duration-normal, 200ms);
+      --ag-sidebar-transition-easing: var(--ag-motion-easing-standard, ease-in-out);
+      --ag-sidebar-z-index: var(--ag-z-sidebar, 1000);
+      --ag-sidebar-backdrop-z-index: var(--ag-z-sidebar-backdrop, 999);
+      --ag-sidebar-toggle-z-index: var(--ag-z-sidebar-toggle, 1001);
+
+    }
+
+    .sidebar-container {
+      display: flex;
+      flex-direction: column;
+      height: 100%;
+      background: var(--ag-sidebar-background);
+    }
+    
+    :host([collapsed]) {
+      overflow: visible;
+    }
+      
+    /* Allow popovers to escape sidebar in collapsed mode */
+    :host([collapsed]) .sidebar-content {
+      overflow: visible;
+      /* Center icon button items in the compact sidebar */
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+    }
+
+    /* Set collapsed width globally so it applies before media queries kick in */
+    :host([collapsed]) .sidebar-container {
+      width: var(--ag-sidebar-width-collapsed);
+      overflow: visible;
+    }
+
+    /* Variant: Bordered */
+    :host([variant="bordered"]) .sidebar-container {
+      border-inline-end: 1px solid var(--ag-sidebar-border);
+    }
+    
+    :host([variant="bordered"][position="right"]) .sidebar-container {
+      border-inline-end: none;
+      border-inline-start: 1px solid var(--ag-sidebar-border);
+    }
+
+    /* Variant: Elevated */
+    :host([variant="elevated"]) .sidebar-container {
+      box-shadow: var(--ag-shadow-lg, 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05));
+      z-index: 1;
+      border-inline-end: none;
+    }
+
+    /* No Transition */
+    :host([no-transition]) *,
+    :host([no-transition]) .sidebar-container,
+    :host([no-transition]) .backdrop,
+    :host([no-transition]) .header-content,
+    :host([no-transition]) .toggle-button {
+      transition: none !important;
+    }
+
+    .sidebar-header, .sidebar-footer {
+      padding-block: var(--ag-space-2);
+      padding-inline: var(--ag-space-4);
+      flex-shrink: 0;
+      transition: opacity var(--ag-sidebar-transition-duration) var(--ag-sidebar-transition-easing),
+                  padding var(--ag-sidebar-transition-duration) var(--ag-sidebar-transition-easing);
+    }
+    .sidebar-header {
+      border-bottom: 1px solid var(--ag-sidebar-border);
+    }
+
+    .sidebar-footer {
+      border-top: 1px solid var(--ag-sidebar-border);
+      overflow: hidden;
+      white-space: nowrap;
+    }
+
+    /* Collapsed state: fade out header content and footer */
+    :host([collapsed]) .header-content,
+    :host([collapsed]) .sidebar-footer {
+      opacity: 0;
+      pointer-events: none;
+    }
+    
+    /* Composable header layout system */
+    .header-layout {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: var(--ag-space-2);
+      width: 100%;
+    }
+    :host([collapsed]) .header-layout {
+      gap: unset;
+    }
+
+    .header-start {
+      flex: 1;
+      min-width: 0; /* Allow text truncation */
+      overflow: hidden;
+      transition: opacity var(--ag-sidebar-transition-duration) var(--ag-sidebar-transition-easing);
+    }
+
+    .header-end {
+      display: flex;
+      align-items: center;
+      gap: var(--ag-space-2);
+      flex-shrink: 0;
+      transition: opacity var(--ag-sidebar-transition-duration) var(--ag-sidebar-transition-easing);
+    }
+
+    /* Collapsed state: hide start content and header-end-content, but keep ag-header-toggle visible */
+    :host([collapsed]) .header-start {
+      opacity: 0;
+      pointer-events: none;
+    }
+
+    :host([collapsed]) .header-end-content {
+      display: none;
+    }
+
+    :host([collapsed]) .header-layout {
+      justify-content: center;
+    }
+    
+    /* Header layout wrapper for showHeaderToggle. Base wrapper - no gap */
+    .header-wrapper {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      width: 100%;
+    }
+
+    /* Gap only when expanded */
+    :host(:not([collapsed])) .header-wrapper {
+      gap: var(--ag-space-2);
+    }
+
+    .header-content {
+      flex: 1;
+      min-width: 0;
+      opacity: 1;
+      transition: opacity var(--ag-sidebar-transition-duration) var(--ag-sidebar-transition-easing);
+    }
+    
+    /* Collapsed state: fade out header content */
+    :host([collapsed]) .header-content {
+      display: none;
+    }
+    
+    /* Collapsed state: center the toggle button */
+    :host([collapsed]) .header-wrapper {
+      justify-content: center;
+    }
+    
+    /* Built-in header toggle button styling */
+    .header-toggle-button {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      width: var(--ag-space-7);
+      height: var(--ag-space-7);
+      border: 1px solid var(--ag-border-subtle);
+      border-radius: 0.375rem;
+      background: var(--ag-background-secondary);
+      color: var(--ag-text-primary);
+      cursor: pointer;
+      transition: background 0.15s;
+      flex-shrink: 0;
+    }
+    
+    .header-toggle-button:hover {
+      background: var(--ag-background-tertiary);
+    }
+    
+    .header-toggle-button:active {
+      transform: scale(0.95);
+    }
+    
+    .header-toggle-button svg {
+      width: 18px;
+      height: 18px;
+      fill: currentColor;
+    }
+    
+
+
+    .sidebar-content {
+      flex: 1;
+      overflow-y: auto;
+      padding: var(--ag-sidebar-padding);
+    }
+
+    .backdrop {
+      display: none;
+    }
+
+    .toggle-button {
+      display: none;
+    }
+
+    /* ===========================================
+       MOBILE: Below breakpoint
+       Overlay drawer that slides in/out
+       =========================================== */
+    @media (max-width: 1023px) {
+      .sidebar-container {
+        position: fixed;
+        top: 0;
+        bottom: 0;
+        z-index: var(--ag-sidebar-z-index);
+        transition: transform var(--ag-sidebar-transition-duration) var(--ag-sidebar-transition-easing);
+      }
+      
+      /* Full width in mobile when NOT collapsed */
+      :host(:not([collapsed])) .sidebar-container {
+        width: var(--ag-sidebar-width);
+      }
+      
+      :host([position="left"]) .sidebar-container {
+        inset-inline-start: 0;
+        transform: translateX(-100%);
+      }
+      
+      :host([position="right"]) .sidebar-container {
+        inset-inline-end: 0;
+        transform: translateX(100%);
+      }
+
+      /* RTL Support */
+      :host-context([dir="rtl"]):host([position="left"]) .sidebar-container {
+        transform: translateX(100%);
+      }
+      :host-context([dir="rtl"]):host([position="right"]) .sidebar-container {
+        transform: translateX(-100%);
+      }
+      
+      :host([open]) .sidebar-container {
+        transform: translateX(0);
+      }
+
+      .backdrop {
+        position: fixed;
+        inset: 0;
+        background: rgba(0, 0, 0, 0.5);
+        z-index: var(--ag-sidebar-backdrop-z-index);
+        opacity: 0;
+        pointer-events: none;
+        transition: opacity var(--ag-sidebar-transition-duration) var(--ag-sidebar-transition-easing);
+      }
+
+      :host([open]) .backdrop {
+        display: block;
+        opacity: 1;
+        pointer-events: auto;
+      }
+    }
+
+    /* ===========================================
+       GLOBAL: Toggle Button Styles
+       Shared between mobile overlay and desktop disable-compact-mode
+       =========================================== */
+    :host([show-mobile-toggle]) .toggle-button {
+      display: flex;
+      position: fixed;
+      width: var(--ag-space-8);
+      height: var(--ag-space-8);
+      border-radius: 50%;
+      background: var(--ag-sidebar-background);
+      border: 1px solid var(--ag-sidebar-border);
+      box-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
+      cursor: pointer;
+      z-index: var(--ag-sidebar-toggle-z-index);
+      align-items: center;
+      justify-content: center;
+      transition: opacity var(--ag-sidebar-transition-duration) var(--ag-sidebar-transition-easing);
+      
+      /* Default hidden on desktop unless disable-compact-mode is active */
+      opacity: 0;
+      pointer-events: none;
+    }
+
+    /* Show toggle on mobile */
+    @media (max-width: 1023px) {
+      :host([show-mobile-toggle]) .toggle-button {
+        opacity: 1;
+        pointer-events: auto;
+      }
+    }
+
+    /* Show toggle on desktop ONLY if disable-compact-mode is active */
+    @media (min-width: 1024px) {
+      :host([disable-compact-mode][show-mobile-toggle]) .toggle-button {
+        opacity: 1;
+        pointer-events: auto;
+      }
+    }
+
+    /* Always hide toggle when sidebar is open - consumer's header button takes over */
+    :host([show-mobile-toggle][open]) .toggle-button {
+      opacity: 0 !important;
+      pointer-events: none !important;
+    }
+
+    .toggle-button:hover {
+      background: var(--ag-background-hover, #f3f4f6);
+    }
+
+    .toggle-button:active {
+      transform: scale(0.95);
+    }
+
+    .toggle-button svg {
+      width: 18px;
+      height: 18px;
+      fill: currentColor;
+    }
+    /* Ensure consumer-provided slotted SVGs match the fallback sizing */
+    .toggle-button ::slotted(svg) {
+      width: 18px;
+      height: 18px;
+      fill: currentColor;
+      display: block;
+    }
+
+    .toggle-button.top-left { top: var(--ag-space-4); inset-inline-start: var(--ag-space-4); }
+    .toggle-button.top-right { top: var(--ag-space-4); inset-inline-end: var(--ag-space-4); }
+    .toggle-button.bottom-left { bottom: var(--ag-space-4); inset-inline-start: var(--ag-space-4); }
+    .toggle-button.bottom-right { bottom: var(--ag-space-4); inset-inline-end: var(--ag-space-4); }
+
+    /* ===========================================
+       DESKTOP: At/above breakpoint
+       Static sidebar with expand/collapse
+       =========================================== */
+    @media (min-width: 1024px) {
+      .sidebar-container {
+        position: relative;
+      }
+      
+      :host(:not([collapsed])) .sidebar-container {
+        width: var(--ag-sidebar-width);
+        transition: width var(--ag-sidebar-transition-duration) var(--ag-sidebar-transition-easing);
+      }
+      
+      :host([collapsed]) .sidebar-container {
+        width: var(--ag-sidebar-width-collapsed);
+        transition: width var(--ag-sidebar-transition-duration) var(--ag-sidebar-transition-easing);
+      }
+      
+      /* When compact mode is disabled, ignore collapsed state on desktop */
+      :host([disable-compact-mode]) .sidebar-container,
+      :host([disable-compact-mode][collapsed]) .sidebar-container {
+        position: fixed;
+        inset-inline-start: 0;
+        top: 0;
+        height: 100%;
+        width: var(--ag-sidebar-width);
+        transform: translateX(0);
+        transition: transform var(--ag-sidebar-transition-duration) var(--ag-sidebar-transition-easing);
+      }
+      
+      :host([disable-compact-mode]:not([open])) .sidebar-container,
+      :host([disable-compact-mode][collapsed]:not([open])) .sidebar-container {
+        transform: translateX(-100%);
+      }
+      
+      :host([disable-compact-mode][position="right"]:not([open])) .sidebar-container,
+      :host([disable-compact-mode][collapsed][position="right"]:not([open])) .sidebar-container {
+        transform: translateX(100%);
+      }
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+      .sidebar-container, .backdrop, .toggle-button, .header-content {
+        transition: none !important;
+      }
+    }
+  `;
+
+  @property({ type: Boolean, reflect: true }) declare open: boolean;
+  @property({ type: Boolean, reflect: true }) declare collapsed: boolean;
+  @property({ type: String, reflect: true }) declare position: 'left' | 'right';
+  @property({ type: String, attribute: 'aria-label' }) declare ariaLabel: string;
+
+  @property({ type: String, reflect: true }) declare variant: 'default' | 'bordered' | 'elevated';
+  @property({ type: Boolean, attribute: 'no-transition', reflect: true }) declare noTransition: boolean;
+  @property({ type: String }) declare width?: string;
+  @property({ type: Boolean, attribute: 'disable-compact-mode', reflect: true }) declare disableCompactMode: boolean;
+  @property({ type: Boolean, attribute: 'show-mobile-toggle', reflect: true }) declare showMobileToggle: boolean;
+  @property({ type: String, attribute: 'mobile-toggle-position' }) declare mobileTogglePosition: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+  @property({ type: Boolean, attribute: 'show-header-toggle', reflect: true }) declare showHeaderToggle: boolean;
+  @property({ attribute: false }) declare onToggle?: (event: AgSidebarToggleEvent) => void;
+  @property({ attribute: false }) declare onCollapse?: (event: AgSidebarCollapseEvent) => void;
+
+  constructor() {
+    super();
+    this.open = false;
+    this.collapsed = false;
+    this.position = 'left';
+    this.ariaLabel = 'Navigation';
+
+    this.variant = 'default';
+    this.noTransition = false;
+    this.width = undefined;
+    this.disableCompactMode = false;
+    this.showMobileToggle = true;
+    this.mobileTogglePosition = 'top-left';
+    this.showHeaderToggle = false;
+  }
+
+  private _mainContentRef?: HTMLElement;
+
+  /**
+   * Checks if the current viewport width is below the mobile breakpoint.
+   * 
+   * This helper ensures consistent viewport detection across the component.
+   * Called on-demand rather than using resize listeners to avoid memory overhead.
+   * 
+   * @returns true if viewport width is less than breakpoint, false otherwise
+   * @private
+   */
+  private _isMobileViewport(): boolean {
+    return window.innerWidth < 1024;
+  }
+
+  /**
+   * Toggle the collapsed state (desktop rail mode)
+   */
+  public toggleCollapse() {
+    this.collapsed = !this.collapsed;
+    this._dispatchCollapseEvent();
+  }
+
+  /**
+   * Intelligent toggle that handles both mobile and desktop contexts.
+   * 
+   * **Behavior:**
+   * - Mobile (< breakpoint) + sidebar open: closes the sidebar overlay
+   * - Desktop (>= breakpoint): toggles collapsed state (rail mode)
+   * - Mobile (< breakpoint) + sidebar closed: toggles collapsed state
+   * 
+   * **When to use:**
+   * Use this method in custom header buttons when you want the sidebar to close
+   * on mobile when it's already open (dismissing the overlay), but toggle
+   * collapsed state on desktop or when closed on mobile.
+   * 
+   * **Comparison with built-in toggle:**
+   * - Built-in `showHeaderToggle`: Always toggles collapsed state (never closes on mobile)
+   * - `toggleResponsive()`: Closes overlay on mobile when open, otherwise toggles collapsed
+   * 
+   * **Resize awareness:**
+   * Checks viewport width on each invocation, ensuring correct behavior even
+   * after window resizes without requiring resize event listeners.
+   * 
+   * @example
+   * ```html
+   * <ag-sidebar id="sidebar">
+   *   <button slot="header" @click=${() => document.getElementById('sidebar').toggleResponsive()}>
+   *     Toggle
+   *   </button>
+   * </ag-sidebar>
+   * ```
+   * 
+   * @example
+   * ```typescript
+   * // In Lit component
+   * const sidebar = this.shadowRoot.querySelector('ag-sidebar');
+   * sidebar.toggleResponsive();
+   * ```
+   */
+  public toggleResponsive(): void {
+    if (this.disableCompactMode) {
+      // When compact mode is disabled, only toggle open/close
+      this.open = !this.open;
+      this._dispatchToggleEvent();
+    } else if (this._isMobileViewport() && this.open) {
+      // Mobile + open: close the overlay
+      this.open = false;
+      this._dispatchToggleEvent();
+    } else {
+      // Desktop or mobile closed: toggle collapsed state
+      this.collapsed = !this.collapsed;
+      this._dispatchCollapseEvent();
+    }
+  }
+
+  override connectedCallback() {
+    super.connectedCallback();
+  }
+
+  override disconnectedCallback() {
+    super.disconnectedCallback();
+    document.removeEventListener('keydown', this._handleKeydown);
+  }
+
+  override willUpdate(changedProperties: PropertyValues) {
+    if (changedProperties.has('width')) {
+      if (this.width) {
+        this.style.setProperty('--ag-sidebar-width', this.width);
+      } else {
+        this.style.removeProperty('--ag-sidebar-width');
+      }
+    }
+
+    if (changedProperties.has('open')) {
+      if (this.open) {
+        document.addEventListener('keydown', this._handleKeydown);
+        this.updateComplete.then(() => this._trapFocus());
+      } else {
+        document.removeEventListener('keydown', this._handleKeydown);
+        this._releaseFocus();
+      }
+    }
+  }
+
+  private _handleBackdropClick = () => {
+    this.open = false;
+    this._dispatchToggleEvent();
+  };
+
+  private _handleToggleClick = () => {
+    this.open = !this.open;
+    this._dispatchToggleEvent();
+  };
+
+  private _handleHeaderToggleClick = () => {
+    if (this.disableCompactMode) {
+      // When compact mode is disabled, toggle open/close instead of collapsed state
+      this.open = !this.open;
+      this._dispatchToggleEvent();
+    } else {
+      // Normal mode: toggles collapsed state (rail mode)
+      // On mobile when open, this collapses to rail mode while keeping overlay open
+      this.collapsed = !this.collapsed;
+      this._dispatchCollapseEvent();
+    }
+  };
+
+  private _handleKeydown = (event: KeyboardEvent) => {
+    if (event.key === 'Escape' && this.open) {
+      event.preventDefault();
+      this.open = false;
+      this._dispatchToggleEvent();
+    }
+  };
+
+  private _dispatchToggleEvent() {
+    const event = new CustomEvent<AgSidebarToggleEventDetail>('ag-sidebar-toggle', {
+      detail: { open: this.open },
+      bubbles: true, composed: true,
+    });
+    this.dispatchEvent(event);
+    this.onToggle?.(event);
+  }
+
+  private _dispatchCollapseEvent() {
+    const event = new CustomEvent<AgSidebarCollapseEventDetail>('ag-sidebar-collapse', {
+      detail: { collapsed: this.collapsed },
+      bubbles: true, composed: true,
+    });
+    this.dispatchEvent(event);
+    this.onCollapse?.(event);
+  }
+
+  private _findMainContent(): HTMLElement | null {
+    return (this.closest('main') || this.parentElement?.querySelector('main') || document.querySelector('main') || document.body);
+  }
+
+  private _trapFocus() {
+    const mainContent = this._findMainContent();
+    if (mainContent && mainContent !== this && !mainContent.contains(this)) {
+      mainContent.setAttribute('inert', '');
+      this._mainContentRef = mainContent;
+    }
+    this.updateComplete.then(() => {
+      const firstFocusable = this.shadowRoot?.querySelector('button:not([disabled]), a[href], input:not([disabled]), [tabindex]:not([tabindex="-1"])') as HTMLElement;
+      firstFocusable?.focus();
+    });
+  }
+
+  private _releaseFocus() {
+    if (this._mainContentRef) {
+      this._mainContentRef.removeAttribute('inert');
+      this._mainContentRef = undefined;
+    }
+  }
+
+  private _handleSlotClick(event: Event) {
+    const path = event.composedPath();
+    const target = path[0] as HTMLElement;
+    const button = target.closest('[aria-expanded]');
+    if (button) {
+      const isExpanded = button.getAttribute('aria-expanded') === 'true';
+      button.setAttribute('aria-expanded', String(!isExpanded));
+
+      const submenu = button.nextElementSibling;
+      if (submenu && submenu.tagName === 'AG-SIDEBAR-NAV-SUBMENU') {
+        if (isExpanded) {
+          submenu.removeAttribute('open');
+        } else {
+          submenu.setAttribute('open', '');
+        }
+      }
+    }
+  }
+
+  private _renderToggleIcon() {
+    // Provide a named slot so consumers can override the floating toggle icon.
+    // Keep the existing SVG as the default fallback.
+    return html`
+      <slot name="ag-toggle-icon">
+        <svg width="18" height="18" viewBox="0 0 18 18" fill="none" xmlns="http://www.w3.org/2000/svg">
+          <path d="M13.7314 1.00488C16.109 1.11926 18 2.98393 18 5.2666V12.7334C18 15.0898 15.9853 17 13.5 17H4.5C2.09247 17 0.126505 15.2074 0.00585938 12.9531L0 12.7334V5.2666C3.72355e-05 2.91022 2.01474 1 4.5 1H13.5L13.7314 1.00488ZM4.5 2.33301C2.79139 2.33301 1.40629 3.6466 1.40625 5.2666V12.7334C1.40629 14.3534 2.79139 15.667 4.5 15.667H4.625V2.33301H4.5ZM6.03125 15.667H13.5C15.2086 15.667 16.5937 14.3534 16.5938 12.7334V5.2666C16.5937 3.6466 15.2086 2.33301 13.5 2.33301H6.03125V15.667Z" fill="currentColor"/>
+        </svg>
+      </slot>
+    `;
+  }
+
+  override render() {
+    return html`
+      <div part="ag-sidebar-backdrop" class="backdrop" @click=${this._handleBackdropClick} aria-hidden="true"></div>
+      
+      <button
+        part="ag-sidebar-toggle-button"
+        class="toggle-button ${this.mobileTogglePosition}"
+        @click=${this._handleToggleClick}
+        aria-label="${this.open ? 'Close sidebar' : 'Open sidebar'}"
+        aria-expanded="${this.open}"
+      >
+        ${this._renderToggleIcon()}
+      </button>
+
+      <aside part="ag-sidebar-container" class="sidebar-container" aria-label=${this.ariaLabel}>
+        <div part="ag-sidebar-header" class="sidebar-header">
+          ${this.showHeaderToggle ? html`
+            <div class="header-wrapper">
+              <div class="header-content">
+                <slot name="ag-header">
+                  <!-- Fallback: if no "header" slot, use composable parts -->
+                  <div class="header-layout">
+                    <div class="header-start">
+                      <slot name="ag-header-start"></slot>
+                    </div>
+                    <div class="header-end">
+                      <slot name="ag-header-end"></slot>
+                    </div>
+                  </div>
+                </slot>
+              </div>
+              <button
+                part="ag-sidebar-header-toggle"
+                class="header-toggle-button"
+                @click=${this._handleHeaderToggleClick}
+                aria-label="${this.collapsed ? 'Expand sidebar' : 'Close sidebar'}"
+              >
+                ${this._renderToggleIcon()}
+              </button>
+            </div>
+          ` : html`
+            <slot name="ag-header">
+              <!-- Fallback: if no "header" slot, use composable parts -->
+              <div class="header-layout">
+                <div class="header-start">
+                  <slot name="ag-header-start"></slot>
+                </div>
+                <div class="header-end">
+                  <div class="header-end-content">
+                    <slot name="ag-header-end"></slot>
+                  </div>
+                  <slot name="ag-header-toggle"></slot>
+                </div>
+              </div>
+            </slot>
+          `}
+        </div>
+        <div part="ag-sidebar-content" class="sidebar-content" @click=${this._handleSlotClick}>
+          <slot></slot>
+        </div>
+        <div part="ag-sidebar-footer" class="sidebar-footer">
+          <slot name="ag-footer"></slot>
+        </div>
+      </aside>
+    `;
+  }
+}