@umami/shiso 0.55.0 → 1.0.0

package/src/components/DocContent.tsx

@@ -0,0 +1,105 @@
+import { Link } from 'react-router';
+import { ContextualMenu } from '@/components/ContextualMenu';
+import { ChevronRight } from '@/components/icons';
+import { getLastModified } from '@/lib/content';
+import { getScopeForPage } from '@/lib/docs-config';
+import { resolveLocale } from '@/lib/locale';
+import { docsSite } from '@/lib/site-config';
+import { resolveContextualOptions } from '@/lib/site-model';
+import type { DocModule, NormalizedDocsPage, SiteModel } from '@/lib/types';
+
+export interface DocContentProps {
+  page: NormalizedDocsPage;
+  doc: DocModule;
+  site: SiteModel;
+}
+
+export function DocContent({ page, doc, site }: DocContentProps) {
+  // Prev/next paging never crosses a version or language boundary.
+  const pagerPages = getScopeForPage(docsSite, page).docs.pages.filter(item => !item.hidden);
+  const pageIndex = pagerPages.findIndex(item => item.slug === page.slug);
+  const prev = pageIndex > 0 ? pagerPages[pageIndex - 1] : undefined;
+  const next = pageIndex >= 0 ? pagerPages[pageIndex + 1] : undefined;
+  const title = doc.frontmatter?.title || page.label;
+  const description = doc.frontmatter?.description;
+  const Content = doc.default;
+  const shouldShowTimestamp =
+    typeof doc.frontmatter?.timestamp === 'boolean'
+      ? doc.frontmatter.timestamp
+      : site.showTimestamp;
+  const lastModified = shouldShowTimestamp ? getLastModified(page.filePath) : undefined;
+  // `styling.eyebrows`: the section name alone, or the full navigation path.
+  const eyebrow =
+    site.styling.eyebrows === 'breadcrumbs'
+      ? [...new Set([page.tabLabel, page.section])].filter(Boolean).join(' / ')
+      : page.section;
+  const contextualOptions = resolveContextualOptions(site.contextualOptions, page, site.labels);
+  // Dates follow the page's language when it is a valid locale code.
+  const dateFormat = new Intl.DateTimeFormat(resolveLocale(page.language, site.locale), {
+    dateStyle: 'medium',
+    timeZone: 'UTC',
+  });
+
+  return (
+    <article className="min-w-0 grow">
+      {eyebrow && <div className="text-sm font-bold text-primary">{eyebrow}</div>}
+      <div className="flex items-start justify-between gap-4">
+        {title && (
+          <h1 className="mt-2 text-4xl text-foreground leading-[1.2] tracking-[-0.03em] [font-family:var(--font-heading)] [font-weight:var(--font-heading-weight,800)]">
+            {title}
+          </h1>
+        )}
+        <ContextualMenu options={contextualOptions} labels={site.labels} />
+      </div>
+      {description && <p className="mt-1 mb-6 text-base text-muted-foreground">{description}</p>}
+      <div className="docs-markdown">
+        <Content />
+      </div>
+      {lastModified && (
+        <div className="mt-8 text-sm text-muted-foreground">
+          {site.labels.lastUpdated}{' '}
+          <time dateTime={lastModified}>{dateFormat.format(new Date(lastModified))}</time>
+        </div>
+      )}
+      <div className="mt-8 flex items-center justify-between">
+        <NavigationButton {...prev} isPrev />
+        <NavigationButton {...next} />
+      </div>
+    </article>
+  );
+}
+
+const NavigationButton = ({
+  label,
+  url,
+  isPrev,
+}: {
+  label?: string;
+  url?: string;
+  isPrev?: boolean;
+}) => {
+  if (!url || !label) {
+    return <div />;
+  }
+
+  return (
+    <Link
+      to={url}
+      className="group my-3 inline-flex items-center gap-3 text-base font-bold text-foreground"
+    >
+      {isPrev && (
+        <ChevronRight
+          size={14}
+          className="rotate-180 text-muted-foreground transition-colors group-hover:text-foreground"
+        />
+      )}
+      {label}
+      {!isPrev && (
+        <ChevronRight
+          size={14}
+          className="text-muted-foreground transition-colors group-hover:text-foreground"
+        />
+      )}
+    </Link>
+  );
+};

