Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
11.4 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file DocsShell.tsx
 * @input Route metadata, the server-built docs nav model, and the AppShell header
 * @output Docs navigation with a stable sidebar offset before hydration
 * @position Docsite-only shell
 */

import {useState, useMemo} from 'react';
import {usePathname} from 'next/navigation';
import {Search, FlaskConical} from 'lucide-react';
import * as stylex from '@stylexjs/stylex';
import {AppShell} from '@astryxdesign/core/AppShell';
import {SideNav, SideNavItem, SideNavSection} from '@astryxdesign/core/SideNav';
import {TextInput} from '@astryxdesign/core/TextInput';
import {Icon} from '@astryxdesign/core/Icon';
import {SharedTopNav} from './SharedTopNav';
import {HeaderHeightSeed} from './HeaderHeightSeed';
import {DocsBanner} from './InternalDocsPrompt';
import type {
  DocsNav,
  DocsNavEntry,
  DocsNavItem,
  DocsNavPackage,
} from './docsNav';
import {docsSidebarGroups} from './docsSidebarData';
import {DocsSidebarItems} from './DocsSidebarItems';

interface DocsShellProps {
  children: React.ReactNode;
  nav: DocsNav;
}

const styles = stylex.create({
  canaryMarker: {
    alignItems: 'center',
    display: 'inline-flex',
    height: 24,
    justifyContent: 'center',
    width: 24,
  },
});

function CanaryCategoryMarker() {
  return (
    <span {...stylex.props(styles.canaryMarker)}>
      <Icon icon={FlaskConical} label="Canary" size="sm" />
    </span>
  );
}

// ── Shell ──────────────────────────────────────────────────────────────

