An open source design system that's fully customizable and agent ready
TypeScript
feat(SideNav, TopNav): add menu popover and heading variants (#1272)
Ernest121d6a014a39
diff --git a/apps/sandbox/public/templates/xds-logo.svg b/apps/sandbox/public/templates/xds-logo.svgnew file mode 100644index 0000000000..99e6cc7f7b--- /dev/null+++ b/apps/sandbox/public/templates/xds-logo.svg@@ -0,0 +1,12 @@+<svg viewBox="0 0 64 48" fill="none" xmlns="http://www.w3.org/2000/svg">+<g id="Frame 1964296695">+<rect width="64" height="48" fill="white" style="fill:white;fill-opacity:1;"/>+<g id="Logo">+<path d="M22.34 6H28V8.76923H22.34C20.2659 8.76923 18.8844 8.77153 17.8243 8.86001C16.7984 8.94562 16.3311 9.09684 16.0347 9.25205C15.2906 9.64168 14.6821 10.2435 14.2882 10.9794C14.1313 11.2725 13.9784 11.7347 13.8918 12.7493C13.8023 13.7978 13.8 15.1641 13.8 17.2154V30.7846C13.8 32.8359 13.8023 34.2022 13.8918 35.2507C13.9784 36.2653 14.1313 36.7275 14.2882 37.0206C14.6821 37.7565 15.2906 38.3583 16.0347 38.7479C16.3311 38.9032 16.7984 39.0544 17.8243 39.14C18.8844 39.2285 20.2659 39.2308 22.34 39.2308H28V42H22.34C18.2875 42 16.2612 42 14.7245 41.1953C13.4844 40.5459 12.4702 39.5429 11.8136 38.3164C11 36.7966 11 34.7926 11 30.7846V17.2154C11 13.2074 11 11.2034 11.8136 9.68356C12.4702 8.45709 13.4844 7.45408 14.7245 6.8047C16.2612 6 18.2875 6 22.34 6Z" fill="var(--fill-0, black)" style="fill:black;fill-opacity:1;"/>+<path d="M41.66 39.2308H36V42H41.66C45.7125 42 47.7388 42 49.2755 41.1953C50.5156 40.5459 51.5298 39.5429 52.1864 38.3164C53 36.7966 53 34.7926 53 30.7846V17.2154C53 13.2074 53 11.2034 52.1864 9.68356C51.5298 8.45709 50.5156 7.45408 49.2755 6.8047C47.7388 6 45.7125 6 41.66 6H36V8.76923H41.66C43.7341 8.76923 45.1156 8.77153 46.1757 8.86001C47.2016 8.94562 47.6689 9.09684 47.9653 9.25205C48.7094 9.64168 49.3179 10.2435 49.7118 10.9794C49.8687 11.2725 50.0216 11.7347 50.1082 12.7493C50.1977 13.7978 50.2 15.1641 50.2 17.2154V30.7846C50.2 32.8359 50.1977 34.2022 50.1082 35.2507C50.0216 36.2653 49.8687 36.7275 49.7118 37.0206C49.3179 37.7565 48.7094 38.3583 47.9653 38.7479C47.6689 38.9032 47.2016 39.0544 46.1757 39.14C45.1156 39.2285 43.7341 39.2308 41.66 39.2308Z" fill="var(--fill-0, black)" style="fill:black;fill-opacity:1;"/>+<path d="M17.9708 26.7697C17.3758 27.6648 16.8333 28.545 16.3433 29.4104H18.6833C19.0083 28.7824 19.3858 28.1271 19.8158 27.4447C20.2458 26.7623 20.6833 26.0972 21.1283 25.4494C21.5733 26.0873 22.0083 26.7524 22.4333 27.4447C22.8633 28.137 23.2458 28.7922 23.5808 29.4104H26.0558C25.5708 28.5598 25.0308 27.6895 24.4358 26.7994C23.8458 25.9043 23.2483 25.0464 22.6433 24.2255C23.2333 23.3947 23.8208 22.5367 24.4058 21.6516C24.9958 20.7615 25.5358 19.8862 26.0258 19.0258H23.6933C23.3683 19.6439 22.9933 20.2917 22.5683 20.9692C22.1433 21.6466 21.7108 22.3043 21.2708 22.9422C20.8308 22.3093 20.4008 21.6516 19.9808 20.9692C19.5608 20.2867 19.1858 19.6389 18.8558 19.0258H16.3733C16.8533 19.8664 17.3858 20.7318 17.9708 21.6219C18.5608 22.5071 19.1583 23.3576 19.7633 24.1736C19.1633 25.0093 18.5658 25.8747 17.9708 26.7697Z" fill="var(--fill-0, black)" style="fill:black;fill-opacity:1;"/>+<path fill-rule="evenodd" clip-rule="evenodd" d="M27.6257 19.0258V29.4104H31.9232C33.0282 29.4104 33.9782 29.1878 34.7732 28.7428C35.5732 28.2928 36.1882 27.6771 36.6182 26.8958C37.0482 26.1145 37.2632 25.2219 37.2632 24.2181C37.2632 23.2142 37.0482 22.3216 36.6182 21.5403C36.1882 20.759 35.5732 20.1458 34.7732 19.7008C33.9782 19.2508 33.0282 19.0258 31.9232 19.0258H27.6257ZM29.7782 20.9469H31.9157C32.8957 20.9469 33.6607 21.2461 34.2107 21.8444C34.7607 22.4378 35.0357 23.2291 35.0357 24.2181C35.0357 25.2021 34.7607 25.9933 34.2107 26.5917C33.6607 27.19 32.8957 27.4892 31.9157 27.4892H29.7782V20.9469Z" fill="var(--fill-0, black)" style="fill:black;fill-opacity:1;"/>+<path d="M40.1569 29.084C40.9269 29.4252 41.8244 29.5958 42.8494 29.5958H43.0669C44.3519 29.5958 45.3669 29.3139 46.1119 28.7502C46.8569 28.1865 47.2294 27.4076 47.2294 26.4137C47.2294 25.8203 47.1094 25.3332 46.8694 24.9524C46.6294 24.5667 46.3269 24.2626 45.9619 24.04C45.6019 23.8175 45.2369 23.6519 44.8669 23.5431C44.4969 23.4343 44.1794 23.3552 43.9144 23.3057L42.3319 23.0016C41.8769 22.9126 41.5019 22.7914 41.2069 22.6381C40.9169 22.4799 40.7719 22.2203 40.7719 21.8593C40.7719 21.5032 40.9444 21.2238 41.2894 21.0211C41.6344 20.8134 42.1169 20.7096 42.7369 20.7096H42.9469C43.4669 20.7096 43.9544 20.8085 44.4094 21.0063C44.8694 21.2041 45.3069 21.5428 45.7219 22.0225L47.0494 20.7466C46.5644 20.1285 45.9794 19.6563 45.2944 19.3299C44.6144 19.0035 43.8394 18.8403 42.9694 18.8403H42.7519C41.9219 18.8403 41.1969 18.9714 40.5769 19.2335C39.9619 19.4906 39.4819 19.8565 39.1369 20.3313C38.7969 20.806 38.6269 21.3672 38.6269 22.015C38.6269 22.5392 38.7294 22.9793 38.9344 23.3354C39.1444 23.6914 39.4119 23.9807 39.7369 24.2032C40.0669 24.4258 40.4169 24.6013 40.7869 24.7299C41.1569 24.8535 41.5019 24.945 41.8219 25.0043L43.4044 25.3159C43.6644 25.3653 43.9219 25.4346 44.1769 25.5236C44.4369 25.6076 44.6519 25.7313 44.8219 25.8944C44.9919 26.0576 45.0769 26.2802 45.0769 26.562C45.0769 27.3236 44.3969 27.7043 43.0369 27.7043H42.8269C42.1869 27.7043 41.5994 27.5856 41.0644 27.3483C40.5344 27.106 40.0619 26.7376 39.6469 26.2431L38.2894 27.5931C38.7694 28.2458 39.3919 28.7428 40.1569 29.084Z" fill="var(--fill-0, black)" style="fill:black;fill-opacity:1;"/>+</g>+</g>+</svg>diff --git a/apps/sandbox/src/app/(fullscreen)/pages/shell-lab/page.tsx b/apps/sandbox/src/app/(fullscreen)/pages/shell-lab/page.tsxindex fefb5bc506..3bbc33910b 100644--- a/apps/sandbox/src/app/(fullscreen)/pages/shell-lab/page.tsx+++ b/apps/sandbox/src/app/(fullscreen)/pages/shell-lab/page.tsx@@ -32,6 +32,7 @@ import {XDSBadge} from '@xds/core/Badge';import {XDSButton} from '@xds/core/Button';import {XDSNavIcon} from '@xds/core/NavIcon';import {XDSBanner} from '@xds/core/Banner';+import {XDSList, XDSListItem} from '@xds/core/List';// =============================================================================// Configuration types@@ -123,6 +124,9 @@ interface ShellConfig {topNavAlignment: 'start' | 'center' | 'end';topNavStyle: 'items' | 'menus' | 'mega';showTopNavHeading: boolean;+ topNavHeadingStyle: 'none' | 'simple' | 'link' | 'menu' | 'full';+ showTopNavSuperheading: boolean;+ showTopNavSubheading: boolean;}const DEFAULT_CONFIG: ShellConfig = {@@ -147,6 +151,9 @@ const DEFAULT_CONFIG: ShellConfig = {topNavAlignment: 'start',topNavStyle: 'items',showTopNavHeading: true,+ topNavHeadingStyle: 'link',+ showTopNavSuperheading: false,+ showTopNavSubheading: false,};// =============================================================================@@ -297,6 +304,36 @@ function ConfigPanel({value={config.showTopNavHeading}onChange={v => onChange({showTopNavHeading: v})}/>+ {config.showTopNavHeading && (+ <>+ <SelectorRow+ label="Heading Style"+ value={config.topNavHeadingStyle}+ onChange={v =>+ onChange({+ topNavHeadingStyle: v as ShellConfig['topNavHeadingStyle'],+ })+ }+ options={[+ {value: 'none', label: 'None'},+ {value: 'simple', label: 'Simple'},+ {value: 'link', label: 'Link'},+ {value: 'menu', label: 'Menu'},+ {value: 'full', label: 'Full'},+ ]}+ />+ <ToggleRow+ label="Superheading"+ value={config.showTopNavSuperheading}+ onChange={v => onChange({showTopNavSuperheading: v})}+ />+ <ToggleRow+ label="Subheading"+ value={config.showTopNavSubheading}+ onChange={v => onChange({showTopNavSubheading: v})}+ />+ </>+ )}<SelectorRowlabel="Alignment"value={config.topNavAlignment}@@ -450,11 +487,11 @@ function SampleSideNav({);const headingMenu = (- <XDSVStack gap={1}>- <XDSSideNavItem label="Switch to Project A" />- <XDSSideNavItem label="Switch to Project B" />- <XDSSideNavItem label="Switch to Project C" />- </XDSVStack>+ <XDSList density="spacious">+ <XDSListItem label="Sibling Product 1" href="#" />+ <XDSListItem label="Sibling Product 2" href="#" />+ <XDSListItem label="Sibling Product 3" href="#" />+ </XDSList>);const heading =@@ -674,30 +711,60 @@ function SampleTopNav({? menuItems: plainItems;+ const topNavLogo = (+ <XDSNavIcon+ icon={+ <svg+ xmlns="http://www.w3.org/2000/svg"+ viewBox="0 0 24 24"+ fill="currentColor"+ width="16"+ height="16">+ <path d="M21 16.5c0 .38-.21.71-.53.88l-7.9 4.44c-.36.2-.8.2-1.14 0l-7.9-4.44A.991.991 0 013 16.5v-9c0-.38.21-.71.53-.88l7.9-4.44c.36-.2.8-.2 1.14 0l7.9 4.44c.32.17.53.5.53.88v9z" />+ </svg>+ }+ />+ );++ const topNavHeadingMenu = (+ <XDSList density="spacious">+ <XDSListItem label="Sibling Product 1" href="#" />+ <XDSListItem label="Sibling Product 2" href="#" />+ <XDSListItem label="Sibling Product 3" href="#" />+ </XDSList>+ );++ const topNavHeading =+ config.showTopNavHeading && config.topNavHeadingStyle !== 'none' ? (+ <XDSTopNavHeading+ logo={topNavLogo}+ heading="Shell Lab"+ headingHref={+ config.topNavHeadingStyle === 'link' ||+ config.topNavHeadingStyle === 'full'+ ? '#'+ : undefined+ }+ superheading={config.showTopNavSuperheading ? 'Acme Suite' : undefined}+ superheadingHref={config.showTopNavSuperheading ? '#' : undefined}+ subheading={+ config.showTopNavSubheading ? 'Business Account' : undefined+ }+ menu={+ config.topNavHeadingStyle === 'menu' ||+ config.topNavHeadingStyle === 'full'+ ? topNavHeadingMenu+ : undefined+ }+ />+ ) : config.showTopNavHeading ? (+ <XDSTopNavHeading logo={topNavLogo} />+ ) : undefined;+return (<XDSTopNavlabel="Shell Lab Navigation"- heading={- config.showTopNavHeading ? (- <XDSTopNavHeading- heading="Shell Lab"- logo={- <XDSNavIcon- icon={- <svg- xmlns="http://www.w3.org/2000/svg"- viewBox="0 0 24 24"- fill="currentColor"- width="16"- height="16">- <path d="M21 16.5c0 .38-.21.71-.53.88l-7.9 4.44c-.36.2-.8.2-1.14 0l-7.9-4.44A.991.991 0 013 16.5v-9c0-.38.21-.71.53-.88l7.9-4.44c.36-.2.8-.2 1.14 0l7.9 4.44c.32.17.53.5.53.88v9z" />- </svg>- }- />- }- />- ) : undefined- }+ heading={topNavHeading}startContent={config.topNavAlignment === 'start' ? navItems : undefined}centerContent={config.topNavAlignment === 'center' ? navItems : undefined}endContent={diff --git a/apps/sandbox/src/app/sandboxPages.ts b/apps/sandbox/src/app/sandboxPages.tsindex f5775490be..41552be0ee 100644--- a/apps/sandbox/src/app/sandboxPages.ts+++ b/apps/sandbox/src/app/sandboxPages.ts@@ -102,11 +102,13 @@ export const categories: SandboxCategory[] = [href: '/templates/library/',description: 'Browsable grid of XDS components organized by category',},- ...autoDiscoveredTemplates.map(t => ({- name: t.isReady ? t.name : t.name + ' (WIP)',- href: t.href,- description: t.description,- })),+ ...autoDiscoveredTemplates+ .filter(t => t.slug !== 'docsite-landing')+ .map(t => ({+ name: t.isReady ? t.name : t.name + ' (WIP)',+ href: t.href,+ description: t.description,+ })),],},{@@ -136,6 +138,12 @@ export const categories: SandboxCategory[] = [description:'Template gallery with AI composer and component documentation',},+ {+ name: 'Docsite Landing',+ href: '/templates/docsite-landing/',+ description:+ 'Template gallery with SideNav layout, AI chat, and resizable preview panel',+ },],},];diff --git a/packages/cli/templates/docsite-landing/page.tsx b/packages/cli/templates/docsite-landing/page.tsxindex f7e14ce776..b44def5879 100644--- a/packages/cli/templates/docsite-landing/page.tsx+++ b/packages/cli/templates/docsite-landing/page.tsx@@ -3,6 +3,7 @@import {useState, useEffect, useRef, useCallback} from 'react';import {XDSAppShell} from '@xds/core/AppShell';import {XDSTopNav, XDSTopNavHeading, XDSTopNavItem} from '@xds/core/TopNav';+import {XDSSideNav, XDSSideNavHeading, XDSSideNavItem} from '@xds/core/SideNav';import {XDSVStack} from '@xds/core/Layout';import {XDSHeading, XDSText} from '@xds/core/Text';import {XDSButton} from '@xds/core/Button';@@ -899,6 +900,83 @@ function ChatPanel({);}+// ---------------------------------------------------------------------------+// SideNavComposer (chat composer for side nav footer)+// ---------------------------------------------------------------------------++function SideNavComposer({onSend}: {onSend?: () => void}) {+ const [prompt, setPrompt] = useState('');++ return (+ <div+ style={{+ borderRadius: 12,+ backgroundColor: 'var(--color-background-card, white)',+ border: '1px solid var(--color-divider)',+ boxShadow: 'var(--shadow-high)',+ padding: 8,+ display: 'flex',+ flexDirection: 'column' as const,+ gap: 8,+ }}>+ <div+ style={{+ display: 'inline-flex',+ alignItems: 'center',+ alignSelf: 'flex-start',+ paddingInline: 8,+ paddingBlock: 2,+ borderRadius: 9999,+ backgroundColor: 'var(--color-background-body, #f1f4f7)',+ fontSize: 12,+ }}>+ Template 01+ </div>+ <div style={{display: 'flex', alignItems: 'center', padding: 8}}>+ <input+ style={{+ flex: 1,+ border: 'none',+ outline: 'none',+ backgroundColor: 'transparent',+ fontFamily: 'inherit',+ fontSize: 14,+ }}+ placeholder="What would you like to customize?"+ value={prompt}+ onChange={e => setPrompt(e.target.value)}+ />+ </div>+ <div+ style={{+ display: 'flex',+ alignItems: 'center',+ justifyContent: 'space-between',+ width: '100%',+ paddingInlineStart: 4,+ paddingTop: 4,+ }}>+ <XDSButton+ label="Attach"+ variant="ghost"+ size="sm"+ icon={<PlusIcon />}+ isIconOnly+ />+ <XDSButton+ label="Send"+ variant="primary"+ size="sm"+ icon={<SendIcon />}+ style={{borderRadius: 9999}}+ onClick={onSend}+ isIconOnly+ />+ </div>+ </div>+ );+}+// ---------------------------------------------------------------------------// Toolbar Icons// ---------------------------------------------------------------------------@@ -975,6 +1053,17 @@ const PhoneIcon = (props: React.SVGProps<SVGSVGElement>) => (</svg>);+const MoonIcon = (props: React.SVGProps<SVGSVGElement>) => (+ <svg+ viewBox="0 0 24 24"+ fill="none"+ stroke="currentColor"+ strokeWidth={2}+ {...props}>+ <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />+ </svg>+);+const TerminalIcon = (props: React.SVGProps<SVGSVGElement>) => (<svgviewBox="0 0 24 24"@@ -1121,222 +1210,219 @@ function TemplatePreview({overflow: 'auto',padding: '0 16px 16px',}}>- {/* Back button */}- <div style={{padding: '8px 0'}}>- <XDSButton- label="Back"- variant="ghost"- icon={<ArrowLeftIcon />}- onClick={onBack}- isIconOnly- />- </div>-- {/* Bordered container: toolbar + preview + code */}- <div- style={{- border: '1px solid var(--color-divider, rgba(0,0,0,0.1))',- borderRadius: 12,- paddingBottom: 8,- display: 'flex',- flexDirection: 'column' as const,- }}>- {/* Toolbar */}- <XDSToolbar- label="Template actions"- startContent={- <>- <XDSTooltip content="Point" placement="below">- <XDSButton- label="Point"- variant="ghost"- icon={<CursorIcon />}- isIconOnly- />- </XDSTooltip>- <XDSDropdownMenu- button={{- label: 'Theme',- variant: 'ghost',- icon: <PaletteIcon />,- isIconOnly: true,- }}- hasChevron={false}- items={XDS_THEMES.map(t => ({- label: t.label,- onClick: () => {},- }))}+ {/* Toolbar */}+ <XDSToolbar+ label="Template actions"+ style={{paddingInline: 0}}+ startContent={+ <>+ <XDSTooltip content="Back" placement="below">+ <XDSButton+ label="Back"+ variant="ghost"+ icon={<ArrowLeftIcon />}+ onClick={onBack}+ isIconOnly/>- <XDSSegmentedControl- value={viewportSize}- onChange={setViewportSize}- label="Viewport size"- size="sm">- <XDSSegmentedControlItem- value="desktop"- label="Desktop"- isLabelHidden- icon={<DesktopIcon />}- />- <XDSSegmentedControlItem- value="tablet"- label="Tablet"- isLabelHidden- icon={<TabletIcon />}- />- <XDSSegmentedControlItem- value="phone"- label="Phone"- isLabelHidden- icon={<PhoneIcon />}- />- </XDSSegmentedControl>- </>- }- centerContent={<XDSButton label={templateName} variant="ghost" />}- endContent={+ </XDSTooltip>+ <XDSButton label={templateName} variant="ghost" />+ </>+ }+ centerContent={+ <>+ <XDSTooltip content="Point" placement="below">+ <XDSButton+ label="Point"+ variant="ghost"+ icon={<CursorIcon />}+ isIconOnly+ />+ </XDSTooltip><XDSDropdownMenu- button={{label: 'Use in...', variant: 'ghost'}}+ button={{+ label: 'Theme',+ variant: 'ghost',+ icon: <PaletteIcon />,+ isIconOnly: true,+ }}hasChevron={false}- menuWidth={220}- items={[- {- label: 'Copy CLI Command...',- icon: TerminalIcon,- onClick: () => {},- },- {type: 'divider' as const},- {label: 'Claude Code', icon: ClaudeIcon, onClick: () => {}},- {label: 'VSCode', icon: VSCodeIcon, onClick: () => {}},- {label: 'Cursor', icon: CursorAIIcon, onClick: () => {}},- ]}+ items={XDS_THEMES.map(t => ({+ label: t.label,+ onClick: () => {},+ }))}/>- }- />+ <XDSTooltip content="Toggle dark mode" placement="below">+ <XDSButton+ label="Dark mode"+ variant="ghost"+ icon={<MoonIcon />}+ isIconOnly+ />+ </XDSTooltip>+ <XDSSegmentedControl+ value={viewportSize}+ onChange={setViewportSize}+ label="Viewport size"+ size="sm">+ <XDSSegmentedControlItem+ value="desktop"+ label="Desktop"+ isLabelHidden+ icon={<DesktopIcon />}+ />+ <XDSSegmentedControlItem+ value="tablet"+ label="Tablet"+ isLabelHidden+ icon={<TabletIcon />}+ />+ <XDSSegmentedControlItem+ value="phone"+ label="Phone"+ isLabelHidden+ icon={<PhoneIcon />}+ />+ </XDSSegmentedControl>+ </>+ }+ endContent={+ <XDSDropdownMenu+ button={{label: 'Use in...', variant: 'ghost'}}+ hasChevron={false}+ menuWidth={220}+ items={[+ {+ label: 'Copy CLI Command...',+ icon: TerminalIcon,+ onClick: () => {},+ },+ {type: 'divider' as const},+ {label: 'Claude Code', icon: ClaudeIcon, onClick: () => {}},+ {label: 'VSCode', icon: VSCodeIcon, onClick: () => {}},+ {label: 'Cursor', icon: CursorAIIcon, onClick: () => {}},+ ]}+ />+ }+ />- {/* Preview image in muted container with grid dots */}+ {/* Preview image in muted container with grid dots */}+ <div+ style={{+ backgroundColor: 'var(--color-background-muted, rgba(0,0,0,0.03))',+ backgroundImage:+ 'radial-gradient(circle, var(--color-divider, rgba(0,0,0,0.1)) 1px, transparent 1px)',+ backgroundSize: '16px 16px',+ borderRadius: 8,+ padding: 22,+ display: 'flex',+ justifyContent: 'center',+ }}><div+ ref={previewRef}style={{- backgroundColor:- 'var(--color-background-muted, rgba(0,0,0,0.03))',- backgroundImage:- 'radial-gradient(circle, var(--color-divider, rgba(0,0,0,0.1)) 1px, transparent 1px)',- backgroundSize: '16px 16px',+ position: 'relative',+ width:+ VIEWPORT_WIDTHS[viewportSize] === '100%'+ ? '100%'+ : VIEWPORT_WIDTHS[viewportSize],+ maxWidth: '100%',+ border: '1px solid var(--color-divider, rgba(0,0,0,0.1))',borderRadius: 8,- padding: 22,- margin: '0 8px',- display: 'flex',- justifyContent: 'center',+ overflow: 'hidden',+ transition:+ 'width var(--duration-medium, 410ms) var(--ease-standard, cubic-bezier(0.24, 1, 0.4, 1))',}}>- <div- ref={previewRef}+ <img+ src={imageSrc}+ alt="Template preview"style={{- position: 'relative',- width:- VIEWPORT_WIDTHS[viewportSize] === '100%'- ? '100%'- : VIEWPORT_WIDTHS[viewportSize],- maxWidth: '100%',- border: '1px solid var(--color-divider, rgba(0,0,0,0.1))',- borderRadius: 8,- overflow: 'hidden',- transition:- 'width var(--duration-medium, 410ms) var(--ease-standard, cubic-bezier(0.24, 1, 0.4, 1))',- }}>- <img- src={imageSrc}- alt="Template preview"+ display: 'block',+ width: '100%',+ aspectRatio: '1920 / 1200',+ objectFit: 'cover',+ opacity: isGenerating ? 0 : 1,+ transition: 'opacity 600ms ease',+ }}+ />+ {showCanvas && (+ <divstyle={{- display: 'block',- width: '100%',- aspectRatio: '1920 / 1200',- objectFit: 'cover',- opacity: isGenerating ? 0 : 1,+ position: 'absolute',+ inset: 0,+ opacity: isGenerating ? 1 : 0,transition: 'opacity 600ms ease',- }}- />- {showCanvas && (- <div- style={{- position: 'absolute',- inset: 0,- opacity: isGenerating ? 1 : 0,- transition: 'opacity 600ms ease',- }}>- <BoidsCanvas- width={previewSize.w}- height={previewSize.h}- simulation={simulation}- />- </div>- )}- </div>+ }}>+ <BoidsCanvas+ width={previewSize.w}+ height={previewSize.h}+ simulation={simulation}+ />+ </div>+ )}</div>+ </div>- {/* Code block */}+ {/* Code block */}+ <div+ style={{+ marginTop: 8,+ border: '1px solid var(--color-divider, rgba(0,0,0,0.1))',+ borderRadius: 8,+ backgroundColor: 'var(--color-background-muted, rgba(0,0,0,0.03))',+ overflow: 'hidden',+ }}>+ {/* Header */}<divstyle={{- margin: '8px 8px 0',- border: '1px solid var(--color-divider, rgba(0,0,0,0.1))',- borderRadius: 8,- backgroundColor:- 'var(--color-background-muted, rgba(0,0,0,0.03))',- overflow: 'hidden',+ display: 'flex',+ alignItems: 'center',+ justifyContent: 'space-between',+ padding: '8px 12px 8px 16px',+ borderBottom: '1px solid var(--color-divider, rgba(0,0,0,0.1))',}}>- {/* Header */}+ <span+ style={{+ fontFamily: '"Roboto Mono", monospace',+ fontSize: 12,+ fontWeight: 500,+ color: 'var(--color-text-secondary, #4e606f)',+ }}>+ typescript — useUser.ts+ </span>+ </div>+ {/* Code */}+ <div style={{display: 'flex'}}>+ {/* Line numbers */}<divstyle={{- display: 'flex',- alignItems: 'center',- justifyContent: 'space-between',- padding: '8px 12px 8px 16px',- borderBottom: '1px solid var(--color-divider, rgba(0,0,0,0.1))',+ padding: '12px 12px 12px 16px',+ borderRight: '1px solid var(--color-divider, rgba(0,0,0,0.1))',+ fontFamily: '"Roboto Mono", monospace',+ fontSize: 14,+ lineHeight: '20px',+ color: 'var(--color-text-disabled, #a4b0bc)',+ textAlign: 'right',+ userSelect: 'none',+ minWidth: 45,}}>- <span- style={{- fontFamily: '"Roboto Mono", monospace',- fontSize: 12,- fontWeight: 500,- color: 'var(--color-text-secondary, #4e606f)',- }}>- typescript — useUser.ts- </span>- </div>- {/* Code */}- <div style={{display: 'flex'}}>- {/* Line numbers */}- <div- style={{- padding: '12px 12px 12px 16px',- borderRight:- '1px solid var(--color-divider, rgba(0,0,0,0.1))',- fontFamily: '"Roboto Mono", monospace',- fontSize: 14,- lineHeight: '20px',- color: 'var(--color-text-disabled, #a4b0bc)',- textAlign: 'right',- userSelect: 'none',- minWidth: 45,- }}>- {MOCK_CODE.split('\n').map((_, i) => (- <div key={i}>{i + 1}</div>- ))}- </div>- {/* Code content */}- <pre- style={{- flex: 1,- padding: '12px 16px',- fontFamily: '"Roboto Mono", monospace',- fontSize: 14,- lineHeight: '20px',- margin: 0,- overflow: 'auto',- color: 'var(--color-text-primary, #0a1317)',- }}>- {MOCK_CODE}- </pre>+ {MOCK_CODE.split('\n').map((_, i) => (+ <div key={i}>{i + 1}</div>+ ))}</div>+ {/* Code content */}+ <pre+ style={{+ flex: 1,+ padding: '12px 16px',+ fontFamily: '"Roboto Mono", monospace',+ fontSize: 14,+ lineHeight: '20px',+ margin: 0,+ overflow: 'auto',+ color: 'var(--color-text-primary, #0a1317)',+ }}>+ {MOCK_CODE}+ </pre></div></div>@@ -1482,7 +1568,18 @@ function AppTopNav() {<><XDSTopNavlabel="XDS navigation"- heading={<XDSTopNavHeading heading="XDS" />}+ heading={+ <XDSTopNavHeading+ heading=""+ logo={+ <img+ src="/templates/xds-logo.svg"+ alt="XDS"+ style={{height: 36, width: 48}}+ />+ }+ />+ }centerContent={<><XDSTopNavItem@@ -1557,6 +1654,9 @@ export default function DocsiteLandingTemplate() {const previewTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);const simRef = useRef<BoidsSimulation | null>(null);const simAnimRef = useRef<number>(0);+ const [sideNavWidth, setSideNavWidth] = useState(480);+ const isResizingRef = useRef(false);+ const [previewReady, setPreviewReady] = useState(false);if (!simRef.current) {simRef.current = createSimulation();@@ -1585,6 +1685,47 @@ export default function DocsiteLandingTemplate() {return () => mql.removeEventListener('change', handler);}, []);+ const handleResizeStart = useCallback(+ (e: React.MouseEvent) => {+ e.preventDefault();+ isResizingRef.current = true;+ const startX = e.clientX;+ const startWidth = sideNavWidth;++ const onMouseMove = (ev: MouseEvent) => {+ if (!isResizingRef.current) return;+ const newWidth = Math.min(+ Math.max(startWidth + (ev.clientX - startX), 320),+ 640,+ );+ setSideNavWidth(newWidth);+ };++ const onMouseUp = () => {+ isResizingRef.current = false;+ document.removeEventListener('mousemove', onMouseMove);+ document.removeEventListener('mouseup', onMouseUp);+ document.body.style.cursor = '';+ document.body.style.userSelect = '';+ };++ document.body.style.cursor = 'col-resize';+ document.body.style.userSelect = 'none';+ document.addEventListener('mousemove', onMouseMove);+ document.addEventListener('mouseup', onMouseUp);+ },+ [sideNavWidth],+ );++ // Trigger enter animation one frame after preview mounts+ useEffect(() => {+ if (useTarget !== null) {+ const id = requestAnimationFrame(() => setPreviewReady(true));+ return () => cancelAnimationFrame(id);+ }+ setPreviewReady(false);+ }, [useTarget]);+const handleMoreLikeThis = useCallback((index: number) => {if (generatingSource !== null) return;@@ -1627,41 +1768,125 @@ export default function DocsiteLandingTemplate() {const isGenerating = generatingSource !== null;return (- <XDSAppShell variant="surface" topNav={<AppTopNav />} contentPadding={0}>- <div- style={{- display: 'flex',- height: '100%',- overflow: 'hidden',- }}>- {/* Chat panel */}+ <XDSAppShell+ variant="surface"+ topNav={useTarget === null ? <AppTopNav /> : undefined}+ contentPadding={0}>+ {useTarget !== null ? (<divstyle={{- width: chatOpen ? 400 : 0,- minWidth: chatOpen ? 400 : 0,+ display: 'flex',+ height: '100%',overflow: 'hidden',- transition:- 'width var(--duration-medium, 410ms) var(--ease-standard, cubic-bezier(0.24, 1, 0.4, 1)), min-width var(--duration-medium, 410ms) var(--ease-standard, cubic-bezier(0.24, 1, 0.4, 1))',- borderRight: 'none',- backgroundColor: 'var(--color-background-surface, white)',}}>- {chatOpen && (- <ChatPanel- isGenerating={isGenerating || previewGenerating}- onSend={useTarget !== null ? handlePreviewSend : undefined}+ {/* Resizable side nav panel */}+ <div+ style={{+ width: previewReady ? sideNavWidth : 0,+ minWidth: previewReady ? 320 : 0,+ maxWidth: 640,+ position: 'relative',+ display: 'flex',+ flexDirection: 'column' as const,+ borderRight: previewReady+ ? '1px solid var(--color-divider, rgba(0,0,0,0.1))'+ : 'none',+ overflow: 'hidden',+ transition:+ 'width 350ms cubic-bezier(0.24, 1, 0.4, 1), min-width 350ms cubic-bezier(0.24, 1, 0.4, 1)',+ }}>+ <XDSSideNav+ style={{width: '100%'}}+ header={+ <XDSSideNavHeading+ icon={+ <img+ src="/templates/xds-logo.svg"+ alt="XDS"+ style={{+ width: 48,+ height: 36,+ marginLeft: 16,+ marginTop: 4,+ maxWidth: 'none',+ cursor: 'pointer',+ }}+ onClick={handleBackFromUse}+ />+ }+ heading=""+ menu={+ <>+ <XDSSideNavItem+ label="Craft"+ isSelected+ href="#"+ size="lg"+ />+ <XDSSideNavItem label="Explore" href="#" size="lg" />+ <XDSSideNavItem label="Doc" href="#" size="lg" />+ </>+ }+ />+ }+ footer={+ <>+ <div+ style={{+ backgroundColor: 'var(--color-background-body, #f1f4f7)',+ borderRadius: 12,+ padding: 12,+ marginBottom: 8,+ marginLeft: 100,+ }}>+ <div+ style={{+ display: 'inline-flex',+ alignItems: 'center',+ paddingInline: 8,+ paddingBlock: 2,+ borderRadius: 9999,+ backgroundColor:+ 'var(--color-overlay-hover, rgba(0,0,0,0.05))',+ fontSize: 12,+ marginBottom: 8,+ }}>+ Template 01+ </div>+ <XDSText type="body">+ Can you customize this template by adding a divider line+ under the header and use a card for the lists+ </XDSText>+ </div>+ <SideNavComposer onSend={handlePreviewSend} />+ </>+ }>+ {null}+ </XDSSideNav>+ {/* Resize handle */}+ <div+ onMouseDown={handleResizeStart}+ style={{+ position: 'absolute',+ top: 0,+ right: -2,+ bottom: 0,+ width: 5,+ cursor: 'col-resize',+ zIndex: 10,+ }}/>- )}- </div>-- {/* Main content area */}- <div- style={{- flex: 1,- overflow: 'hidden',- display: 'flex',- flexDirection: 'column' as const,- }}>- {useTarget !== null ? (+ </div>+ {/* Main content */}+ <div+ style={{+ flex: 1,+ overflow: 'hidden',+ display: 'flex',+ flexDirection: 'column' as const,+ opacity: previewReady ? 1 : 0,+ transition: 'opacity 300ms ease 100ms',+ }}><TemplatePreviewtemplateName={templateNames[useTarget % templateNames.length]}imageSrc={REPEATED_IMAGES[useTarget]}@@ -1669,7 +1894,42 @@ export default function DocsiteLandingTemplate() {isGenerating={previewGenerating}simulation={simRef.current!}/>- ) : (+ </div>+ </div>+ ) : (+ <div+ style={{+ display: 'flex',+ height: '100%',+ overflow: 'hidden',+ }}>+ {/* Chat panel */}+ <div+ style={{+ width: chatOpen ? 400 : 0,+ minWidth: chatOpen ? 400 : 0,+ overflow: 'hidden',+ transition:+ 'width var(--duration-medium, 410ms) var(--ease-standard, cubic-bezier(0.24, 1, 0.4, 1)), min-width var(--duration-medium, 410ms) var(--ease-standard, cubic-bezier(0.24, 1, 0.4, 1))',+ borderRight: 'none',+ backgroundColor: 'var(--color-background-surface, white)',+ }}>+ {chatOpen && (+ <ChatPanel+ isGenerating={isGenerating || previewGenerating}+ onSend={undefined}+ />+ )}+ </div>++ {/* Main content area */}+ <div+ style={{+ flex: 1,+ overflow: 'hidden',+ display: 'flex',+ flexDirection: 'column' as const,+ }}><divstyle={{flex: 1,@@ -1704,11 +1964,11 @@ export default function DocsiteLandingTemplate() {</XDSGrid></div></div>- )}+ </div></div>- </div>+ )}- {!chatOpen && <AIComposer />}+ {useTarget === null && !chatOpen && <AIComposer />}</XDSAppShell>);}diff --git a/packages/core/src/SideNav/XDSSideNav.test.tsx b/packages/core/src/SideNav/XDSSideNav.test.tsxindex 4c19fcb8fa..c7ac593af7 100644--- a/packages/core/src/SideNav/XDSSideNav.test.tsx+++ b/packages/core/src/SideNav/XDSSideNav.test.tsx@@ -157,6 +157,28 @@ describe('XDSSideNavHeading', () => {expect(link).toHaveTextContent('My App');});+ it('uses custom link component from as prop', () => {+ render(+ <XDSSideNavHeading+ heading="My App"+ headingHref="/home"+ as={CustomLink}+ />,+ );+ const link = screen.getByRole('link');+ expect(link).toHaveAttribute('data-custom-link');+ });++ it('uses custom link component from XDSLinkProvider', () => {+ render(+ <XDSLinkProvider component={CustomLink}>+ <XDSSideNavHeading heading="My App" headingHref="/home" />+ </XDSLinkProvider>,+ );+ const link = screen.getByRole('link');+ expect(link).toHaveAttribute('data-custom-link');+ });+it('renders independent links when headingHref and superheadingHref are provided', () => {render(<XDSSideNavHeading@@ -194,8 +216,7 @@ describe('XDSSideNavHeading', () => {expect(button).toHaveAttribute('aria-expanded', 'false');});- it('toggles popover on click when menu is provided', async () => {- const user = userEvent.setup();+ it('has popoverTarget on trigger button when menu is provided', () => {render(<XDSSideNavHeadingheading="My App"@@ -203,8 +224,10 @@ describe('XDSSideNavHeading', () => {/>,);const button = screen.getByRole('button');- await user.click(button);- expect(button).toHaveAttribute('aria-expanded', 'true');+ // Native popover toggle via popoverTarget attribute (jsdom doesn't+ // support the Popover API, so we verify the attribute is set instead+ // of testing the full open/close cycle).+ expect(button).toHaveAttribute('popovertarget');});it('renders chevron as separate trigger when menu and hrefs are provided', () => {@@ -354,7 +377,7 @@ describe('XDSSideNavHeading headerEndContent', () => {expect(badge.closest('a')).not.toBeNull();});- it('renders headerEndContent inside the button trigger in isWholeHeadingTrigger path', () => {+ it('renders headerEndContent in isWholeHeadingTrigger path', () => {render(<XDSSideNavHeadingheading="My App"@@ -364,8 +387,8 @@ describe('XDSSideNavHeading headerEndContent', () => {);const badge = screen.getByTestId('end-badge');expect(badge).toBeInTheDocument();- // Badge renders inside the button trigger- expect(badge.closest('button')).not.toBeNull();+ // Badge renders inside the heading container (div), alongside the chevron button+ expect(badge.closest('[class]')).not.toBeNull();});it('renders headerEndContent in mixed mode (menu + href)', () => {diff --git a/packages/core/src/SideNav/XDSSideNavHeading.tsx b/packages/core/src/SideNav/XDSSideNavHeading.tsxindex a7cf974363..871bcd9167 100644--- a/packages/core/src/SideNav/XDSSideNavHeading.tsx+++ b/packages/core/src/SideNav/XDSSideNavHeading.tsx@@ -35,6 +35,8 @@ import {getIcon} from '../Icon/globalIconRegistry';import {XDSTooltip} from '../Tooltip';import {navItemStyles} from '../NavItem/navItemStyles.stylex';import {useXDSSideNavCollapse} from './XDSSideNavCollapseContext';+import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';+import type {XDSLinkComponentType} from '../Link/types';import {xdsClassName, mergeProps} from '../utils';// =============================================================================@@ -72,6 +74,19 @@ const styles = stylex.create({},},},+ // Menu trigger: like interactive but no hover background.+ // Only cursor:pointer signals interactivity; the popover provides context.+ menuTrigger: {+ cursor: 'pointer',+ borderRadius: radiusVars['--radius-element'],+ borderWidth: 0,+ borderStyle: 'none',+ backgroundColor: 'transparent',+ fontFamily: 'inherit',+ fontSize: 'inherit',+ fontWeight: fontWeightVars['--font-weight-normal'],+ textAlign: 'start',+ },interactiveCollapsed: {backgroundColor: {default: 'transparent',@@ -113,9 +128,8 @@ const styles = stylex.create({textOverflow: 'ellipsis',whiteSpace: 'nowrap',},- // When super/sub headings are present, scale down the app name+ // When super/sub headings are present, keep same size but allow compact layoutheadingCompact: {- fontSize: typeScaleVars['--text-label-size'],fontWeight: fontWeightVars['--font-weight-semibold'],},subheading: {@@ -127,6 +141,18 @@ const styles = stylex.create({textOverflow: 'ellipsis',whiteSpace: 'nowrap',},+ headingRow: {+ display: 'flex',+ alignItems: 'center',+ gap: spacingVars['--spacing-1'],+ },+ headingLink: {+ textDecoration: 'none',+ color: 'inherit',+ overflow: 'hidden',+ textOverflow: 'ellipsis',+ whiteSpace: 'nowrap',+ },chevron: {flexShrink: 0,display: 'flex',@@ -146,10 +172,41 @@ const styles = stylex.create({padding: spacingVars['--spacing-1'],overflow: 'hidden',},+ // Static heading replica inside the popover — matches inline heading layout.+ // Clickable to close the popover.+ popoverHeading: {+ display: 'flex',+ alignItems: 'center',+ gap: spacingVars['--spacing-2'],+ padding: 0,+ marginBlockStart: spacingVars['--spacing-1'],+ marginBlockEnd: spacingVars['--spacing-2'],+ marginInline: spacingVars['--spacing-1'],+ cursor: 'pointer',+ },+ // Chevron inside the popover heading — same as chevron but rotated up+ popoverChevron: {+ flexShrink: 0,+ display: 'flex',+ alignItems: 'center',+ justifyContent: 'center',+ minWidth: spacingVars['--spacing-7'],+ minHeight: spacingVars['--spacing-7'],+ color: colorVars['--color-icon-secondary'],+ transform: 'rotate(180deg)',+ },popover: {minWidth: 'anchor-size(width)',marginBlockStart: spacingVars['--spacing-1'],},+ // Overlap variant: popover covers the trigger so heading appears "in place".+ // Add 4px padding inside, then widen and shift to compensate so the+ // heading text inside the popover still aligns with the inline heading.+ popoverOverlap: {+ minWidth: 'calc(anchor-size(width) + 16px)',+ marginBlockStart: 'calc(-1 * anchor-size(height) - 8px)',+ marginInlineStart: '-8px',+ },});// =============================================================================@@ -163,6 +220,12 @@ export interface XDSSideNavHeadingProps {* Product/app icon.*/icon?: ReactNode;+ /**+ * Custom component to render instead of `<a>`.+ * Overrides the provider-level default set by XDSLinkProvider.+ * Must accept href, className, style, and children props.+ */+ as?: XDSLinkComponentType;/*** Product/app name.*/@@ -264,6 +327,7 @@ export interface XDSSideNavHeadingProps {* ```*/export function XDSSideNavHeading({+ as,icon,heading,headingHref,@@ -280,6 +344,7 @@ export function XDSSideNavHeading({ref,...props}: XDSSideNavHeadingProps) {+ const LinkComponent = useXDSLinkComponent(as);const {isCollapsed} = useXDSSideNavCollapse();const rootRef = useRef<HTMLDivElement>(null);const collapsedItemRef = useRef<HTMLElement>(null);@@ -288,10 +353,6 @@ export function XDSSideNavHeading({dialogLabel: 'Navigation menu',});- const handleToggle = useCallback(() => {- popover.toggle();- }, [popover]);-const setRef = useCallback((el: HTMLDivElement | null) => {(rootRef as React.MutableRefObject<HTMLDivElement | null>).current = el;@@ -329,7 +390,7 @@ export function XDSSideNavHeading({if (headingHref) {collapsedElement = (- <a+ <LinkComponentref={collapsedSetRef as React.Ref<HTMLAnchorElement>}href={headingHref}aria-label={heading}@@ -341,7 +402,7 @@ export function XDSSideNavHeading({style,)}>{collapsedIcon}- </a>+ </LinkComponent>);} else if (menu) {collapsedElement = (@@ -349,7 +410,7 @@ export function XDSSideNavHeading({<buttonref={collapsedSetRef as React.Ref<HTMLButtonElement>}type="button"- onClick={handleToggle}+ popoverTarget={popover.id}aria-label={heading}data-testid={testId}{...popover.triggerProps}@@ -358,8 +419,7 @@ export function XDSSideNavHeading({stylex.props(navItemStyles.item,styles.rootCollapsed,- styles.interactive,- styles.interactiveCollapsed,+ styles.menuTrigger,xstyle,),className,@@ -368,7 +428,40 @@ export function XDSSideNavHeading({{collapsedIcon}</button>{popover.render(- <div {...stylex.props(styles.popoverContent)}>{menu}</div>,+ <div {...stylex.props(styles.popoverContent)}>+ <div+ {...stylex.props(styles.popoverHeading)}+ onClick={() => popover.hide()}+ role="button"+ tabIndex={0}>+ {icon && <span {...stylex.props(styles.icon)}>{icon}</span>}+ <span {...stylex.props(styles.textContainer)}>+ {superheading && (+ <span {...stylex.props(styles.superheading)}>+ {superheading}+ </span>+ )}+ <span {...stylex.props(styles.headingRow)}>+ <span+ {...stylex.props(+ styles.heading,+ !!(superheading || subheading) && styles.headingCompact,+ )}>+ {heading}+ </span>+ <span {...stylex.props(styles.popoverChevron)}>+ {getIcon('chevronDown')}+ </span>+ </span>+ {subheading && (+ <span {...stylex.props(styles.subheading)}>+ {subheading}+ </span>+ )}+ </span>+ </div>+ {menu}+ </div>,{placement: 'below', alignment: 'start', xstyle: styles.popover},)}</>@@ -411,8 +504,8 @@ export function XDSSideNavHeading({const isWholeHeadingLink =!!headingHref && !menu && !superheadingHref && !subheadingHref;- // Render text content- const renderTextContent = () => (+ // Render text content with optional inline chevron+ const renderTextContent = (inlineChevron?: ReactNode) => (<span {...stylex.props(styles.textContainer)}>{superheading &&(hasAnyHref && superheadingHref && menu ? (@@ -426,23 +519,18 @@ export function XDSSideNavHeading({) : (<span {...stylex.props(styles.superheading)}>{superheading}</span>))}- {hasAnyHref && headingHref && menu ? (- <XDSLink- label={heading}- href={headingHref}- color="primary"- weight="semibold">- {heading}- </XDSLink>- ) : (- <span- {...stylex.props(- styles.heading,- hasCompactHeading && styles.headingCompact,- )}>- {heading}- </span>- )}+ <span {...stylex.props(styles.headingRow)}>+ {hasAnyHref && headingHref && menu ? (+ <LinkComponent+ href={headingHref}+ {...stylex.props(styles.heading, styles.headingLink)}>+ {heading}+ </LinkComponent>+ ) : (+ <span {...stylex.props(styles.heading)}>{heading}</span>+ )}+ {inlineChevron}+ </span>{subheading &&(hasAnyHref && subheadingHref && menu ? (<XDSLink@@ -466,16 +554,33 @@ export function XDSSideNavHeading({<span {...stylex.props(styles.headerEndContent)}>{headerEndContent}</span>);+ // Shared popover heading content — uses renderTextContent for consistent+ // sizing, with flipped chevron inline after the title. Always static (no links).+ const popoverHeadingContent = (+ <div+ {...stylex.props(styles.popoverHeading)}+ onClick={() => popover.hide()}+ role="button"+ tabIndex={0}>+ {icon && <span {...stylex.props(styles.icon)}>{icon}</span>}+ {renderTextContent(+ <span {...stylex.props(styles.popoverChevron)}>+ {getIcon('chevronDown')}+ </span>,+ )}+ </div>+ );+// Whole heading is a link (no menu, single headingHref)if (isWholeHeadingLink) {return (- <a+ <LinkComponentref={ref as React.Ref<HTMLAnchorElement>}- href={headingHref}+ href={headingHref!}data-testid={testId}{...mergeProps(xdsClassName('side-nav-heading'),- stylex.props(styles.root, styles.interactive, xstyle),+ stylex.props(styles.root, styles.menuTrigger, xstyle),className,style,)}@@ -484,7 +589,7 @@ export function XDSSideNavHeading({{renderTextContent()}{headerEndContentElement}{chevronElement}- </a>+ </LinkComponent>);}@@ -492,26 +597,38 @@ export function XDSSideNavHeading({if (isWholeHeadingTrigger) {return (<>- <button- ref={setRef as React.Ref<HTMLButtonElement>}- type="button"- onClick={handleToggle}+ <div+ ref={setRef}data-testid={testId}- {...popover.triggerProps}{...mergeProps(xdsClassName('side-nav-heading'),- stylex.props(styles.root, styles.interactive, xstyle),+ stylex.props(styles.root, styles.menuTrigger, xstyle),className,style,)}>{icon && <span {...stylex.props(styles.icon)}>{icon}</span>}- {renderTextContent()}+ {renderTextContent(+ <button+ type="button"+ popoverTarget={popover.id}+ aria-label="Open menu"+ {...popover.triggerProps}+ {...stylex.props(styles.chevron, styles.interactive)}>+ {getIcon('chevronDown')}+ </button>,+ )}{headerEndContentElement}- {chevronElement}- </button>+ </div>{popover.render(- <div {...stylex.props(styles.popoverContent)}>{menu}</div>,- {placement: 'below', alignment: 'start', xstyle: styles.popover},+ <div {...stylex.props(styles.popoverContent)}>+ {popoverHeadingContent}+ {menu}+ </div>,+ {+ placement: 'below',+ alignment: 'start',+ xstyle: styles.popoverOverlap,+ },)}</>);@@ -534,28 +651,36 @@ export function XDSSideNavHeading({)}>{icon &&(headingHref ? (- <a href={headingHref} {...stylex.props(styles.icon)}>+ <LinkComponent href={headingHref} {...stylex.props(styles.icon)}>{icon}- </a>+ </LinkComponent>) : (<span {...stylex.props(styles.icon)}>{icon}</span>))}- {renderTextContent()}- {headerEndContentElement}- {showChevron && (- <button- type="button"- onClick={handleToggle}- aria-label="Open menu"- {...popover.triggerProps}- {...stylex.props(styles.chevron, styles.interactive)}>- {getIcon('chevronDown')}- </button>+ {renderTextContent(+ showChevron ? (+ <button+ type="button"+ popoverTarget={popover.id}+ aria-label="Open menu"+ {...popover.triggerProps}+ {...stylex.props(styles.chevron, styles.interactive)}>+ {getIcon('chevronDown')}+ </button>+ ) : undefined,)}+ {headerEndContentElement}</div>{popover.render(- <div {...stylex.props(styles.popoverContent)}>{menu}</div>,- {placement: 'below', alignment: 'start', xstyle: styles.popover},+ <div {...stylex.props(styles.popoverContent)}>+ {popoverHeadingContent}+ {menu}+ </div>,+ {+ placement: 'below',+ alignment: 'start',+ xstyle: styles.popoverOverlap,+ },)}</>);@@ -576,9 +701,9 @@ export function XDSSideNavHeading({{...props}>{icon &&(headingHref ? (- <a href={headingHref} {...stylex.props(styles.icon)}>+ <LinkComponent href={headingHref} {...stylex.props(styles.icon)}>{icon}- </a>+ </LinkComponent>) : (<span {...stylex.props(styles.icon)}>{icon}</span>))}diff --git a/packages/core/src/TopNav/XDSTopNavHeading.tsx b/packages/core/src/TopNav/XDSTopNavHeading.tsxindex 71358e4211..989391e826 100644--- a/packages/core/src/TopNav/XDSTopNavHeading.tsx+++ b/packages/core/src/TopNav/XDSTopNavHeading.tsx@@ -2,10 +2,14 @@/*** @file XDSTopNavHeading.tsx- * @input Uses React, HTMLAttributes, ReactNode+ * @input Uses React, useRef, useCallback, ReactNode, StyleX, useXDSPopover* @output Exports XDSTopNavHeading component and XDSTopNavHeadingProps* @position Companion component for XDSTopNav heading slot*+ * Product/suite/account heading with smart interaction boundary logic.+ * Mirrors XDSSideNavHeading features: superheading, subheading, menu popover,+ * chevron indicator, and independent link boundaries.+ ** SYNC: When modified, update these files to stay in sync:* - /packages/core/src/TopNav/TopNav.doc.mjs* - /packages/core/src/TopNav/XDSTopNav.test.tsx@@ -13,121 +17,609 @@* - /apps/storybook/stories/TopNav.stories.tsx*/-import {type ReactNode} from 'react';-import type {XDSBaseProps} from '../XDSBaseProps';+import {useCallback, useRef, type ReactNode} from 'react';import * as stylex from '@stylexjs/stylex';+import type {StyleXStyles} from '@stylexjs/stylex';import {colorVars,spacingVars,fontWeightVars,+ radiusVars,typeScaleVars,} from '../theme/tokens.stylex';+import {useXDSPopover} from '../Popover/useXDSPopover';+import {XDSLink} from '../Link';+import {getIcon} from '../Icon/globalIconRegistry';import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';import type {XDSLinkComponentType} from '../Link/types';import {xdsClassName, mergeProps} from '../utils';-/**- * Heading styles- */+// =============================================================================+// Styles+// =============================================================================+const styles = stylex.create({- base: {+ root: {display: 'flex',alignItems: 'center',gap: spacingVars['--spacing-2'],+ padding: 0,+ boxSizing: 'border-box',textDecoration: 'none',color: colorVars['--color-text-primary'],+ cursor: 'default',+ },+ interactive: {+ cursor: 'pointer',+ borderRadius: radiusVars['--radius-element'],+ borderWidth: 0,+ borderStyle: 'none',+ backgroundColor: 'transparent',+ fontFamily: 'inherit',+ fontSize: 'inherit',+ fontWeight: fontWeightVars['--font-weight-normal'],+ textAlign: 'start',+ ':hover': {+ '@media (hover: hover)': {+ backgroundColor: colorVars['--color-overlay-hover'],+ },+ },+ },+ menuTrigger: {+ cursor: 'pointer',+ borderRadius: radiusVars['--radius-element'],+ borderWidth: 0,+ borderStyle: 'none',+ backgroundColor: 'transparent',+ fontFamily: 'inherit',+ fontSize: 'inherit',+ fontWeight: fontWeightVars['--font-weight-normal'],+ textAlign: 'start',+ },+ logo: {+ flexShrink: 0,+ display: 'flex',+ alignItems: 'center',+ justifyContent: 'center',+ },+ textContainer: {+ display: 'flex',+ flexDirection: 'column',+ minWidth: 0,},- headingText: {+ superheading: {+ fontSize: typeScaleVars['--text-supporting-size'],+ lineHeight: typeScaleVars['--text-supporting-leading'],+ color: colorVars['--color-text-secondary'],+ textDecoration: 'none',+ overflow: 'hidden',+ textOverflow: 'ellipsis',+ whiteSpace: 'nowrap',+ },+ heading: {fontSize: typeScaleVars['--text-large-size'],fontWeight: fontWeightVars['--font-weight-semibold'],lineHeight: typeScaleVars['--text-large-leading'],+ color: colorVars['--color-text-primary'],+ textDecoration: 'none',+ overflow: 'hidden',+ textOverflow: 'ellipsis',whiteSpace: 'nowrap',},- logo: {+ subheading: {+ fontSize: typeScaleVars['--text-supporting-size'],+ lineHeight: typeScaleVars['--text-supporting-leading'],+ color: colorVars['--color-text-secondary'],+ textDecoration: 'none',+ overflow: 'hidden',+ textOverflow: 'ellipsis',+ whiteSpace: 'nowrap',+ },+ headingRow: {+ display: 'flex',+ alignItems: 'center',+ gap: spacingVars['--spacing-1'],+ },+ headingLink: {+ textDecoration: 'none',+ color: 'inherit',+ overflow: 'hidden',+ textOverflow: 'ellipsis',+ whiteSpace: 'nowrap',+ },+ chevron: {+ flexShrink: 0,display: 'flex',alignItems: 'center',justifyContent: 'center',+ minWidth: spacingVars['--spacing-7'],+ minHeight: spacingVars['--spacing-7'],+ color: colorVars['--color-icon-secondary'],+ },+ headerEndContent: {flexShrink: 0,+ display: 'flex',+ alignItems: 'center',+ marginInlineStart: 'auto',+ },+ popoverContent: {+ padding: spacingVars['--spacing-1'],+ overflow: 'hidden',},- clickable: {+ popoverHeading: {+ display: 'flex',+ alignItems: 'center',+ gap: spacingVars['--spacing-2'],+ padding: 0,+ marginBlockStart: spacingVars['--spacing-1'],+ marginBlockEnd: spacingVars['--spacing-2'],+ marginInline: spacingVars['--spacing-1'],cursor: 'pointer',},+ popoverChevron: {+ flexShrink: 0,+ display: 'flex',+ alignItems: 'center',+ justifyContent: 'center',+ minWidth: spacingVars['--spacing-7'],+ minHeight: spacingVars['--spacing-7'],+ color: colorVars['--color-icon-secondary'],+ transform: 'rotate(180deg)',+ },+ popover: {+ minWidth: 'anchor-size(width)',+ marginBlockStart: spacingVars['--spacing-1'],+ },+ popoverOverlap: {+ minWidth: 'calc(anchor-size(width) + 16px)',+ marginBlockStart: 'calc(-1 * anchor-size(height) - 8px)',+ marginInlineStart: '-8px',+ },});-export interface XDSTopNavHeadingProps extends XDSBaseProps<HTMLElement> {+// =============================================================================+// Types+// =============================================================================++export interface XDSTopNavHeadingProps {/** Ref forwarded to the root element */ref?: React.Ref<HTMLElement>;- /**- * The heading text to display.- */- heading?: string;/*** Logo element to display before the heading.* Can be an image, XDSNavIcon, or any ReactNode.*/logo?: ReactNode;/**+ * Product/app name.+ */+ heading?: string;+ /**+ * Link for the heading (e.g., product home).+ * Alias: `href` (for backward compatibility).+ */+ headingHref?: string;+ /**+ * @deprecated Use `headingHref` instead.* URL to navigate to when the heading is clicked.- * If provided, renders as a link element.*/href?: string;+ /**+ * Text above the heading (e.g., suite name).+ */+ superheading?: string;+ /**+ * Link for the superheading (e.g., suite home).+ */+ superheadingHref?: string;+ /**+ * Text below the heading (e.g., account context).+ */+ subheading?: string;+ /**+ * Link for the subheading.+ */+ subheadingHref?: string;+ /**+ * Content rendered at the trailing edge of the heading row.+ */+ headerEndContent?: ReactNode;+ /**+ * Menu content shown in a popover. When provided, the header composes+ * useXDSPopover internally and shows a dropdown chevron. The trigger+ * boundary is determined automatically:+ * - No hrefs → whole header is the trigger+ * - With hrefs → links are independent, chevron/remaining area is the trigger+ */+ menu?: ReactNode;/*** Custom component to render instead of `<a>`.* Overrides the provider-level default set by XDSLinkProvider.* Must accept href, className, style, and children props.*/as?: XDSLinkComponentType;+ /**+ * StyleX styles created via `stylex.create()`.+ */+ xstyle?: StyleXStyles;+ /**+ * CSS class name(s) appended to the root element.+ */+ className?: string;+ /**+ * Inline styles to apply to the root element.+ */+ style?: React.CSSProperties;+ /**+ * Test ID for the root element.+ */+ 'data-testid'?: string;}+// =============================================================================+// Component+// =============================================================================+/**- * Heading component for XDSTopNav.+ * Product/suite/account heading for XDSTopNav.+ *+ * Supports smart interaction boundary logic:+ * - No hrefs + menu → whole heading is the popover trigger+ * - headingHref only, no menu → whole heading is one link+ * - headingHref + superheadingHref, no menu → each is an independent link+ * - menu + hrefs → links are independent, chevron/remaining area is the trigger*- * Displays a logo and/or heading text, optionally as a clickable link.- * Use with XDSNavIcon to create a circular icon background.+ * The chevron indicator is automatically shown when `menu` is provided.** @example* ```+ * <XDSTopNavHeading logo={<XDSNavIcon icon={<HomeIcon />} />} heading="My App" headingHref="/" />* <XDSTopNavHeading- * heading="My App"- * logo={<img src="/logo.svg" alt="" width={24} height={24} />}- * href="/"+ * logo={<XDSNavIcon icon={<SuiteIcon />} />}+ * superheading="Suite Name"+ * superheadingHref="/suite"+ * heading="Product Name"+ * headingHref="/product"+ * menu={<ProductSwitcher />}* />- * <XDSTopNavHeading- * heading="Dashboard"- * logo={<XDSNavIcon icon={<HomeIcon />} />}- * />- * <XDSTopNavHeading logo={<BrandLogo />} href="/" />* ```*/export function XDSTopNavHeading({as,- heading,logo,+ heading,+ headingHref: headingHrefProp,href,+ superheading,+ superheadingHref,+ subheading,+ subheadingHref,+ headerEndContent,+ menu,xstyle,className,style,+ 'data-testid': testId,ref,...props}: XDSTopNavHeadingProps) {const LinkComponent = useXDSLinkComponent(as);- const isLink = href != null;- const Element = isLink ? LinkComponent : 'div';+ // Support both headingHref and legacy href+ const headingHref = headingHrefProp ?? href;++ const rootRef = useRef<HTMLElement>(null);++ const popover = useXDSPopover({+ dialogLabel: 'Navigation menu',+ });++ const setRef = useCallback(+ (el: HTMLElement | null) => {+ (rootRef as React.MutableRefObject<HTMLElement | null>).current = el;+ if (typeof ref === 'function') {+ ref(el);+ } else if (ref) {+ (ref as React.MutableRefObject<HTMLElement | null>).current = el;+ }+ if (menu) {+ popover.triggerRef(el);+ }+ },+ [ref, popover, menu],+ );++ const showChevron = !!menu;+ const hasAnyHref = !!(headingHref || superheadingHref || subheadingHref);++ // Determine interaction mode+ const isWholeHeadingTrigger = !!menu && !hasAnyHref;+ const isWholeHeadingLink =+ !!headingHref && !menu && !superheadingHref && !subheadingHref;++ // Render text content with optional inline chevron+ const renderTextContent = (inlineChevron?: ReactNode) => (+ <span {...stylex.props(styles.textContainer)}>+ {superheading &&+ (hasAnyHref && superheadingHref && menu ? (+ <XDSLink+ label={superheading}+ href={superheadingHref}+ color="secondary"+ size="xsm">+ {superheading}+ </XDSLink>+ ) : (+ <span {...stylex.props(styles.superheading)}>{superheading}</span>+ ))}+ <span {...stylex.props(styles.headingRow)}>+ {hasAnyHref && headingHref && menu ? (+ <LinkComponent+ href={headingHref}+ {...stylex.props(styles.heading, styles.headingLink)}>+ {heading}+ </LinkComponent>+ ) : (+ <span {...stylex.props(styles.heading)}>{heading}</span>+ )}+ {inlineChevron}+ </span>+ {subheading &&+ (hasAnyHref && subheadingHref && menu ? (+ <XDSLink+ label={subheading}+ href={subheadingHref}+ color="secondary"+ size="xsm">+ {subheading}+ </XDSLink>+ ) : (+ <span {...stylex.props(styles.subheading)}>{subheading}</span>+ ))}+ </span>+ );++ const chevronElement = showChevron && (+ <span {...stylex.props(styles.chevron)}>{getIcon('chevronDown')}</span>+ );++ const headerEndContentElement = headerEndContent && (+ <span {...stylex.props(styles.headerEndContent)}>{headerEndContent}</span>+ );++ // Shared popover heading content — uses renderTextContent for consistent+ // sizing, with flipped chevron inline after the title. Always static (no links).+ const popoverHeadingContent = (+ <div+ {...stylex.props(styles.popoverHeading)}+ onClick={() => popover.hide()}+ role="button"+ tabIndex={0}>+ {logo && <span {...stylex.props(styles.logo)}>{logo}</span>}+ {renderTextContent(+ <span {...stylex.props(styles.popoverChevron)}>+ {getIcon('chevronDown')}+ </span>,+ )}+ </div>+ );++ // Simple: no heading text, just logo (backward compat for logo-only usage)+ if (!heading && !menu) {+ const Element = headingHref ? LinkComponent : 'div';+ return (+ <Element+ ref={ref as React.Ref<HTMLAnchorElement & HTMLDivElement>}+ href={headingHref}+ data-testid={testId}+ {...mergeProps(+ xdsClassName('top-nav-heading'),+ stylex.props(+ styles.root,+ !!headingHref && styles.menuTrigger,+ xstyle,+ ),+ className,+ style,+ )}+ {...props}>+ {logo && <span {...stylex.props(styles.logo)}>{logo}</span>}+ </Element>+ );+ }++ // Whole heading is a link (no menu, single headingHref)+ if (isWholeHeadingLink) {+ return (+ <LinkComponent+ ref={ref as React.Ref<HTMLAnchorElement>}+ href={headingHref!}+ data-testid={testId}+ {...mergeProps(+ xdsClassName('top-nav-heading'),+ stylex.props(styles.root, styles.menuTrigger, xstyle),+ className,+ style,+ )}+ {...(props as React.AnchorHTMLAttributes<HTMLAnchorElement>)}>+ {logo && <span {...stylex.props(styles.logo)}>{logo}</span>}+ {renderTextContent()}+ {headerEndContentElement}+ {chevronElement}+ </LinkComponent>+ );+ }++ // Whole header is the popover trigger (menu, no hrefs)+ if (isWholeHeadingTrigger) {+ return (+ <>+ <div+ ref={setRef}+ data-testid={testId}+ {...mergeProps(+ xdsClassName('top-nav-heading'),+ stylex.props(styles.root, styles.menuTrigger, xstyle),+ className,+ style,+ )}>+ {logo && <span {...stylex.props(styles.logo)}>{logo}</span>}+ {renderTextContent(+ <button+ type="button"+ popoverTarget={popover.id}+ aria-label="Open menu"+ {...popover.triggerProps}+ {...stylex.props(styles.chevron, styles.interactive)}>+ {getIcon('chevronDown')}+ </button>,+ )}+ {headerEndContentElement}+ </div>+ {popover.render(+ <div {...stylex.props(styles.popoverContent)}>+ {popoverHeadingContent}+ {menu}+ </div>,+ {+ placement: 'below',+ alignment: 'start',+ xstyle: styles.popoverOverlap,+ },+ )}+ </>+ );+ }++ // Mixed mode: independent links + chevron trigger for menu+ if (menu && hasAnyHref) {+ return (+ <>+ <div+ ref={setRef}+ data-testid={testId}+ {...mergeProps(+ xdsClassName('top-nav-heading'),+ stylex.props(styles.root, xstyle),+ className,+ style,+ )}>+ {logo &&+ (headingHref ? (+ <LinkComponent href={headingHref} {...stylex.props(styles.logo)}>+ {logo}+ </LinkComponent>+ ) : (+ <span {...stylex.props(styles.logo)}>{logo}</span>+ ))}+ {renderTextContent(+ showChevron ? (+ <button+ type="button"+ popoverTarget={popover.id}+ aria-label="Open menu"+ {...popover.triggerProps}+ {...stylex.props(styles.chevron, styles.interactive)}>+ {getIcon('chevronDown')}+ </button>+ ) : undefined,+ )}+ {headerEndContentElement}+ </div>+ {popover.render(+ <div {...stylex.props(styles.popoverContent)}>+ {popoverHeadingContent}+ {menu}+ </div>,+ {+ placement: 'below',+ alignment: 'start',+ xstyle: styles.popoverOverlap,+ },+ )}+ </>+ );+ }++ // Static heading with independent links (no menu)+ if (hasAnyHref && !isWholeHeadingLink) {+ return (+ <div+ ref={ref as React.Ref<HTMLDivElement>}+ data-testid={testId}+ {...mergeProps(+ xdsClassName('top-nav-heading'),+ stylex.props(styles.root, xstyle),+ className,+ style,+ )}+ {...props}>+ {logo &&+ (headingHref ? (+ <LinkComponent href={headingHref} {...stylex.props(styles.logo)}>+ {logo}+ </LinkComponent>+ ) : (+ <span {...stylex.props(styles.logo)}>{logo}</span>+ ))}+ <span {...stylex.props(styles.textContainer)}>+ {superheading &&+ (superheadingHref ? (+ <XDSLink+ label={superheading}+ href={superheadingHref}+ color="secondary"+ size="xsm">+ {superheading}+ </XDSLink>+ ) : (+ <span {...stylex.props(styles.superheading)}>{superheading}</span>+ ))}+ {headingHref ? (+ <XDSLink+ label={heading ?? ''}+ href={headingHref}+ color="primary"+ weight="semibold">+ {heading}+ </XDSLink>+ ) : (+ <span {...stylex.props(styles.heading)}>{heading}</span>+ )}+ {subheading &&+ (subheadingHref ? (+ <XDSLink+ label={subheading}+ href={subheadingHref}+ color="secondary"+ size="xsm">+ {subheading}+ </XDSLink>+ ) : (+ <span {...stylex.props(styles.subheading)}>{subheading}</span>+ ))}+ </span>+ {headerEndContentElement}+ {chevronElement}+ </div>+ );+ }+ // Default: static heading, no links, no menureturn (- <Element- ref={ref as React.Ref<HTMLAnchorElement & HTMLDivElement>}- href={href}+ <div+ ref={ref as React.Ref<HTMLDivElement>}+ data-testid={testId}{...mergeProps(xdsClassName('top-nav-heading'),- stylex.props(styles.base, isLink && styles.clickable, xstyle),+ stylex.props(styles.root, xstyle),className,style,)}{...props}>{logo && <span {...stylex.props(styles.logo)}>{logo}</span>}- {heading && <span {...stylex.props(styles.headingText)}>{heading}</span>}- </Element>+ {renderTextContent()}+ {headerEndContentElement}+ {chevronElement}+ </div>);}