package/src/components/Docs.tsx

@@ -0,0 +1,134 @@
+import { useEffect, useState } from 'react';
+import { useLocation, useNavigate } from 'react-router';
+import { DocContent } from '@/components/DocContent';
+import { Footer } from '@/components/Footer';
+import { Menu } from '@/components/icons';
+import { LanguageSwitcher } from '@/components/LanguageSwitcher';
+import { PageLinks } from '@/components/PageLinks';
+import { SideNav } from '@/components/SideNav';
+import { Button } from '@/components/ui/button';
+import { Sheet, SheetContent, SheetTitle, SheetTrigger } from '@/components/ui/sheet';
+import { VersionSwitcher } from '@/components/VersionSwitcher';
+import { renderInlineMarkdown } from '@/lib/inline-markdown';
+import { docsHomeUrl, getScopeByPathname } from '@/lib/site-config';
+import type { DocModule, NormalizedDocsPage, SiteModel } from '@/lib/types';
+
+/**
+ * 404 view driven by the `errors.404` config key. The standard defaults to
+ * redirecting home; that happens after hydration rather than during render,
+ * because the prerendered 404.html must stay a static page for hosts that
+ * serve it for every unknown path.
+ */
+function NotFound({ site }: { site: SiteModel }) {
+  const navigate = useNavigate();
+  const { redirect, title, description } = site.error404;
+
+  useEffect(() => {
+    if (redirect) {
+      navigate(docsHomeUrl, { replace: true });
+    }
+  }, [redirect, navigate]);
+
+  return (
+    <div className="py-16 text-center">
+      <h1>{title || site.labels.notFound}</h1>
+      {description && <p>{renderInlineMarkdown(description)}</p>}
+    </div>
+  );
+}
+
+export interface DocsProps {
+  page: NormalizedDocsPage | null;
+  doc: DocModule | null;
+  site: SiteModel;
+}
+
+export function Docs({ page, doc, site }: DocsProps) {
+  const { pathname } = useLocation();
+  const [menuOpen, setMenuOpen] = useState(false);
+  // Navigation follows the scope (version/language) that owns the current page.
+  const scopeDocs = getScopeByPathname(pathname).docs;
+  const { tabs, navigation } = scopeDocs;
+
+  // Close the mobile menu and start each newly loaded page at the top. Hash
+  // links keep their native section-scrolling behavior.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: pathname is the trigger
+  useEffect(() => {
+    setMenuOpen(false);
+    if (!window.location.hash) {
+      window.scrollTo({ top: 0, left: 0 });
+    }
+  }, [pathname]);
+
+  if (!page || !doc) {
+    return (
+      <div className="flex min-h-full flex-col">
+        <div className="grow">
+          <NotFound site={site} />
+        </div>
+        <Footer footer={site.footer} />
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex min-h-full flex-col gap-6 lg:gap-0">
+      <Sheet open={menuOpen} onOpenChange={setMenuOpen}>
+        <div className="flex justify-end lg:hidden">
+          <SheetTrigger render={<Button variant="outline" className="bg-card" />}>
+            <Menu className="size-3.5" />
+            {site.labels.menu}
+          </SheetTrigger>
+        </div>
+        <SheetContent
+          side="right"
+          className="w-[min(320px,85vw)] gap-0 overflow-y-auto bg-background p-4 sm:max-w-80"
+        >
+          <SheetTitle className="sr-only">{site.labels.documentationNavigation}</SheetTitle>
+          <div className="pt-8">
+            <div className="flex items-center gap-2 pb-4 lg:hidden">
+              <VersionSwitcher />
+              <LanguageSwitcher />
+            </div>
+            <SideNav
+              tabs={tabs}
+              navigation={navigation}
+              anchors={scopeDocs.anchors}
+              drilldown={site.drilldown}
+              navigationLabel={site.labels.documentationNavigation}
+              expandLabel={site.labels.expand}
+              collapseLabel={site.labels.collapse}
+            />
+          </div>
+        </SheetContent>
+      </Sheet>
+      <div className="flex items-start gap-12 lg:min-h-[calc(100dvh-var(--header-height))] lg:pt-6">
+        <div className="hidden min-w-0 max-w-60 basis-60 self-start lg:sticky lg:top-[calc(var(--header-height)+1.5rem)] lg:block lg:h-[calc(100dvh-var(--header-height)-3rem)] lg:shrink-0">
+          <SideNav
+            tabs={tabs}
+            navigation={navigation}
+            anchors={scopeDocs.anchors}
+            isSticky
+            drilldown={site.drilldown}
+            navigationLabel={site.labels.documentationNavigation}
+            expandLabel={site.labels.expand}
+            collapseLabel={site.labels.collapse}
+          />
+        </div>
+        <div className="flex min-w-0 grow self-stretch flex-col">
+          <div className="flex grow items-start gap-12">
+            <DocContent page={page} doc={doc} site={site} />
+            <div className="hidden min-w-0 max-w-60 basis-60 self-start lg:sticky lg:top-[calc(var(--header-height)+1.5rem)] lg:block lg:shrink-0">
+              <PageLinks
+                items={doc.toc}
+                title={site.labels.tableOfContents}
+                navigationLabel={site.labels.tableOfContentsNavigation}
+              />
+            </div>
+          </div>
+          <Footer footer={site.footer} className="lg:mr-72" />
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/Footer.tsx

@@ -0,0 +1,81 @@
+import { ConfiguredIcon } from '@/components/ConfiguredIcon';
+import type { NormalizedFooter } from '@/lib/types';
+
+export function Footer({
+  footer,
+  className = '',
+}: {
+  footer: NormalizedFooter | null;
+  className?: string;
+}) {
+  if (!footer) {
+    return null;
+  }
+
+  const { socials, links: columns, attribution } = footer;
+
+  return (
+    <footer className={`mt-8 border-border border-t py-8 text-muted-foreground ${className}`}>
+      {columns.length > 0 && (
+        <div className="mb-8 grid grid-cols-[repeat(auto-fit,minmax(10rem,max-content))] gap-x-16 gap-y-8">
+          {columns.map((column, index) => (
+            <div key={column.header || index}>
+              {column.header && (
+                <div className="mb-3 text-sm font-semibold text-foreground">{column.header}</div>
+              )}
+              <ul className="m-0 flex list-none flex-col gap-2 p-0">
+                {column.items.map(item => (
+                  <li key={item.href}>
+                    <a
+                      href={item.href}
+                      target={item.target}
+                      rel={item.target === '_blank' ? 'noreferrer' : undefined}
+                      className="text-sm text-muted-foreground hover:text-foreground"
+                    >
+                      {item.label}
+                    </a>
+                  </li>
+                ))}
+              </ul>
+            </div>
+          ))}
+        </div>
+      )}
+      {attribution || socials.length > 0 ? (
+        <div className="flex items-center justify-between gap-4">
+          {attribution ? (
+            <a
+              href="https://shiso.umami.is?ref=docs-footer"
+              className="text-sm hover:text-foreground"
+            >
+              Powered by <span className="font-bold">shiso</span>
+            </a>
+          ) : (
+            <span />
+          )}
+          {socials.length > 0 && (
+            <div className="flex items-center gap-1">
+              {socials.map(link => {
+                const iconOnly = !link.label;
+
+                return (
+                  <a
+                    key={link.href}
+                    href={link.href}
+                    target={link.target}
+                    rel={link.target === '_blank' ? 'noreferrer' : undefined}
+                    className={`inline-flex min-h-8 items-center justify-center rounded-md text-muted-foreground hover:bg-accent hover:text-foreground ${iconOnly ? 'size-8' : 'gap-1.5 px-2'}`}
+                    aria-label={iconOnly ? link.ariaLabel || link.icon || link.href : undefined}
+                  >
+                    <ConfiguredIcon icon={link.icon} />
+                    {link.label}
+                  </a>
+                );
+              })}
+            </div>
+          )}
+        </div>
+      ) : null}
+    </footer>
+  );
+}

package/src/components/Header.tsx

@@ -0,0 +1,82 @@
+import { useLocation } from 'react-router';
+import { ConfiguredIcon } from '@/components/ConfiguredIcon';
+import { LanguageSwitcher } from '@/components/LanguageSwitcher';
+import { Search } from '@/components/Search';
+import { ThemeToggle } from '@/components/ThemeToggle';
+import { TopNav } from '@/components/TopNav';
+import { VersionSwitcher } from '@/components/VersionSwitcher';
+import { docsHomeUrl, getScopeByPathname } from '@/lib/site-config';
+import type { NormalizedLink, SiteModel } from '@/lib/types';
+
+function NavbarLinkItem({ link, primary = false }: { link: NormalizedLink; primary?: boolean }) {
+  const iconOnly = !link.label;
+  const accessibleLabel = link.ariaLabel || link.icon || link.href;
+
+  return (
+    <a
+      href={link.href}
+      className={
+        primary
+          ? `ml-1 inline-flex items-center justify-center rounded-full bg-primary text-sm font-semibold text-primary-foreground hover:opacity-90 ${iconOnly ? 'size-8' : 'gap-1.5 px-3.5 py-1.5'}`
+          : `inline-flex items-center rounded-md text-sm font-medium text-foreground hover:bg-accent hover:text-foreground ${iconOnly ? 'size-8 justify-center' : 'gap-1.5 px-2.5 py-1.5'}`
+      }
+      target={link.target}
+      rel={link.target === '_blank' ? 'noreferrer' : undefined}
+      aria-label={iconOnly ? accessibleLabel : undefined}
+    >
+      <ConfiguredIcon icon={link.icon} />
+      {link.label}
+    </a>
+  );
+}
+
+export function Header({ site }: { site: SiteModel }) {
+  const { logo, navbar, name, appearance, labels, search } = site;
+  const { pathname } = useLocation();
+  // The header renders the navigation of whichever scope owns the current page.
+  const docs = getScopeByPathname(pathname).docs;
+  const brandHref = logo?.href || docsHomeUrl;
+  const hasBrand = !!name || !!logo?.light || !!logo?.dark;
+
+  return (
+    <header className="sticky top-0 z-50 h-[var(--header-height)] shrink-0 border-border border-b bg-[color-mix(in_srgb,var(--background)_92%,transparent)] backdrop-blur-md">
+      <div className="mx-auto grid h-full max-w-[1600px] grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center px-5">
+        <div className="flex min-w-0 items-center gap-5 justify-self-start">
+          {hasBrand ? (
+            <a
+              href={brandHref}
+              target={logo?.target}
+              rel={logo?.target === '_blank' ? 'noreferrer' : undefined}
+              className="inline-flex items-center gap-2 text-xl font-bold text-foreground tracking-[-0.03em]"
+            >
+              {logo?.light ? (
+                <img src={logo.light} alt="" className="h-6 w-auto dark:hidden" />
+              ) : null}
+              {logo?.dark ? (
+                <img
+                  src={logo.dark}
+                  alt=""
+                  className={`hidden h-6 w-auto dark:block ${logo.light === logo.dark ? 'dark:invert' : ''}`}
+                />
+              ) : null}
+              {name ? <span>{name}</span> : null}
+            </a>
+          ) : null}
+          <div className="hidden items-center gap-2 lg:flex">
+            <VersionSwitcher />
+            <LanguageSwitcher />
+          </div>
+        </div>
+        {docs.showTabs ? <TopNav docs={docs} label={labels.sections} /> : null}
+        <div className="flex min-w-0 items-center gap-2 justify-self-end">
+          <Search config={search} labels={labels} />
+          {navbar?.links.map(link => (
+            <NavbarLinkItem key={link.href} link={link} />
+          ))}
+          {!appearance.strict && <ThemeToggle label={labels.toggleTheme} />}
+          {navbar?.primary ? <NavbarLinkItem link={navbar.primary} primary /> : null}
+        </div>
+      </div>
+    </header>
+  );
+}

package/src/components/LanguageSwitcher.tsx

@@ -0,0 +1,59 @@
+import { useLocation, useNavigate } from 'react-router';
+import { Check, ChevronRight } from '@/components/icons';
+import { Button } from '@/components/ui/button';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { getLanguageScopes } from '@/lib/docs-config';
+import { docsSite, getScopeByPathname } from '@/lib/site-config';
+
+/**
+ * Language selector for multi-language sites. Each option is a language's
+ * landing scope — its default version — so switching languages always lands
+ * on that language's default-version first page. Hidden languages never
+ * appear as options.
+ */
+export function LanguageSwitcher() {
+  const { pathname } = useLocation();
+  const navigate = useNavigate();
+  const current = getScopeByPathname(pathname);
+  const options = getLanguageScopes(docsSite);
+
+  if (!current.language || (options.length < 2 && !current.hidden)) {
+    return null;
+  }
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger
+        render={
+          <Button
+            variant="outline"
+            className="h-auto gap-1.5 rounded-md bg-card px-2.5 py-1.5 text-sm font-medium text-foreground"
+          />
+        }
+      >
+        {current.language}
+        <ChevronRight className="size-3.5 rotate-90 text-muted-foreground" />
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="start" className="min-w-32">
+        {options.map(scope => (
+          <DropdownMenuItem
+            key={scope.id}
+            onClick={() => {
+              if (scope.language !== current.language) {
+                navigate(scope.firstPageUrl);
+              }
+            }}
+          >
+            <span className="grow">{scope.language}</span>
+            {scope.language === current.language ? <Check className="size-3.5" /> : null}
+          </DropdownMenuItem>
+        ))}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}

package/src/components/Layout.tsx

@@ -0,0 +1,24 @@
+import type { ReactNode } from 'react';
+import { useLocation } from 'react-router';
+import { Banner } from '@/components/Banner';
+import { Header } from '@/components/Header';
+import { useHead } from '@/lib/head';
+import type { SiteModel } from '@/lib/types';
+
+export function Layout({ children, site }: { children: ReactNode; site: SiteModel }) {
+  const { pathname } = useLocation();
+
+  // Keep metadata, document language, and text direction synchronized after
+  // client-side navigation. The prerendered values are retained on hydration.
+  useHead(pathname);
+
+  return (
+    <div className="flex min-h-dvh flex-col">
+      <Banner banner={site.banner} dismissLabel={site.labels.dismissBanner} />
+      <Header site={site} />
+      <div className="mx-auto flex min-h-0 w-full max-w-[1600px] grow flex-col px-5">
+        <main className="min-h-0 grow">{children}</main>
+      </div>
+    </div>
+  );
+}

package/src/components/PageLinks.tsx

@@ -0,0 +1,71 @@
+import classNames from 'classnames';
+import { useEffect, useState } from 'react';
+import type { TocEntry } from '@/lib/types';
+
+export interface PageLinksProps {
+  items?: TocEntry[];
+  title: string;
+  navigationLabel: string;
+}
+
+export function PageLinks({ items = [], title, navigationLabel }: PageLinksProps) {
+  const [hash, setHash] = useState(items?.[0]?.id);
+
+  useEffect(() => {
+    setHash(items?.[0]?.id);
+
+    const callback = () => {
+      const found = [...items].reverse().find(({ id }) => {
+        const rect = document.getElementById(id)?.getBoundingClientRect();
+        return rect && rect.top <= 0;
+      });
+
+      if (found) {
+        setHash(found.id);
+      }
+    };
+
+    window.addEventListener('scroll', callback, false);
+
+    return () => {
+      window.removeEventListener('scroll', callback, false);
+    };
+  }, [items]);
+
+  if (!items?.length) {
+    return null;
+  }
+
+  const indent = (size: number) => {
+    if (size <= 2) {
+      return '0px';
+    }
+
+    return `${(size - 2) * 10}px`;
+  };
+
+  return (
+    <div className="flex h-max min-w-60 flex-col gap-3 text-sm">
+      <div className="font-bold text-foreground">{title}</div>
+      <nav className="flex flex-col" aria-label={navigationLabel}>
+        {items.map(({ name, id, size }) => {
+          const isActive = hash === id;
+
+          return (
+            <a
+              key={id}
+              href={`#${id}`}
+              className={classNames('block border-l px-3 py-1.5', {
+                'border-l-primary font-medium text-primary': isActive,
+                'border-border text-muted-foreground hover:text-foreground': !isActive,
+              })}
+              aria-current={isActive ? 'location' : undefined}
+            >
+              <span style={{ marginLeft: indent(size), display: 'block' }}>{name}</span>
+            </a>
+          );
+        })}
+      </nav>
+    </div>
+  );
+}