export function DocsShell({children, nav}: DocsShellProps) {
  const pathname = usePathname();
  const [componentQuery, setComponentQuery] = useState('');

  const {packages, docTopics, componentItems, utilities, canaryCategories} =
    nav;

  const q = componentQuery.trim().toLowerCase();

  // When searching, flatten every readiness category to individual entries so
  // results are all at the same level with no nesting.
  const flatSearchResults = useMemo<DocsNavEntry[]>(() => {
    if (!q) {
      return [];
    }
    const allItems = [
      ...componentItems,
      ...canaryCategories.flatMap(category => category.componentItems),
    ];
    return allItems.flatMap(item => {
      if (item.type === 'entry') {
        return item.displayName.toLowerCase().includes(q) ? [item] : [];
      }
      return item.entries.filter(e => e.displayName.toLowerCase().includes(q));
    });
  }, [canaryCategories, componentItems, q]);

  const filteredUtilities = useMemo(() => {
    const allUtilities = [
      ...utilities,
      ...canaryCategories.flatMap(category => category.utilities),
    ];
    return q
      ? allUtilities.filter(u => u.displayName.toLowerCase().includes(q))
      : utilities;
  }, [canaryCategories, utilities, q]);

  // Classify packages
  const isTheme = (p: DocsNavPackage) => p.name.includes('theme-');
  const libraryPackages = packages.filter(p => !isTheme(p) && !p.canaryOnly);
  const canaryPackages = packages.filter(p => !isTheme(p) && p.canaryOnly);

  // Classify doc topics by category (from data).
  const {guide: guideItems, foundations: foundationItems} =
    docsSidebarGroups(docTopics);

  // True for the /components index AND every /components/[name] detail page.
  // On these routes we hide every non-Components section so the sidebar is
  // focused on the component library — the top nav handles cross-area
  // navigation.
  const isOnComponentsRoute = pathname.startsWith('/components');

  const componentSearch = (
    <TextInput
      label="Search components"
      isLabelHidden
      value={componentQuery}
      onChange={setComponentQuery}
      placeholder="Search components…"
      startIcon={Search}
      hasClear
    />
  );

  const renderComponentItems = (items: DocsNavItem[]) =>
    items.map(item =>
      item.type === 'entry' ? (
        <SideNavItem
          key={`${item.packageName}:${item.name}`}
          label={item.displayName}
          href={item.href}
          isSelected={pathname === item.href}
        />
      ) : (
        <SideNavItem
          key={`${item.packageName}:${item.label}`}
          label={item.displayName}
          collapsible={{
            defaultIsCollapsed: !item.entries.some(e => pathname === e.href),
          }}>
          {item.entries.map(entry => (
            <SideNavItem
              key={`${entry.packageName}:${entry.name}`}
              label={entry.displayName}
              href={entry.href}
              isSelected={pathname === entry.href}
            />
          ))}
        </SideNavItem>
      ),
    );

  return (
    <AppShell
      className="astryx-docs-shell"
      variant="surface"
      height="auto"
      banner={<DocsBanner />}
      topNav={
        <>
          <SharedTopNav />
          <HeaderHeightSeed />
        </>
      }
      sideNav={
        <SideNav topContent={isOnComponentsRoute ? componentSearch : undefined}>
          {!isOnComponentsRoute && (
            <>
              {/* Getting Started */}
              <SideNavSection title="Documentation" isHeaderHidden>
                <SideNavItem
                  label="Getting Started"
                  href="/docs/getting-started"
                  isSelected={pathname === '/docs/getting-started'}
                />
                <SideNavItem
                  label="What's New"
                  href="/changelog"
                  isSelected={pathname === '/changelog'}
                />
              </SideNavSection>

              {/* Guide */}
              <SideNavSection title="Guide" isHeaderHidden>
                <SideNavItem
                  label="Guide"
                  collapsible={{defaultIsCollapsed: false}}>
                  <DocsSidebarItems items={guideItems} pathname={pathname} />
                </SideNavItem>
              </SideNavSection>

              {/* Foundations */}
              <SideNavSection title="Foundations" isHeaderHidden>
                <SideNavItem
                  label="Foundations"
                  collapsible={{defaultIsCollapsed: false}}>
                  <DocsSidebarItems
                    items={foundationItems}
                    pathname={pathname}
                  />
                </SideNavItem>
              </SideNavSection>

              {/* Stable libraries */}
              <SideNavSection title="Libraries" isHeaderHidden>
                <SideNavItem
                  label="Libraries"
                  collapsible={{defaultIsCollapsed: false}}>
                  {libraryPackages.map(p => (
                    <SideNavItem
                      key={p.name}
                      label={p.name}
                      href={`/docs/${p.name.replace('@astryxdesign/', '')}`}
                      isSelected={
                        pathname ===
                        `/docs/${p.name.replace('@astryxdesign/', '')}`
                      }
                    />
                  ))}
                </SideNavItem>
              </SideNavSection>

              {canaryPackages.length > 0 && (
                <SideNavSection title="Canary libraries" isHeaderHidden>
                  {canaryPackages.map(p => (
                    <SideNavItem
                      key={p.name}
                      label={p.displayName}
                      endContent={<CanaryCategoryMarker />}
                      href={`/docs/${p.name.replace('@astryxdesign/', '')}`}
                      isSelected={
                        pathname ===
                        `/docs/${p.name.replace('@astryxdesign/', '')}`
                      }
                    />
                  ))}
                </SideNavSection>
              )}
            </>
          )}

          {/* Components — only shown on /components routes */}
          {isOnComponentsRoute && (
            <>
              <SideNavSection title="Components" isHeaderHidden>
                {!q && (
                  <SideNavItem
                    label="Overview"
                    href="/components"
                    isSelected={pathname === '/components'}
                  />
                )}
                {q
                  ? flatSearchResults.map(item => (
                      <SideNavItem
                        key={`${item.packageName}:${item.name}`}
                        label={item.displayName}
                        href={item.href}
                        isSelected={pathname === item.href}
                      />
                    ))
                  : renderComponentItems(componentItems)}
                {/* Utilities — secondary list rendered below the main Components
                    section. Always starts collapsed; users can expand on demand. */}
                {filteredUtilities.length > 0 &&
                  (q ? (
                    filteredUtilities.map(comp => (
                      <SideNavItem
                        key={`${comp.packageName}:${comp.name}`}
                        label={comp.displayName}
                        href={comp.href}
                        isSelected={pathname === comp.href}
                      />
                    ))
                  ) : (
                    <SideNavItem
                      label="Utilities"
                      collapsible={{defaultIsCollapsed: true}}>
                      {utilities.map(comp => (
                        <SideNavItem
                          key={`${comp.packageName}:${comp.name}`}
                          label={comp.displayName}
                          href={comp.href}
                          isSelected={pathname === comp.href}
                        />
                      ))}
                    </SideNavItem>
                  ))}
              </SideNavSection>

              {!q && canaryCategories.length > 0 && (
                <SideNavSection title="Canary components" isHeaderHidden>
                  {canaryCategories.map(category => (
                    <SideNavItem
                      key={category.packageName}
                      label={category.displayName}
                      endContent={<CanaryCategoryMarker />}
                      collapsible={{
                        defaultIsCollapsed: ![
                          ...category.componentItems.flatMap(item =>
                            item.type === 'entry' ? [item] : item.entries,
                          ),
                          ...category.utilities,
                        ].some(entry => pathname === entry.href),
                      }}>
                      {renderComponentItems(category.componentItems)}
                      {category.utilities.length > 0 && (
                        <SideNavItem
                          label="Utilities"
                          collapsible={{defaultIsCollapsed: true}}>
                          {category.utilities.map(comp => (
                            <SideNavItem
                              key={`${comp.packageName}:${comp.name}`}
                              label={comp.displayName}
                              href={comp.href}
                              isSelected={pathname === comp.href}
                            />
                          ))}
                        </SideNavItem>
                      )}
                    </SideNavItem>
                  ))}
                </SideNavSection>
              )}
            </>
          )}
        </SideNav>
      }>
      {children}
    </AppShell>
  );
}