@umami/shiso 0.55.0 → 1.0.0

package/src/components/Search.tsx

@@ -0,0 +1,217 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useLocation, useNavigate } from 'react-router';
+import { Search as SearchIcon } from '@/components/icons';
+import { Button } from '@/components/ui/button';
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from '@/components/ui/command';
+import { Dialog, DialogContent, DialogTitle, DialogTrigger } from '@/components/ui/dialog';
+import type { SearchResult } from '@/lib/search';
+import type { ResolvedSearchConfig } from '@/lib/search/config';
+import { resolveSearchProvider, type SearchProvider } from '@/lib/search/provider';
+import { getScopeByPathname } from '@/lib/site-config';
+import type { ThemeLabels } from '@/lib/types';
+
+/**
+ * Provider-neutral search dialog. The selected provider and its index or
+ * client are loaded on demand, so search stays out of the initial bundle.
+ */
+export function Search({ config, labels }: { config: ResolvedSearchConfig; labels: ThemeLabels }) {
+  const navigate = useNavigate();
+  const { pathname } = useLocation();
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState('');
+  const [results, setResults] = useState<SearchResult[]>([]);
+  const [status, setStatus] = useState<'idle' | 'loading' | 'ready' | 'error'>('idle');
+  const provider = useRef<Promise<SearchProvider> | null>(null);
+  const requestId = useRef(0);
+
+  const loadProvider = useCallback(() => {
+    if (!provider.current) {
+      provider.current = resolveSearchProvider(config.provider, config.options)
+        .then(resolved => {
+          if (resolved.fellBack) {
+            console.warn(
+              `[shiso] Unknown search provider "${config.provider}" — using the built-in local provider.`,
+            );
+          }
+
+          return resolved.provider;
+        })
+        .catch(error => {
+          provider.current = null;
+          throw error;
+        });
+    }
+
+    return provider.current;
+  }, [config.options, config.provider]);
+
+  const runQuery = useCallback(
+    async (value: string) => {
+      const currentRequest = ++requestId.current;
+      setQuery(value);
+
+      if (!value.trim()) {
+        setResults([]);
+        setStatus('idle');
+        return;
+      }
+
+      setResults([]);
+      setStatus('loading');
+
+      try {
+        const activeProvider = await loadProvider();
+        // Search stays inside the version/language scope being browsed.
+        // Providers that predate the context argument simply ignore it.
+        const scope = getScopeByPathname(pathname);
+        const nextResults = await activeProvider.search(value, undefined, {
+          scopeId: scope.id,
+          language: scope.language,
+          version: scope.version,
+        });
+
+        if (currentRequest === requestId.current) {
+          setResults(nextResults);
+          setStatus('ready');
+        }
+      } catch (error) {
+        if (currentRequest === requestId.current) {
+          console.error('[shiso] Search provider failed:', error);
+          setResults([]);
+          setStatus('error');
+        }
+      }
+    },
+    [loadProvider, pathname],
+  );
+
+  const openDialog = useCallback(() => {
+    if (!config.enabled) {
+      return;
+    }
+
+    setOpen(true);
+    void loadProvider().catch(error => {
+      console.error('[shiso] Search provider failed to load:', error);
+    });
+  }, [config.enabled, loadProvider]);
+
+  const closeDialog = useCallback(() => {
+    requestId.current += 1;
+    setOpen(false);
+    setQuery('');
+    setResults([]);
+    setStatus('idle');
+  }, []);
+
+  // Global shortcut configured by docs.json.
+  useEffect(() => {
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (
+        config.enabled &&
+        config.shortcut &&
+        (event.metaKey || event.ctrlKey) &&
+        event.key.toLowerCase() === config.shortcut
+      ) {
+        event.preventDefault();
+        openDialog();
+      }
+    };
+
+    window.addEventListener('keydown', onKeyDown);
+    return () => window.removeEventListener('keydown', onKeyDown);
+  }, [config.enabled, config.shortcut, openDialog]);
+
+  const select = (result: SearchResult) => {
+    closeDialog();
+    navigate(result.url);
+  };
+
+  if (!config.enabled) {
+    return null;
+  }
+
+  const hasQuery = !!query.trim();
+
+  return (
+    <Dialog open={open} onOpenChange={nextOpen => (nextOpen ? openDialog() : closeDialog())}>
+      <DialogTrigger
+        render={
+          <Button
+            variant="outline"
+            className="h-auto gap-2 rounded-md bg-card px-2.5 py-1.5 text-muted-foreground hover:border-input hover:bg-card hover:text-foreground"
+          />
+        }
+      >
+        <SearchIcon className="size-3.5" />
+        <span className="min-w-24 text-left">{config.prompt}</span>
+        {config.shortcut ? (
+          <kbd className="rounded-sm border border-border bg-muted px-[0.3rem] py-[0.05rem] text-[0.7rem] font-sans">
+            {config.shortcutLabel}
+          </kbd>
+        ) : null}
+      </DialogTrigger>
+      <DialogContent
+        showCloseButton={false}
+        overlayClassName="bg-black/40 supports-backdrop-filter:backdrop-blur-none"
+        className="top-[10vh] max-w-[calc(100%-2rem)] -translate-y-0 gap-0 overflow-hidden rounded-lg border border-border bg-background p-0 ring-0 shadow-[0_10px_40px_rgba(0,0,0,0.2)] sm:max-w-[34rem]"
+      >
+        <DialogTitle className="sr-only">{labels.searchTitle}</DialogTitle>
+        <Command shouldFilter={false} className="rounded-none bg-background p-0">
+          <CommandInput
+            autoFocus
+            className="text-base md:text-base"
+            placeholder={config.prompt}
+            value={query}
+            onValueChange={runQuery}
+            onKeyDownCapture={event => {
+              if (event.key === 'Home' || event.key === 'End') {
+                event.stopPropagation();
+              }
+            }}
+          />
+          <CommandList className="max-h-[50vh] border-border border-t">
+            {hasQuery ? (
+              <CommandEmpty>
+                {status === 'loading'
+                  ? labels.searching
+                  : status === 'error'
+                    ? labels.searchUnavailable
+                    : labels.noResults}
+              </CommandEmpty>
+            ) : null}
+            {hasQuery && results.length ? (
+              <CommandGroup className="p-2">
+                {results.map(result => (
+                  <CommandItem
+                    key={result.url}
+                    value={result.url}
+                    className="block whitespace-normal rounded-md px-3 py-2 text-left [&>svg:last-child]:hidden"
+                    onSelect={() => select(result)}
+                  >
+                    <div className="text-[0.9rem] font-semibold text-foreground">
+                      {result.page}
+                      {result.heading ? ` › ${result.heading}` : ''}
+                    </div>
+                    {result.snippet && (
+                      <div className="mt-[0.15rem] line-clamp-2 text-[0.8rem] text-muted-foreground">
+                        {result.snippet}
+                      </div>
+                    )}
+                  </CommandItem>
+                ))}
+              </CommandGroup>
+            ) : null}
+          </CommandList>
+        </Command>
+      </DialogContent>
+    </Dialog>
+  );
+}

