DocsSubHeader.astro

---
/**
 * DocsSubHeader
 *
 * A secondary fixed header bar rendered below the GlobalNavBar.
 * Contains the search input and cross-product navigation links.
 *
 * Positioning (set in DocsLayout / custom.css):
 *   --docs-global-nav-height   height of the GlobalNavBar above (default 86px)
 *   --docs-subheader-height    height of this bar (default 40px)
 *
 * Note: The breadcrumb that previously lived in `.subheader-context` has been
 * moved to the `DocsBreadcrumb` component, rendered inside the main frame.
 */
import { platform as virtualPlatform } from 'virtual:docs-template/nav-html';
import { productLinks, sidebar as sidebarData, title as siteTitle, packages as virtualPackages, selectedPackage as virtualSelectedPackage } from 'virtual:docs-template/site-meta';
import Search from '../Search/Search.astro';
import type { SidebarEntry } from '../../lib/sidebar/types';
import { getBreadcrumb } from '../../lib/sidebar/helpers';
import './DocsSubHeader.scss';

const PLATFORM_ICONS: Record<string, string> = {
  angular: 'angular-logo',
  react: 'react-logo',
  blazor: 'blazor-logo',
  'web-components': 'wc-logo',
};

function getPlatformIcon(text: string): string | null {
  const t = text.toLowerCase();
  if (t.includes('angular'))                                                         return 'angular-logo';
  if (t.includes('react'))                                                           return 'react-logo';
  if (t.includes('blazor'))                                                          return 'blazor-logo';
  if (t.includes('web-component') || t.includes('webcomponent') || t.includes('wc')) return 'wc-logo';
  return null;
}

interface ProductLink {
  label: string;
  href: string;
  platform?: string;
}

interface Props {
  /** Fallback title if the slug is not present in the sidebar tree. */
  pageTitle?: string | null;
  /** Current page slug — used to derive the breadcrumb from the sidebar tree. */
  currentSlug?: string;
  /**
   * Override the site title shown on the left. Defaults to the virtual module value.
   * Useful when consuming without `siteMetaIntegration`.
   */
  siteTitle?: string;
  /**
   * Override the cross-product navigation links. Defaults to the virtual module value.
   * Useful when consuming without `siteMetaIntegration`.
   */
  productLinks?: ProductLink[];
  /**
   * Override the sidebar tree used for breadcrumb generation.
   * Defaults to the virtual module value.
   */
  sidebarItems?: SidebarEntry[];
  /**
   * Items for the package/platform selector dropdown. When omitted the selector is hidden.
   * Each entry is either a plain string label, or an object with a `label`, optional `value`
   * (defaults to `label`), and optional `href` to navigate to when selected.
   */
  packages?: Array<string | { label: string; value?: string; href?: string }>;
  /** Currently selected package value (must match one of `packages`). */
  selectedPackage?: string;
  /** Label rendered before the package selector. Defaults to `'Package'`. */
  packageLabel?: string;
  /** Version labels for the version selector dropdown. When omitted the selector is hidden. */
  versions?: string[];
  /** Currently selected version (must match one of `versions`). */
  selectedVersion?: string;
  /** Label rendered before the version selector. Defaults to `'Version'`. */
  versionLabel?: string;
  /** Show a light/dark theme toggle button. */
  showThemeToggle?: boolean;
  /** `localStorage` key for persisting the theme. Defaults to `'docs-theme'`. */
  themeStorageKey?: string;
  /**
   * Text label shown in the logo area when the GlobalNavBar is visible.
   * Fades out and is replaced by the SVG logo once the subheader becomes sticky.
   * Defaults to `'IgniteUI'`.
   */
  logoText?: string;
}

