{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "app-sidebar", "title": "App Sidebar", "author": "ilinxa", "description": "App-shell sidebar with mobile drawer mode, twelve composition slots, prefab nav parts, and a headless state hook.", "dependencies": [ "lucide-react" ], "registryDependencies": [ "avatar", "button", "dropdown-menu", "sheet" ], "files": [ { "path": "src/registry/components/navigation/app-sidebar/app-sidebar.tsx", "content": "\"use client\";\n\nimport { PanelLeft, PanelLeftClose } from \"lucide-react\";\nimport {\n useCallback,\n useEffect,\n useId,\n useImperativeHandle,\n useMemo,\n useRef,\n} from \"react\";\nimport { cn } from \"@/lib/utils\";\nimport { Sheet, SheetContent, SheetTitle } from \"@/components/ui/sheet\";\nimport { useActiveDetection } from \"./hooks/use-active-detection\";\nimport { useMatchMedia, resolveBreakpointQuery } from \"./hooks/use-match-media\";\nimport { useSidebarReducer } from \"./hooks/use-sidebar-reducer\";\nimport { useStorageSync } from \"./hooks/use-storage-sync\";\nimport {\n AppSidebarContext,\n type AppSidebarContextValue,\n} from \"./contexts/sidebar-nav-context\";\nimport { buildHandle } from \"./lib/build-handle\";\nimport { deriveCssVars } from \"./lib/derive-css-vars\";\nimport { flattenEntriesForKeyboard } from \"./lib/flatten-entries\";\nimport { handleSidebarKeydown } from \"./lib/keyboard-handler\";\nimport { DefaultLink } from \"./parts/default-link\";\nimport { NavBrand } from \"./parts/nav-brand\";\nimport { NavPrimaryAction } from \"./parts/nav-primary-action\";\nimport { NavUser } from \"./parts/nav-user\";\nimport { SidebarEmptyState } from \"./parts/sidebar-empty-state\";\nimport { SidebarLoadingSkeleton } from \"./parts/sidebar-loading-skeleton\";\nimport { SidebarNavList } from \"./parts/sidebar-nav-list\";\nimport { SidebarSkipLink } from \"./parts/sidebar-skip-link\";\nimport type {\n NavUserMenuItemSelectEvent,\n AppSidebarEmptyReason,\n AppSidebarHandle,\n AppSidebarMobileOpenReason,\n AppSidebarProps,\n} from \"./types\";\n\n/** Breakpoint → CSS class lookup (L44 — CSS-gated, not JS-gated rendering). */\nconst BREAKPOINT_DESKTOP_VISIBLE: Record = {\n sm: \"sm:flex\",\n md: \"md:flex\",\n lg: \"lg:flex\",\n xl: \"xl:flex\",\n \"2xl\": \"2xl:flex\",\n};\nconst BREAKPOINT_MOBILE_VISIBLE: Record = {\n sm: \"sm:hidden\",\n md: \"md:hidden\",\n lg: \"lg:hidden\",\n xl: \"xl:hidden\",\n \"2xl\": \"2xl:hidden\",\n};\n\n/**\n * C3 — items rendering + active detection.\n *\n * Items now actually render. Active item highlighted (full-fill paint;\n * activeVariant matrix lands C5). Sections render their items inline\n * (full section UI with header lands C4). Click sequence per L28 wired.\n */\nexport function AppSidebar(props: AppSidebarProps) {\n const {\n items,\n currentPath,\n isActive,\n defaultMatch = \"exact\",\n linkComponent = DefaultLink,\n className,\n id: idProp,\n \"aria-label\": ariaLabel = \"Main navigation\",\n defaultCollapsed,\n defaultMobileOpen,\n defaultCollapsedSectionIds,\n isCollapsed,\n isMobileOpen,\n onCollapsedChange,\n onMobileOpenChange,\n onItemClick,\n onItemNavigate,\n onSectionToggle,\n autoCloseMobileOnNavigate = true,\n keepEmptySections = false,\n permissions,\n renderItem,\n renderSection,\n renderBadge,\n renderTooltipContent,\n renderLoading,\n renderEmptyState,\n loading = false,\n state: externalState,\n storageKey,\n autoExpandActiveSection = true,\n autoScrollActiveIntoView = true,\n brandSlot,\n brand,\n headerSlot,\n navAccessorySlot,\n primaryActionSlot,\n primaryAction,\n footerSlot,\n footer,\n side = \"left\",\n activeVariant = \"fill\",\n collapsedWidth,\n expandedWidth,\n transitionDuration,\n style,\n mobileBreakpoint = \"lg\",\n mobileDrawerSide,\n drawerHeaderSlot,\n skipLinkTarget,\n skipLinkLabel = \"Skip to content\",\n onPermissionDenied,\n onSkipLinkActivated,\n onBrandClick,\n onPrimaryActionClick,\n onFooterTriggerOpen,\n onFooterMenuItemClick,\n ref: externalRef,\n // v0.2.0 — additive (L41–L52)\n topSlot,\n hrefTemplateValues,\n resolveHref,\n isOwner,\n currentMaxMembers,\n bypassFiltering,\n } = props;\n\n // L32: id defaults via useId() for \n const autoId = useId();\n const sidebarId = idProp ?? `app-sidebar-${autoId}`;\n\n // Section-collapse init priority (plan §8): explicit prop > per-section\n // defaultCollapsed. Storage rehydration (C11) will outrank both via\n // EXTERNAL_SYNC after mount.\n const initialCollapsedSectionIds = useMemo(() => {\n if (defaultCollapsedSectionIds) return defaultCollapsedSectionIds;\n const fromItems: string[] = [];\n for (const entry of items) {\n if (entry.kind === \"section\" && entry.defaultCollapsed) {\n fromItems.push(entry.id);\n }\n }\n return fromItems;\n }, [defaultCollapsedSectionIds, items]);\n\n // Reducer + Defense-1 + Defense-2 wiring\n const { state, dispatch } = useSidebarReducer({\n defaultCollapsed,\n defaultMobileOpen,\n defaultCollapsedSectionIds: initialCollapsedSectionIds,\n isCollapsed,\n isMobileOpen,\n onCollapsedChange,\n onMobileOpenChange,\n });\n\n // localStorage opt-in (L23). Per L43: when external `state` provided,\n // the hook owns storageKey; component's storageKey is ignored + dev warn.\n const effectiveStorageKey = externalState ? undefined : storageKey;\n if (\n externalState &&\n storageKey &&\n process.env.NODE_ENV !== \"production\"\n ) {\n console.warn(\n \"[app-sidebar] `storageKey` is ignored when `state` (lifted hook) is provided — the hook owns persistence (L43). Move storageKey to useAppSidebarState() options.\",\n );\n }\n useStorageSync(state, dispatch, effectiveStorageKey);\n\n // Items pipeline: derive visible entries → compute active item\n const { visible, active } = useActiveDetection({\n items,\n currentPath,\n isActive,\n defaultMatch,\n permissions,\n keepEmptySections,\n // v0.2.0 — three-gate intersection (L46) + bypass (Q21)\n isOwner,\n currentMaxMembers,\n bypassFiltering,\n });\n\n // F1 — auto-expand section containing the active item (L48-b).\n // When external state is provided, the hook (useAppSidebarState)\n // owns F1; component-internal effect skipped to avoid double-firing.\n useEffect(() => {\n if (externalState) return;\n if (!autoExpandActiveSection) return;\n if (!active.sectionId) return;\n if (!state.collapsedSectionIds.has(active.sectionId)) return;\n dispatch({\n type: \"SET_SECTION_COLLAPSED\",\n sectionId: active.sectionId,\n collapsed: false,\n });\n }, [\n externalState,\n autoExpandActiveSection,\n active.sectionId,\n state.collapsedSectionIds,\n dispatch,\n ]);\n\n // Breakpoint resolution — CSS class names for the L44 CSS-gated render path.\n // `useMatchMedia` returns the live mobile state for JS BEHAVIOR gating only\n // (e.g., autoCloseMobileOnNavigate timing decisions — actual visual swap is\n // CSS-driven, no SSR flash).\n const desktopVisibleClass =\n typeof mobileBreakpoint === \"string\" &&\n mobileBreakpoint in BREAKPOINT_DESKTOP_VISIBLE\n ? BREAKPOINT_DESKTOP_VISIBLE[mobileBreakpoint]\n : \"lg:flex\";\n const mobileVisibleClass =\n typeof mobileBreakpoint === \"string\" &&\n mobileBreakpoint in BREAKPOINT_MOBILE_VISIBLE\n ? BREAKPOINT_MOBILE_VISIBLE[mobileBreakpoint]\n : \"lg:hidden\";\n\n const isMobileBehavior = useMatchMedia(resolveBreakpointQuery(mobileBreakpoint));\n\n // closeMobile / toggleSection are wired through `finalHandle` so they\n // mutate the EXTERNAL state when one is provided, or the internal\n // reducer otherwise. Trade-off (L20 reasons): when external state,\n // the auto-close path loses the \"item-click\" reason discriminator —\n // `onMobileOpenChange` fires with \"imperative\" instead. Acceptable\n // for v0.1; a future polish commit can add `setMobileOpenWithReason`\n // to the handle if needed.\n\n // Imperative handle — refreshed with items + active-detection results.\n // v0.3.0 (C5, F5): delegated to the shared `buildHandle` factory.\n // Identical factory consumed by `useAppSidebarState` so the two state\n // paths can't drift apart.\n const handle = useMemo(\n () => buildHandle({ state, dispatch, items, visible, active }),\n [state, dispatch, items, visible, active],\n );\n\n // L30 — state prop precedence: external lifted state wins entirely over\n // internal reducer state. Internal reducer still computed for hooks-rules\n // compliance (L47), but its values flow through `finalCollapsed` /\n // `finalMobileOpen` / etc. only when external state isn't supplied.\n const finalCollapsed = externalState?.collapsed ?? state.collapsed;\n const finalMobileOpen = externalState?.mobileOpen ?? state.mobileOpen;\n const finalCollapsedSectionIds =\n externalState?.collapsedSectionIds ?? state.collapsedSectionIds;\n const finalActiveItem = externalState?.activeItem ?? active.item;\n const finalVisibleEntries = externalState?.visibleEntries ?? visible.entries;\n const finalHandle: AppSidebarHandle = externalState ?? handle;\n\n // F-cross-13 (v0.3.2): `onPointerDownOutside` / `onEscapeKeyDown` are\n // Radix-only SheetContent props — Base UI's DialogPopup rejects them. The\n // public `onMobileOpenChange.reason` discriminator (\"outside-click\" |\n // \"escape\") survives via own attribution: capture-phase document listeners\n // record the reason (with a freshness stamp so a non-closing Escape can't\n // mis-tag a later close); the cross-backend onOpenChange dispatch reads it.\n const mobilePanelRef = useRef(null);\n const mobileCloseReasonRef = useRef<{\n reason: AppSidebarMobileOpenReason;\n t: number;\n } | null>(null);\n useEffect(() => {\n if (!finalMobileOpen) return;\n const onPointerDown = (e: PointerEvent) => {\n const panel = mobilePanelRef.current;\n if (panel && e.target instanceof Node && !panel.contains(e.target)) {\n mobileCloseReasonRef.current = { reason: \"outside-click\", t: Date.now() };\n }\n };\n const onKeyDown = (e: KeyboardEvent) => {\n if (e.key === \"Escape\") {\n mobileCloseReasonRef.current = { reason: \"escape\", t: Date.now() };\n }\n };\n document.addEventListener(\"pointerdown\", onPointerDown, true);\n document.addEventListener(\"keydown\", onKeyDown, true);\n return () => {\n document.removeEventListener(\"pointerdown\", onPointerDown, true);\n document.removeEventListener(\"keydown\", onKeyDown, true);\n mobileCloseReasonRef.current = null;\n };\n }, [finalMobileOpen]);\n\n // Flattened keyboard traversal sequence (L37). Section headers (collapsible\n // only) interleave with their items; items hide when section is collapsed.\n const keyboardFlat = useMemo(\n () =>\n flattenEntriesForKeyboard(finalVisibleEntries, finalCollapsedSectionIds),\n [finalVisibleEntries, finalCollapsedSectionIds],\n );\n const keyboardEntryId = keyboardFlat.length > 0 ? keyboardFlat[0].id : null;\n\n // Reducer-driven focus state. Even when external `state` is provided,\n // focus tracking lives in the internal reducer — focus is transient UI,\n // not persistable consumer state.\n const focusedItemId = state.focusedItemId;\n\n // L38 — onPermissionDenied diff-firing. Fire once per item initially +\n // again for any item NEWLY entering the filtered set on subsequent renders.\n // Comparison runs on each render via the ref-tracked previous set.\n const prevFilteredRef = useRef | null>(null);\n useEffect(() => {\n const currentFiltered = visible.filteredByPermission;\n const currentIds = new Set(currentFiltered.map((f) => f.item.id));\n if (onPermissionDenied) {\n const prevIds = prevFilteredRef.current;\n for (const entry of currentFiltered) {\n if (prevIds === null || !prevIds.has(entry.item.id)) {\n onPermissionDenied({\n item: entry.item,\n requiredPermission: entry.requiredPermission,\n });\n }\n }\n }\n prevFilteredRef.current = currentIds;\n }, [visible.filteredByPermission, onPermissionDenied]);\n\n // Programmatic focus follow-up — when reducer's focusedItemId changes,\n // move DOM focus to the matching row (via `data-nav-id`). Layout effect\n // so focus lands before the browser paints, avoiding visible flashes.\n useEffect(() => {\n if (!focusedItemId) return;\n if (typeof document === \"undefined\") return;\n const nav = document.getElementById(sidebarId);\n if (!nav) return;\n // v0.3.0 (C3, F3): CSS.escape is universal in modern browsers\n // (Chrome 46+ / Edge 79+ / Firefox 31+ / Safari 10+) — the SSR guard\n // above already gates this code to the browser. The old `replace`\n // fallback only escaped `\"` and `\\`, missing `:`, `]`, leading digits,\n // and dozens of other selector-illegal characters.\n const escaped = window.CSS.escape(focusedItemId);\n const target = nav.querySelector(\n `[data-nav-id=\"${escaped}\"]`,\n );\n if (target && document.activeElement !== target) {\n target.focus();\n }\n }, [focusedItemId, sidebarId]);\n\n const handleKeyDown = useCallback(\n (event: React.KeyboardEvent) => {\n handleSidebarKeydown(event, {\n flat: keyboardFlat,\n focusedId: focusedItemId,\n setFocusedId: (id) => dispatch({ type: \"FOCUS_ITEM\", itemId: id }),\n toggleSection: (id) => finalHandle.toggleSection(id),\n isSectionCollapsed: (id) => finalCollapsedSectionIds.has(id),\n });\n },\n [keyboardFlat, focusedItemId, dispatch, finalHandle, finalCollapsedSectionIds],\n );\n\n // F2 — auto-scroll active item into view on mount + currentPath change (L48-c)\n useEffect(() => {\n if (!autoScrollActiveIntoView) return;\n if (typeof document === \"undefined\") return;\n if (!finalActiveItem) return;\n const nav = document.getElementById(sidebarId);\n if (!nav) return;\n const activeEl = nav.querySelector('[data-active=\"true\"]');\n if (!(activeEl instanceof HTMLElement)) return;\n const reducedMotion =\n typeof window !== \"undefined\" &&\n window.matchMedia?.(\"(prefers-reduced-motion: reduce)\").matches;\n activeEl.scrollIntoView({\n block: \"nearest\",\n behavior: reducedMotion ? \"auto\" : \"smooth\",\n });\n }, [autoScrollActiveIntoView, finalActiveItem, sidebarId]);\n\n // Helpers used by render — wired through finalHandle so they mutate\n // external state (when provided) or internal reducer (default).\n // v0.3.0 (C2, L54): closeMobile accepts a reason for the discriminator\n // (default \"imperative\" if unspecified — preserves v0.2.x callers).\n const closeMobile = useCallback(\n (reason?: AppSidebarMobileOpenReason) => {\n if (!isMobileBehavior) return;\n finalHandle.closeMobile(reason);\n },\n [finalHandle, isMobileBehavior],\n );\n\n const toggleSection = useCallback(\n (sectionId: string) => {\n finalHandle.toggleSection(sectionId);\n },\n [finalHandle],\n );\n\n // Attach the imperative handle to the consumer-supplied ref (React 19\n // ref-as-prop pattern). When external state provided, ref exposes the\n // external handle so trigger toggles drive the right state machine.\n useImperativeHandle(externalRef, () => finalHandle, [finalHandle]);\n\n const contextValue = useMemo(\n () => ({\n state: { ...state, collapsed: finalCollapsed, mobileOpen: finalMobileOpen, collapsedSectionIds: finalCollapsedSectionIds },\n dispatch,\n handle: finalHandle,\n sidebarId,\n }),\n [state, dispatch, finalHandle, sidebarId, finalCollapsed, finalMobileOpen, finalCollapsedSectionIds],\n );\n\n const cssVars = useMemo(\n () => deriveCssVars({ collapsedWidth, expandedWidth, transitionDuration }),\n [collapsedWidth, expandedWidth, transitionDuration],\n );\n\n const defaultAccessory = (\n finalHandle.toggleCollapse()}\n aria-label={finalCollapsed ? \"Expand sidebar\" : \"Collapse sidebar\"}\n aria-expanded={!finalCollapsed}\n aria-controls={sidebarId}\n className={cn(\n \"inline-flex h-8 w-8 shrink-0 items-center justify-center rounded-md\",\n \"text-muted-foreground hover:bg-muted hover:text-foreground\",\n \"focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-card\",\n )}\n >\n {finalCollapsed ? (\n \n ) : (\n \n )}\n \n );\n\n // Shared inner chrome — used by BOTH desktop \n\n {/* Mobile render path — CSS-hidden ABOVE breakpoint */}\n \n {\n if (typeof nextOpen !== \"boolean\") return;\n if (nextOpen) {\n finalHandle.openMobile();\n return;\n }\n const stamped = mobileCloseReasonRef.current;\n mobileCloseReasonRef.current = null;\n if (stamped && Date.now() - stamped.t < 500) {\n finalHandle.closeMobile(stamped.reason);\n } else {\n finalHandle.closeMobile();\n }\n }}\n >\n \n {ariaLabel}\n {skipLinkTarget && (\n \n )}\n {renderInnerChrome(\"mobile\")}\n \n \n \n \n );\n}\n", "type": "registry:component", "target": "components/app-sidebar/app-sidebar.tsx" }, { "path": "src/registry/components/navigation/app-sidebar/index.ts", "content": "export { AppSidebar } from \"./app-sidebar\";\nexport { AppSidebarTrigger } from \"./parts/sidebar-nav-trigger\";\nexport { NavBadge } from \"./parts/nav-badge\";\nexport { NavBrand } from \"./parts/nav-brand\";\nexport { NavPrimaryAction } from \"./parts/nav-primary-action\";\nexport { NavUser } from \"./parts/nav-user\";\nexport { useAppSidebarState } from \"./hooks/use-sidebar-nav-state\";\nexport { useFilteredNavSections } from \"./hooks/use-filtered-nav-sections\";\nexport type { UseFilteredNavSectionsOpts } from \"./hooks/use-filtered-nav-sections\";\n\nexport type {\n // Items schema\n NavItem,\n NavSection,\n NavSeparator,\n NavEntry,\n BasicNavItems,\n SidebarNavItems,\n\n // Link primitive\n NavLinkProps,\n NavLinkComponent,\n\n // Prefab part configs\n NavBadgeConfig,\n NavBrandConfig,\n NavPrimaryActionConfig,\n NavUserMenuItem,\n NavUserMenuItemSelectEvent, // v0.3.0 (L56) — event arg type for NavUserMenuItem.onClick\n NavUserConfig,\n\n // Main component\n AppSidebarProps,\n AppSidebarHandle,\n AppSidebarStateValue,\n AppSidebarMobileOpenReason,\n AppSidebarEmptyReason,\n AppSidebarEventArgs,\n\n // Render-prop slot args\n AppSidebarRenderItemArgs,\n AppSidebarRenderBadgeArgs,\n AppSidebarRenderTooltipContentArgs,\n AppSidebarRenderSectionArgs,\n AppSidebarRenderLoadingArgs,\n AppSidebarRenderEmptyStateArgs,\n\n // Companion + hook options\n AppSidebarTriggerProps,\n UseAppSidebarStateOptions,\n\n // v0.2.0 — additive\n NavContext,\n} from \"./types\";\n", "type": "registry:component", "target": "components/app-sidebar/index.ts" }, { "path": "src/registry/components/navigation/app-sidebar/types.ts", "content": "import type { ComponentType, CSSProperties, ReactNode, Ref } from \"react\";\n\n// ─────────────────────────────────────────────────────────────────────────\n// Items schema (L4 + L5 + L36 + L48)\n// ─────────────────────────────────────────────────────────────────────────\n\nexport interface NavItem {\n kind?: \"item\";\n id: string;\n label: string;\n icon?: ReactNode | ComponentType<{ className?: string }>;\n href?: string;\n onClick?: (event: React.MouseEvent) => void;\n badge?: number | string | NavBadgeConfig;\n match?: \"exact\" | \"prefix\";\n shortcut?: string;\n description?: string;\n accessory?: ReactNode;\n tooltipContent?: ReactNode;\n target?: \"_blank\" | \"_self\" | \"_parent\" | \"_top\";\n rel?: string;\n permission?: string;\n /**\n * v0.2.0 — When `true`, item is hidden in the filter pass unless the\n * sidebar's `isOwner` prop is also `true`. Default `false`. Works\n * alongside `permission` and `minMembers` — all three gates pass\n * independently (intersection per L46).\n */\n ownerOnly?: boolean;\n /**\n * v0.2.0 — When set, item is hidden unless sidebar's `currentMaxMembers`\n * prop is `>=` this value. Default unset (no min). Useful for plan-tier\n * gating (Members tab visible only when seat capacity ≥ N).\n */\n minMembers?: number;\n disabled?: boolean;\n hidden?: boolean;\n className?: string;\n \"data-testid\"?: string;\n}\n\nexport interface NavSection {\n kind: \"section\";\n id: string;\n title?: string;\n icon?: ReactNode | ComponentType<{ className?: string }>;\n collapsible?: boolean;\n defaultCollapsed?: boolean;\n items: ReadonlyArray;\n permission?: string;\n hidden?: boolean;\n}\n\nexport interface NavSeparator {\n kind: \"separator\";\n id?: string;\n}\n\nexport type NavEntry = NavItem | NavSection | NavSeparator;\nexport type BasicNavItems = ReadonlyArray;\nexport type SidebarNavItems = ReadonlyArray;\n\n// ─────────────────────────────────────────────────────────────────────────\n// NavContext discriminated union (v0.2.0 — L48 + I-6)\n// ─────────────────────────────────────────────────────────────────────────\n\n/**\n * Discriminated union for app-shell context types — exported helper for\n * consumers building multi-tenant SaaS surfaces. Type-only export; library\n * does NOT ship a `useNavContext` hook because the URL→context derivation\n * is coupled to the consumer's router (Next.js, TanStack Router, plain\n * `location` — all different). Consumers type their derivation function\n * with `(): NavContext` and TypeScript narrows correctly across the\n * discriminant.\n *\n * Source of the 5-case shape: migration analysis §8.2 (the kasder\n * socialmedia-adv-nav-system app-shell). Consumers needing different\n * context shapes type their own; this is a documented helper, not\n * mandatory. R13 acknowledges the opinionated shape.\n */\nexport type NavContext =\n | { type: \"personal\" }\n | { type: \"business\"; slug: string; accountId: string; accountName: string }\n | { type: \"platform\"; accountId: string }\n | { type: \"governance\" }\n | { type: \"cms\"; mode: \"platform\" }\n | { type: \"cms\"; mode: \"business\"; slug: string; accountId: string; accountName: string };\n\n// ─────────────────────────────────────────────────────────────────────────\n// Link primitive (L10 + L15)\n// ─────────────────────────────────────────────────────────────────────────\n\nexport interface NavLinkProps {\n href: string;\n className?: string;\n \"aria-current\"?: \"page\" | undefined;\n \"aria-label\"?: string;\n \"aria-disabled\"?: boolean | \"true\" | \"false\" | undefined;\n \"data-active\"?: boolean;\n children?: ReactNode;\n onClick?: (e: React.MouseEvent) => void;\n onMouseEnter?: (e: React.MouseEvent) => void;\n onFocus?: (e: React.FocusEvent) => void;\n target?: string;\n rel?: string;\n tabIndex?: number;\n ref?: Ref;\n [key: `data-${string}`]: unknown;\n}\n\nexport type NavLinkComponent = ComponentType;\n\n// ─────────────────────────────────────────────────────────────────────────\n// Prefab part configs (L14, L15)\n// ─────────────────────────────────────────────────────────────────────────\n\nexport interface NavBadgeConfig {\n value: number | string | ReactNode;\n max?: number;\n variant?: \"number\" | \"dot\" | \"pulse\";\n tone?: \"default\" | \"accent\" | \"destructive\" | \"muted\";\n position?: \"inline-end\" | \"corner\";\n showZero?: boolean;\n className?: string;\n}\n\nexport interface NavBrandConfig {\n logo?: ReactNode | { src: string; alt?: string };\n label: string;\n href?: string;\n linkComponent?: NavLinkComponent;\n}\n\nexport interface NavPrimaryActionConfig {\n icon: ReactNode | ComponentType<{ className?: string }>;\n label: string;\n onClick?: (event: React.MouseEvent) => void;\n href?: string;\n linkComponent?: NavLinkComponent;\n variant?: \"default\" | \"outline\" | \"ghost\" | \"secondary\";\n tone?: \"default\" | \"accent\" | \"destructive\";\n}\n\n/**\n * v0.3.0 — Event union for `NavUserMenuItem.onClick` callbacks. The underlying\n * primitive (`DropdownMenuItem.onSelect`) passes a plain `Event` for keyboard\n * activations and a `React.MouseEvent` for clicks. Use this alias to type\n * custom `onClick` handlers without spelling out the union:\n *\n * ```ts\n * const handler = (event: NavUserMenuItemSelectEvent) => {\n * if (event instanceof MouseEvent) { console.log(event.clientX); }\n * };\n * ```\n */\nexport type NavUserMenuItemSelectEvent = Event | React.MouseEvent;\n\nexport interface NavUserMenuItem {\n kind: \"item\";\n icon?: ReactNode | ComponentType<{ className?: string }>;\n label: string;\n /**\n * v0.3.0 — widened from `React.MouseEvent` to `Event | React.MouseEvent` to\n * honestly type the event arg passed by Radix's `DropdownMenuItem.onSelect`\n * (which may be a plain `Event` or `MouseEvent` depending on input modality\n * and primitive vendor). v0.2.x consumers reading MouseEvent-only fields\n * (e.g. `event.clientX`) narrow with `if (event instanceof MouseEvent) { … }`\n * or cast at the call site.\n */\n onClick?: (event: NavUserMenuItemSelectEvent) => void;\n href?: string;\n linkComponent?: NavLinkComponent;\n variant?: \"default\" | \"destructive\";\n shortcut?: string;\n disabled?: boolean;\n}\n\nexport interface NavUserConfig {\n user: {\n name: string;\n handle?: string;\n avatarUrl?: string;\n avatarFallback?: string;\n status?: \"online\" | \"offline\" | \"busy\" | \"away\" | \"invisible\";\n };\n menuItems: ReadonlyArray;\n onTriggerOpen?: (args: { open: boolean }) => void;\n}\n\n// ─────────────────────────────────────────────────────────────────────────\n// Events + state (L20 — object-args throughout)\n// ─────────────────────────────────────────────────────────────────────────\n\nexport type AppSidebarMobileOpenReason =\n | \"trigger\"\n | \"item-click\"\n | \"outside-click\"\n | \"escape\"\n | \"imperative\";\n\nexport interface AppSidebarHandle {\n // Collapse\n toggleCollapse(): void;\n setCollapsed(next: boolean): void;\n isCollapsed(): boolean;\n\n // Mobile drawer\n // v0.3.0 (L54): optional `reason?` param propagates through to\n // `onMobileOpenChange.reason`. Default `\"imperative\"` preserves v0.2.x\n // call sites — `handle.closeMobile()` still works exactly as before.\n /** Open the mobile drawer. Optional `reason` reaches `onMobileOpenChange.reason`. Default `\"imperative\"`. */\n openMobile(reason?: AppSidebarMobileOpenReason): void;\n /** Close the mobile drawer. Optional `reason` reaches `onMobileOpenChange.reason`. Default `\"imperative\"`. */\n closeMobile(reason?: AppSidebarMobileOpenReason): void;\n /** Toggle the mobile drawer. Optional `reason` reaches `onMobileOpenChange.reason`. Default `\"imperative\"`. */\n toggleMobile(reason?: AppSidebarMobileOpenReason): void;\n isMobileOpen(): boolean;\n\n // Section state\n toggleSection(sectionId: string): void;\n expandSection(sectionId: string): void;\n collapseSection(sectionId: string): void;\n /** Expand every section (clears the entire collapsed-set). */\n expandAllSections(): void;\n /**\n * Collapse every currently-VISIBLE section.\n *\n * v0.3.0 NOTE: operates on sections that survive the permission /\n * ownerOnly / minMembers filter pass — sections hidden by gates are not\n * touched. To collapse a section regardless of visibility, call\n * `collapseSection(id)` directly with its id.\n */\n collapseAllSections(): void;\n isSectionCollapsed(sectionId: string): boolean;\n\n // Items + active\n getItems(): ReadonlyArray;\n getItemById(id: string): NavItem | undefined;\n getActiveItem(): NavItem | undefined;\n\n // Focus\n focusItem(id: string): void;\n focusFirstItem(): void;\n focusLastItem(): void;\n\n // Snapshot\n getState(): AppSidebarStateValue;\n}\n\nexport interface AppSidebarStateValue extends AppSidebarHandle {\n collapsed: boolean;\n mobileOpen: boolean;\n collapsedSectionIds: ReadonlySet;\n activeItemId: string | null;\n activeItem: NavItem | null;\n visibleEntries: ReadonlyArray;\n}\n\n// ─────────────────────────────────────────────────────────────────────────\n// Empty-state reason (L48)\n// ─────────────────────────────────────────────────────────────────────────\n\nexport type AppSidebarEmptyReason =\n | \"no-items\"\n | \"all-filtered-by-permission\"\n | \"all-hidden\"\n | \"all-filtered-by-loading\";\n\n// ─────────────────────────────────────────────────────────────────────────\n// Render-prop slot arg shapes (L29)\n// ─────────────────────────────────────────────────────────────────────────\n\nexport interface AppSidebarRenderItemArgs {\n item: NavItem;\n isActive: boolean;\n isCollapsed: boolean;\n isFocused: boolean;\n isDisabled: boolean;\n sectionId: string | null;\n indexInSection: number;\n defaultRender: ReactNode;\n}\n\nexport interface AppSidebarRenderBadgeArgs {\n item: NavItem;\n badge: NavBadgeConfig;\n position: \"inline-end\" | \"corner\";\n defaultRender: ReactNode;\n}\n\nexport interface AppSidebarRenderTooltipContentArgs {\n item: NavItem;\n isActive: boolean;\n}\n\nexport interface AppSidebarRenderSectionArgs {\n section: NavSection;\n isCollapsed: boolean;\n visibleItemCount: number;\n defaultRender: ReactNode;\n}\n\nexport interface AppSidebarRenderLoadingArgs {\n isCollapsed: boolean;\n defaultRender: ReactNode;\n}\n\nexport interface AppSidebarRenderEmptyStateArgs {\n reason: AppSidebarEmptyReason;\n}\n\n// ─────────────────────────────────────────────────────────────────────────\n// Event arg shapes (L20)\n// ─────────────────────────────────────────────────────────────────────────\n\nexport interface AppSidebarEventArgs {\n collapsedChange: { collapsed: boolean };\n mobileOpenChange: { open: boolean; reason: AppSidebarMobileOpenReason };\n itemClick: { item: NavItem; isActive: boolean; event: React.MouseEvent };\n itemHover: { item: NavItem; event: React.MouseEvent };\n itemFocus: { item: NavItem; event: React.FocusEvent };\n itemNavigate: { item: NavItem };\n activeItemChange: { item: NavItem | null; previousItem: NavItem | null };\n sectionToggle: { section: NavSection; collapsed: boolean };\n permissionDenied: { item: NavItem; requiredPermission: string };\n brandClick: { event: React.MouseEvent };\n primaryActionClick: { event: React.MouseEvent };\n footerTriggerOpen: { open: boolean };\n // v0.3.0 (C4, F10): event widened to NavUserMenuItemSelectEvent to match\n // the widened NavUserMenuItem.onClick. Same callback chain — must be\n // self-consistent. Consumers narrow with `event instanceof MouseEvent`.\n footerMenuItemClick: { menuItem: NavUserMenuItem; event: NavUserMenuItemSelectEvent };\n skipLinkActivated: { event: React.MouseEvent };\n mount: { initialState: AppSidebarStateValue };\n}\n\n// ─────────────────────────────────────────────────────────────────────────\n// Main component props (the full surface)\n// ─────────────────────────────────────────────────────────────────────────\n\nexport interface AppSidebarProps {\n // Items\n items: ReadonlyArray;\n\n // Active detection\n currentPath: string;\n isActive?: (item: NavItem, currentPath: string) => boolean;\n defaultMatch?: \"exact\" | \"prefix\";\n\n // Link primitive\n linkComponent?: NavLinkComponent;\n\n // Collapse (uncontrolled / controlled / lifted via state)\n defaultCollapsed?: boolean;\n isCollapsed?: boolean;\n /**\n * Fired when the collapsed state changes.\n *\n * v0.3.0 NOTE: does NOT fire during localStorage rehydration on mount. The\n * persisted collapsed state is already reflected in the initial render via\n * the storage-read effect; firing the callback at that point would be\n * confusing (the consumer didn't request the change). The callback only\n * fires on user-initiated transitions: toggle button, controlled-prop\n * change, or imperative handle call (`handle.toggleCollapse()` /\n * `setCollapsed(next)`).\n */\n onCollapsedChange?: (args: AppSidebarEventArgs[\"collapsedChange\"]) => void;\n\n // Mobile drawer (L8 + L24 + L44)\n defaultMobileOpen?: boolean;\n isMobileOpen?: boolean;\n onMobileOpenChange?: (args: AppSidebarEventArgs[\"mobileOpenChange\"]) => void;\n mobileBreakpoint?: \"sm\" | \"md\" | \"lg\" | \"xl\" | \"2xl\" | (string & {});\n mobileDrawerSide?: \"left\" | \"right\";\n autoCloseMobileOnNavigate?: boolean;\n\n // Lifted state (L30 — wins over individual props above)\n state?: AppSidebarStateValue;\n\n // Layout\n side?: \"left\" | \"right\";\n collapsedWidth?: string;\n expandedWidth?: string;\n transitionDuration?: string;\n activeVariant?: \"fill\" | \"left-bar\" | \"right-bar\" | \"outline\" | \"subtle\";\n\n // Sections (L48-b)\n autoExpandActiveSection?: boolean;\n defaultCollapsedSectionIds?: ReadonlyArray;\n keepEmptySections?: boolean;\n\n // Active item view (L48-c)\n autoScrollActiveIntoView?: boolean;\n\n // Persistence (L23)\n storageKey?: string;\n\n // Permissions (L22)\n permissions?: ReadonlySet;\n\n // Slots — named (L14)\n headerSlot?: ReactNode;\n brandSlot?: ReactNode;\n brand?: NavBrandConfig;\n navAccessorySlot?: ReactNode;\n primaryActionSlot?: ReactNode;\n primaryAction?: NavPrimaryActionConfig;\n footerSlot?: ReactNode;\n footer?: NavUserConfig;\n drawerHeaderSlot?: ReactNode;\n\n // Slots — render-prop (L13)\n renderItem?: (args: AppSidebarRenderItemArgs) => ReactNode;\n renderBadge?: (args: AppSidebarRenderBadgeArgs) => ReactNode;\n renderTooltipContent?: (args: AppSidebarRenderTooltipContentArgs) => ReactNode;\n renderSection?: (args: AppSidebarRenderSectionArgs) => ReactNode;\n renderLoading?: (args: AppSidebarRenderLoadingArgs) => ReactNode;\n renderEmptyState?: (args: AppSidebarRenderEmptyStateArgs) => ReactNode;\n\n // Loading\n loading?: boolean;\n\n // Events\n onItemClick?: (args: AppSidebarEventArgs[\"itemClick\"]) => void;\n onItemHover?: (args: AppSidebarEventArgs[\"itemHover\"]) => void;\n onItemFocus?: (args: AppSidebarEventArgs[\"itemFocus\"]) => void;\n onItemNavigate?: (args: AppSidebarEventArgs[\"itemNavigate\"]) => void;\n onActiveItemChange?: (args: AppSidebarEventArgs[\"activeItemChange\"]) => void;\n onSectionToggle?: (args: AppSidebarEventArgs[\"sectionToggle\"]) => void;\n onPermissionDenied?: (args: AppSidebarEventArgs[\"permissionDenied\"]) => void;\n onBrandClick?: (args: AppSidebarEventArgs[\"brandClick\"]) => void;\n onPrimaryActionClick?: (args: AppSidebarEventArgs[\"primaryActionClick\"]) => void;\n onFooterTriggerOpen?: (args: AppSidebarEventArgs[\"footerTriggerOpen\"]) => void;\n onFooterMenuItemClick?: (args: AppSidebarEventArgs[\"footerMenuItemClick\"]) => void;\n onSkipLinkActivated?: (args: AppSidebarEventArgs[\"skipLinkActivated\"]) => void;\n onMount?: (args: AppSidebarEventArgs[\"mount\"]) => void;\n onUnmount?: () => void;\n\n // Standard\n className?: string;\n style?: CSSProperties;\n \"aria-label\"?: string;\n id?: string;\n skipLinkTarget?: string;\n skipLinkLabel?: string;\n ref?: Ref;\n\n // ───────────────────────────────────────────────────────────────────────\n // v0.2.0 — additive expansion (L41–L52). Zero breaking changes for v0.1.x\n // consumers; every new prop is optional and defaults to v0.1 behavior.\n // ───────────────────────────────────────────────────────────────────────\n\n /**\n * v0.2.0 — Slot above the brand row. Geographically distinct from v0.1's\n * `headerSlot` (which is INSIDE the brand row, to the LEFT of brand).\n * Hierarchy top → bottom: `topSlot` → `headerSlot` → `brandSlot` →\n * `navAccessorySlot`. Consumer Fragment-stacks if multiple widgets\n * needed (L41). Canonical occupant: ``.\n */\n topSlot?: ReactNode;\n\n /**\n * v0.2.0 — Map of placeholder values for href substitution. When present,\n * every `{key}` substring in any `NavItem.href` is replaced with\n * `templateValues[key]` via `String.prototype.replaceAll`. Items whose\n * href has no `{...}` placeholders render unchanged. Combines with\n * `resolveHref` — `resolveHref` wins when both provided (L43).\n *\n * Dev-warns when an href references a `{xxx}` placeholder not present\n * in the map (only at the substitution site; tree-shaken in prod).\n */\n hrefTemplateValues?: Record;\n\n /**\n * v0.2.0 — Escape-hatch callback for href resolution. When provided,\n * wins precedence over `hrefTemplateValues`. Called per item per render\n * — should be a stable function (`useCallback`). Return value is the\n * final href string (strict `string`; consumer suppresses href by\n * removing the item from `items`).\n */\n resolveHref?: (\n item: NavItem,\n templateValues: Record | undefined,\n ) => string;\n\n /**\n * v0.2.0 — Whether the current user is an owner. Fed into the filter\n * pass; default `false` → all `ownerOnly` items hidden. Raw scalar, not\n * opaque membership object (L52).\n */\n isOwner?: boolean;\n\n /**\n * v0.2.0 — Current plan-tier seat capacity. Fed into the filter pass;\n * default `Infinity` → all `minMembers` items visible.\n */\n currentMaxMembers?: number;\n\n /**\n * v0.2.0 — When `true`, bypass the three permission gates (`permission`\n * / `ownerOnly` / `minMembers`) at BOTH section AND item levels (Finding\n * 4 — prevents \"section disappears, items remain\" inconsistency).\n * `hidden: true` is still respected (Q21). Use case: personal-context\n * shortcuts, admin overrides, debug views.\n */\n bypassFiltering?: boolean;\n}\n\n// ─────────────────────────────────────────────────────────────────────────\n// Companion component (L17)\n// ─────────────────────────────────────────────────────────────────────────\n\nexport interface AppSidebarTriggerProps {\n controls?: Ref | AppSidebarHandle | null;\n className?: string;\n children?: ReactNode;\n \"aria-label\"?: string;\n asChild?: boolean;\n}\n\n// ─────────────────────────────────────────────────────────────────────────\n// Headless hook options (L16)\n// ─────────────────────────────────────────────────────────────────────────\n\nexport interface UseAppSidebarStateOptions {\n defaultCollapsed?: boolean;\n defaultMobileOpen?: boolean;\n defaultCollapsedSectionIds?: ReadonlyArray;\n items?: ReadonlyArray;\n currentPath?: string;\n isActive?: (item: NavItem, currentPath: string) => boolean;\n defaultMatch?: \"exact\" | \"prefix\";\n permissions?: ReadonlySet;\n storageKey?: string;\n autoExpandActiveSection?: boolean;\n}\n", "type": "registry:component", "target": "components/app-sidebar/types.ts" }, { "path": "src/registry/components/navigation/app-sidebar/contexts/sidebar-nav-context.tsx", "content": "\"use client\";\n\nimport { createContext, useContext } from \"react\";\nimport type { SidebarReducerAction, SidebarReducerState } from \"../lib/sidebar-reducer\";\nimport type { AppSidebarHandle } from \"../types\";\n\n/**\n * Context shape consumed by (C7), prefab parts\n * (, , ) (C6/C9), and any consumer-rendered\n * descendant that wants to read sidebar state without prop drilling.\n *\n * L40: each creates its own provider scoped to its subtree,\n * so multi-instance pages get isolated contexts automatically. \n * reads the NEAREST provider (standard React context behavior).\n *\n * The context value is `null` when there's no provider above — descendants\n * MUST handle this (e.g., falls back to disabled + dev warn;\n * falls back to position=\"inline-end\" per L46).\n */\nexport interface AppSidebarContextValue {\n // Latest reducer state — descendants read here, not via prop drilling\n state: SidebarReducerState;\n\n // Dispatch — descendants use this to mutate (e.g., dispatches TOGGLE_MOBILE)\n dispatch: React.Dispatch;\n\n // Imperative handle — same surface as the \n // (descendants like use this when they're given an explicit `controls` prop)\n handle: AppSidebarHandle;\n\n // Element id of the sidebar — `` hooks into this\n sidebarId: string;\n}\n\nexport const AppSidebarContext = createContext(null);\nAppSidebarContext.displayName = \"AppSidebarContext\";\n\n/** Internal helper — returns the context value or null. Used by prefab parts + trigger. */\nexport function useAppSidebarContextOrNull(): AppSidebarContextValue | null {\n return useContext(AppSidebarContext);\n}\n", "type": "registry:component", "target": "components/app-sidebar/contexts/sidebar-nav-context.tsx" }, { "path": "src/registry/components/navigation/app-sidebar/hooks/use-active-detection.ts", "content": "import { useMemo } from \"react\";\nimport { computeActiveItem, type ActiveItemResult } from \"../lib/compute-active-item\";\nimport { deriveVisibleEntries, type VisibleEntriesResult } from \"../lib/derive-visible-entries\";\nimport type { NavEntry, NavItem } from \"../types\";\n\ninterface UseActiveDetectionOptions {\n items: ReadonlyArray;\n currentPath: string;\n isActive?: (item: NavItem, currentPath: string) => boolean;\n defaultMatch?: \"exact\" | \"prefix\";\n permissions?: ReadonlySet;\n keepEmptySections?: boolean;\n // v0.2.0 — gates threaded to deriveVisibleEntries (L44 / L45 / Q21).\n isOwner?: boolean;\n currentMaxMembers?: number;\n bypassFiltering?: boolean;\n}\n\nexport interface UseActiveDetectionResult {\n visible: VisibleEntriesResult;\n active: ActiveItemResult;\n}\n\n/**\n * Memoize the items[] → visible-entries → active-item pipeline.\n *\n * Reference stability of `items` is critical (L34) — non-memoized items[]\n * invalidate this memo every render. Guide.md teaches consumers to memoize.\n *\n * v0.2.0 — also threads `isOwner`, `currentMaxMembers`, `bypassFiltering`\n * into the deriveVisibleEntries call (L44–L46 + Q21).\n */\nexport function useActiveDetection(\n options: UseActiveDetectionOptions,\n): UseActiveDetectionResult {\n const visible = useMemo(\n () =>\n deriveVisibleEntries({\n items: options.items,\n permissions: options.permissions,\n keepEmptySections: options.keepEmptySections,\n isOwner: options.isOwner,\n currentMaxMembers: options.currentMaxMembers,\n bypassFiltering: options.bypassFiltering,\n }),\n [\n options.items,\n options.permissions,\n options.keepEmptySections,\n options.isOwner,\n options.currentMaxMembers,\n options.bypassFiltering,\n ],\n );\n\n const active = useMemo(\n () =>\n computeActiveItem({\n entries: visible.entries,\n currentPath: options.currentPath,\n isActive: options.isActive,\n defaultMatch: options.defaultMatch,\n }),\n [visible.entries, options.currentPath, options.isActive, options.defaultMatch],\n );\n\n return { visible, active };\n}\n", "type": "registry:component", "target": "components/app-sidebar/hooks/use-active-detection.ts" }, { "path": "src/registry/components/navigation/app-sidebar/hooks/use-match-media.ts", "content": "import { useCallback, useSyncExternalStore } from \"react\";\n\n/**\n * SSR-safe matchMedia hook via `useSyncExternalStore`.\n *\n * Server snapshot returns `false` (matches the SSR HTML). Client snapshot\n * reads `window.matchMedia(query).matches`. Subscribe wires the change\n * event. This avoids the React-19 cascading-render antipattern\n * (setState-in-effect) — `useSyncExternalStore` is the right primitive\n * for synchronizing with browser APIs.\n *\n * IMPORTANT (L44): Mobile-vs-desktop RENDERING is gated by CSS classes\n * (`hidden lg:flex` etc.), NOT by this hook. This hook is for JS BEHAVIOR\n * gating only — e.g., deciding whether `autoCloseMobileOnNavigate` should\n * trigger when an item is clicked. The SSR-default `false` is harmless\n * because CSS owns the visual decision.\n */\nexport function useMatchMedia(query: string): boolean {\n const subscribe = useCallback(\n (callback: () => void) => {\n if (typeof window === \"undefined\" || !window.matchMedia) return () => {};\n const mql = window.matchMedia(query);\n if (typeof mql.addEventListener === \"function\") {\n mql.addEventListener(\"change\", callback);\n return () => mql.removeEventListener(\"change\", callback);\n }\n // Safari < 14 fallback\n mql.addListener(callback);\n return () => mql.removeListener(callback);\n },\n [query],\n );\n\n const getSnapshot = useCallback(() => {\n if (typeof window === \"undefined\" || !window.matchMedia) return false;\n return window.matchMedia(query).matches;\n }, [query]);\n\n const getServerSnapshot = useCallback(() => false, []);\n\n return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);\n}\n\n// Tailwind v4 default breakpoints (px). Used to translate the enum\n// values `\"sm\" | \"md\" | \"lg\" | \"xl\" | \"2xl\"` to CSS media queries.\nexport const TAILWIND_BREAKPOINTS = {\n sm: 640,\n md: 768,\n lg: 1024,\n xl: 1280,\n \"2xl\": 1536,\n} as const;\n\n/** Resolve a `mobileBreakpoint` prop value to a CSS media query string. */\nexport function resolveBreakpointQuery(\n bp: \"sm\" | \"md\" | \"lg\" | \"xl\" | \"2xl\" | (string & {}),\n): string {\n if (bp in TAILWIND_BREAKPOINTS) {\n const px = TAILWIND_BREAKPOINTS[bp as keyof typeof TAILWIND_BREAKPOINTS];\n return `(max-width: ${px - 1}px)`;\n }\n // Raw CSS query passed through (PQ7 union with raw string)\n return bp;\n}\n", "type": "registry:component", "target": "components/app-sidebar/hooks/use-match-media.ts" }, { "path": "src/registry/components/navigation/app-sidebar/hooks/use-sidebar-nav-state.ts", "content": "\"use client\";\n\nimport { useEffect, useMemo } from \"react\";\nimport type {\n NavEntry,\n AppSidebarHandle,\n AppSidebarStateValue,\n UseAppSidebarStateOptions,\n} from \"../types\";\nimport { buildHandle } from \"../lib/build-handle\";\nimport { useActiveDetection } from \"./use-active-detection\";\nimport { useSidebarReducer } from \"./use-sidebar-reducer\";\nimport { useStorageSync } from \"./use-storage-sync\";\n\n/**\n * Headless state hook — public API (L16).\n *\n * Returns a AppSidebarStateValue (superset of AppSidebarHandle plus\n * live state fields). Consumers using slots heavily OR building their\n * own UI lift state via this hook and pass it back to ``\n * via the `state` prop (which wins over individual props per L30).\n *\n * `` calls this hook internally too — the public hook is\n * the durable composition seam, not a parallel state machine.\n */\nexport function useAppSidebarState(\n options: UseAppSidebarStateOptions = {},\n): AppSidebarStateValue {\n const items = options.items ?? EMPTY_ITEMS;\n\n // Section-collapse init priority: explicit prop > per-section\n // defaultCollapsed field. Storage rehydration outranks both via\n // EXTERNAL_SYNC after mount.\n const initialCollapsedSectionIds = useMemo(() => {\n if (options.defaultCollapsedSectionIds) {\n return options.defaultCollapsedSectionIds;\n }\n const fromItems: string[] = [];\n for (const entry of items) {\n if (entry.kind === \"section\" && entry.defaultCollapsed) {\n fromItems.push(entry.id);\n }\n }\n return fromItems;\n }, [options.defaultCollapsedSectionIds, items]);\n\n const { state, dispatch } = useSidebarReducer({\n defaultCollapsed: options.defaultCollapsed,\n defaultMobileOpen: options.defaultMobileOpen,\n defaultCollapsedSectionIds: initialCollapsedSectionIds,\n });\n\n // localStorage opt-in\n useStorageSync(state, dispatch, options.storageKey);\n\n // Active detection (filtered visible entries + active item)\n const { visible, active } = useActiveDetection({\n items,\n currentPath: options.currentPath ?? \"\",\n isActive: options.isActive,\n defaultMatch: options.defaultMatch,\n permissions: options.permissions,\n });\n\n // F1 — auto-expand section containing the active item (L48-b)\n const autoExpandActiveSection = options.autoExpandActiveSection ?? true;\n useEffect(() => {\n if (!autoExpandActiveSection) return;\n if (!active.sectionId) return;\n if (!state.collapsedSectionIds.has(active.sectionId)) return;\n dispatch({\n type: \"SET_SECTION_COLLAPSED\",\n sectionId: active.sectionId,\n collapsed: false,\n });\n }, [\n autoExpandActiveSection,\n active.sectionId,\n state.collapsedSectionIds,\n dispatch,\n ]);\n\n // v0.3.0 (C5, F5): delegated to the shared `buildHandle` factory. Identical\n // factory consumed by `app-sidebar.tsx` so the two state paths can't drift.\n const handle = useMemo(\n () => buildHandle({ state, dispatch, items, visible, active }),\n [state, dispatch, items, visible, active],\n );\n\n return useMemo(\n () => ({\n ...handle,\n collapsed: state.collapsed,\n mobileOpen: state.mobileOpen,\n collapsedSectionIds: state.collapsedSectionIds,\n activeItemId: active.item?.id ?? null,\n activeItem: active.item,\n visibleEntries: visible.entries,\n }),\n [handle, state, active, visible],\n );\n}\n\nconst EMPTY_ITEMS: ReadonlyArray = [];\n", "type": "registry:component", "target": "components/app-sidebar/hooks/use-sidebar-nav-state.ts" }, { "path": "src/registry/components/navigation/app-sidebar/hooks/use-sidebar-reducer.ts", "content": "import { useReducer, useEffect, useMemo, useRef, useCallback } from \"react\";\nimport {\n type SidebarReducerAction,\n type SidebarReducerInitOptions,\n type SidebarReducerState,\n createInitialState,\n sidebarReducer,\n} from \"../lib/sidebar-reducer\";\nimport type { AppSidebarEventArgs } from \"../types\";\n\nexport interface UseSidebarReducerOptions extends SidebarReducerInitOptions {\n // Controlled-mode props (when provided, drive state via EXTERNAL_SYNC)\n isCollapsed?: boolean;\n isMobileOpen?: boolean;\n\n // Defense 1 — microtask-defer for these\n onCollapsedChange?: (args: AppSidebarEventArgs[\"collapsedChange\"]) => void;\n onMobileOpenChange?: (args: AppSidebarEventArgs[\"mobileOpenChange\"]) => void;\n}\n\nexport interface UseSidebarReducerResult {\n state: SidebarReducerState;\n dispatch: React.Dispatch;\n}\n\n/**\n * Internal reducer hook.\n *\n * Three-defenses controlled-mode wiring (L7):\n * • Defense 1 — microtask-defer onCollapsedChange / onMobileOpenChange callbacks\n * so consumers that synchronously sync to other state can't re-enter the reducer.\n * • Defense 2 — content-equality short-circuit on EXTERNAL_SYNC (handled inside\n * reducer's `EXTERNAL_SYNC` case via `lastSyncedSnapshot` check).\n * • Defense 3 — N/A for discrete boolean state (no continuous flow to suppress).\n *\n * NOT exported from index.ts — purely internal.\n */\nexport function useSidebarReducer(\n options: UseSidebarReducerOptions = {},\n): UseSidebarReducerResult {\n const [state, dispatch] = useReducer(\n sidebarReducer,\n {\n defaultCollapsed: options.defaultCollapsed,\n defaultMobileOpen: options.defaultMobileOpen,\n defaultCollapsedSectionIds: options.defaultCollapsedSectionIds,\n },\n createInitialState,\n );\n\n // Latest-ref pattern for callbacks (avoid stale closures in microtask defers)\n const onCollapsedChangeRef = useRef(options.onCollapsedChange);\n const onMobileOpenChangeRef = useRef(options.onMobileOpenChange);\n useEffect(() => {\n onCollapsedChangeRef.current = options.onCollapsedChange;\n onMobileOpenChangeRef.current = options.onMobileOpenChange;\n });\n\n // Controlled-mode → reducer sync (Defense 2 short-circuit inside reducer)\n useEffect(() => {\n if (options.isCollapsed === undefined && options.isMobileOpen === undefined) {\n return;\n }\n dispatch({\n type: \"EXTERNAL_SYNC\",\n collapsed: options.isCollapsed ?? state.collapsed,\n mobileOpen: options.isMobileOpen ?? state.mobileOpen,\n });\n // Intentionally NOT including state.* — this effect ONLY fires on controlled\n // prop changes; internal state changes shouldn't loop back through here.\n // eslint-disable-next-line react-hooks/exhaustive-deps\n }, [options.isCollapsed, options.isMobileOpen]);\n\n // Defense 1 — fire change callbacks via microtask defer when state mutates.\n // Skipped when the transition was EXTERNAL_SYNC-originated (consumer already\n // knows). v0.3.1 (review 5.4): \"sync-originated\" is now detected by snapshot\n // IDENTITY (EXTERNAL_SYNC mints a new `lastSyncedSnapshot` object on every\n // transition it causes) instead of comparing values against the snapshot —\n // the old value-compare also swallowed INTERNAL toggles that happened to land\n // back on the last-synced value (e.g. the 2nd click while a constant\n // controlled prop holds the rendered value), so the consumer never got the\n // change request.\n const prevCollapsedRef = useRef(state.collapsed);\n const prevMobileOpenRef = useRef(state.mobileOpen);\n const prevSnapshotRef = useRef(state.lastSyncedSnapshot);\n useEffect(() => {\n const syncOriginated = prevSnapshotRef.current !== state.lastSyncedSnapshot;\n prevSnapshotRef.current = state.lastSyncedSnapshot;\n if (prevCollapsedRef.current !== state.collapsed) {\n const next = state.collapsed;\n prevCollapsedRef.current = next;\n // Skip if this transition came from EXTERNAL_SYNC (consumer originated it)\n if (!(syncOriginated && state.lastSyncedSnapshot.collapsed === next)) {\n queueMicrotask(() => {\n onCollapsedChangeRef.current?.({ collapsed: next });\n });\n }\n }\n if (prevMobileOpenRef.current !== state.mobileOpen) {\n const next = state.mobileOpen;\n prevMobileOpenRef.current = next;\n if (!(syncOriginated && state.lastSyncedSnapshot.mobileOpen === next)) {\n // v0.3.0 (C2, L53): read the reason the dispatching action wrote into\n // reducer state. EXTERNAL_SYNC resets to \"imperative\" on transition;\n // SET/TOGGLE write the explicit reason; the no-op guard in the reducer\n // prevents re-entry from Sheet's onOpenChange from overwriting.\n const reason = state.lastMobileOpenReason ?? \"imperative\";\n queueMicrotask(() => {\n onMobileOpenChangeRef.current?.({\n open: next,\n reason,\n });\n });\n }\n }\n }, [state.collapsed, state.mobileOpen, state.lastSyncedSnapshot, state.lastMobileOpenReason]);\n\n // Stable dispatch (useReducer's dispatch is already stable; wrap for symmetry)\n const stableDispatch = useCallback>(\n (action) => dispatch(action),\n [],\n );\n\n // v0.3.1 (review 5.4) — controlled props win at READ time, not only on prop\n // CHANGE. Previously a controlled `isCollapsed`/`isMobileOpen` was only\n // honored via the EXTERNAL_SYNC effect above (which fires on prop change),\n // so an internal toggle could diverge the rendered state from a CONSTANT\n // controlled prop and the prop never won it back. The raw reducer state\n // still mutates on internal dispatches (so the Defense-1 effect above still\n // fires the change-request callbacks and the consumer can update its state);\n // what the component RENDERS is the prop whenever the prop is defined.\n const derivedState = useMemo(() => {\n if (\n options.isCollapsed === undefined &&\n options.isMobileOpen === undefined\n ) {\n return state;\n }\n return {\n ...state,\n collapsed: options.isCollapsed ?? state.collapsed,\n mobileOpen: options.isMobileOpen ?? state.mobileOpen,\n };\n }, [state, options.isCollapsed, options.isMobileOpen]);\n\n return { state: derivedState, dispatch: stableDispatch };\n}\n", "type": "registry:component", "target": "components/app-sidebar/hooks/use-sidebar-reducer.ts" }, { "path": "src/registry/components/navigation/app-sidebar/hooks/use-storage-sync.ts", "content": "\"use client\";\n\nimport { useEffect, useRef } from \"react\";\nimport type { SidebarReducerAction, SidebarReducerState } from \"../lib/sidebar-reducer\";\nimport {\n STORAGE_SCHEMA_VERSION,\n type StoredState,\n isStoredState,\n} from \"../lib/storage-schema\";\n\n/**\n * Opt-in localStorage persistence for collapse + collapsed-sections state.\n *\n * Rules (L23):\n * • No-op when `storageKey` is undefined or `window` is unavailable (SSR).\n * • Read on mount via useEffect — never during render (SSR-safe).\n * • Write on state change, debounced 50ms (rapid section-toggle spam\n * doesn't thrash localStorage).\n * • mobileOpen is NOT persisted (transient UI, not user-preference).\n * • Schema-versioned JSON; mismatch silently drops the stored payload.\n * • Quota / serialization failures silently swallowed.\n */\nexport function useStorageSync(\n state: SidebarReducerState,\n dispatch: React.Dispatch,\n storageKey: string | undefined,\n): void {\n const hasReadRef = useRef(false);\n const writeTimerRef = useRef | null>(null);\n\n // Read once on mount (or when storageKey changes)\n useEffect(() => {\n if (!storageKey || typeof window === \"undefined\") return;\n if (hasReadRef.current) return;\n hasReadRef.current = true;\n try {\n const raw = window.localStorage.getItem(storageKey);\n if (!raw) return;\n const parsed: unknown = JSON.parse(raw);\n if (!isStoredState(parsed)) return;\n dispatch({\n type: \"EXTERNAL_SYNC\",\n collapsed: parsed.collapsed,\n mobileOpen: state.mobileOpen,\n });\n // v0.3.1 (review): whole-set REPLACE, not per-id collapse replay.\n // The old per-id SET-collapsed loop could only ADD collapses — a\n // section the user had EXPANDED (i.e. removed from the stored array,\n // but present in defaultCollapsedSectionIds) re-collapsed on every\n // reload because its default-collapsed state was never cleared.\n dispatch({\n type: \"COLLAPSE_ALL_SECTIONS\",\n allSectionIds: parsed.collapsedSectionIds,\n });\n } catch {\n // Corrupted storage — silently fall back to defaults.\n }\n // Intentionally only re-runs when storageKey changes.\n // eslint-disable-next-line react-hooks/exhaustive-deps\n }, [storageKey]);\n\n // Debounced write on state change\n useEffect(() => {\n if (!storageKey || typeof window === \"undefined\") return;\n if (!hasReadRef.current) return; // don't write before initial read\n if (writeTimerRef.current) clearTimeout(writeTimerRef.current);\n writeTimerRef.current = setTimeout(() => {\n const payload: StoredState = {\n v: STORAGE_SCHEMA_VERSION,\n collapsed: state.collapsed,\n collapsedSectionIds: [...state.collapsedSectionIds],\n };\n try {\n window.localStorage.setItem(storageKey, JSON.stringify(payload));\n } catch {\n // Quota or serialization failure — silently ignored.\n }\n }, 50);\n\n return () => {\n if (writeTimerRef.current) clearTimeout(writeTimerRef.current);\n };\n }, [storageKey, state.collapsed, state.collapsedSectionIds]);\n}\n", "type": "registry:component", "target": "components/app-sidebar/hooks/use-storage-sync.ts" }, { "path": "src/registry/components/navigation/app-sidebar/hooks/use-filtered-nav-sections.ts", "content": "import { useMemo } from \"react\";\nimport { deriveVisibleEntries } from \"../lib/derive-visible-entries\";\nimport type { NavEntry } from \"../types\";\n\nexport interface UseFilteredNavSectionsOpts {\n sections: ReadonlyArray;\n permissions?: ReadonlySet;\n isOwner?: boolean;\n currentMaxMembers?: number;\n bypassFiltering?: boolean;\n}\n\n/**\n * Pure helper hook — returns the filtered `NavEntry[]` with all three\n * gates applied (permission ∩ ownerOnly ∩ minMembers per L46) and empty\n * sections dropped. `bypassFiltering: true` skips the three permission\n * gates at BOTH section + item levels; `hidden: true` is unconditionally\n * respected (Q21).\n *\n * **Memoized over 5 inputs (Q16)** — returns referentially-stable sections\n * when inputs don't change by reference (or value, for boolean/number).\n * Mitigates R14: downstream `` memoization holds.\n *\n * **Consumer-side memo guidance (Finding 6 / R16):** `permissions` is a\n * `ReadonlySet` — wrap construction in `useMemo([source])` on the\n * caller side, else the hook's memo will invalidate every render.\n *\n * Items-only return per PQ1 — diagnostic struct stays internal to\n * ``. NOT coupled to the `` component; consumers\n * rendering their own arbitrary sidebar UI use this standalone.\n */\nexport function useFilteredNavSections(\n opts: UseFilteredNavSectionsOpts,\n): ReadonlyArray {\n const { sections, permissions, isOwner, currentMaxMembers, bypassFiltering } = opts;\n\n return useMemo(\n () =>\n deriveVisibleEntries({\n items: sections,\n permissions,\n isOwner,\n currentMaxMembers,\n bypassFiltering,\n }).entries,\n [sections, permissions, isOwner, currentMaxMembers, bypassFiltering],\n );\n}\n", "type": "registry:component", "target": "components/app-sidebar/hooks/use-filtered-nav-sections.ts" }, { "path": "src/registry/components/navigation/app-sidebar/lib/active-variant-classes.ts", "content": "import type { AppSidebarProps } from \"../types\";\n\ntype Variant = NonNullable;\n\n/**\n * Per-variant Tailwind class composition (L12 + L17).\n *\n * Returns the class string for the link element based on:\n * - the chosen `activeVariant`\n * - whether the row is active or not\n *\n * renderItem slot (L13) bypasses this helper entirely — the slot decides\n * how to paint active state.\n */\nexport function getActiveVariantClasses(\n variant: Variant | undefined,\n isActive: boolean,\n): string {\n if (!isActive) {\n return \"text-foreground hover:bg-muted\";\n }\n\n switch (variant ?? \"fill\") {\n case \"fill\":\n return \"bg-(--ilinxa-nav-active-bg) text-(--ilinxa-nav-active-fg)\";\n\n case \"left-bar\":\n return [\n \"relative text-(--ilinxa-nav-active-bg)\",\n \"before:absolute before:left-0 before:top-1.5 before:bottom-1.5\",\n \"before:w-(--ilinxa-nav-active-bar-w) before:rounded-r-full\",\n \"before:bg-(--ilinxa-nav-active-bg)\",\n ].join(\" \");\n\n case \"right-bar\":\n return [\n \"relative text-(--ilinxa-nav-active-bg)\",\n \"after:absolute after:right-0 after:top-1.5 after:bottom-1.5\",\n \"after:w-(--ilinxa-nav-active-bar-w) after:rounded-l-full\",\n \"after:bg-(--ilinxa-nav-active-bg)\",\n ].join(\" \");\n\n case \"outline\":\n return \"ring-2 ring-inset ring-(--ilinxa-nav-active-bg) text-(--ilinxa-nav-active-bg)\";\n\n case \"subtle\":\n return \"bg-accent/30 text-foreground font-semibold\";\n\n default:\n return \"bg-(--ilinxa-nav-active-bg) text-(--ilinxa-nav-active-fg)\";\n }\n}\n", "type": "registry:component", "target": "components/app-sidebar/lib/active-variant-classes.ts" }, { "path": "src/registry/components/navigation/app-sidebar/lib/badge-format.ts", "content": "/**\n * Format a NavBadge `value` for display.\n *\n * - Numbers > max render as \"{max}+\" (cap overflow)\n * - Numbers ≤ max render as `String(value)`\n * - Non-numbers pass through unchanged (consumer supplied a string / ReactNode)\n * - Zero is filtered upstream by `` via `showZero` flag — not handled here.\n */\nexport function formatBadgeValue(\n value: number | string,\n max: number,\n): string {\n if (typeof value === \"number\") {\n return value > max ? `${max}+` : String(value);\n }\n return value;\n}\n", "type": "registry:component", "target": "components/app-sidebar/lib/badge-format.ts" }, { "path": "src/registry/components/navigation/app-sidebar/lib/build-handle.ts", "content": "import type { ActiveItemResult } from \"./compute-active-item\";\nimport type { VisibleEntriesResult } from \"./derive-visible-entries\";\nimport { flattenEntriesForKeyboard } from \"./flatten-entries\";\nimport type {\n SidebarReducerAction,\n SidebarReducerState,\n} from \"./sidebar-reducer\";\nimport type {\n NavEntry,\n NavItem,\n AppSidebarHandle,\n AppSidebarStateValue,\n} from \"../types\";\n\n/**\n * Build the imperative handle exposed to consumers (`ref` + ``).\n *\n * Shared by:\n * - `app-sidebar.tsx` — the component's own `useImperativeHandle` target.\n * - `hooks/use-sidebar-nav-state.ts` — the headless `useAppSidebarState()` hook.\n *\n * v0.3.0 (C5, F5): extracted from two near-identical inline builders that had\n * silently drifted between v0.2 bumps. Single source of truth.\n *\n * NOT exported from `index.ts` — internal-only. Consumers interact via the\n * handle object or the public `useAppSidebarState()` return value.\n */\nexport function buildHandle(deps: {\n state: SidebarReducerState;\n dispatch: React.Dispatch;\n items: ReadonlyArray;\n visible: VisibleEntriesResult;\n active: ActiveItemResult;\n}): AppSidebarHandle {\n const { state, dispatch, items, visible, active } = deps;\n\n // Lookup table for getItemById — uses visible.entries so consumers don't\n // resolve items hidden by permission / ownerOnly / minMembers gates.\n const itemsLookup = new Map();\n for (const entry of visible.entries) {\n if (entry.kind === \"section\") {\n for (const child of entry.items) itemsLookup.set(child.id, child);\n } else if (entry.kind !== \"separator\") {\n itemsLookup.set(entry.id, entry);\n }\n }\n\n const methods: Omit = {\n // Collapse\n toggleCollapse: () => dispatch({ type: \"TOGGLE_COLLAPSED\" }),\n setCollapsed: (next) =>\n dispatch({ type: \"SET_COLLAPSED\", collapsed: next }),\n isCollapsed: () => state.collapsed,\n\n // Mobile drawer — v0.3.0 (C2, L54) reason? plumbing.\n openMobile: (reason) =>\n dispatch({\n type: \"SET_MOBILE_OPEN\",\n open: true,\n reason: reason ?? \"imperative\",\n }),\n closeMobile: (reason) =>\n dispatch({\n type: \"SET_MOBILE_OPEN\",\n open: false,\n reason: reason ?? \"imperative\",\n }),\n // TOGGLE_MOBILE (NOT a translated SET) so the reducer reads FRESH\n // state.mobileOpen — handles rapid same-tick double-clicks correctly\n // (a translated SET would use closure-captured stale state and the\n // reducer's no-op guard would drop the second dispatch).\n toggleMobile: (reason) =>\n dispatch({ type: \"TOGGLE_MOBILE\", reason }),\n isMobileOpen: () => state.mobileOpen,\n\n // Section state — v0.3.0 (C5, F8): no allSectionIds payload on EXPAND.\n toggleSection: (sectionId) =>\n dispatch({ type: \"TOGGLE_SECTION\", sectionId }),\n expandSection: (sectionId) =>\n dispatch({ type: \"SET_SECTION_COLLAPSED\", sectionId, collapsed: false }),\n collapseSection: (sectionId) =>\n dispatch({ type: \"SET_SECTION_COLLAPSED\", sectionId, collapsed: true }),\n expandAllSections: () => dispatch({ type: \"EXPAND_ALL_SECTIONS\" }),\n collapseAllSections: () => {\n // v0.3.0 (C5, F9): source from visible.entries (post-filter) so we\n // don't collapse sections the user can't see.\n const ids = visible.entries\n .filter((e) => \"kind\" in e && e.kind === \"section\")\n .map((e) => (e as { id: string }).id);\n dispatch({ type: \"COLLAPSE_ALL_SECTIONS\", allSectionIds: ids });\n },\n isSectionCollapsed: (id) => state.collapsedSectionIds.has(id),\n\n // Items + active\n getItems: () => items,\n getItemById: (id) => itemsLookup.get(id),\n getActiveItem: () => active.item ?? undefined,\n\n // Focus — v0.3.1 (review): focusFirstItem/focusLastItem were public\n // no-ops (both dispatched `itemId: null`). Now resolved against the\n // same flattened keyboard-traversal sequence the arrow keys use\n // (visible entries minus collapsed-section items / disabled items).\n focusItem: (itemId) => dispatch({ type: \"FOCUS_ITEM\", itemId }),\n focusFirstItem: () => {\n const flat = flattenEntriesForKeyboard(\n visible.entries,\n state.collapsedSectionIds,\n );\n if (flat.length > 0) {\n dispatch({ type: \"FOCUS_ITEM\", itemId: flat[0].id });\n }\n },\n focusLastItem: () => {\n const flat = flattenEntriesForKeyboard(\n visible.entries,\n state.collapsedSectionIds,\n );\n if (flat.length > 0) {\n dispatch({ type: \"FOCUS_ITEM\", itemId: flat[flat.length - 1].id });\n }\n },\n };\n\n const handleObj: AppSidebarHandle = {\n ...methods,\n getState: (): AppSidebarStateValue => ({\n ...handleObj,\n collapsed: state.collapsed,\n mobileOpen: state.mobileOpen,\n collapsedSectionIds: state.collapsedSectionIds,\n activeItemId: active.item?.id ?? null,\n activeItem: active.item,\n visibleEntries: visible.entries,\n }),\n };\n return handleObj;\n}\n", "type": "registry:component", "target": "components/app-sidebar/lib/build-handle.ts" }, { "path": "src/registry/components/navigation/app-sidebar/lib/compute-active-item.ts", "content": "import type { NavEntry, NavItem } from \"../types\";\n\nexport interface ActiveItemResult {\n item: NavItem | null;\n // Section ID the active item lives inside (null = top-level)\n sectionId: string | null;\n}\n\ninterface ComputeOptions {\n // Already-filtered visible entries (post-permissions, post-hidden)\n entries: ReadonlyArray;\n currentPath: string;\n isActive?: (item: NavItem, currentPath: string) => boolean;\n defaultMatch?: \"exact\" | \"prefix\";\n}\n\n/**\n * Compute the active NavItem given a currentPath.\n *\n * Resolution order (L9):\n * 1. `isActive` predicate (if supplied) wins for every item.\n * 2. Per-item `match: \"exact\" | \"prefix\"` fallback.\n * 3. `defaultMatch` (default \"exact\") for items without `match`.\n *\n * Tie-break (L42): longest matching `item.href` wins for prefix matches.\n */\nexport function computeActiveItem(opts: ComputeOptions): ActiveItemResult {\n const { entries, currentPath, isActive, defaultMatch = \"exact\" } = opts;\n\n // Flatten: track each NavItem alongside its containing sectionId (null if top-level).\n const flat: { item: NavItem; sectionId: string | null }[] = [];\n for (const entry of entries) {\n if (entry.kind === \"section\") {\n for (const child of entry.items) {\n if (child.disabled) continue;\n flat.push({ item: child, sectionId: entry.id });\n }\n } else if (entry.kind === \"separator\") {\n continue;\n } else {\n if (entry.disabled) continue;\n flat.push({ item: entry, sectionId: null });\n }\n }\n\n if (isActive) {\n // Predicate wins; first match in flat order.\n for (const { item, sectionId } of flat) {\n if (isActive(item, currentPath)) return { item, sectionId };\n }\n return { item: null, sectionId: null };\n }\n\n // Exact pass first — any exact match wins immediately (cheaper than longest-prefix)\n for (const { item, sectionId } of flat) {\n const mode = item.match ?? defaultMatch;\n if (mode === \"exact\" && item.href === currentPath) {\n return { item, sectionId };\n }\n }\n\n // Prefix pass — collect all prefix candidates, pick longest href.\n let best: { item: NavItem; sectionId: string | null; length: number } | null = null;\n for (const { item, sectionId } of flat) {\n const mode = item.match ?? defaultMatch;\n if (mode !== \"prefix\" || !item.href) continue;\n // True prefix: currentPath starts with href + (next char is \"/\" or end)\n if (!currentPath.startsWith(item.href)) continue;\n const after = currentPath.charAt(item.href.length);\n if (after !== \"\" && after !== \"/\") continue;\n const length = item.href.length;\n if (!best || length > best.length) best = { item, sectionId, length };\n }\n\n if (best) return { item: best.item, sectionId: best.sectionId };\n return { item: null, sectionId: null };\n}\n", "type": "registry:component", "target": "components/app-sidebar/lib/compute-active-item.ts" }, { "path": "src/registry/components/navigation/app-sidebar/lib/derive-avatar-fallback.ts", "content": "/**\n * Derive 2-character avatar fallback initials from a name (L35).\n *\n * Examples:\n * \"Ahmet Kaya\" → \"AK\"\n * \"Slack\" → \"SL\"\n * \" spaced out \" → \"SO\"\n * \"\" → \"?\"\n * \"🙃 emoji\" → \"🙃E\" (preserves leading char graceful for emoji)\n */\nexport function deriveAvatarFallback(name: string | undefined | null): string {\n if (!name) return \"?\";\n const words = name.trim().split(/\\s+/).filter(Boolean);\n if (words.length === 0) return \"?\";\n if (words.length === 1) {\n return words[0].slice(0, 2).toUpperCase();\n }\n return (words[0][0] + words[1][0]).toUpperCase();\n}\n", "type": "registry:component", "target": "components/app-sidebar/lib/derive-avatar-fallback.ts" }, { "path": "src/registry/components/navigation/app-sidebar/lib/derive-css-vars.ts", "content": "import type { CSSProperties } from \"react\";\nimport type { AppSidebarProps } from \"../types\";\n\n/**\n * Build the inline-style object that sets the component's CSS variables\n * on the