@reliability-design/web 1.0.3 → 1.1.1

package/dist/components/rel-sidebar/rel-sidebar.ts

@@ -0,0 +1,1166 @@
+import { LitElement, html, css, nothing } from "lit";
+import { customElement, property, state, query } from "lit/decorators.js";
+import "@reliability-design/icons/rel-icon";
+
+export type SidebarVariant = "sidebar" | "floating" | "inset";
+export type SidebarSide = "left" | "right";
+export type SidebarCollapsible = "offcanvas" | "icon" | "none";
+export type SidebarWidth = "sm" | "md" | "lg";
+export type SidebarChangeReason = "trigger" | "rail" | "overlay" | "escape" | "shortcut" | "api";
+
+// ============================================================================
+// rel-sidebar-provider (Root State Manager)
+// ============================================================================
+@customElement("rel-sidebar-provider")
+export class RelSidebarProvider extends LitElement {
+  @property({ type: Boolean, reflect: true }) open?: boolean;
+  @property({ type: Boolean, attribute: "defaultopen" }) defaultOpen = true;
+  @property({ type: Boolean, reflect: true }) collapsed?: boolean;
+  @property({ type: Boolean, attribute: "defaultcollapsed" }) defaultCollapsed = false;
+  @property({ type: String }) variant: SidebarVariant = "sidebar";
+  @property({ type: String }) side: SidebarSide = "left";
+  @property({ type: String }) collapsible: SidebarCollapsible = "icon";
+  @property({ type: String }) width: SidebarWidth = "md";
+  @property({ type: String, attribute: "persist-key" }) persistKey = "rel-sidebar";
+  @property({ type: Boolean, attribute: "keyboard-shortcut" }) keyboardShortcut = true;
+  @property({ type: Boolean, attribute: "disable-persist" }) disablePersist = false;
+  @property({ type: Boolean, attribute: "disable-overlay-close" }) disableOverlayClose = false;
+
+  @state() private internalOpen = true;
+  @state() private internalCollapsed = false;
+  @state() public isMobile = false;
+
+  private mediaQuery: MediaQueryList | null = null;
+  private isInitialized = false;
+  private _uid = Math.random().toString(36).slice(2);
+
+  private get _storageKey(): string {
+    return `rel-sidebar:${this.id || this._uid}`;
+  }
+
+  static styles = css`
+    :host {
+      display: contents;
+    }
+  `;
+
+  connectedCallback() {
+    super.connectedCallback();
+
+    // Setup mobile detection first (synchronous)
+    this.setupMediaQuery();
+
+    // Load state with mobile awareness
+    this.loadInitialState();
+
+    // Setup keyboard shortcut
+    if (this.keyboardShortcut) {
+      document.addEventListener("keydown", this.handleKeyDown);
+    }
+
+    this.isInitialized = true;
+
+    // Notify children of initial state after a microtask
+    requestAnimationFrame(() => {
+      this.notifyStateChange();
+    });
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    if (this.mediaQuery) {
+      this.mediaQuery.removeEventListener("change", this.handleMediaChange);
+    }
+    document.removeEventListener("keydown", this.handleKeyDown);
+  }
+
+  updated(changed: Map<string, unknown>) {
+    if (changed.has("open") && this.isOpenControlled()) {
+      this.internalOpen = !!this.open;
+      this.notifyStateChange();
+    }
+    if (changed.has("collapsed") && this.isCollapsedControlled()) {
+      this.internalCollapsed = !!this.collapsed;
+      this.notifyStateChange();
+    }
+  }
+
+  private isOpenControlled() {
+    return this.open !== undefined;
+  }
+
+  private isCollapsedControlled() {
+    return this.collapsed !== undefined;
+  }
+
+  get activeOpen() {
+    return this.isOpenControlled() ? !!this.open : this.internalOpen;
+  }
+
+  get activeCollapsed() {
+    return this.isCollapsedControlled() ? !!this.collapsed : this.internalCollapsed;
+  }
+
+  private setupMediaQuery() {
+    this.mediaQuery = window.matchMedia("(max-width: 768px)");
+    this.isMobile = this.mediaQuery.matches;
+    this.mediaQuery.addEventListener("change", this.handleMediaChange);
+  }
+
+  private handleMediaChange = (e: MediaQueryListEvent) => {
+    const wasMobile = this.isMobile;
+    this.isMobile = e.matches;
+
+    // When switching to mobile, close the sidebar unless controlled
+    if (!wasMobile && this.isMobile && !this.isOpenControlled()) {
+      this.internalOpen = false;
+      this.persistState();
+    }
+
+    this.notifyStateChange();
+  };
+
+  private isOffcanvasMode(): boolean {
+    return this.isMobile || this.collapsible === "offcanvas";
+  }
+
+  private loadInitialState() {
+    // If controlled, use controlled value
+    if (this.isOpenControlled()) {
+      this.internalOpen = !!this.open;
+    } else if (this.isOffcanvasMode()) {
+      // Mobile/offcanvas: always start closed, ignore persisted state
+      this.internalOpen = false;
+    } else {
+      // Desktop: use persisted state or default
+      if (!this.disablePersist) {
+        this.loadPersistedState();
+      } else {
+        this.internalOpen = this.defaultOpen;
+        this.internalCollapsed = this.defaultCollapsed;
+      }
+    }
+
+    // Load collapsed state
+    if (!this.isCollapsedControlled()) {
+      if (!this.disablePersist && !this.isOffcanvasMode()) {
+        const persisted = this.getPersistedState();
+        if (persisted) {
+          this.internalCollapsed = persisted.collapsed ?? this.defaultCollapsed;
+        } else {
+          this.internalCollapsed = this.defaultCollapsed;
+        }
+      } else {
+        this.internalCollapsed = this.defaultCollapsed;
+      }
+    } else {
+      this.internalCollapsed = !!this.collapsed;
+    }
+  }
+
+  private getPersistedState(): { open?: boolean; collapsed?: boolean } | null {
+    try {
+      const stored = localStorage.getItem(this._storageKey);
+      if (stored) {
+        return JSON.parse(stored);
+      }
+    } catch (e) {
+      // ignore
+    }
+    return null;
+  }
+
+  private loadPersistedState() {
+    const persisted = this.getPersistedState();
+    if (persisted) {
+      this.internalOpen = persisted.open ?? this.defaultOpen;
+      this.internalCollapsed = persisted.collapsed ?? this.defaultCollapsed;
+    } else {
+      this.internalOpen = this.defaultOpen;
+      this.internalCollapsed = this.defaultCollapsed;
+    }
+  }
+
+  private persistState() {
+    if (this.disablePersist) return;
+
+    // Don't persist open state for offcanvas mode
+    const stateToPersist = this.isOffcanvasMode()
+      ? { collapsed: this.activeCollapsed }
+      : { open: this.activeOpen, collapsed: this.activeCollapsed };
+
+    try {
+      localStorage.setItem(this._storageKey, JSON.stringify(stateToPersist));
+    } catch (e) {
+      // Silently fail if localStorage is unavailable
+    }
+  }
+
+  private handleKeyDown = (e: KeyboardEvent) => {
+    if (!this.keyboardShortcut) return;
+
+    // Ctrl/Cmd + B
+    if ((e.ctrlKey || e.metaKey) && e.key === "b") {
+      e.preventDefault();
+
+      if (this.isMobile || this.collapsible === "offcanvas") {
+        // Toggle open state
+        this.setOpen(!this.activeOpen, "shortcut");
+      } else if (this.collapsible === "icon") {
+        // Toggle collapsed state
+        this.setCollapsed(!this.activeCollapsed, "shortcut");
+      }
+    }
+  };
+
+  setOpen(next: boolean, reason: SidebarChangeReason = "api") {
+    if (!this.isOpenControlled()) {
+      this.internalOpen = next;
+    }
+
+    this.persistState();
+    this.notifyStateChange();
+    this.dispatchChangeEvent(reason);
+  }
+
+  setCollapsed(next: boolean, reason: SidebarChangeReason = "api") {
+    if (!this.isCollapsedControlled()) {
+      this.internalCollapsed = next;
+    }
+
+    this.persistState();
+    this.notifyStateChange();
+    this.dispatchChangeEvent(reason);
+  }
+
+  private dispatchChangeEvent(reason: SidebarChangeReason) {
+    this.dispatchEvent(
+      new CustomEvent("rel-sidebar-change", {
+        detail: {
+          open: this.activeOpen,
+          collapsed: this.activeCollapsed,
+          reason,
+        },
+        bubbles: true,
+        composed: true,
+      })
+    );
+  }
+
+  private notifyStateChange() {
+    // Dispatch a state event that children can listen to
+    this.dispatchEvent(
+      new CustomEvent("rel-sidebar-state", {
+        detail: {
+          isOpen: this.activeOpen,
+          isCollapsed: this.activeCollapsed,
+          isMobile: this.isMobile,
+          side: this.side,
+          variant: this.variant,
+          collapsible: this.collapsible,
+          width: this.width,
+        },
+        bubbles: true,
+        composed: true,
+      })
+    );
+  }
+
+  render() {
+    return html`<slot></slot>`;
+  }
+}
+
+// ============================================================================
+// rel-sidebar (Visual Container)
+// ============================================================================
+@customElement("rel-sidebar")
+export class RelSidebar extends LitElement {
+  @property({ type: Boolean }) inset = false;
+
+  @state() private isOpen = true;
+  @state() private isCollapsed = false;
+  @state() private isMobile = false;
+  @state() private side: SidebarSide = "left";
+  @state() private variant: SidebarVariant = "sidebar";
+  @state() private collapsible: SidebarCollapsible = "icon";
+  @state() private width: SidebarWidth = "md";
+
+  @query(".sidebar-container") private containerElement!: HTMLElement;
+
+  private provider: RelSidebarProvider | null = null;
+  private triggerElement: HTMLElement | null = null;
+  private originalBodyOverflow = "";
+  private originalBodyPaddingRight = "";
+
+  static styles = css`
+    :host {
+      --sidebar-width-sm: 240px;
+      --sidebar-width-md: 280px;
+      --sidebar-width-lg: 320px;
+      --sidebar-width-collapsed: 56px;
+      --sidebar-transition-duration: 0.2s;
+      --sidebar-transition-timing: cubic-bezier(0.4, 0, 0.2, 1);
+    }
+
+    .sidebar-wrapper {
+      position: relative;
+      height: 100%;
+    }
+
+    /* Overlay for offcanvas mode */
+    .overlay {
+      position: fixed;
+      top: 0;
+      left: 0;
+      right: 0;
+      bottom: 0;
+      /* TODO: replace scrim fallback with a proper dark-aware token in vars.css */
+      background: var(--rel-overlay-scrim, rgba(0, 0, 0, 0.6));
+      z-index: 999;
+      opacity: 0;
+      pointer-events: none;
+      transition: opacity var(--sidebar-transition-duration)
+        var(--sidebar-transition-timing);
+    }
+
+    .overlay.visible {
+      opacity: 1;
+      pointer-events: auto;
+    }
+
+    /* Sidebar container */
+    .sidebar-container {
+      position: fixed;
+      top: 0;
+      bottom: 0;
+      z-index: 1000;
+      background: var(--rel-surface-secondary, #fafafa);
+      color: var(--rel-text-primary, #333);
+      display: flex;
+      flex-direction: column;
+      transition: transform var(--sidebar-transition-duration)
+          var(--sidebar-transition-timing),
+        width var(--sidebar-transition-duration)
+          var(--sidebar-transition-timing);
+      width: var(--sidebar-width);
+      outline: none;
+      overflow: hidden;
+    }
+
+    /* Left side */
+    .sidebar-container[data-side="left"] {
+      left: 0;
+      border-right: 1px solid var(--rel-border-default, #ddd);
+    }
+
+    .sidebar-container[data-side="left"].offcanvas-hidden {
+      transform: translateX(-100%);
+    }
+
+    /* Right side */
+    .sidebar-container[data-side="right"] {
+      right: 0;
+      border-left: 1px solid var(--rel-border-default, #ddd);
+    }
+
+    .sidebar-container[data-side="right"].offcanvas-hidden {
+      transform: translateX(100%);
+    }
+
+    /* Floating variant */
+    .sidebar-container.variant-floating {
+      top: var(--rel-spacing-space-md, 16px);
+      bottom: var(--rel-spacing-space-md, 16px);
+      background: var(--rel-surface-secondary, #fafafa);
+      border: 1px solid var(--rel-border-default, #ddd);
+      border-radius: var(--rel-borders-radius-border-radius-300, 16px);
+      box-shadow: var(--rel-shadows-shadow-400);
+    }
+
+    .sidebar-container.variant-floating[data-side="left"] {
+      left: var(--rel-spacing-space-md, 16px);
+    }
+
+    .sidebar-container.variant-floating[data-side="right"] {
+      right: var(--rel-spacing-space-md, 16px);
+    }
+
+    /* Inset variant */
+    .sidebar-container.variant-inset {
+      position: relative;
+      border: none;
+      border-radius: 0;
+      box-shadow: none;
+    }
+
+    .sidebar-container.variant-inset[data-side="left"] {
+      border-right: 1px solid var(--rel-border-default, #ddd);
+    }
+
+    .sidebar-container.variant-inset[data-side="right"] {
+      border-left: 1px solid var(--rel-border-default, #ddd);
+    }
+
+    /* Desktop mode - not offcanvas */
+    @media (min-width: 769px) {
+      .sidebar-container:not(.offcanvas-mode) {
+        position: relative;
+      }
+
+      .overlay:not(.offcanvas-mode) {
+        display: none;
+      }
+    }
+
+    /* Collapsed state */
+    .sidebar-container.collapsed {
+      width: var(--sidebar-width-collapsed);
+    }
+
+    /* Reduced motion */
+    @media (prefers-reduced-motion: reduce) {
+      .overlay,
+      .sidebar-container {
+        transition: none;
+      }
+    }
+  `;
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.findProvider();
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.cleanup();
+  }
+
+  private findProvider() {
+    let parent = this.parentElement;
+    while (parent) {
+      if (parent instanceof RelSidebarProvider) {
+        this.provider = parent;
+        break;
+      }
+      parent = parent.parentElement;
+    }
+
+    if (this.provider) {
+      this.provider.addEventListener(
+        "rel-sidebar-state",
+        this.handleStateChange,
+      );
+      // Trigger initial state sync
+      this.syncState();
+    }
+  }
+
+  private syncState() {
+    if (!this.provider) return;
+
+    const wasOpen = this.isOpen;
+    const wasOffcanvas = this.isOffcanvasMode();
+
+    this.isOpen = this.provider.activeOpen;
+    this.isCollapsed = this.provider.activeCollapsed;
+    this.isMobile = this.provider.isMobile;
+    this.side = this.provider.side;
+    this.variant = this.provider.variant;
+    this.collapsible = this.provider.collapsible;
+    this.width = this.provider.width;
+
+    const isOffcanvas = this.isOffcanvasMode();
+
+    // Handle offcanvas behavior
+    if (isOffcanvas) {
+      if (this.isOpen && !wasOpen) {
+        this.lockScroll();
+        this.setupFocusTrap();
+      } else if (!this.isOpen && wasOpen) {
+        this.unlockScroll();
+        this.removeFocusTrap();
+      }
+    } else if (wasOffcanvas && !isOffcanvas) {
+      // Switched from offcanvas to normal mode
+      this.unlockScroll();
+      this.removeFocusTrap();
+    }
+
+    this.requestUpdate();
+  }
+
+  private handleStateChange = (e: Event) => {
+    this.syncState();
+  };
+
+  private isOffcanvasMode(): boolean {
+    return this.isMobile || this.collapsible === "offcanvas";
+  }
+
+  private lockScroll() {
+    if (typeof document === "undefined") return;
+
+    const scrollbarWidth =
+      window.innerWidth - document.documentElement.clientWidth;
+
+    this.originalBodyOverflow = document.body.style.overflow;
+    this.originalBodyPaddingRight = document.body.style.paddingRight;
+
+    document.body.style.overflow = "hidden";
+    if (scrollbarWidth > 0) {
+      document.body.style.paddingRight = `${scrollbarWidth}px`;
+    }
+  }
+
+  private unlockScroll() {
+    if (typeof document === "undefined") return;
+
+    document.body.style.overflow = this.originalBodyOverflow;
+    document.body.style.paddingRight = this.originalBodyPaddingRight;
+  }
+
+  private setupFocusTrap() {
+    this.triggerElement = document.activeElement as HTMLElement;
+    document.addEventListener("keydown", this.handleKeydown);
+
+    // Focus first focusable element or container
+    requestAnimationFrame(() => {
+      const focusable = this.getFocusableElements();
+      if (focusable.length > 0) {
+        focusable[0].focus();
+      } else if (this.containerElement) {
+        this.containerElement.setAttribute("tabindex", "-1");
+        this.containerElement.focus();
+      }
+    });
+  }
+
+  private removeFocusTrap() {
+    document.removeEventListener("keydown", this.handleKeydown);
+
+    // Restore focus to trigger
+    if (this.triggerElement && this.triggerElement.focus) {
+      requestAnimationFrame(() => {
+        this.triggerElement?.focus();
+        this.triggerElement = null;
+      });
+    }
+  }
+
+  private getFocusableElements(): HTMLElement[] {
+    if (!this.containerElement) return [];
+
+    const selectors = [
+      "a[href]",
+      "button:not([disabled])",
+      "textarea:not([disabled])",
+      "input:not([disabled])",
+      "select:not([disabled])",
+      '[tabindex]:not([tabindex="-1"])',
+    ].join(",");
+
+    const elements = Array.from(
+      this.containerElement.querySelectorAll(selectors),
+    ) as HTMLElement[];
+
+    return elements.filter((el) => el.offsetWidth || el.offsetHeight);
+  }
+
+  private handleKeydown = (e: KeyboardEvent) => {
+    if (!this.isOpen || !this.isOffcanvasMode()) return;
+
+    if (e.key === "Escape") {
+      e.preventDefault();
+      this.provider?.setOpen(false, "escape");
+      return;
+    }
+
+    // Focus trap
+    if (e.key === "Tab") {
+      const focusable = this.getFocusableElements();
+      if (focusable.length === 0) {
+        e.preventDefault();
+        return;
+      }
+
+      const firstFocusable = focusable[0];
+      const lastFocusable = focusable[focusable.length - 1];
+      const activeElement =
+        this.shadowRoot?.activeElement || document.activeElement;
+
+      if (e.shiftKey) {
+        if (activeElement === firstFocusable) {
+          e.preventDefault();
+          lastFocusable.focus();
+        }
+      } else {
+        if (activeElement === lastFocusable) {
+          e.preventDefault();
+          firstFocusable.focus();
+        }
+      }
+    }
+  };
+
+  private handleOverlayClick = () => {
+    if (this.provider && !this.provider.disableOverlayClose) {
+      this.provider.setOpen(false, "overlay");
+    }
+  };
+
+  private cleanup() {
+    this.unlockScroll();
+    this.removeFocusTrap();
+    if (this.provider) {
+      this.provider.removeEventListener(
+        "rel-sidebar-state",
+        this.handleStateChange,
+      );
+    }
+  }
+
+  private getWidthValue(): string {
+    const widthMap: Record<SidebarWidth, string> = {
+      sm: "var(--sidebar-width-sm)",
+      md: "var(--sidebar-width-md)",
+      lg: "var(--sidebar-width-lg)",
+    };
+    return widthMap[this.width] || widthMap.md;
+  }
+
+  render() {
+    const isOffcanvas = this.isOffcanvasMode();
+    const showOverlay = isOffcanvas && this.isOpen;
+    const containerClasses = [
+      "sidebar-container",
+      `variant-${this.variant}`,
+      this.isCollapsed && !isOffcanvas ? "collapsed" : "",
+      isOffcanvas ? "offcanvas-mode" : "",
+      isOffcanvas && !this.isOpen ? "offcanvas-hidden" : "",
+    ]
+      .filter(Boolean)
+      .join(" ");
+
+    return html`
+      <div class="sidebar-wrapper">
+        ${showOverlay
+          ? html`
+              <div
+                class="overlay visible"
+                @click="${this.handleOverlayClick}"
+              ></div>
+            `
+          : ""}
+
+        <nav
+          class="${containerClasses}"
+          data-side="${this.side}"
+          style="--sidebar-width: ${this.getWidthValue()}"
+          role="navigation"
+          aria-hidden="${isOffcanvas && !this.isOpen}"
+          tabindex="-1"
+        >
+          <slot></slot>
+        </nav>
+      </div>
+    `;
+  }
+}
+
+// ============================================================================
+// rel-sidebar-trigger (Toggle Button)
+// ============================================================================
+@customElement("rel-sidebar-trigger")
+export class RelSidebarTrigger extends LitElement {
+  @state() private isOpen = true;
+  @state() private isCollapsed = false;
+
+  private provider: RelSidebarProvider | null = null;
+
+  static styles = css`
+    :host {
+      display: inline-block;
+    }
+
+    button {
+      background: none;
+      border: none;
+      padding: var(--rel-spacing-space-xs, 8px);
+      margin: 0;
+      cursor: pointer;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      border-radius: var(--rel-borders-radius-border-radius-200, 8px);
+      color: var(--rel-text-heading, #2b2b2b);
+      transition: background 0.15s ease;
+    }
+
+    button:hover {
+      background: var(--rel-surface-surface, #f5f5f5);
+    }
+
+    button:active {
+      background: var(--rel-border-default, #ddd);
+    }
+
+    button:focus-visible {
+      outline: 2px solid var(--rel-border-info, #0091ea);
+      outline-offset: 2px;
+    }
+  `;
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.findProvider();
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    if (this.provider) {
+      this.provider.removeEventListener(
+        "rel-sidebar-state",
+        this.handleStateChange,
+      );
+    }
+  }
+
+  private findProvider() {
+    let parent = this.parentElement;
+    while (parent) {
+      if (parent instanceof RelSidebarProvider) {
+        this.provider = parent;
+        break;
+      }
+      parent = parent.parentElement;
+    }
+
+    if (this.provider) {
+      this.provider.addEventListener(
+        "rel-sidebar-state",
+        this.handleStateChange,
+      );
+      this.syncState();
+    }
+  }
+
+  private syncState() {
+    if (!this.provider) return;
+    this.isOpen = this.provider.activeOpen;
+    this.isCollapsed = this.provider.activeCollapsed;
+  }
+
+  private handleStateChange = () => {
+    this.syncState();
+  };
+
+  private handleClick = () => {
+    if (!this.provider) return;
+
+    if (this.provider.isMobile || this.provider.collapsible === "offcanvas") {
+      this.provider.setOpen(!this.isOpen, "trigger");
+    } else if (this.provider.collapsible === "icon") {
+      this.provider.setCollapsed(!this.isCollapsed, "rail");
+    }
+  };
+
+  render() {
+    return html`
+      <button
+        @click="${this.handleClick}"
+        type="button"
+        aria-expanded="${this.isOpen}"
+        aria-label="Toggle sidebar"
+      >
+        <slot>
+          <svg
+            width="20"
+            height="20"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            stroke-width="2"
+          >
+            <line x1="3" y1="12" x2="21" y2="12"></line>
+            <line x1="3" y1="6" x2="21" y2="6"></line>
+            <line x1="3" y1="18" x2="21" y2="18"></line>
+          </svg>
+        </slot>
+      </button>
+    `;
+  }
+}
+
+// ============================================================================
+// Layout Helpers
+// ============================================================================
+
+@customElement("rel-sidebar-header")
+export class RelSidebarHeader extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+      padding: var(--rel-spacing-space-md, 16px);
+      border-bottom: 1px solid var(--rel-border-default, #ddd);
+      flex-shrink: 0;
+      color: var(--rel-text-heading, #2b2b2b);
+    }
+  `;
+
+  render() {
+    return html`<slot></slot>`;
+  }
+}
+
+@customElement("rel-sidebar-content")
+export class RelSidebarContent extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+      flex: 1;
+      overflow-y: auto;
+      padding: var(--rel-spacing-space-sm, 12px) var(--rel-spacing-space-xs, 8px);
+    }
+
+    /* Scrollbar styling */
+    :host::-webkit-scrollbar {
+      width: 4px;
+    }
+    :host::-webkit-scrollbar-track {
+      background: transparent;
+    }
+    :host::-webkit-scrollbar-thumb {
+      background: var(--rel-border-default, #ddd);
+      border-radius: 2px;
+    }
+  `;
+
+  render() {
+    return html`<slot></slot>`;
+  }
+}
+
+@customElement("rel-sidebar-footer")
+export class RelSidebarFooter extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+      padding: var(--rel-spacing-space-md, 16px);
+      border-top: 1px solid var(--rel-border-default, #ddd);
+      flex-shrink: 0;
+      color: var(--rel-text-primary, #333);
+    }
+  `;
+
+  render() {
+    return html`<slot></slot>`;
+  }
+}
+
+@customElement("rel-sidebar-group")
+export class RelSidebarGroup extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+      margin-bottom: var(--rel-spacing-space-md, 16px);
+    }
+
+    :host(:last-child) {
+      margin-bottom: 0;
+    }
+  `;
+
+  render() {
+    return html`<slot></slot>`;
+  }
+}
+
+@customElement("rel-sidebar-group-label")
+export class RelSidebarGroupLabel extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+      font-size: var(--rel-fontSizes-xs, 10px);
+      font-weight: var(--rel-fontWeights-semibold, 600);
+      color: var(--rel-text-placeholder, #a9a9a9);
+      text-transform: uppercase;
+      letter-spacing: 0.05em;
+      padding: var(--rel-spacing-space-xs, 8px) var(--rel-spacing-space-sm, 12px) var(--rel-spacing-space-2xs, 4px);
+      margin-bottom: var(--rel-spacing-space-2xs, 4px);
+    }
+
+    :host(.collapsed) {
+      text-align: center;
+      font-size: var(--rel-fontSizes-xs, 10px);
+      padding: var(--rel-spacing-space-xs, 8px) var(--rel-spacing-space-2xs, 4px) var(--rel-spacing-space-2xs, 4px);
+    }
+  `;
+
+  render() {
+    return html`<slot></slot>`;
+  }
+}
+
+@customElement("rel-sidebar-group-content")
+export class RelSidebarGroupContent extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+    }
+  `;
+
+  render() {
+    return html`<slot></slot>`;
+  }
+}
+
+// ============================================================================
+// Menu Primitives
+// ============================================================================
+
+@customElement("rel-sidebar-menu")
+export class RelSidebarMenu extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+      list-style: none;
+      margin: 0;
+      padding: 0;
+    }
+  `;
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.addEventListener("keydown", this.handleKeyDown);
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.removeEventListener("keydown", this.handleKeyDown);
+  }
+
+  private handleKeyDown = (e: KeyboardEvent) => {
+    if (e.key !== "ArrowUp" && e.key !== "ArrowDown") return;
+
+    e.preventDefault();
+    const items = Array.from(
+      this.querySelectorAll("rel-sidebar-menu-button:not([disabled])"),
+    ) as HTMLElement[];
+    if (items.length === 0) return;
+
+    const active = items.findIndex(
+      (item) => item.shadowRoot?.activeElement || item === document.activeElement,
+    );
+    let next: number;
+    if (e.key === "ArrowDown") {
+      next = active < items.length - 1 ? active + 1 : 0;
+    } else {
+      next = active > 0 ? active - 1 : items.length - 1;
+    }
+
+    const btn = items[next]?.shadowRoot?.querySelector("button") as HTMLElement | null;
+    btn?.focus();
+  };
+
+  render() {
+    return html`<slot></slot>`;
+  }
+}
+
+@customElement("rel-sidebar-menu-item")
+export class RelSidebarMenuItem extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+      margin-bottom: var(--rel-spacing-space-2xs, 4px);
+      padding: 0 var(--rel-spacing-space-xs, 8px);
+    }
+  `;
+
+  render() {
+    return html`<slot></slot>`;
+  }
+}
+
+@customElement("rel-sidebar-menu-button")
+export class RelSidebarMenuButton extends LitElement {
+  @property({ type: Boolean }) active = false;
+  @property({ type: Boolean }) disabled = false;
+  @property({ type: String }) tooltip = "";
+  @property({ type: String }) icon: string = "";
+
+  @state() private isCollapsed = false;
+
+  private provider: RelSidebarProvider | null = null;
+
+  static styles = css`
+    :host {
+      display: block;
+    }
+
+    button {
+      width: 100%;
+      display: flex;
+      align-items: center;
+      gap: var(--rel-spacing-space-sm, 12px);
+      padding: var(--rel-spacing-space-xs, 8px) var(--rel-spacing-space-sm, 12px);
+      min-height: 40px;
+      background: none;
+      border: none;
+      border-radius: var(--rel-borders-radius-border-radius-200, 8px);
+      cursor: pointer;
+      font-family: var(--rel-fontFamilies-primary, sans-serif);
+      font-size: var(--rel-fontSizes-md, 14px);
+      font-weight: var(--rel-fontWeights-medium, 500);
+      color: var(--rel-text-primary, #333);
+      transition: background 0.15s ease, color 0.15s ease;
+      text-align: left;
+      position: relative;
+    }
+
+    button:hover:not([disabled]) {
+      background: var(--rel-surface-surface, #f5f5f5);
+      color: var(--rel-text-heading, #2b2b2b);
+    }
+
+    button:active:not([disabled]) {
+      background: var(--rel-border-default, #ddd);
+    }
+
+    button:focus-visible {
+      outline: 2px solid var(--rel-border-info, #0091ea);
+      outline-offset: -2px;
+    }
+
+    button[disabled] {
+      opacity: 0.5;
+      cursor: not-allowed;
+    }
+
+    button.active {
+      background: var(--rel-surface-surface, #f5f5f5);
+      color: var(--rel-text-heading, #2b2b2b);
+      font-weight: var(--rel-fontWeights-semibold, 600);
+    }
+
+    button.active::before {
+      content: "";
+      position: absolute;
+      left: 0;
+      top: 50%;
+      transform: translateY(-50%);
+      width: 3px;
+      height: 20px;
+      background: var(--rel-colors-primary-500, #0091ea);
+      border-radius: 0 2px 2px 0;
+    }
+
+    button.collapsed {
+      justify-content: center;
+      padding: var(--rel-spacing-space-xs, 8px);
+      min-height: 40px;
+    }
+
+    button.collapsed.active::before {
+      display: none;
+    }
+
+    button.collapsed.active {
+      background: var(--rel-surface-surface, #f5f5f5);
+    }
+
+    .icon {
+      flex-shrink: 0;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      width: 18px;
+      height: 18px;
+    }
+
+    .label {
+      flex: 1;
+      white-space: nowrap;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      line-height: 1.4;
+    }
+
+    button.collapsed .label {
+      display: none;
+    }
+  `;
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.findProvider();
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    if (this.provider) {
+      this.provider.removeEventListener(
+        "rel-sidebar-state",
+        this.handleStateChange,
+      );
+    }
+  }
+
+  private findProvider() {
+    let parent = this.parentElement;
+    while (parent) {
+      if (parent instanceof RelSidebarProvider) {
+        this.provider = parent;
+        break;
+      }
+      parent = parent.parentElement;
+    }
+
+    if (this.provider) {
+      this.provider.addEventListener(
+        "rel-sidebar-state",
+        this.handleStateChange,
+      );
+      this.syncState();
+    }
+  }
+
+  private syncState() {
+    if (!this.provider) return;
+    this.isCollapsed = this.provider.activeCollapsed && !this.provider.isMobile;
+  }
+
+  private handleStateChange = () => {
+    this.syncState();
+  };
+
+  render() {
+    const buttonClass = [
+      this.active ? "active" : "",
+      this.isCollapsed ? "collapsed" : "",
+    ]
+      .filter(Boolean)
+      .join(" ");
+
+    const tooltipTitle = this.isCollapsed && this.tooltip ? this.tooltip : "";
+
+    return html`
+      <button
+        class="${buttonClass}"
+        ?disabled="${this.disabled}"
+        title="${tooltipTitle}"
+        aria-current="${this.active ? "page" : "false"}"
+        part="button"
+      >
+        <span class="icon" part="icon">
+          ${this.icon ? html`<rel-icon name="${this.icon}"></rel-icon>` : nothing}
+        </span>
+        <span class="label" part="label">
+          <slot></slot>
+        </span>
+      </button>
+    `;
+  }
+}