const {
  pageTitle = '',
  currentSlug = '',
  siteTitle: siteTitleProp,
  productLinks: productLinksProp,
  sidebarItems,
  packages: packagesProp,
  selectedPackage: selectedPackageProp,
  packageLabel = 'Package',
  versions,
  selectedVersion,
  versionLabel = 'Version',
  showThemeToggle = false,
  themeStorageKey = 'docs-theme',
  logoText = 'Ignite UI',
} = Astro.props;
const resolvedSiteTitle = siteTitleProp ?? siteTitle;
const currentPlatform = virtualPlatform ?? null;
const resolvedLinks = (productLinksProp ?? productLinks) as ProductLink[];
const filteredLinks = resolvedLinks.filter((l: ProductLink) => l.platform !== currentPlatform);
type PackageEntry = string | { label: string; value?: string; href?: string };
const rawPackages = packagesProp ?? (virtualPackages?.length > 0 ? virtualPackages : undefined);
const packages = (rawPackages as PackageEntry[] | undefined)?.map((p: PackageEntry) =>
    typeof p === 'string' ? { label: p, value: p, href: undefined } : { label: p.label, value: p.value ?? p.label, href: p.href }
);
const selectedPackage = selectedPackageProp ?? (virtualSelectedPackage || undefined) ?? packages?.[0]?.value;
const platformIcon = PLATFORM_ICONS[selectedPackage ?? ''] ?? PLATFORM_ICONS[currentPlatform ?? ''] ?? null;

const resolvedSidebar = (sidebarItems ?? sidebarData) as SidebarEntry[];
const sidebarCrumbs = currentSlug ? getBreadcrumb(resolvedSidebar, currentSlug) : [];
const crumbs = sidebarCrumbs.length > 0 ? sidebarCrumbs : (pageTitle ? [pageTitle] : []);

const PLATFORM_LABELS: Record<string, string> = {
  angular: 'Angular',
  react: 'React',
  blazor: 'Blazor',
  'web-components': 'Web Components',
};
const platformLabel = currentPlatform ? (PLATFORM_LABELS[currentPlatform] ?? null) : null;
---

<docs-subheader-menu class="igd-docs-subheader" data-platform={currentPlatform ?? ''}>
        <div class="igd-logo">
            <!-- Sidebar toggle — visible only when the sidebar is hidden (tablet + mobile) -->
            <igc-icon-button
                    class="subheader-sidebar-toggle"
                    variant="flat"
                    data-sidebar-toggle
                    aria-label="Toggle sidebar navigation"
                    aria-expanded="false"
                    title="Toggle sidebar">
                <igc-icon name="hamburger-menu" collection="docs" aria-hidden="true"></igc-icon>
            </igc-icon-button>
            <div class="igd-logo__text">
                {/* Keep as <span>, not <h1> — avoids competing with the page <h1> in search. */}
                <span class="igd-logo-text">{logoText}</span>
                {platformLabel && <span class="igd-logo__platform">for {platformLabel}</span>}
            </div>
        </div>

        <div class="igd-docs-subheader__content">
            <!-- Search (overridable via named slot) -->
            <slot name="search"><Search /></slot>

            <!-- Package selector -->
            {packages && packages.length > 0 && (
                <igc-select distance="4" id="package-select" class="igd-package-select" outlined value={selectedPackage} aria-label={packageLabel}>
                    {platformIcon && <igc-icon name={platformIcon} collection="docs" slot="prefix" aria-hidden="true"></igc-icon>}
                    {packages.map((p) => {
                        const icon = getPlatformIcon(p.value ?? '') ?? getPlatformIcon(p.label ?? '');
                        return (
                            <igc-select-item value={p.value} data-href={p.href}>
                                {icon && <igc-icon slot="prefix" name={icon} collection="docs" aria-hidden="true"></igc-icon>}
                                {p.label}
                            </igc-select-item>
                        );
                    })}
                </igc-select>
            )}

            <!-- Version selector -->
            {versions && versions.length > 0 && (
                <igc-select distance="4" id="version-select" class="igd-version-select" outlined value={selectedVersion} aria-label={versionLabel}>
                    {versions.map((v) => (
                        <igc-select-item value={v}>{v}</igc-select-item>
                    ))}
                </igc-select>
            )}


            <!-- TODO WHY WE NEED THIS? -->
            <!--{filteredLinks.length > 0 && (-->
            <!--    <div class="subheader-links">-->
            <!--        {filteredLinks.map((link, i) => (-->
            <!--                <>-->
            <!--                    {i > 0 && <span class="product-sep" aria-hidden="true">|</span>}-->
            <!--                    <a href={link.href} class="product-link">{link.label}</a>-->
            <!--                </>-->
            <!--        ))}-->
            <!--    </div>-->
            <!--)}-->
        </div>
</docs-subheader-menu>

