@sondor-technology/sondor-components 1.0.0-1165-initial-setup.11 → 1.0.0

package/src/components/page-layout/page-layout.ts

@@ -1,705 +1,705 @@
-import { LitElement, html, css, PropertyValues } from 'lit';
-import { customElement, property, state } from 'lit/decorators.js';
-import { resetStyles } from '../../styles/reset.js';
-
-export type LayoutVariant = 'app-shell' | 'content-sidebar' | 'single-column' | 'three-column';
-
-@customElement('st-page-layout')
-export class StPageLayout extends LitElement {
-  /**
-   * Defines the structural layout variant to render.
-   */
-  @property({ type: String, reflect: true })
-  variant: LayoutVariant = 'single-column';
-
-  /**
-   * Maximum width for the left sidebar section (e.g., '20rem', '300px').
-   */
-  @property({ type: String, attribute: 'sidebar-width' })
-  sidebarWidth = '';
-
-  /**
-   * Maximum width for the right sidebar section (e.g., '16rem', '250px').
-   */
-  @property({ type: String, attribute: 'right-sidebar-width' })
-  rightSidebarWidth = '';
-
-  /**
-   * Optional maximum width for the main content area (e.g., '48rem', '800px').
-   */
-  @property({ type: String, attribute: 'main-max-width' })
-  mainMaxWidth = '';
-
-  /**
-   * When true, expands the main content area to fill 100% of the available width between sidebars.
-   */
-  @property({ type: Boolean, attribute: 'fill-main', reflect: true })
-  fillMain = false;
-
-  @state()
-  private _mobileMenuOpen = false;
-
-  private _touchStartX = 0;
-  private _currentTranslateX = 0;
-  private _isDragging = false;
-
-  override updated(changedProperties: PropertyValues<this>) {
-    super.updated(changedProperties);
-
-    if (changedProperties.has('sidebarWidth')) {
-      if (this.sidebarWidth) {
-        this.style.setProperty('--layout-sidebar-width', this.sidebarWidth);
-      } else {
-        this.style.removeProperty('--layout-sidebar-width');
-      }
-    }
-
-    if (changedProperties.has('rightSidebarWidth')) {
-      if (this.rightSidebarWidth) {
-        this.style.setProperty('--layout-right-sidebar-width', this.rightSidebarWidth);
-      } else {
-        this.style.removeProperty('--layout-right-sidebar-width');
-      }
-    }
-
-    if (changedProperties.has('mainMaxWidth')) {
-      if (this.mainMaxWidth) {
-        this.style.setProperty('--layout-main-max-width', this.mainMaxWidth);
-      } else {
-        this.style.removeProperty('--layout-main-max-width');
-      }
-    }
-  }
-
-  private _toggleMobileMenu = () => {
-    this._mobileMenuOpen = !this._mobileMenuOpen;
-  };
-
-  private _closeMobileMenu = () => {
-    this._mobileMenuOpen = false;
-  };
-
-  // Only close if an actual navigation link/item was clicked
-  private _handleNavClick = (e: MouseEvent) => {
-    const path = e.composedPath();
-    const clickedLink = path.some(node => {
-      const el = node as HTMLElement;
-      return el.tagName === 'A' || el.tagName === 'ST-VERTICAL-NAV-ITEM';
-    });
-
-    if (clickedLink) {
-      this._closeMobileMenu();
-    }
-  };
-
-  private _handleTouchStart = (e: TouchEvent) => {
-    if (window.innerWidth >= 768) return;
-    this._touchStartX = e.touches[0].clientX;
-    this._isDragging = true;
-    const sidebar = e.currentTarget as HTMLElement;
-    sidebar.style.transition = 'none';
-  };
-
-  private _handleTouchMove = (e: TouchEvent) => {
-    if (!this._isDragging || window.innerWidth >= 768) return;
-    const currentX = e.touches[0].clientX;
-    const diff = currentX - this._touchStartX;
-    const sidebar = e.currentTarget as HTMLElement;
-
-    if (diff < 0) {
-      this._currentTranslateX = diff;
-      sidebar.style.transform = `translateX(${diff}px)`;
-    }
-  };
-
-  private _handleTouchEnd = (e: TouchEvent) => {
-    if (!this._isDragging || window.innerWidth >= 768) return;
-    this._isDragging = false;
-    const sidebar = e.currentTarget as HTMLElement;
-    sidebar.style.transition = '';
-
-    if (this._currentTranslateX < -70) {
-      this._closeMobileMenu();
-      sidebar.style.transform = '';
-    } else {
-      sidebar.style.transform = '';
-    }
-    this._currentTranslateX = 0;
-  };
-
-  private _resizeListener = () => {
-    if (window.innerWidth >= 768 && this._mobileMenuOpen) {
-      this._mobileMenuOpen = false;
-    }
-  };
-
-  connectedCallback() {
-    super.connectedCallback();
-    window.addEventListener('resize', this._resizeListener);
-  }
-
-  disconnectedCallback() {
-    super.disconnectedCallback();
-    window.removeEventListener('resize', this._resizeListener);
-  }
-
-  static styles = [
-    resetStyles,
-    css`
-      :host {
-        display: block;
-        box-sizing: border-box;
-        --layout-bg-color: var(--st-color-bg, #ffffff);
-        --layout-surface-color: var(--st-color-surface, #f8fafc);
-        --layout-border-color: var(--st-color-border, #e2e8f0);
-        --layout-sidebar-width: 16rem;
-        --layout-right-sidebar-width: 14rem;
-        --layout-main-max-width: none;
-        --layout-nav-height: 4rem;
-      }
-
-      *, *::before, *::after {
-        box-sizing: inherit;
-      }
-
-      /* ==========================================================
-         Mobile Hamburger Toggle Button Styles
-         ========================================================== */
-      .mobile-menu-btn {
-        display: flex;
-        align-items: center;
-        justify-content: center;
-        background: transparent;
-        border: 1px solid var(--layout-border-color);
-        border-radius: var(--st-radius-sm, 0.375rem);
-        width: 2.25rem;
-        height: 2.25rem;
-        cursor: pointer;
-        color: var(--st-color-text);
-        margin-right: var(--st-spacing-sm);
-        flex-shrink: 0;
-      }
-
-      .mobile-menu-btn svg {
-        width: 1.25rem;
-        height: 1.25rem;
-        stroke: currentColor;
-        stroke-width: 2;
-        stroke-linecap: round;
-        stroke-linejoin: round;
-        fill: none;
-      }
-
-      @media (min-width: 768px) {
-        .mobile-menu-btn {
-          display: none;
-        }
-      }
-
-      /* ==========================================================
-         Mobile Backdrop Overlay
-         ========================================================== */
-      .mobile-backdrop {
-        position: fixed;
-        top: 0;
-        left: 0;
-        width: 100vw;
-        height: 100vh;
-        background-color: rgba(0, 0, 0, 0.5);
-        backdrop-filter: blur(2px);
-        z-index: 1000;
-        display: none;
-      }
-
-      .mobile-backdrop.open {
-        display: block;
-      }
-
-      @media (min-width: 768px) {
-        .mobile-backdrop {
-          display: none !important;
-        }
-      }
-
-      /* ==========================================================
-         Mobile Drawer Header (Only visible < 768px)
-         ========================================================== */
-      .mobile-drawer-header {
-        display: flex;
-        align-items: center;
-        justify-content: space-between;
-        padding: var(--st-spacing-md) var(--st-spacing-lg);
-        border-bottom: 1px solid var(--layout-border-color);
-        flex-shrink: 0;
-      }
-
-      .mobile-drawer-title {
-        font-weight: var(--st-font-weight-bold);
-        font-size: var(--st-font-size-sm);
-        color: var(--st-color-text);
-        text-transform: uppercase;
-        letter-spacing: 0.05em;
-      }
-
-      .mobile-close-btn {
-        background: transparent;
-        border: none;
-        cursor: pointer;
-        color: var(--st-color-text-muted);
-        padding: 0.25rem;
-        display: flex;
-        align-items: center;
-        justify-content: center;
-        border-radius: var(--st-radius-sm, 0.375rem);
-      }
-
-      .mobile-close-btn:hover {
-        color: var(--st-color-text);
-        background-color: var(--st-color-surface-muted, #f1f5f9);
-      }
-
-      .mobile-close-btn svg {
-        width: 1.25rem;
-        height: 1.25rem;
-        stroke: currentColor;
-        stroke-width: 2;
-        stroke-linecap: round;
-        stroke-linejoin: round;
-        fill: none;
-      }
-
-      @media (min-width: 768px) {
-        .mobile-drawer-header {
-          display: none !important;
-        }
-      }
-
-      /* ==========================================================
-         1. App Shell Layout
-         ========================================================== */
-      .layout-app-shell {
-        display: flex;
-        height: 100vh;
-        overflow: hidden;
-        background-color: var(--layout-surface-color);
-      }
-      
-      .app-shell-sidebar {
-        display: none;
-        border-right: 1px solid var(--layout-border-color);
-        background: var(--layout-bg-color);
-      }
-
-      .app-shell-sidebar-inner {
-        flex: 1;
-        overflow-y: auto;
-      }
-      
-      .app-shell-content {
-        display: flex;
-        flex-direction: column;
-        flex: 1;
-        width: 100%;
-      }
-      
-      .app-shell-nav {
-        height: var(--layout-nav-height);
-        border-bottom: 1px solid var(--layout-border-color);
-        background: var(--layout-bg-color);
-        display: flex;
-        align-items: center;
-        padding: 0 var(--st-spacing-md);
-      }
-      
-      .app-shell-main {
-        flex: 1;
-        overflow-y: auto;
-        padding: var(--st-spacing-lg);
-      }
-      
-      .app-shell-footer {
-        background: var(--layout-bg-color);
-        border-top: 1px solid var(--layout-border-color);
-        padding: var(--st-spacing-md);
-      }
-
-      @media (min-width: 768px) {
-        .app-shell-sidebar {
-          display: flex;
-          flex-direction: column;
-          width: 100%;
-          max-width: var(--layout-sidebar-width);
-          flex-shrink: 0;
-        }
-      }
-
-      /* ==========================================================
-         2. Content Sidebar Layout
-         ========================================================== */
-      .layout-content-sidebar {
-        min-height: 100vh;
-        display: flex;
-        flex-direction: column;
-        background: var(--layout-bg-color);
-      }
-      
-      .content-sidebar-nav {
-        border-bottom: 1px solid var(--layout-border-color);
-        background: var(--layout-bg-color);
-      }
-      
-      .content-sidebar-container {
-        flex: 1;
-        width: 100%;
-        max-width: 72rem;
-        margin: 0 auto;
-        padding: var(--st-spacing-xl) var(--st-spacing-md);
-        display: flex;
-        flex-direction: column;
-        gap: var(--st-spacing-xl);
-      }
-      
-      .content-sidebar-main {
-        flex: 1;
-        max-width: 48rem;
-      }
-      
-      .content-sidebar-aside {
-        width: 100%;
-        flex-shrink: 0;
-      }
-      
-      .content-sidebar-footer {
-        margin-top: auto;
-        border-top: 1px solid var(--layout-border-color);
-        background: var(--layout-surface-color);
-      }
-
-      @media (min-width: 1024px) {
-        .content-sidebar-container {
-          flex-direction: row;
-          gap: 3rem;
-        }
-        .content-sidebar-aside {
-          width: 100%;
-          max-width: var(--layout-sidebar-width);
-        }
-        .content-sidebar-aside-inner {
-          position: sticky;
-          top: var(--st-spacing-lg);
-        }
-      }
-
-      /* ==========================================================
-         3. Single Column Layout
-         ========================================================== */
-      .layout-single-column {
-        min-height: 100vh;
-        display: flex;
-        flex-direction: column;
-        background: var(--layout-bg-color);
-      }
-      
-      .single-column-nav {
-        position: sticky;
-        top: 0;
-        z-index: 50;
-        width: 100%;
-        background: var(--layout-bg-color);
-        border-bottom: 1px solid var(--layout-border-color);
-      }
-      
-      .single-column-main {
-        flex: 1;
-        display: flex;
-        flex-direction: column;
-      }
-      
-      .single-column-footer {
-        margin-top: auto;
-      }
-
-      /* ==========================================================
-         4. Three-Column Layout (Docs Shell)
-         ========================================================== */
-      .layout-three-column {
-        min-height: 100vh;
-        display: flex;
-        flex-direction: column;
-        background: var(--layout-bg-color);
-      }
-
-      .three-column-nav {
-        position: sticky;
-        top: 0;
-        z-index: 50;
-        height: var(--layout-nav-height);
-        border-bottom: 1px solid var(--layout-border-color);
-        background: var(--layout-bg-color);
-        display: flex;
-        align-items: center;
-        padding: 0 var(--st-spacing-md);
-      }
-
-      .three-column-body {
-        flex: 1;
-        width: 100%;
-        max-width: 96rem;
-        margin: 0 auto;
-        display: flex;
-      }
-
-      :host([fill-main]) .three-column-body {
-        max-width: 100%;
-      }
-
-      .three-column-sidebar-left {
-        display: none;
-        width: 100%;
-        max-width: var(--layout-sidebar-width);
-        flex-shrink: 0;
-        border-right: 1px solid var(--layout-border-color);
-        background: var(--layout-bg-color);
-      }
-
-      .three-column-sidebar-left-inner {
-        position: sticky;
-        top: calc(var(--layout-nav-height) + 1rem);
-        height: calc(100vh - var(--layout-nav-height) - 2rem);
-        overflow-y: auto;
-        padding: var(--st-spacing-md) 0;
-      }
-
-      .three-column-main {
-        flex: 1;
-        min-width: 0;
-        padding: var(--st-spacing-xl) var(--st-spacing-lg);
-        max-width: var(--layout-main-max-width);
-        margin-left: auto;
-        margin-right: auto;
-      }
-
-      .three-column-sidebar-right {
-        display: none;
-        width: 100%;
-        max-width: var(--layout-right-sidebar-width);
-        flex-shrink: 0;
-        border-left: 1px solid var(--layout-border-color);
-        background: var(--layout-bg-color);
-      }
-
-      .three-column-sidebar-right-inner {
-        position: sticky;
-        top: calc(var(--layout-nav-height) + 1rem);
-        height: calc(100vh - var(--layout-nav-height) - 2rem);
-        overflow-y: auto;
-        padding: var(--st-spacing-md) var(--st-spacing-sm);
-      }
-
-      .three-column-footer {
-        border-top: 1px solid var(--layout-border-color);
-        background: var(--layout-surface-color);
-        padding: var(--st-spacing-lg);
-      }
-
-      @media (min-width: 768px) {
-        .three-column-sidebar-left {
-          display: block;
-        }
-      }
-
-      @media (min-width: 1280px) {
-        .three-column-sidebar-right {
-          display: block;
-        }
-      }
-
-      /* ==========================================================
-         Mobile Drawer Transformation & Touch Support (< 768px)
-         ========================================================== */
-      @media (max-width: 767px) {
-        .three-column-sidebar-left,
-        .app-shell-sidebar {
-          position: fixed;
-          top: 0;
-          left: 0;
-          width: 100%;
-          max-width: var(--layout-sidebar-width);
-          height: 100vh;
-          background: var(--layout-bg-color);
-          z-index: 1001;
-          box-shadow: 4px 0 24px rgba(0, 0, 0, 0.15);
-          transform: translateX(-100%);
-          transition: transform 0.3s cubic-bezier(0.16, 1, 0.3, 1);
-          display: flex !important;
-          flex-direction: column;
-          touch-action: pan-y;
-        }
-
-        .three-column-sidebar-left.open,
-        .app-shell-sidebar.open {
-          transform: translateX(0);
-        }
-
-        .three-column-sidebar-left-inner {
-          position: static;
-          height: auto;
-          flex: 1;
-          overflow-y: auto;
-        }
-      }
-    `
-  ];
-
-  render() {
-    const backdrop = html`
-      <div 
-        class="mobile-backdrop ${this._mobileMenuOpen ? 'open' : ''}" 
-        @click=${this._closeMobileMenu}
-      ></div>
-    `;
-
-    const hamburgerBtn = html`
-      <button class="mobile-menu-btn" @click=${this._toggleMobileMenu} aria-label="Open Navigation Menu">
-        <svg viewBox="0 0 24 24"><path d="M3 12h18M3 6h18M3 18h18"></path></svg>
-      </button>
-    `;
-
-    const drawerHeader = html`
-      <div class="mobile-drawer-header">
-        <span class="mobile-drawer-title">Menu</span>
-        <button class="mobile-close-btn" @click=${this._closeMobileMenu} aria-label="Close Navigation Menu">
-          <svg viewBox="0 0 24 24"><path d="M18 6L6 18M6 6l12 12"></path></svg>
-        </button>
-      </div>
-    `;
-
-    if (this.variant === 'app-shell') {
-      return html`
-        ${backdrop}
-        <div class="layout-app-shell">
-          <aside 
-            class="app-shell-sidebar ${this._mobileMenuOpen ? 'open' : ''}" 
-            @click=${this._handleNavClick}
-            @touchstart=${this._handleTouchStart}
-            @touchmove=${this._handleTouchMove}
-            @touchend=${this._handleTouchEnd}
-          >
-            ${drawerHeader}
-            <div class="app-shell-sidebar-inner">
-              <slot name="sidebar"></slot>
-            </div>
-          </aside>
-          
-          <div class="app-shell-content">
-            <header class="app-shell-nav">
-              ${hamburgerBtn}
-              <slot name="nav"></slot>
-            </header>
-            
-            <main class="app-shell-main">
-              <slot></slot>
-            </main>
-            
-            <footer class="app-shell-footer">
-              <slot name="footer"></slot>
-            </footer>
-          </div>
-        </div>
-      `;
-    }
-
-    if (this.variant === 'content-sidebar') {
-      return html`
-        <div class="layout-content-sidebar">
-          <header class="content-sidebar-nav">
-            <div style="display: flex; align-items: center; padding: 0 var(--st-spacing-md); height: var(--layout-nav-height);">
-              <slot name="nav"></slot>
-            </div>
-          </header>
-          
-          <div class="content-sidebar-container">
-            <main class="content-sidebar-main">
-              <slot></slot>
-            </main>
-            
-            <aside class="content-sidebar-aside">
-              <div class="content-sidebar-aside-inner">
-                <slot name="aside"></slot>
-              </div>
-            </aside>
-          </div>
-          
-          <footer class="content-sidebar-footer">
-            <slot name="footer"></slot>
-          </footer>
-        </div>
-      `;
-    }
-
-    if (this.variant === 'three-column') {
-      return html`
-        ${backdrop}
-        <div class="layout-three-column">
-          <header class="three-column-nav">
-            ${hamburgerBtn}
-            <slot name="nav"></slot>
-          </header>
-
-          <div class="three-column-body">
-            <aside 
-              class="three-column-sidebar-left ${this._mobileMenuOpen ? 'open' : ''}" 
-              @click=${this._handleNavClick}
-              @touchstart=${this._handleTouchStart}
-              @touchmove=${this._handleTouchMove}
-              @touchend=${this._handleTouchEnd}
-            >
-              ${drawerHeader}
-              <div class="three-column-sidebar-left-inner">
-                <slot name="sidebar-left"></slot>
-              </div>
-            </aside>
-
-            <main class="three-column-main">
-              <slot></slot>
-            </main>
-
-            <aside class="three-column-sidebar-right">
-              <div class="three-column-sidebar-right-inner">
-                <slot name="sidebar-right"></slot>
-              </div>
-            </aside>
-          </div>
-
-          <footer class="three-column-footer">
-            <slot name="footer"></slot>
-          </footer>
-        </div>
-      `;
-    }
-
-    return html`
-      <div class="layout-single-column">
-        <header class="single-column-nav">
-          <div style="display: flex; align-items: center; padding: 0 var(--st-spacing-md); height: var(--layout-nav-height);">
-            <slot name="nav"></slot>
-          </div>
-        </header>
-        
-        <main class="single-column-main">
-          <slot></slot>
-        </main>
-        
-        <footer class="single-column-footer">
-          <slot name="footer"></slot>
-        </footer>
-      </div>
-    `;
-  }
-}
-
-declare global {
-  interface HTMLElementTagNameMap {
-    'st-page-layout': StPageLayout;
-  }
+import { LitElement, html, css, PropertyValues } from 'lit';
+import { customElement, property, state } from 'lit/decorators.js';
+import { resetStyles } from '../../styles/reset.js';
+
+export type LayoutVariant = 'app-shell' | 'content-sidebar' | 'single-column' | 'three-column';
+
+@customElement('st-page-layout')
+export class StPageLayout extends LitElement {
+  /**
+   * Defines the structural layout variant to render.
+   */
+  @property({ type: String, reflect: true })
+  variant: LayoutVariant = 'single-column';
+
+  /**
+   * Maximum width for the left sidebar section (e.g., '20rem', '300px').
+   */
+  @property({ type: String, attribute: 'sidebar-width' })
+  sidebarWidth = '';
+
+  /**
+   * Maximum width for the right sidebar section (e.g., '16rem', '250px').
+   */
+  @property({ type: String, attribute: 'right-sidebar-width' })
+  rightSidebarWidth = '';
+
+  /**
+   * Optional maximum width for the main content area (e.g., '48rem', '800px').
+   */
+  @property({ type: String, attribute: 'main-max-width' })
+  mainMaxWidth = '';
+
+  /**
+   * When true, expands the main content area to fill 100% of the available width between sidebars.
+   */
+  @property({ type: Boolean, attribute: 'fill-main', reflect: true })
+  fillMain = false;
+
+  @state()
+  private _mobileMenuOpen = false;
+
+  private _touchStartX = 0;
+  private _currentTranslateX = 0;
+  private _isDragging = false;
+
+  override updated(changedProperties: PropertyValues<this>) {
+    super.updated(changedProperties);
+
+    if (changedProperties.has('sidebarWidth')) {
+      if (this.sidebarWidth) {
+        this.style.setProperty('--layout-sidebar-width', this.sidebarWidth);
+      } else {
+        this.style.removeProperty('--layout-sidebar-width');
+      }
+    }
+
+    if (changedProperties.has('rightSidebarWidth')) {
+      if (this.rightSidebarWidth) {
+        this.style.setProperty('--layout-right-sidebar-width', this.rightSidebarWidth);
+      } else {
+        this.style.removeProperty('--layout-right-sidebar-width');
+      }
+    }
+
+    if (changedProperties.has('mainMaxWidth')) {
+      if (this.mainMaxWidth) {
+        this.style.setProperty('--layout-main-max-width', this.mainMaxWidth);
+      } else {
+        this.style.removeProperty('--layout-main-max-width');
+      }
+    }
+  }
+
+  private _toggleMobileMenu = () => {
+    this._mobileMenuOpen = !this._mobileMenuOpen;
+  };
+
+  private _closeMobileMenu = () => {
+    this._mobileMenuOpen = false;
+  };
+
+  // Only close if an actual navigation link/item was clicked
+  private _handleNavClick = (e: MouseEvent) => {
+    const path = e.composedPath();
+    const clickedLink = path.some(node => {
+      const el = node as HTMLElement;
+      return el.tagName === 'A' || el.tagName === 'ST-VERTICAL-NAV-ITEM';
+    });
+
+    if (clickedLink) {
+      this._closeMobileMenu();
+    }
+  };
+
+  private _handleTouchStart = (e: TouchEvent) => {
+    if (window.innerWidth >= 768) return;
+    this._touchStartX = e.touches[0].clientX;
+    this._isDragging = true;
+    const sidebar = e.currentTarget as HTMLElement;
+    sidebar.style.transition = 'none';
+  };
+
+  private _handleTouchMove = (e: TouchEvent) => {
+    if (!this._isDragging || window.innerWidth >= 768) return;
+    const currentX = e.touches[0].clientX;
+    const diff = currentX - this._touchStartX;
+    const sidebar = e.currentTarget as HTMLElement;
+
+    if (diff < 0) {
+      this._currentTranslateX = diff;
+      sidebar.style.transform = `translateX(${diff}px)`;
+    }
+  };
+
+  private _handleTouchEnd = (e: TouchEvent) => {
+    if (!this._isDragging || window.innerWidth >= 768) return;
+    this._isDragging = false;
+    const sidebar = e.currentTarget as HTMLElement;
+    sidebar.style.transition = '';
+
+    if (this._currentTranslateX < -70) {
+      this._closeMobileMenu();
+      sidebar.style.transform = '';
+    } else {
+      sidebar.style.transform = '';
+    }
+    this._currentTranslateX = 0;
+  };
+
+  private _resizeListener = () => {
+    if (window.innerWidth >= 768 && this._mobileMenuOpen) {
+      this._mobileMenuOpen = false;
+    }
+  };
+
+  connectedCallback() {
+    super.connectedCallback();
+    window.addEventListener('resize', this._resizeListener);
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    window.removeEventListener('resize', this._resizeListener);
+  }
+
+  static styles = [
+    resetStyles,
+    css`
+      :host {
+        display: block;
+        box-sizing: border-box;
+        --layout-bg-color: var(--st-color-bg, #ffffff);
+        --layout-surface-color: var(--st-color-surface, #f8fafc);
+        --layout-border-color: var(--st-color-border, #e2e8f0);
+        --layout-sidebar-width: 16rem;
+        --layout-right-sidebar-width: 14rem;
+        --layout-main-max-width: none;
+        --layout-nav-height: 4rem;
+      }
+
+      *, *::before, *::after {
+        box-sizing: inherit;
+      }
+
+      /* ==========================================================
+         Mobile Hamburger Toggle Button Styles
+         ========================================================== */
+      .mobile-menu-btn {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        background: transparent;
+        border: 1px solid var(--layout-border-color);
+        border-radius: var(--st-radius-sm, 0.375rem);
+        width: 2.25rem;
+        height: 2.25rem;
+        cursor: pointer;
+        color: var(--st-color-text);
+        margin-right: var(--st-spacing-sm);
+        flex-shrink: 0;
+      }
+
+      .mobile-menu-btn svg {
+        width: 1.25rem;
+        height: 1.25rem;
+        stroke: currentColor;
+        stroke-width: 2;
+        stroke-linecap: round;
+        stroke-linejoin: round;
+        fill: none;
+      }
+
+      @media (min-width: 768px) {
+        .mobile-menu-btn {
+          display: none;
+        }
+      }
+
+      /* ==========================================================
+         Mobile Backdrop Overlay
+         ========================================================== */
+      .mobile-backdrop {
+        position: fixed;
+        top: 0;
+        left: 0;
+        width: 100vw;
+        height: 100vh;
+        background-color: rgba(0, 0, 0, 0.5);
+        backdrop-filter: blur(2px);
+        z-index: 1000;
+        display: none;
+      }
+
+      .mobile-backdrop.open {
+        display: block;
+      }
+
+      @media (min-width: 768px) {
+        .mobile-backdrop {
+          display: none !important;
+        }
+      }
+
+      /* ==========================================================
+         Mobile Drawer Header (Only visible < 768px)
+         ========================================================== */
+      .mobile-drawer-header {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        padding: var(--st-spacing-md) var(--st-spacing-lg);
+        border-bottom: 1px solid var(--layout-border-color);
+        flex-shrink: 0;
+      }
+
+      .mobile-drawer-title {
+        font-weight: var(--st-font-weight-bold);
+        font-size: var(--st-font-size-sm);
+        color: var(--st-color-text);
+        text-transform: uppercase;
+        letter-spacing: 0.05em;
+      }
+
+      .mobile-close-btn {
+        background: transparent;
+        border: none;
+        cursor: pointer;
+        color: var(--st-color-text-muted);
+        padding: 0.25rem;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        border-radius: var(--st-radius-sm, 0.375rem);
+      }
+
+      .mobile-close-btn:hover {
+        color: var(--st-color-text);
+        background-color: var(--st-color-surface-muted, #f1f5f9);
+      }
+
+      .mobile-close-btn svg {
+        width: 1.25rem;
+        height: 1.25rem;
+        stroke: currentColor;
+        stroke-width: 2;
+        stroke-linecap: round;
+        stroke-linejoin: round;
+        fill: none;
+      }
+
+      @media (min-width: 768px) {
+        .mobile-drawer-header {
+          display: none !important;
+        }
+      }
+
+      /* ==========================================================
+         1. App Shell Layout
+         ========================================================== */
+      .layout-app-shell {
+        display: flex;
+        height: 100vh;
+        overflow: hidden;
+        background-color: var(--layout-surface-color);
+      }
+      
+      .app-shell-sidebar {
+        display: none;
+        border-right: 1px solid var(--layout-border-color);
+        background: var(--layout-bg-color);
+      }
+
+      .app-shell-sidebar-inner {
+        flex: 1;
+        overflow-y: auto;
+      }
+      
+      .app-shell-content {
+        display: flex;
+        flex-direction: column;
+        flex: 1;
+        width: 100%;
+      }
+      
+      .app-shell-nav {
+        height: var(--layout-nav-height);
+        border-bottom: 1px solid var(--layout-border-color);
+        background: var(--layout-bg-color);
+        display: flex;
+        align-items: center;
+        padding: 0 var(--st-spacing-md);
+      }
+      
+      .app-shell-main {
+        flex: 1;
+        overflow-y: auto;
+        padding: var(--st-spacing-lg);
+      }
+      
+      .app-shell-footer {
+        background: var(--layout-bg-color);
+        border-top: 1px solid var(--layout-border-color);
+        padding: var(--st-spacing-md);
+      }
+
+      @media (min-width: 768px) {
+        .app-shell-sidebar {
+          display: flex;
+          flex-direction: column;
+          width: 100%;
+          max-width: var(--layout-sidebar-width);
+          flex-shrink: 0;
+        }
+      }
+
+      /* ==========================================================
+         2. Content Sidebar Layout
+         ========================================================== */
+      .layout-content-sidebar {
+        min-height: 100vh;
+        display: flex;
+        flex-direction: column;
+        background: var(--layout-bg-color);
+      }
+      
+      .content-sidebar-nav {
+        border-bottom: 1px solid var(--layout-border-color);
+        background: var(--layout-bg-color);
+      }
+      
+      .content-sidebar-container {
+        flex: 1;
+        width: 100%;
+        max-width: 72rem;
+        margin: 0 auto;
+        padding: var(--st-spacing-xl) var(--st-spacing-md);
+        display: flex;
+        flex-direction: column;
+        gap: var(--st-spacing-xl);
+      }
+      
+      .content-sidebar-main {
+        flex: 1;
+        max-width: 48rem;
+      }
+      
+      .content-sidebar-aside {
+        width: 100%;
+        flex-shrink: 0;
+      }
+      
+      .content-sidebar-footer {
+        margin-top: auto;
+        border-top: 1px solid var(--layout-border-color);
+        background: var(--layout-surface-color);
+      }
+
+      @media (min-width: 1024px) {
+        .content-sidebar-container {
+          flex-direction: row;
+          gap: 3rem;
+        }
+        .content-sidebar-aside {
+          width: 100%;
+          max-width: var(--layout-sidebar-width);
+        }
+        .content-sidebar-aside-inner {
+          position: sticky;
+          top: var(--st-spacing-lg);
+        }
+      }
+
+      /* ==========================================================
+         3. Single Column Layout
+         ========================================================== */
+      .layout-single-column {
+        min-height: 100vh;
+        display: flex;
+        flex-direction: column;
+        background: var(--layout-bg-color);
+      }
+      
+      .single-column-nav {
+        position: sticky;
+        top: 0;
+        z-index: 50;
+        width: 100%;
+        background: var(--layout-bg-color);
+        border-bottom: 1px solid var(--layout-border-color);
+      }
+      
+      .single-column-main {
+        flex: 1;
+        display: flex;
+        flex-direction: column;
+      }
+      
+      .single-column-footer {
+        margin-top: auto;
+      }
+
+      /* ==========================================================
+         4. Three-Column Layout (Docs Shell)
+         ========================================================== */
+      .layout-three-column {
+        min-height: 100vh;
+        display: flex;
+        flex-direction: column;
+        background: var(--layout-bg-color);
+      }
+
+      .three-column-nav {
+        position: sticky;
+        top: 0;
+        z-index: 50;
+        height: var(--layout-nav-height);
+        border-bottom: 1px solid var(--layout-border-color);
+        background: var(--layout-bg-color);
+        display: flex;
+        align-items: center;
+        padding: 0 var(--st-spacing-md);
+      }
+
+      .three-column-body {
+        flex: 1;
+        width: 100%;
+        max-width: 96rem;
+        margin: 0 auto;
+        display: flex;
+      }
+
+      :host([fill-main]) .three-column-body {
+        max-width: 100%;
+      }
+
+      .three-column-sidebar-left {
+        display: none;
+        width: 100%;
+        max-width: var(--layout-sidebar-width);
+        flex-shrink: 0;
+        border-right: 1px solid var(--layout-border-color);
+        background: var(--layout-bg-color);
+      }
+
+      .three-column-sidebar-left-inner {
+        position: sticky;
+        top: calc(var(--layout-nav-height) + 1rem);
+        height: calc(100vh - var(--layout-nav-height) - 2rem);
+        overflow-y: auto;
+        padding: var(--st-spacing-md) 0;
+      }
+
+      .three-column-main {
+        flex: 1;
+        min-width: 0;
+        padding: var(--st-spacing-xl) var(--st-spacing-lg);
+        max-width: var(--layout-main-max-width);
+        margin-left: auto;
+        margin-right: auto;
+      }
+
+      .three-column-sidebar-right {
+        display: none;
+        width: 100%;
+        max-width: var(--layout-right-sidebar-width);
+        flex-shrink: 0;
+        border-left: 1px solid var(--layout-border-color);
+        background: var(--layout-bg-color);
+      }
+
+      .three-column-sidebar-right-inner {
+        position: sticky;
+        top: calc(var(--layout-nav-height) + 1rem);
+        height: calc(100vh - var(--layout-nav-height) - 2rem);
+        overflow-y: auto;
+        padding: var(--st-spacing-md) var(--st-spacing-sm);
+      }
+
+      .three-column-footer {
+        border-top: 1px solid var(--layout-border-color);
+        background: var(--layout-surface-color);
+        padding: var(--st-spacing-lg);
+      }
+
+      @media (min-width: 768px) {
+        .three-column-sidebar-left {
+          display: block;
+        }
+      }
+
+      @media (min-width: 1280px) {
+        .three-column-sidebar-right {
+          display: block;
+        }
+      }
+
+      /* ==========================================================
+         Mobile Drawer Transformation & Touch Support (< 768px)
+         ========================================================== */
+      @media (max-width: 767px) {
+        .three-column-sidebar-left,
+        .app-shell-sidebar {
+          position: fixed;
+          top: 0;
+          left: 0;
+          width: 100%;
+          max-width: var(--layout-sidebar-width);
+          height: 100vh;
+          background: var(--layout-bg-color);
+          z-index: 1001;
+          box-shadow: 4px 0 24px rgba(0, 0, 0, 0.15);
+          transform: translateX(-100%);
+          transition: transform 0.3s cubic-bezier(0.16, 1, 0.3, 1);
+          display: flex !important;
+          flex-direction: column;
+          touch-action: pan-y;
+        }
+
+        .three-column-sidebar-left.open,
+        .app-shell-sidebar.open {
+          transform: translateX(0);
+        }
+
+        .three-column-sidebar-left-inner {
+          position: static;
+          height: auto;
+          flex: 1;
+          overflow-y: auto;
+        }
+      }
+    `
+  ];
+
+  render() {
+    const backdrop = html`
+      <div 
+        class="mobile-backdrop ${this._mobileMenuOpen ? 'open' : ''}" 
+        @click=${this._closeMobileMenu}
+      ></div>
+    `;
+
+    const hamburgerBtn = html`
+      <button class="mobile-menu-btn" @click=${this._toggleMobileMenu} aria-label="Open Navigation Menu">
+        <svg viewBox="0 0 24 24"><path d="M3 12h18M3 6h18M3 18h18"></path></svg>
+      </button>
+    `;
+
+    const drawerHeader = html`
+      <div class="mobile-drawer-header">
+        <span class="mobile-drawer-title">Menu</span>
+        <button class="mobile-close-btn" @click=${this._closeMobileMenu} aria-label="Close Navigation Menu">
+          <svg viewBox="0 0 24 24"><path d="M18 6L6 18M6 6l12 12"></path></svg>
+        </button>
+      </div>
+    `;
+
+    if (this.variant === 'app-shell') {
+      return html`
+        ${backdrop}
+        <div class="layout-app-shell">
+          <aside 
+            class="app-shell-sidebar ${this._mobileMenuOpen ? 'open' : ''}" 
+            @click=${this._handleNavClick}
+            @touchstart=${this._handleTouchStart}
+            @touchmove=${this._handleTouchMove}
+            @touchend=${this._handleTouchEnd}
+          >
+            ${drawerHeader}
+            <div class="app-shell-sidebar-inner">
+              <slot name="sidebar"></slot>
+            </div>
+          </aside>
+          
+          <div class="app-shell-content">
+            <header class="app-shell-nav">
+              ${hamburgerBtn}
+              <slot name="nav"></slot>
+            </header>
+            
+            <main class="app-shell-main">
+              <slot></slot>
+            </main>
+            
+            <footer class="app-shell-footer">
+              <slot name="footer"></slot>
+            </footer>
+          </div>
+        </div>
+      `;
+    }
+
+    if (this.variant === 'content-sidebar') {
+      return html`
+        <div class="layout-content-sidebar">
+          <header class="content-sidebar-nav">
+            <div style="display: flex; align-items: center; padding: 0 var(--st-spacing-md); height: var(--layout-nav-height);">
+              <slot name="nav"></slot>
+            </div>
+          </header>
+          
+          <div class="content-sidebar-container">
+            <main class="content-sidebar-main">
+              <slot></slot>
+            </main>
+            
+            <aside class="content-sidebar-aside">
+              <div class="content-sidebar-aside-inner">
+                <slot name="aside"></slot>
+              </div>
+            </aside>
+          </div>
+          
+          <footer class="content-sidebar-footer">
+            <slot name="footer"></slot>
+          </footer>
+        </div>
+      `;
+    }
+
+    if (this.variant === 'three-column') {
+      return html`
+        ${backdrop}
+        <div class="layout-three-column">
+          <header class="three-column-nav">
+            ${hamburgerBtn}
+            <slot name="nav"></slot>
+          </header>
+
+          <div class="three-column-body">
+            <aside 
+              class="three-column-sidebar-left ${this._mobileMenuOpen ? 'open' : ''}" 
+              @click=${this._handleNavClick}
+              @touchstart=${this._handleTouchStart}
+              @touchmove=${this._handleTouchMove}
+              @touchend=${this._handleTouchEnd}
+            >
+              ${drawerHeader}
+              <div class="three-column-sidebar-left-inner">
+                <slot name="sidebar-left"></slot>
+              </div>
+            </aside>
+
+            <main class="three-column-main">
+              <slot></slot>
+            </main>
+
+            <aside class="three-column-sidebar-right">
+              <div class="three-column-sidebar-right-inner">
+                <slot name="sidebar-right"></slot>
+              </div>
+            </aside>
+          </div>
+
+          <footer class="three-column-footer">
+            <slot name="footer"></slot>
+          </footer>
+        </div>
+      `;
+    }
+
+    return html`
+      <div class="layout-single-column">
+        <header class="single-column-nav">
+          <div style="display: flex; align-items: center; padding: 0 var(--st-spacing-md); height: var(--layout-nav-height);">
+            <slot name="nav"></slot>
+          </div>
+        </header>
+        
+        <main class="single-column-main">
+          <slot></slot>
+        </main>
+        
+        <footer class="single-column-footer">
+          <slot name="footer"></slot>
+        </footer>
+      </div>
+    `;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'st-page-layout': StPageLayout;
+  }
 }