ember-freestyle 0.21.0 → 0.23.0

package/CHANGELOG.md

@@ -6,6 +6,17 @@ All notable changes to this project will be documented in this file.
 
 
 
+
+## v0.23.0 (2026-03-22)
+
+#### :rocket: Enhancement
+* [#1025](https://github.com/chrislopresto/ember-freestyle/pull/1025) feat: enhanced FreestyleMenu with collapsible sections, search, keyboard nav, and scroll spy ([@mattmcmanus](https://github.com/mattmcmanus))
+
+#### Committers: 1
+- Matt McManus ([@mattmcmanus](https://github.com/mattmcmanus))
+
+## v0.22.0 (2025-03-18)
+
 ## v0.21.0 (2024-09-27)
 
 #### :boom: Breaking Change

package/addon/components/freestyle-guide/index.hbs

@@ -22,7 +22,7 @@
     </button>
   </header>
   <main class="FreestyleGuide-body">
-    <article class="FreestyleGuide-content">
+    <article class="FreestyleGuide-content" {{freestyle-scroll-spy}}>
       {{yield}}
       {{#if (and (not this.allowRenderingAllSections) (not this.isSectionSelected))}}
         <div class="FreestyleGuide-chooseSectionMessage" data-test-choose-section>

package/addon/components/freestyle-menu/index.hbs

@@ -1,27 +1,57 @@
-<ul class="FreestyleMenu">
-  {{#if this.includeAllOption}}
-    <li class="FreestyleMenu-item">
-      <LinkTo @query={{hash s=null ss=null f=null}} class="FreestyleMenu-itemLink">
-        All
-      </LinkTo>
-    </li>
-  {{/if}}
-  {{#each this.menu as |section|}}
-    <li class="FreestyleMenu-item">
-      <LinkTo @query={{hash f=null s=section.name ss=null}} class="FreestyleMenu-itemLink">
-        {{section.name}}
-      </LinkTo>
-      {{#if section.subsections.length}}
-        <ul class="FreestyleMenu-submenu">
-          {{#each section.subsections as |subsection|}}
-            <li class="FreestyleMenu-submenuItem">
-              <LinkTo @query={{hash f=null s=section.name ss=subsection.name}} class="FreestyleMenu-submenuItemLink">
-                {{subsection.name}}
-              </LinkTo>
-            </li>
-          {{/each}}
-        </ul>
-      {{/if}}
-    </li>
-  {{/each}}
-</ul>
+<nav class="FreestyleMenu" aria-label="Component navigation">
+  <div class="FreestyleMenu-search">
+    <input
+      type="text"
+      class="FreestyleMenu-searchInput"
+      placeholder="Filter components..."
+      aria-label="Filter components"
+      value={{this.filterText}}
+      {{on "input" this.onFilterInput}}
+      {{on "keydown" this.handleKeydown}}
+    />
+  </div>
+  <ul class="FreestyleMenu-list">
+    {{#if this.includeAllOption}}
+      <li class="FreestyleMenu-item">
+        <LinkTo @query={{hash s=null ss=null f=null}} class="FreestyleMenu-itemLink">
+          All
+        </LinkTo>
+      </li>
+    {{/if}}
+    {{#each this.filteredMenu as |entry|}}
+      <li class="FreestyleMenu-item {{if entry.isExpanded 'is-expanded'}} {{if entry.isSectionActive 'is-active'}}">
+        <div class="FreestyleMenu-itemHeader">
+          <LinkTo @query={{hash f=null s=entry.section.name ss=null}} class="FreestyleMenu-itemLink" {{on "click" (fn this.expandSection entry.section.name)}}>
+            {{#if entry.subsections.length}}
+              <span class="FreestyleMenu-chevron {{if entry.isExpanded 'is-expanded'}}"></span>
+            {{/if}}
+            {{entry.section.name}}
+          </LinkTo>
+          {{#if entry.subsections.length}}
+            <button
+              type="button"
+              class="FreestyleMenu-collapseToggle"
+              {{on "click" (fn this.toggleSection entry.section.name)}}
+              aria-label="Toggle {{entry.section.name}}"
+              aria-expanded="{{if entry.isExpanded 'true' 'false'}}"
+            ></button>
+          {{/if}}
+        </div>
+        {{#if (and entry.subsections.length entry.isExpanded)}}
+          <ul class="FreestyleMenu-submenu">
+            {{#each entry.subsections as |subsection|}}
+              <li
+                class="FreestyleMenu-submenuItem {{if subsection.isHighlighted 'is-highlighted'}} {{if subsection.isActive 'is-active'}}"
+                id="{{this.elementIdPrefix}}-item-{{subsection.flatIndex}}"
+              >
+                <LinkTo @query={{hash f=null s=entry.section.name ss=subsection.name}} class="FreestyleMenu-submenuItemLink">
+                  {{subsection.name}}
+                </LinkTo>
+              </li>
+            {{/each}}
+          </ul>
+        {{/if}}
+      </li>
+    {{/each}}
+  </ul>
+</nav>

package/addon/components/freestyle-menu/index.ts

@@ -3,9 +3,36 @@ import Component from '@glimmer/component';
 import { inject as service } from '@ember/service';
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import { reads } from 'macro-decorators';
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { action } from '@ember/object';
+import { tracked, cached } from '@glimmer/tracking';
+import { schedule } from '@ember/runloop';
+import { guidFor } from '@ember/object/internals';
+import type RouterService from '@ember/routing/router-service';
 import type EmberFreestyleService from '../../services/ember-freestyle';
-import { type Section } from '../../services/ember-freestyle';
-import { TrackedArray } from 'tracked-built-ins';
+import { type Section, type Subsection } from '../../services/ember-freestyle';
+import { TrackedArray, TrackedSet } from 'tracked-built-ins';
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface FilteredSubsection {
+  name: string;
+  flatIndex: number;
+  isHighlighted: boolean;
+  isActive: boolean;
+}
+
+export interface FilteredSection {
+  section: Section;
+  subsections: FilteredSubsection[];
+  isExpanded: boolean;
+  isSectionActive: boolean;
+}
+
+interface FlatSubsectionItem {
+  sectionName: string;
+  subsectionName: string;
+}
 
 interface Signature {
   Args: {
@@ -13,8 +40,290 @@ interface Signature {
   };
 }
 
+// ── DOM helpers ────────────────────────────────────────────────────────────
+
+function subsectionSelector(
+  sectionName: string,
+  subsectionName: string,
+): string {
+  return `.FreestyleSubsection[data-section="${sectionName}"][data-subsection="${subsectionName}"]`;
+}
+
+function scrollElementIntoView(
+  el: Element | null,
+  behavior: ScrollBehavior = 'auto',
+  block: ScrollLogicalPosition = 'nearest',
+): void {
+  if (el) {
+    el.scrollIntoView({ behavior, block });
+  }
+}
+
+// ── Component ──────────────────────────────────────────────────────────────
+
 export default class FreestyleMenu extends Component<Signature> {
   @service declare emberFreestyle: EmberFreestyleService;
+  @service declare router: RouterService;
   @reads('args.includeAllOption', true) declare includeAllOption: boolean;
   @reads('emberFreestyle.menu') declare menu: TrackedArray<Section>;
+
+  expandedSections = new TrackedSet<string>();
+  userCollapsedSections = new TrackedSet<string>();
+  @tracked filterText = '';
+  @tracked highlightedIndex = -1;
+
+  /** Stable prefix for element IDs to avoid collisions */
+  elementIdPrefix = `freestyle-menu-${guidFor(this)}`;
+
+  // ── Derived state ──────────────────────────────────────────────────────
+
+  get isFiltering(): boolean {
+    return this.filterText.length > 0;
+  }
+
+  get activeDescendantId(): string | undefined {
+    if (this.highlightedIndex >= 0) {
+      return `${this.elementIdPrefix}-item-${this.highlightedIndex}`;
+    }
+    return undefined;
+  }
+
+  /**
+   * Sections filtered by search text, with expansion state resolved.
+   * Does NOT include highlight/active enrichment — that's in `filteredMenu`.
+   */
+  @cached
+  get visibleSections(): {
+    section: Section;
+    subsections: Subsection[];
+    isExpanded: boolean;
+  }[] {
+    const filter = this.filterText.toLowerCase();
+    const spySection = this.emberFreestyle.scrollSpySection;
+    const hasKeyboardHighlight = this.highlightedIndex >= 0;
+
+    return this.menu
+      .map((section: Section) => {
+        if (!filter) {
+          let isExpanded = this.isSectionExpanded(section.name);
+
+          if (
+            !isExpanded &&
+            spySection === section.name &&
+            !hasKeyboardHighlight &&
+            section.subsections.length > 0 &&
+            !this.userCollapsedSections.has(section.name)
+          ) {
+            isExpanded = true;
+          }
+
+          return {
+            section,
+            subsections: section.subsections,
+            isExpanded,
+          };
+        }
+
+        const sectionMatches = section.name.toLowerCase().includes(filter);
+        const matchingSubs = sectionMatches
+          ? section.subsections
+          : section.subsections.filter((sub: Subsection) =>
+              sub.name.toLowerCase().includes(filter),
+            );
+
+        if (!sectionMatches && matchingSubs.length === 0) {
+          return null;
+        }
+
+        return { section, subsections: matchingSubs, isExpanded: true };
+      })
+      .filter(Boolean) as {
+      section: Section;
+      subsections: Subsection[];
+      isExpanded: boolean;
+    }[];
+  }
+
+  /**
+   * Enriches `visibleSections` with highlight/active state and flat indices
+   * for keyboard navigation and scroll spy. Also schedules sidebar
+   * auto-scroll when scroll spy is active.
+   */
+  get filteredMenu(): FilteredSection[] {
+    const spySection = this.emberFreestyle.scrollSpySection;
+    const spySubsection = this.emberFreestyle.scrollSpySubsection;
+    const hasKeyboardHighlight = this.highlightedIndex >= 0;
+    let flatIndex = 0;
+
+    const result = this.visibleSections.map(
+      ({ section, subsections, isExpanded }) => {
+        const enrichedSubs = isExpanded
+          ? subsections.map((sub: Subsection) => {
+              const idx = flatIndex++;
+              return {
+                name: sub.name,
+                flatIndex: idx,
+                isHighlighted: idx === this.highlightedIndex,
+                isActive:
+                  !hasKeyboardHighlight &&
+                  spySection === section.name &&
+                  spySubsection === sub.name,
+              };
+            })
+          : subsections.map((sub: Subsection) => ({
+              name: sub.name,
+              flatIndex: -1,
+              isHighlighted: false,
+              isActive: false,
+            }));
+
+        return {
+          section,
+          subsections: enrichedSubs,
+          isExpanded,
+          isSectionActive: !hasKeyboardHighlight && spySection === section.name,
+        };
+      },
+    );
+
+    // Clean up collapsed overrides for sections no longer in scroll spy
+    if (spySection) {
+      for (const name of this.userCollapsedSections) {
+        if (name !== spySection) {
+          schedule('afterRender', () =>
+            this.userCollapsedSections.delete(name),
+          );
+        }
+      }
+      schedule('afterRender', this, this.scrollActiveItemIntoView);
+    }
+
+    return result;
+  }
+
+  get flatSubsectionItems(): FlatSubsectionItem[] {
+    const items: FlatSubsectionItem[] = [];
+    for (const entry of this.filteredMenu) {
+      if (entry.isExpanded) {
+        for (const sub of entry.subsections) {
+          items.push({
+            sectionName: entry.section.name,
+            subsectionName: sub.name,
+          });
+        }
+      }
+    }
+    return items;
+  }
+
+  isSectionExpanded(sectionName: string): boolean {
+    const currentSection = this.emberFreestyle.section;
+    if (currentSection && currentSection === sectionName) {
+      return true;
+    }
+    return this.expandedSections.has(sectionName);
+  }
+
+  // ── Actions ────────────────────────────────────────────────────────────
+
+  @action
+  onFilterInput(event: Event): void {
+    this.filterText = (event.target as HTMLInputElement).value;
+    this.highlightedIndex = -1;
+  }
+
+  @action
+  handleKeydown(event: KeyboardEvent): void {
+    if (event.key === 'ArrowDown') {
+      event.preventDefault();
+      this.moveHighlight(1);
+    } else if (event.key === 'ArrowUp') {
+      event.preventDefault();
+      this.moveHighlight(-1);
+    } else if (event.key === 'Enter') {
+      event.preventDefault();
+      this.navigateToHighlighted();
+    } else if (event.key === 'Escape') {
+      this.filterText = '';
+      this.highlightedIndex = -1;
+    }
+  }
+
+  @action
+  toggleSection(sectionName: string): void {
+    if (this.expandedSections.has(sectionName)) {
+      this.expandedSections.delete(sectionName);
+      this.userCollapsedSections.add(sectionName);
+    } else {
+      this.expandedSections.add(sectionName);
+      this.userCollapsedSections.delete(sectionName);
+    }
+  }
+
+  @action
+  expandSection(sectionName: string): void {
+    this.expandedSections.add(sectionName);
+    this.userCollapsedSections.delete(sectionName);
+  }
+
+  // ── Navigation ─────────────────────────────────────────────────────────
+
+  moveHighlight(direction: 1 | -1): void {
+    const items = this.flatSubsectionItems;
+    const nextIndex = this.highlightedIndex + direction;
+
+    if (nextIndex < 0 || nextIndex >= items.length) return;
+
+    this.highlightedIndex = nextIndex;
+    schedule('afterRender', this, this.scrollHighlightedIntoView);
+
+    const item = items[nextIndex];
+    if (item) {
+      this.scrollToSubsection(item.sectionName, item.subsectionName);
+    }
+  }
+
+  navigateToHighlighted(): void {
+    const items = this.flatSubsectionItems;
+    if (this.highlightedIndex < 0 || this.highlightedIndex >= items.length) {
+      return;
+    }
+    const item = items[this.highlightedIndex];
+    if (!item) return;
+
+    this.expandedSections.add(item.sectionName);
+    this.router.transitionTo({
+      queryParams: {
+        f: null,
+        s: item.sectionName,
+        ss: item.subsectionName,
+      },
+    });
+
+    schedule('afterRender', () =>
+      this.scrollToSubsection(item.sectionName, item.subsectionName),
+    );
+  }
+
+  // ── Scroll helpers ─────────────────────────────────────────────────────
+
+  scrollToSubsection(sectionName: string, subsectionName: string): void {
+    const el = document.querySelector(
+      subsectionSelector(sectionName, subsectionName),
+    );
+    scrollElementIntoView(el, 'smooth', 'start');
+  }
+
+  scrollHighlightedIntoView(): void {
+    const el = document.getElementById(
+      `${this.elementIdPrefix}-item-${this.highlightedIndex}`,
+    );
+    scrollElementIntoView(el);
+  }
+
+  scrollActiveItemIntoView(): void {
+    scrollElementIntoView(
+      document.querySelector('.FreestyleMenu-submenuItem.is-active'),
+    );
+  }
 }

package/addon/components/freestyle-section/index.hbs

@@ -1,5 +1,6 @@
 <div
   class="FreestyleSection {{if this.show 'FreestyleSection--showing' 'FreestyleSection--hidden'}}"
+  data-section={{@name}}
   ...attributes
 >
   {{#if this.show}}

package/addon/components/freestyle-subsection/index.hbs

@@ -1,4 +1,6 @@
 <div class="FreestyleSubsection {{if this.show 'is-showing' 'is-hidden'}}"
+  data-section={{@section}}
+  data-subsection={{@name}}
   ...attributes
 >
   {{#if this.show}}

package/addon/modifiers/freestyle-scroll-spy.ts

@@ -0,0 +1,154 @@
+import Modifier from 'ember-modifier';
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { inject as service } from '@ember/service';
+import type EmberFreestyleService from '../services/ember-freestyle';
+
+const SELECTOR =
+  '.FreestyleSubsection.is-showing, .FreestyleSection.FreestyleSection--showing[data-section]';
+
+export default class FreestyleScrollSpy extends Modifier {
+  @service declare emberFreestyle: EmberFreestyleService;
+
+  private intersectionObserver: IntersectionObserver | null = null;
+  private mutationObserver: MutationObserver | null = null;
+  private visibleElements = new Set<Element>();
+  private observedElements = new Set<Element>();
+  private _isDestroyed = false;
+  private _service: EmberFreestyleService | null = null;
+  private _pendingMutationFrame: number | null = null;
+
+  modify(element: HTMLElement): void {
+    if (this.intersectionObserver) {
+      return;
+    }
+
+    // Eagerly resolve service while the owner is still alive
+    this._service = this.emberFreestyle;
+
+    this.intersectionObserver = new IntersectionObserver(
+      (entries) => {
+        if (this._isDestroyed) return;
+
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            this.visibleElements.add(entry.target);
+          } else {
+            this.visibleElements.delete(entry.target);
+          }
+        }
+        this.updateActive();
+      },
+      {
+        root: null,
+        threshold: 0,
+        // Shrink the effective viewport by 50px top so elements with just
+        // a sliver visible at the very top don't count as "topmost"
+        rootMargin: '-50px 0px 0px 0px',
+      },
+    );
+
+    // Debounce MutationObserver with rAF to coalesce rapid DOM changes
+    // (e.g. Glimmer's own rendering)
+    this.mutationObserver = new MutationObserver(() => {
+      if (this._isDestroyed) return;
+      if (this._pendingMutationFrame !== null) return;
+      this._pendingMutationFrame = requestAnimationFrame(() => {
+        this._pendingMutationFrame = null;
+        if (this._isDestroyed) return;
+        this.syncObservedElements(element);
+      });
+    });
+
+    this.mutationObserver.observe(element, {
+      childList: true,
+      subtree: true,
+    });
+
+    this.syncObservedElements(element);
+  }
+
+  /**
+   * Diff-based re-observation: only observe/unobserve elements that changed,
+   * preserving the IntersectionObserver's internal state and visibleElements set.
+   */
+  private syncObservedElements(container: HTMLElement): void {
+    if (!this.intersectionObserver) return;
+
+    const currentElements = new Set(container.querySelectorAll(SELECTOR));
+
+    // Unobserve elements that are no longer in the DOM
+    for (const el of this.observedElements) {
+      if (!currentElements.has(el)) {
+        this.intersectionObserver.unobserve(el);
+        this.observedElements.delete(el);
+        this.visibleElements.delete(el);
+      }
+    }
+
+    // Observe newly added elements
+    for (const el of currentElements) {
+      if (!this.observedElements.has(el)) {
+        this.intersectionObserver.observe(el);
+        this.observedElements.add(el);
+      }
+    }
+  }
+
+  private updateActive(): void {
+    if (this._isDestroyed || !this._service) return;
+
+    let topmostSubsection: Element | null = null;
+    let topmostSubsectionTop = Infinity;
+    let topmostSection: Element | null = null;
+    let topmostSectionTop = Infinity;
+
+    for (const el of this.visibleElements) {
+      const isSubsection =
+        el.classList.contains('FreestyleSubsection') &&
+        el.classList.contains('is-showing');
+      const isSection =
+        el.classList.contains('FreestyleSection') &&
+        el.classList.contains('FreestyleSection--showing');
+
+      if (!isSubsection && !isSection) continue;
+
+      const rect = el.getBoundingClientRect();
+
+      if (isSubsection && rect.top < topmostSubsectionTop) {
+        topmostSubsectionTop = rect.top;
+        topmostSubsection = el;
+      }
+      if (isSection && rect.top < topmostSectionTop) {
+        topmostSectionTop = rect.top;
+        topmostSection = el;
+      }
+    }
+
+    // Prefer subsections; fall back to section-level for sections without children
+    const topmost = topmostSubsection || topmostSection;
+    if (topmost) {
+      const section = topmost.getAttribute('data-section');
+      const subsection = topmost.getAttribute('data-subsection') || null;
+      this._service.setScrollSpyActive(section, subsection);
+    } else {
+      this._service.setScrollSpyActive(null, null);
+    }
+  }
+
+  willDestroy(): void {
+    this._isDestroyed = true;
+    this._service = null;
+    if (this._pendingMutationFrame !== null) {
+      cancelAnimationFrame(this._pendingMutationFrame);
+      this._pendingMutationFrame = null;
+    }
+    const io = this.intersectionObserver;
+    const mo = this.mutationObserver;
+    this.intersectionObserver = null;
+    this.mutationObserver = null;
+    this.visibleElements.clear();
+    this.observedElements.clear();
+    if (io) io.disconnect();
+    if (mo) mo.disconnect();
+  }
+}

package/addon/services/ember-freestyle.ts

@@ -10,7 +10,7 @@ export interface Section {
   subsections: Subsection[];
 }
 
-interface Subsection {
+export interface Subsection {
   name: string;
 }
 
@@ -31,6 +31,16 @@ export default class EmberFreestyleService extends Service {
   @tracked subsection = null;
   @tracked focus: string | null = null;
 
+  @tracked scrollSpySection: string | null = null;
+  @tracked scrollSpySubsection: string | null = null;
+
+  @action
+  setScrollSpyActive(section: string | null, subsection: string | null): void {
+    if (this.isDestroyed || this.isDestroying) return;
+    this.scrollSpySection = section;
+    this.scrollSpySubsection = subsection;
+  }
+
   get notFocused(): boolean {
     return !this.focus;
   }

package/addon/template-registry.ts

@@ -34,6 +34,7 @@ import type FreestyleUsageString from 'ember-freestyle/components/freestyle/usag
 
 // modifiers
 import type FreestyleHighlight from 'ember-freestyle/modifiers/freestyle-highlight';
+import type FreestyleScrollSpy from 'ember-freestyle/modifiers/freestyle-scroll-spy';
 import EnsureFreestyleTheme from './modifiers/ensure-freestyle-theme';
 
 export default interface EmberFreestyleRegistry {
@@ -105,5 +106,6 @@ export default interface EmberFreestyleRegistry {
 
   // modifiers
   'freestyle-highlight': typeof FreestyleHighlight;
+  'freestyle-scroll-spy': typeof FreestyleScrollSpy;
   'ensure-freestyle-theme': typeof EnsureFreestyleTheme;
 }

package/app/modifiers/freestyle-scroll-spy.js

@@ -0,0 +1 @@
+export { default } from 'ember-freestyle/modifiers/freestyle-scroll-spy';

package/app/styles/components/freestyle-menu.scss

@@ -1,37 +1,186 @@
+// Darker variant of primary for active text (avoids deprecated darken())
+$FreestyleMenu-color--active: #008a9e;
+
 .FreestyleMenu {
   font-size: 14px;
   list-style: none;
-  padding-left: 1rem;
+  padding: 0;
+  margin: 0;
 
-  &-item,
-  &-submenuItem {
-    padding-top: 0.1rem;
+  &-search {
+    padding: 0 0.75rem 0.75rem;
   }
 
-  &-itemLink,
-  &-submenuItemLink {
-    border-radius: 6px;
+  &-searchInput {
+    box-sizing: border-box;
+    width: 100%;
+    padding: 0.5rem 0.75rem;
+    border: none;
+    border-radius: 100px;
+    font-size: 13px;
+    font-family: inherit;
+    outline: none;
+    background-color: rgba($FreestyleGuide-color--foreground, 0.06);
+    color: $FreestyleGuide-color--foreground;
+
+    &::placeholder {
+      color: rgba($FreestyleGuide-color--foreground, 0.5);
+    }
+
+    &:focus {
+      background-color: rgba($FreestyleGuide-color--foreground, 0.1);
+      box-shadow: 0 0 0 2px rgba($FreestyleGuide-color--primary, 0.3);
+    }
+  }
+
+  &-list {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+  }
+
+  // Top-level menu items (section groups)
+  &-item {
+    list-style: none;
+    margin: 0 0.5rem;
+    border-radius: 12px;
+    transition: background-color 0.2s ease;
+
+    // Expanded group: tinted background
+    &.is-expanded {
+      background-color: rgba($FreestyleGuide-color--primary, 0.06);
+      margin-bottom: 2px;
+      padding-bottom: 2px;
+    }
+
+    // Section-level scroll spy active (sections without children)
+    &.is-active:not(.is-expanded) {
+      background-color: rgba($FreestyleGuide-color--primary, 0.1);
+    }
+  }
+
+  &-itemHeader {
+    position: relative;
+  }
+
+  &-chevron {
+    display: inline-block;
+    width: 0;
+    height: 0;
+    border-top: 3.5px solid transparent;
+    border-bottom: 3.5px solid transparent;
+    border-left: 5px solid currentColor;
+    margin-right: 0.3rem;
+    transition: transform 0.2s ease;
+    vertical-align: middle;
+    opacity: 0.5;
+
+    &.is-expanded {
+      transform: rotate(90deg);
+    }
+  }
+
+  // Toggle overlay on chevron area
+  &-collapseToggle {
+    position: absolute;
+    left: 0;
+    top: 0;
+    width: 2rem;
+    height: 100%;
+    background: none;
+    border: none;
+    cursor: pointer;
+    padding: 0;
+
+    &:focus-visible {
+      outline: 2px solid $FreestyleGuide-color--primary;
+      outline-offset: -2px;
+      border-radius: 4px;
+    }
+  }
+
+  // Section header links — padding-left accounts for chevron width so
+  // items with and without chevrons align their text at the same position
+  &-itemLink {
+    border-radius: 100px;
     color: $FreestyleGuide-color--foreground;
     display: block;
-    padding: 0.3rem 0.3rem 0.3rem 0.5rem;
+    padding: 0.45rem 0.75rem 0.45rem 1.4rem;
     text-decoration: none;
+    font-weight: 500;
+    letter-spacing: 0.01em;
 
+    // Ember active route
     &.active {
-      background-color: $FreestyleGuide-color--primary;
-      color: white;
+      background-color: rgba($FreestyleGuide-color--primary, 0.18);
+      color: $FreestyleMenu-color--active;
       text-decoration: none;
-      font-weight: bold;
+      font-weight: 600;
     }
 
     &:hover {
-      background-color: $FreestyleGuide-color--primary;
-      color: white;
+      background-color: rgba($FreestyleGuide-color--foreground, 0.06);
       text-decoration: none;
     }
+
+    // Bold when section is expanded
+    .FreestyleMenu-item.is-expanded > .FreestyleMenu-itemHeader > & {
+      font-weight: 600;
+    }
+
+    // Bold when section is scroll-spy active (no children)
+    .FreestyleMenu-item.is-active > .FreestyleMenu-itemHeader > & {
+      font-weight: 600;
+    }
   }
 
+  // Child item list
   &-submenu {
     list-style: none;
-    padding-left: 1rem;
+    padding: 0 0 0.15rem;
+    margin: 0;
+  }
+
+  // Child item links
+  &-submenuItemLink {
+    border-radius: 100px;
+    color: rgba($FreestyleGuide-color--foreground, 0.7);
+    display: block;
+    padding: 0.3rem 0.75rem 0.3rem 1.75rem;
+    text-decoration: none;
+    font-size: 12px;
+    font-weight: 400;
+    letter-spacing: 0.01em;
+
+    // Ember active route
+    &.active {
+      background-color: rgba($FreestyleGuide-color--primary, 0.18);
+      color: $FreestyleMenu-color--active;
+      text-decoration: none;
+      font-weight: 600;
+    }
+
+    &:hover {
+      background-color: rgba($FreestyleGuide-color--foreground, 0.06);
+      color: $FreestyleGuide-color--foreground;
+      text-decoration: none;
+    }
+
+    // Keyboard highlight
+    .FreestyleMenu-submenuItem.is-highlighted > & {
+      background-color: rgba($FreestyleGuide-color--primary, 0.18);
+      color: $FreestyleMenu-color--active;
+      font-weight: 600;
+    }
+
+    // Scroll spy active: bold text (section group already has tint)
+    .FreestyleMenu-submenuItem.is-active > & {
+      color: $FreestyleGuide-color--foreground;
+      font-weight: 700;
+    }
+  }
+
+  &-submenuItem {
+    padding: 0 0.35rem;
   }
 }

package/components/freestyle-menu/index.d.ts

@@ -1,7 +1,24 @@
 import Component from '@glimmer/component';
+import type RouterService from '@ember/routing/router-service';
 import type EmberFreestyleService from '../../services/ember-freestyle';
-import { type Section } from '../../services/ember-freestyle';
-import { TrackedArray } from 'tracked-built-ins';
+import { type Section, type Subsection } from '../../services/ember-freestyle';
+import { TrackedArray, TrackedSet } from 'tracked-built-ins';
+export interface FilteredSubsection {
+    name: string;
+    flatIndex: number;
+    isHighlighted: boolean;
+    isActive: boolean;
+}
+export interface FilteredSection {
+    section: Section;
+    subsections: FilteredSubsection[];
+    isExpanded: boolean;
+    isSectionActive: boolean;
+}
+interface FlatSubsectionItem {
+    sectionName: string;
+    subsectionName: string;
+}
 interface Signature {
     Args: {
         includeAllOption?: boolean;
@@ -9,7 +26,42 @@ interface Signature {
 }
 export default class FreestyleMenu extends Component<Signature> {
     emberFreestyle: EmberFreestyleService;
+    router: RouterService;
     includeAllOption: boolean;
     menu: TrackedArray<Section>;
+    expandedSections: TrackedSet<string>;
+    userCollapsedSections: TrackedSet<string>;
+    filterText: string;
+    highlightedIndex: number;
+    /** Stable prefix for element IDs to avoid collisions */
+    elementIdPrefix: string;
+    get isFiltering(): boolean;
+    get activeDescendantId(): string | undefined;
+    /**
+     * Sections filtered by search text, with expansion state resolved.
+     * Does NOT include highlight/active enrichment — that's in `filteredMenu`.
+     */
+    get visibleSections(): {
+        section: Section;
+        subsections: Subsection[];
+        isExpanded: boolean;
+    }[];
+    /**
+     * Enriches `visibleSections` with highlight/active state and flat indices
+     * for keyboard navigation and scroll spy. Also schedules sidebar
+     * auto-scroll when scroll spy is active.
+     */
+    get filteredMenu(): FilteredSection[];
+    get flatSubsectionItems(): FlatSubsectionItem[];
+    isSectionExpanded(sectionName: string): boolean;
+    onFilterInput(event: Event): void;
+    handleKeydown(event: KeyboardEvent): void;
+    toggleSection(sectionName: string): void;
+    expandSection(sectionName: string): void;
+    moveHighlight(direction: 1 | -1): void;
+    navigateToHighlighted(): void;
+    scrollToSubsection(sectionName: string, subsectionName: string): void;
+    scrollHighlightedIntoView(): void;
+    scrollActiveItemIntoView(): void;
 }
 export {};

package/modifiers/freestyle-scroll-spy.d.ts

@@ -0,0 +1,20 @@
+import Modifier from 'ember-modifier';
+import type EmberFreestyleService from '../services/ember-freestyle';
+export default class FreestyleScrollSpy extends Modifier {
+    emberFreestyle: EmberFreestyleService;
+    private intersectionObserver;
+    private mutationObserver;
+    private visibleElements;
+    private observedElements;
+    private _isDestroyed;
+    private _service;
+    private _pendingMutationFrame;
+    modify(element: HTMLElement): void;
+    /**
+     * Diff-based re-observation: only observe/unobserve elements that changed,
+     * preserving the IntersectionObserver's internal state and visibleElements set.
+     */
+    private syncObservedElements;
+    private updateActive;
+    willDestroy(): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ember-freestyle",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Create a living styleguide for your Ember app.",
   "keywords": [
     "ember-addon"
@@ -39,6 +39,7 @@
     "@glimmer/component": "^1.1.2",
     "@glimmer/tracking": "^1.1.2",
     "ember-auto-import": "^2.4.3",
+    "ember-cached-decorator-polyfill": "^1.0.2",
     "ember-cli-babel": "^8.2.0",
     "ember-cli-htmlbars": "^6.3.0",
     "ember-cli-typescript": "^5.1.1",
@@ -49,7 +50,7 @@
     "json-formatter-js": "^2.3.4",
     "macro-decorators": "^0.1.2",
     "strip-indent": "^3.0.0",
-    "tracked-built-ins": "^3.1.0"
+    "tracked-built-ins": "^3.1.0 || ^4.0.0"
   },
   "devDependencies": {
     "@ember/optional-features": "^2.0.0",

package/services/ember-freestyle.d.ts

@@ -4,7 +4,7 @@ export interface Section {
     name: string;
     subsections: Subsection[];
 }
-interface Subsection {
+export interface Subsection {
     name: string;
 }
 export default class EmberFreestyleService extends Service {
@@ -19,6 +19,9 @@ export default class EmberFreestyleService extends Service {
     section: null;
     subsection: null;
     focus: string | null;
+    scrollSpySection: string | null;
+    scrollSpySubsection: string | null;
+    setScrollSpyActive(section: string | null, subsection: string | null): void;
     get notFocused(): boolean;
     shouldShowSection(sectionName: string): boolean;
     shouldShowSubsection(sectionName: string, subsectionName: string): boolean;
@@ -40,4 +43,3 @@ declare module '@ember/service' {
         'ember-freestyle': EmberFreestyleService;
     }
 }
-export {};

package/template-registry.d.ts

@@ -31,6 +31,7 @@ import type FreestyleUsageObject from 'ember-freestyle/components/freestyle/usag
 import type FreestyleUsageStringControl from 'ember-freestyle/components/freestyle/usage/string/control';
 import type FreestyleUsageString from 'ember-freestyle/components/freestyle/usage/string';
 import type FreestyleHighlight from 'ember-freestyle/modifiers/freestyle-highlight';
+import type FreestyleScrollSpy from 'ember-freestyle/modifiers/freestyle-scroll-spy';
 import EnsureFreestyleTheme from './modifiers/ensure-freestyle-theme';
 export default interface EmberFreestyleRegistry {
     'freestyle-annotation': typeof FreestyleAnnotation;
@@ -98,5 +99,6 @@ export default interface EmberFreestyleRegistry {
     'freestyle/usage/string': typeof FreestyleUsageString;
     'Freestyle::Usage::String': typeof FreestyleUsageString;
     'freestyle-highlight': typeof FreestyleHighlight;
+    'freestyle-scroll-spy': typeof FreestyleScrollSpy;
     'ensure-freestyle-theme': typeof EnsureFreestyleTheme;
 }

package/types/glimmer-tracking-cached.d.ts

@@ -0,0 +1,10 @@
+// Type augmentation for @cached (provided at runtime by ember-cached-decorator-polyfill)
+import '@glimmer/tracking';
+
+declare module '@glimmer/tracking' {
+  export function cached(
+    target: object,
+    propertyKey: string,
+    descriptor: PropertyDescriptor,
+  ): PropertyDescriptor;
+}

package/vendor/ember-freestyle.css

@@ -324,32 +324,146 @@ END-FREESTYLE-USAGE */
 .FreestyleMenu {
   font-size: 14px;
   list-style: none;
-  padding-left: 1rem;
+  padding: 0;
+  margin: 0;
 }
-.FreestyleMenu-item, .FreestyleMenu-submenuItem {
-  padding-top: 0.1rem;
+.FreestyleMenu-search {
+  padding: 0 0.75rem 0.75rem;
 }
-.FreestyleMenu-itemLink, .FreestyleMenu-submenuItemLink {
-  border-radius: 6px;
+.FreestyleMenu-searchInput {
+  box-sizing: border-box;
+  width: 100%;
+  padding: 0.5rem 0.75rem;
+  border: none;
+  border-radius: 100px;
+  font-size: 13px;
+  font-family: inherit;
+  outline: none;
+  background-color: rgba(33, 33, 33, 0.06);
+  color: #212121;
+}
+.FreestyleMenu-searchInput::placeholder {
+  color: rgba(33, 33, 33, 0.5);
+}
+.FreestyleMenu-searchInput:focus {
+  background-color: rgba(33, 33, 33, 0.1);
+  box-shadow: 0 0 0 2px rgba(0, 188, 212, 0.3);
+}
+.FreestyleMenu-list {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+.FreestyleMenu-item {
+  list-style: none;
+  margin: 0 0.5rem;
+  border-radius: 12px;
+  transition: background-color 0.2s ease;
+}
+.FreestyleMenu-item.is-expanded {
+  background-color: rgba(0, 188, 212, 0.06);
+  margin-bottom: 2px;
+  padding-bottom: 2px;
+}
+.FreestyleMenu-item.is-active:not(.is-expanded) {
+  background-color: rgba(0, 188, 212, 0.1);
+}
+.FreestyleMenu-itemHeader {
+  position: relative;
+}
+.FreestyleMenu-chevron {
+  display: inline-block;
+  width: 0;
+  height: 0;
+  border-top: 3.5px solid transparent;
+  border-bottom: 3.5px solid transparent;
+  border-left: 5px solid currentColor;
+  margin-right: 0.3rem;
+  transition: transform 0.2s ease;
+  vertical-align: middle;
+  opacity: 0.5;
+}
+.FreestyleMenu-chevron.is-expanded {
+  transform: rotate(90deg);
+}
+.FreestyleMenu-collapseToggle {
+  position: absolute;
+  left: 0;
+  top: 0;
+  width: 2rem;
+  height: 100%;
+  background: none;
+  border: none;
+  cursor: pointer;
+  padding: 0;
+}
+.FreestyleMenu-collapseToggle:focus-visible {
+  outline: 2px solid #00bcd4;
+  outline-offset: -2px;
+  border-radius: 4px;
+}
+.FreestyleMenu-itemLink {
+  border-radius: 100px;
   color: #212121;
   display: block;
-  padding: 0.3rem 0.3rem 0.3rem 0.5rem;
+  padding: 0.45rem 0.75rem 0.45rem 1.4rem;
   text-decoration: none;
+  font-weight: 500;
+  letter-spacing: 0.01em;
 }
-.FreestyleMenu-itemLink.active, .FreestyleMenu-submenuItemLink.active {
-  background-color: #00bcd4;
-  color: white;
+.FreestyleMenu-itemLink.active {
+  background-color: rgba(0, 188, 212, 0.18);
+  color: #008a9e;
   text-decoration: none;
-  font-weight: bold;
+  font-weight: 600;
 }
-.FreestyleMenu-itemLink:hover, .FreestyleMenu-submenuItemLink:hover {
-  background-color: #00bcd4;
-  color: white;
+.FreestyleMenu-itemLink:hover {
+  background-color: rgba(33, 33, 33, 0.06);
   text-decoration: none;
 }
+.FreestyleMenu-item.is-expanded > .FreestyleMenu-itemHeader > .FreestyleMenu-itemLink {
+  font-weight: 600;
+}
+.FreestyleMenu-item.is-active > .FreestyleMenu-itemHeader > .FreestyleMenu-itemLink {
+  font-weight: 600;
+}
 .FreestyleMenu-submenu {
   list-style: none;
-  padding-left: 1rem;
+  padding: 0 0 0.15rem;
+  margin: 0;
+}
+.FreestyleMenu-submenuItemLink {
+  border-radius: 100px;
+  color: rgba(33, 33, 33, 0.7);
+  display: block;
+  padding: 0.3rem 0.75rem 0.3rem 1.75rem;
+  text-decoration: none;
+  font-size: 12px;
+  font-weight: 400;
+  letter-spacing: 0.01em;
+}
+.FreestyleMenu-submenuItemLink.active {
+  background-color: rgba(0, 188, 212, 0.18);
+  color: #008a9e;
+  text-decoration: none;
+  font-weight: 600;
+}
+.FreestyleMenu-submenuItemLink:hover {
+  background-color: rgba(33, 33, 33, 0.06);
+  color: #212121;
+  text-decoration: none;
+}
+.FreestyleMenu-submenuItem.is-highlighted > .FreestyleMenu-submenuItemLink {
+  background-color: rgba(0, 188, 212, 0.18);
+  color: #008a9e;
+  font-weight: 600;
+}
+.FreestyleMenu-submenuItem.is-active > .FreestyleMenu-submenuItemLink {
+  color: #212121;
+  font-weight: 700;
+}
+.FreestyleMenu-submenuItem {
+  padding: 0 0.35rem;
 }
 
 .FreestyleSource-title {