@umami/shiso 0.54.0 → 0.61.0

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>
+  );
+}

package/src/components/TopNav.tsx

@@ -0,0 +1,127 @@
+import classNames from 'classnames';
+import { Link, useLocation, useNavigate } from 'react-router';
+import { ConfiguredIcon } from '@/components/ConfiguredIcon';
+import { ChevronRight } from '@/components/icons';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import type { DocsTab, LinkTarget, NavNode, NormalizedDocsConfig } from '@/lib/types';
+
+interface MenuLink {
+  label: string;
+  href: string;
+  target: LinkTarget;
+  routed: boolean;
+}
+
+function collectMenuLinks(nodes: NavNode[]): MenuLink[] {
+  const links: MenuLink[] = [];
+
+  for (const node of nodes) {
+    if (node.kind === 'page') {
+      if (!node.page.hidden) {
+        links.push({ label: node.page.label, href: node.page.url, target: '_self', routed: true });
+      }
+    } else if (node.kind === 'link') {
+      if (!node.hidden) {
+        links.push({ label: node.label, href: node.href, target: node.target, routed: false });
+      }
+    } else if (!node.hidden) {
+      if (node.root && !node.root.page.hidden) {
+        links.push({
+          label: node.root.page.label,
+          href: node.root.page.url,
+          target: '_self',
+          routed: true,
+        });
+      }
+      links.push(...collectMenuLinks(node.children));
+    }
+  }
+
+  return links;
+}
+
+export function TopNav({ docs, label }: { docs: NormalizedDocsConfig; label: string }) {
+  const { pathname } = useLocation();
+  const navigate = useNavigate();
+  const tabs = docs.tabs.filter(tab => !tab.hidden);
+
+  if (!tabs.length) {
+    return null;
+  }
+
+  const page = docs.pages.find(item => item.url === pathname);
+  const selected =
+    page?.tabId ||
+    [...tabs]
+      .sort((a, b) => b.url.length - a.url.length)
+      .find(tab => pathname === tab.url || pathname.startsWith(`${tab.url}/`))?.id ||
+    tabs[0]?.id;
+  const tabClass = (tab: DocsTab) =>
+    classNames(
+      'flex h-full items-center gap-1 whitespace-nowrap border-transparent border-b-2 font-medium',
+      {
+        'border-b-primary text-foreground': tab.id === selected,
+        'text-muted-foreground hover:text-foreground': tab.id !== selected,
+      },
+    );
+
+  return (
+    <nav
+      className="hidden h-[calc(100%+1px)] max-w-screen self-start items-center gap-7 overflow-x-auto text-sm [scrollbar-width:none] lg:flex [&::-webkit-scrollbar]:hidden"
+      aria-label={label}
+    >
+      {tabs.map(tab => {
+        if (tab.presentation === 'dropdown') {
+          const menuLinks = collectMenuLinks(docs.navigation[tab.id] || []);
+
+          return (
+            <DropdownMenu key={tab.id}>
+              <DropdownMenuTrigger render={<button type="button" className={tabClass(tab)} />}>
+                <ConfiguredIcon icon={tab.icon} />
+                {tab.label}
+                <ChevronRight className="size-3.5 rotate-90" />
+              </DropdownMenuTrigger>
+              <DropdownMenuContent align="start" className="min-w-48">
+                {menuLinks.map(item => (
+                  <DropdownMenuItem
+                    key={item.href}
+                    onClick={() => {
+                      if (item.routed) {
+                        navigate(item.href);
+                      } else {
+                        window.open(
+                          item.href,
+                          item.target,
+                          item.target === '_blank' ? 'noreferrer' : undefined,
+                        );
+                      }
+                    }}
+                  >
+                    {item.label}
+                  </DropdownMenuItem>
+                ))}
+              </DropdownMenuContent>
+            </DropdownMenu>
+          );
+        }
+
+        return (
+          <Link
+            key={tab.id}
+            to={tab.url}
+            className={tabClass(tab)}
+            aria-current={tab.id === selected ? 'page' : undefined}
+          >
+            <ConfiguredIcon icon={tab.icon} />
+            {tab.label}
+          </Link>
+        );
+      })}
+    </nav>
+  );
+}

package/src/components/docs/Accordion.tsx

@@ -0,0 +1,68 @@
+import type { ReactNode } from 'react';
+import {
+  AccordionContent,
+  AccordionItem,
+  Accordion as AccordionPrimitive,
+  AccordionTrigger,
+} from '@/components/ui/accordion';
+import { styles } from './styles';
+import { resolveIcon, toElementArray } from './utils';
+
+export interface AccordionProps {
+  title?: ReactNode;
+  icon?: ReactNode | string;
+  defaultOpen?: boolean;
+  children?: ReactNode;
+}
+
+function AccordionSection({ value, title, icon, children }: AccordionProps & { value: string }) {
+  return (
+    <AccordionItem value={value} className={styles.accordionItem}>
+      <AccordionTrigger className={styles.accordionTrigger}>
+        <span className="flex min-w-0 items-center gap-2">
+          {resolveIcon(icon)}
+          {title}
+        </span>
+      </AccordionTrigger>
+      <AccordionContent className={styles.accordionContent}>{children}</AccordionContent>
+    </AccordionItem>
+  );
+}
+
+export function Accordion({ title, icon, defaultOpen, children }: AccordionProps) {
+  const value = 'accordion-item';
+
+  return (
+    <AccordionPrimitive defaultValue={defaultOpen ? [value] : []} className={styles.accordion}>
+      <AccordionSection value={value} title={title} icon={icon}>
+        {children}
+      </AccordionSection>
+    </AccordionPrimitive>
+  );
+}
+
+export interface AccordionGroupProps {
+  children?: ReactNode;
+  defaultOpen?: boolean;
+}
+
+export function AccordionGroup({ children, defaultOpen = false }: AccordionGroupProps) {
+  const items = toElementArray<AccordionProps>(children);
+
+  if (!items.length) {
+    return null;
+  }
+
+  const values = items.map((_, index) => `accordion-${index + 1}`);
+  const defaultValue = values.filter((_, index) => {
+    return items[index].props.defaultOpen ?? (defaultOpen && index === 0);
+  });
+
+  return (
+    <AccordionPrimitive multiple defaultValue={defaultValue} className={styles.accordionGroup}>
+      {items.map((child, index) => (
+        <AccordionSection key={child.key ?? values[index]} value={values[index]} {...child.props} />
+      ))}
+    </AccordionPrimitive>
+  );
+}