package/src/components/SideNav.tsx

@@ -0,0 +1,347 @@
+import classNames from 'classnames';
+import { type ReactNode, useEffect, useState } from 'react';
+import { Link, useLocation, useNavigate } from 'react-router';
+import { resolveIcon } from '@/components/docs/utils';
+import { ChevronRight, ExternalLink } from '@/components/icons';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@/components/ui/collapsible';
+import { ScrollArea } from '@/components/ui/scroll-area';
+import { flattenNav, isNodeHidden } from '@/lib/docs-config';
+import type { DocsTab, NavGroupNode, NavNode } from '@/lib/types';
+
+const sectionLabelClass =
+  'flex min-w-0 flex-1 items-center gap-[0.4rem] pb-2 pr-1 font-bold text-inherit';
+const groupLabelClass =
+  'flex min-w-0 flex-1 items-center gap-[0.4rem] px-3 py-2 font-medium text-inherit';
+const selectedClass =
+  'border-l-sidebar-primary font-medium text-sidebar-primary hover:text-sidebar-primary';
+
+export interface SideNavProps {
+  tabs: DocsTab[];
+  navigation: Record<string, NavNode[]>;
+  anchors: NavNode[];
+  isSticky?: boolean;
+  drilldown?: boolean;
+  navigationLabel: string;
+  expandLabel: string;
+  collapseLabel: string;
+}
+
+/** True when the group's root or any descendant page is the current page. */
+function containsPage(node: NavGroupNode, pathname: string): boolean {
+  if (node.root?.page.url === pathname) {
+    return true;
+  }
+
+  return flattenNav(node.children).some(page => page.url === pathname);
+}
+
+/**
+ * Group section. Groups with `collapsible: false` stay open; otherwise,
+ * top-level groups start expanded and nested groups start collapsed unless
+ * `expanded: true` or the current page is inside.
+ *
+ * Click behavior follows `interaction.drilldown`:
+ * - true: expanding also navigates to the group's root or first page
+ * - false: the header only expands/collapses
+ * - unset: headers with a root page navigate, others toggle
+ */
+function CollapsibleGroup({
+  node,
+  pathname,
+  depth,
+  drilldown,
+  expandLabel,
+  collapseLabel,
+}: {
+  node: NavGroupNode;
+  pathname: string;
+  depth: number;
+  drilldown?: boolean;
+  expandLabel: string;
+  collapseLabel: string;
+}) {
+  const navigate = useNavigate();
+  const active = containsPage(node, pathname);
+  const collapsible = node.collapsible !== false;
+  // Top-level sections stay open by default so the sidebar is usable on first load.
+  const [expanded, setExpanded] = useState(
+    !collapsible || depth === 0 || !!node.expanded || active,
+  );
+  const isExpanded = !collapsible || expanded;
+
+  useEffect(() => {
+    if (!collapsible || active) {
+      setExpanded(true);
+    }
+  }, [active, collapsible]);
+
+  const firstPage = node.root?.page || flattenNav(node.children).find(page => !page.hidden);
+
+  const handleOpenChange = (next: boolean) => {
+    setExpanded(next);
+
+    if (next && drilldown === true && firstPage) {
+      navigate(firstPage.url);
+    }
+  };
+
+  const chevron = (
+    <ChevronRight className="size-3.5 shrink-0 origin-center text-muted-foreground transition-[color,transform] duration-150 group-hover/section:text-sidebar-accent-foreground group-aria-expanded/collapsible-trigger:rotate-90" />
+  );
+
+  const isTopLevel = depth === 0;
+  const rootSelected = node.root?.page.url === pathname;
+  const headerClass = isTopLevel
+    ? 'flex min-w-0 items-center text-sidebar-foreground'
+    : classNames(
+        'flex items-center border-sidebar-border border-l text-muted-foreground hover:text-sidebar-accent-foreground',
+        { 'pl-6': depth > 1 },
+      );
+
+  const fixedHeader = (
+    <div
+      className={classNames(headerClass, {
+        [selectedClass]: rootSelected && !isTopLevel,
+        'text-sidebar-primary': rootSelected && isTopLevel,
+      })}
+    >
+      {node.root ? (
+        <Link to={node.root.page.url} className={isTopLevel ? sectionLabelClass : groupLabelClass}>
+          {resolveIcon(node.icon)}
+          {node.label}
+        </Link>
+      ) : (
+        <span className={isTopLevel ? sectionLabelClass : groupLabelClass}>
+          {resolveIcon(node.icon)}
+          {node.label}
+        </span>
+      )}
+    </div>
+  );
+
+  // Navigating collapsible headers keep a separate chevron button so collapse stays reachable.
+  const header = !collapsible ? (
+    fixedHeader
+  ) : drilldown !== false && node.root ? (
+    <div
+      className={classNames(headerClass, 'group/section flex items-center', {
+        [selectedClass]: rootSelected && !isTopLevel,
+        'text-sidebar-primary': rootSelected && isTopLevel,
+      })}
+    >
+      <Link to={node.root.page.url} className={isTopLevel ? sectionLabelClass : groupLabelClass}>
+        {resolveIcon(node.icon)}
+        {node.label}
+      </Link>
+      <CollapsibleTrigger
+        render={
+          <Button
+            type="button"
+            variant="ghost"
+            size="icon-xs"
+            className={classNames(
+              'group/collapsible-trigger inline-flex size-6 items-center justify-center rounded-sm text-muted-foreground hover:bg-sidebar-accent hover:text-sidebar-accent-foreground',
+              { 'mr-[0.35rem]': !isTopLevel },
+            )}
+            aria-label={`${isExpanded ? collapseLabel : expandLabel} ${node.label}`}
+          />
+        }
+      >
+        {chevron}
+      </CollapsibleTrigger>
+    </div>
+  ) : (
+    <CollapsibleTrigger
+      render={
+        <Button
+          type="button"
+          variant="ghost"
+          className={classNames(
+            headerClass,
+            'group/section group/collapsible-trigger flex h-auto w-full items-center justify-start gap-[0.4rem] whitespace-normal rounded-none px-0 py-0 text-left hover:bg-transparent aria-expanded:bg-transparent dark:hover:bg-transparent [&>svg:last-child]:ml-auto',
+            {
+              'pb-2 font-bold text-sidebar-foreground': isTopLevel,
+              'border-sidebar-border border-l px-3 py-2 font-medium text-muted-foreground hover:text-sidebar-accent-foreground':
+                !isTopLevel,
+            },
+          )}
+        />
+      }
+    >
+      {resolveIcon(node.icon)}
+      {node.label}
+      {chevron}
+    </CollapsibleTrigger>
+  );
+
+  if (!collapsible) {
+    return (
+      <div className="flex flex-col">
+        {fixedHeader}
+        <div className="flex flex-col">
+          <NavNodes
+            nodes={node.children}
+            pathname={pathname}
+            depth={depth + 1}
+            drilldown={drilldown}
+            expandLabel={expandLabel}
+            collapseLabel={collapseLabel}
+          />
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <Collapsible open={expanded} onOpenChange={handleOpenChange} className="flex flex-col">
+      {header}
+      <CollapsibleContent>
+        <div className="flex flex-col">
+          <NavNodes
+            nodes={node.children}
+            pathname={pathname}
+            depth={depth + 1}
+            drilldown={drilldown}
+            expandLabel={expandLabel}
+            collapseLabel={collapseLabel}
+          />
+        </div>
+      </CollapsibleContent>
+    </Collapsible>
+  );
+}
+
+function NavNodes({
+  nodes,
+  pathname,
+  depth,
+  drilldown,
+  expandLabel,
+  collapseLabel,
+}: {
+  nodes: NavNode[];
+  pathname: string;
+  depth: number;
+  drilldown?: boolean;
+  expandLabel: string;
+  collapseLabel: string;
+}) {
+  const rendered: ReactNode[] = [];
+
+  nodes.forEach(node => {
+    if (isNodeHidden(node)) {
+      return;
+    }
+
+    if (node.kind === 'link') {
+      rendered.push(
+        <a
+          key={`link-${node.href}`}
+          href={node.href}
+          target={node.target}
+          rel={node.target === '_blank' ? 'noreferrer' : undefined}
+          className={classNames(
+            'flex min-w-0 items-center gap-[0.4rem] border-sidebar-border border-l px-3 py-[0.55rem] text-muted-foreground hover:text-sidebar-accent-foreground [overflow-wrap:anywhere]',
+            { 'pl-6': depth > 1 },
+          )}
+        >
+          {resolveIcon(node.icon)}
+          {node.label}
+          <ExternalLink size={12} className="ml-auto opacity-60" />
+        </a>,
+      );
+      return;
+    }
+
+    if (node.kind === 'page') {
+      const { url, label, icon, tag } = node.page;
+      const isSelected = url === pathname;
+
+      rendered.push(
+        <Link
+          key={url}
+          to={url}
+          className={classNames(
+            'flex min-w-0 items-center gap-[0.4rem] border-sidebar-border border-l px-3 py-[0.55rem] [overflow-wrap:anywhere]',
+            {
+              'pl-6': depth > 1,
+              [selectedClass]: isSelected,
+              'text-muted-foreground hover:text-sidebar-accent-foreground': !isSelected,
+            },
+          )}
+        >
+          {resolveIcon(icon)}
+          {label}
+          {tag ? (
+            <Badge
+              variant="secondary"
+              className="ml-auto h-auto rounded-sm px-[0.35rem] py-[0.05rem] text-[0.7rem] text-muted-foreground uppercase"
+            >
+              {tag}
+            </Badge>
+          ) : null}
+        </Link>,
+      );
+      return;
+    }
+
+    rendered.push(
+      <CollapsibleGroup
+        key={`group-${node.label}`}
+        node={node}
+        pathname={pathname}
+        depth={depth}
+        drilldown={drilldown}
+        expandLabel={expandLabel}
+        collapseLabel={collapseLabel}
+      />,
+    );
+  });
+
+  return <>{rendered}</>;
+}
+
+export function SideNav({
+  tabs,
+  navigation,
+  anchors,
+  isSticky,
+  drilldown,
+  navigationLabel,
+  expandLabel,
+  collapseLabel,
+}: SideNavProps) {
+  const { pathname } = useLocation();
+
+  const tab = [...tabs]
+    .sort((a, b) => b.url.length - a.url.length)
+    .find(item => pathname === item.url || pathname.startsWith(`${item.url}/`));
+  const nodes = navigation[tab?.id || tabs?.[0]?.id] || [];
+
+  return (
+    <ScrollArea className={classNames('w-full max-w-full', { 'h-full': isSticky })}>
+      <nav className="flex w-full flex-col gap-6 pr-4 text-sm" aria-label={navigationLabel}>
+        {anchors.length ? (
+          <NavNodes
+            nodes={anchors}
+            pathname={pathname}
+            depth={0}
+            drilldown={drilldown}
+            expandLabel={expandLabel}
+            collapseLabel={collapseLabel}
+          />
+        ) : null}
+        <NavNodes
+          nodes={nodes}
+          pathname={pathname}
+          depth={0}
+          drilldown={drilldown}
+          expandLabel={expandLabel}
+          collapseLabel={collapseLabel}
+        />
+      </nav>
+    </ScrollArea>
+  );
+}

package/src/components/SocialIcon.tsx

@@ -0,0 +1,88 @@
+import { Globe, Podcast } from 'lucide-react';
+import {
+  siBluesky,
+  siDiscord,
+  siFacebook,
+  siGithub,
+  siInstagram,
+  siMedium,
+  siReddit,
+  siTelegram,
+  siThreads,
+  siX,
+  siYcombinator,
+  siYoutube,
+} from 'simple-icons';
+
+interface BrandIcon {
+  path: string;
+}
+
+/**
+ * Slack and LinkedIn were removed from both simple-icons and lucide for
+ * trademark reasons, so their (widely mirrored) 24x24 paths live here.
+ */
+const LOCAL_BRANDS: Record<string, BrandIcon> = {
+  slack: {
+    path: 'M5.042 15.165a2.528 2.528 0 0 1-2.52 2.523A2.528 2.528 0 0 1 0 15.165a2.527 2.527 0 0 1 2.522-2.52h2.52v2.52zM6.313 15.165a2.527 2.527 0 0 1 2.521-2.52 2.527 2.527 0 0 1 2.521 2.52v6.313A2.528 2.528 0 0 1 8.834 24a2.528 2.528 0 0 1-2.521-2.522v-6.313zM8.834 5.042a2.528 2.528 0 0 1-2.521-2.52A2.528 2.528 0 0 1 8.834 0a2.528 2.528 0 0 1 2.521 2.522v2.52H8.834zM8.834 6.313a2.528 2.528 0 0 1 2.521 2.521 2.528 2.528 0 0 1-2.521 2.521H2.522A2.528 2.528 0 0 1 0 8.834a2.528 2.528 0 0 1 2.522-2.521h6.312zM18.956 8.834a2.528 2.528 0 0 1 2.522-2.521A2.528 2.528 0 0 1 24 8.834a2.528 2.528 0 0 1-2.522 2.521h-2.522V8.834zM17.688 8.834a2.528 2.528 0 0 1-2.523 2.521 2.527 2.527 0 0 1-2.52-2.521V2.522A2.527 2.527 0 0 1 15.165 0a2.528 2.528 0 0 1 2.523 2.522v6.312zM15.165 18.956a2.528 2.528 0 0 1 2.523 2.522A2.528 2.528 0 0 1 15.165 24a2.527 2.527 0 0 1-2.52-2.522v-2.522h2.52zM15.165 17.688a2.527 2.527 0 0 1-2.52-2.523 2.526 2.526 0 0 1 2.52-2.52h6.313A2.527 2.527 0 0 1 24 15.165a2.528 2.528 0 0 1-2.522 2.523h-6.313z',
+  },
+  linkedin: {
+    path: 'M20.447 20.452h-3.554v-5.569c0-1.328-.027-3.037-1.852-3.037-1.853 0-2.136 1.445-2.136 2.939v5.667H9.351V9h3.414v1.561h.046c.477-.9 1.637-1.85 3.37-1.85 3.601 0 4.267 2.37 4.267 5.455v6.286zM5.337 7.433c-1.144 0-2.063-.926-2.063-2.065 0-1.138.92-2.063 2.063-2.063 1.14 0 2.064.925 2.064 2.063 0 1.139-.925 2.065-2.064 2.065zm1.782 13.019H3.555V9h3.564v11.452zM22.225 0H1.771C.792 0 0 .774 0 1.729v20.542C0 23.227.792 24 1.771 24h20.451C23.2 24 24 23.227 24 22.271V1.729C24 .774 23.2 0 22.225 0z',
+  },
+};
+
+/**
+ * Icons for every platform name the footer `socials` config accepts. Brand
+ * marks come from simple-icons; generic ones (website, podcast) fall back
+ * to lucide.
+ */
+const BRAND_ICONS: Record<string, BrandIcon> = {
+  x: siX,
+  twitter: siX,
+  'x-twitter': siX,
+  github: siGithub,
+  facebook: siFacebook,
+  youtube: siYoutube,
+  discord: siDiscord,
+  instagram: siInstagram,
+  'hacker-news': siYcombinator,
+  medium: siMedium,
+  telegram: siTelegram,
+  bluesky: siBluesky,
+  threads: siThreads,
+  reddit: siReddit,
+  ...LOCAL_BRANDS,
+};
+
+const LUCIDE_ICONS = {
+  website: Globe,
+  'earth-americas': Globe,
+  podcast: Podcast,
+} as const;
+
+export function isKnownPlatform(platform: string): boolean {
+  return platform in BRAND_ICONS || platform in LUCIDE_ICONS;
+}
+
+export function SocialIcon({ platform, size = 18 }: { platform: string; size?: number }) {
+  const brand = BRAND_ICONS[platform];
+
+  if (brand) {
+    return (
+      <svg
+        role="img"
+        aria-hidden="true"
+        viewBox="0 0 24 24"
+        width={size}
+        height={size}
+        fill="currentColor"
+      >
+        <path d={brand.path} />
+      </svg>
+    );
+  }
+
+  const Lucide = LUCIDE_ICONS[platform as keyof typeof LUCIDE_ICONS] || Globe;
+
+  return <Lucide size={size} aria-hidden="true" />;
+}

package/src/components/ThemeToggle.tsx

@@ -0,0 +1,34 @@
+import { Moon, Sun } from '@/components/icons';
+import { Button } from '@/components/ui/button';
+
+/**
+ * Both icons are always rendered and toggled via CSS on [data-theme], so the
+ * server render matches the client regardless of the user's stored theme.
+ */
+export function ThemeToggle({ label }: { label: string }) {
+  const handleClick = () => {
+    const current = document.documentElement.getAttribute('data-theme');
+    const next = current === 'dark' ? 'light' : 'dark';
+    document.documentElement.setAttribute('data-theme', next);
+
+    try {
+      localStorage.setItem('shiso-theme', next);
+    } catch {
+      // Ignore storage failures (private mode, etc).
+    }
+  };
+
+  return (
+    <Button
+      type="button"
+      variant="ghost"
+      size="icon"
+      className="inline-flex size-8 items-center justify-center rounded-md text-foreground hover:bg-accent"
+      onClick={handleClick}
+      aria-label={label}
+    >
+      <Sun className="size-3.5 dark:hidden" />
+      <Moon className="hidden size-3.5 dark:block" />
+    </Button>
+  );
+}