<script>
    if (!customElements.get('docs-subheader-menu')) {
        class DocsSubHeaderMenu extends HTMLElement {
            private _ac: AbortController | null = null;

            connectedCallback() {
                this._ac?.abort();
                this._ac = new AbortController();
                const { signal } = this._ac;
                // Package selector navigation
                const packageSelect = this.querySelector('#package-select');
                const packageTooltip = this.querySelector<any>('#package-tooltip');
                if (packageSelect) {
                    // Truncates the native input value directly so the '\u2026' is baked in,
                    // Keep the full package label in the native input and apply truncation
                    // only as a visual style so assistive technologies still get the full text.
                    function applyTriggerTruncation() {
                        const igcInput = (packageSelect as any).shadowRoot?.querySelector('igc-input');
                        const nativeInput = igcInput?.shadowRoot?.querySelector('input') as HTMLInputElement | null;
                        if (!nativeInput || !nativeInput.value) return;

                        const text = nativeInput.value;

                        // Preserve the full label for accessibility and hover disclosure.
                        nativeInput.setAttribute('aria-label', text);
                        nativeInput.title = text;

                        // Apply truncation only to the rendered text.
                        nativeInput.style.overflow = 'hidden';
                        nativeInput.style.textOverflow = 'ellipsis';
                        nativeInput.style.whiteSpace = 'nowrap';
                    }

                    // Run after igcInput's Lit render cycle settles (two rAFs = after microtasks + first paint)
                    requestAnimationFrame(() => requestAnimationFrame(() => applyTriggerTruncation()));

                    // igcInput re-renders with the full text each time the dropdown closes;
                    // re-apply truncation afterwards.
                    packageSelect.addEventListener('igcClosed', () =>
                        requestAnimationFrame(() => applyTriggerTruncation())
                    );

                    packageSelect.addEventListener('igcChange', (e: Event) => {
                        const val = (e as CustomEvent).detail?.value ?? (packageSelect as any).value;
                        const item = packageSelect.querySelector<HTMLElement>(`igc-select-item[value="${val}"]`);
                        const href = item?.dataset?.href;
                        if (href) window.location.href = href;
                        // Sync tooltip content with the new selection label
                        if (packageTooltip) {
                            packageTooltip.textContent = item?.textContent?.trim() ?? val;
                        }
                    });
                }
                // Only show the package tooltip when the label is visually truncated
                if (packageTooltip && packageSelect) {
                    packageTooltip.addEventListener('igcOpening', (e: Event) => {
                        const igcInput = (packageSelect as any).shadowRoot?.querySelector('igc-input');
                        const nativeInput = igcInput?.shadowRoot?.querySelector('input');
                        // Show when we applied manual truncation (ends with '\u2026') or
                        // when there is natural CSS overflow.
                        const truncated = nativeInput?.value?.endsWith('\u2026');
                        const overflows = nativeInput && nativeInput.scrollWidth > nativeInput.clientWidth;
                        if (!truncated && !overflows) {
                            e.preventDefault();
                        }
                    });
                }

                // Close open selects on scroll, and prevent the browser's
                // focus-triggered scrollIntoView from jumping the page when a
                // select is clicked while the user is scrolled down.
                const selectsForScroll = Array.from(
                    this.querySelectorAll<HTMLElement>('#package-select, #version-select')
                );
                selectsForScroll.forEach(select => {
                    // Patch igc-input.focus to always use preventScroll:true.
                    // igc-select calls this._input.focus() programmatically on
                    // close/selection — this prevents those from scrolling the page.
                    // Click-to-open focus is browser-assigned and bypasses JS focus(),
                    // so it is handled separately by the savedY scroll guard below.
                    const igcInput = (select as any).shadowRoot?.querySelector('igc-input');
                    if (igcInput && !('_preventScrollPatched' in igcInput)) {
                        const orig = igcInput.focus.bind(igcInput);
                        igcInput.focus = (o?: FocusOptions) => orig({ ...o, preventScroll: true });
                        (igcInput as any)._preventScrollPatched = true;
                    }

                    let savedY: number | null = null;
                    let guardTimer: ReturnType<typeof setTimeout> | null = null;

                    select.addEventListener('pointerdown', () => {
                        savedY = window.scrollY;
                        if (guardTimer) clearTimeout(guardTimer);
                        guardTimer = setTimeout(() => { savedY = null; guardTimer = null; }, 300);

                        // DocsLayout sets scroll-behavior:smooth on <html>. The browser's
                        // focus-triggered scrollIntoView respects this and animates over
                        // multiple frames — our scroll correction fires mid-animation,
                        // leaving one rendered frame at the wrong position (the flicker).
                        // Temporarily forcing 'auto' makes the focus scroll instant so
                        // our correction applies in the same frame with no visible jump.
                        const html = document.documentElement;
                        html.style.scrollBehavior = 'auto';
                        select.addEventListener('focusin', () => {
                            requestAnimationFrame(() => { html.style.scrollBehavior = ''; });
                        }, { once: true, signal });
                        setTimeout(() => { html.style.scrollBehavior = ''; }, 500);
                    }, { signal });

                    window.addEventListener('scroll', () => {
                        if (savedY !== null) {
                            window.scrollTo({ top: savedY, left: 0, behavior: 'instant' as ScrollBehavior });
                            return;
                        }
                        if ((select as any).open) (select as any).hide();
                    }, { signal });
                });

                // Sidebar toggle
                const sidebarBtn = this.querySelector<HTMLButtonElement>('[data-sidebar-toggle]');
                if (sidebarBtn) {
                    sidebarBtn.addEventListener('click', () => {
                        const expanded = document.body.hasAttribute('data-sidebar-open');
                        document.body.toggleAttribute('data-sidebar-open', !expanded);
                        sidebarBtn.setAttribute('aria-expanded', String(!expanded));
                    }, { signal });
                }

                // Close sidebar on Escape
                document.addEventListener('keyup', (e: KeyboardEvent) => {
                    if (e.key === 'Escape' && document.body.hasAttribute('data-sidebar-open')) {
                        document.body.removeAttribute('data-sidebar-open');
                        sidebarBtn?.setAttribute('aria-expanded', 'false');
                        sidebarBtn?.focus();
                    }
                }, { signal });

                // Close sidebar on page navigation
                document.addEventListener('astro:page-load', () => {
                    document.body.removeAttribute('data-sidebar-open');
                    sidebarBtn?.setAttribute('aria-expanded', 'false');
                }, { signal });
            }

            disconnectedCallback() {
                this._ac?.abort();
            }
        }

        customElements.define('docs-subheader-menu', DocsSubHeaderMenu);
    }
</script>

<script>
    import { defineComponents, IgcIconComponent, IgcIconButtonComponent, IgcSelectComponent, IgcSelectItemComponent } from 'igniteui-webcomponents';
    import { registerIcons } from '../../scripts/icon-registry';
    defineComponents(IgcIconComponent, IgcIconButtonComponent, IgcSelectComponent, IgcSelectItemComponent);
    registerIcons();

    function getPlatformIcon(text: string): string | null {
        const t = text.toLowerCase();
        if (t.includes('angular'))                                                         return 'angular-logo';
        if (t.includes('react'))                                                           return 'react-logo';
        if (t.includes('blazor'))                                                          return 'blazor-logo';
        if (t.includes('web-component') || t.includes('webcomponent') || t.includes('wc')) return 'wc-logo';
        return null;
    }

    function syncTriggerIcon(select: Element, val: string) {
        const icon = getPlatformIcon(val);
        let prefixIcon = select.querySelector<any>(':scope > igc-icon[slot="prefix"]');
        if (icon) {
            if (!prefixIcon) {
                prefixIcon = document.createElement('igc-icon') as any;
                prefixIcon.setAttribute('slot', 'prefix');
                prefixIcon.setAttribute('aria-hidden', 'true');
                prefixIcon.setAttribute('collection', 'docs');
                select.prepend(prefixIcon);
            }
            prefixIcon.setAttribute('name', icon);
        } else if (prefixIcon) {
            prefixIcon.remove();
        }
    }

    function initSelectors() {
        const packageSelect = document.querySelector('#package-select');
        if (packageSelect) {
            packageSelect.addEventListener('igcChange', (e: Event) => {
                const val = (e as CustomEvent).detail?.value ?? (packageSelect as any).value;
                const item = packageSelect.querySelector<HTMLElement>(`igc-select-item[value="${val}"]`);
                syncTriggerIcon(packageSelect, val);
                const href = item?.dataset?.href;
                if (href) window.location.href = href;
            });
        }
    }

    document.addEventListener('astro:page-load', initSelectors);
    initSelectors();
</script>