@umami/shiso 0.54.0 → 0.61.0

package/scripts/validate-config.mjs

@@ -0,0 +1,104 @@
+/**
+ * Validates docs.json against docs.schema.json.
+ *
+ * The schema is the source of truth for the public config format. Documented
+ * settings are strictly validated and every other key is rejected.
+ */
+import path from 'node:path';
+import process from 'node:process';
+import { Ajv } from 'ajv';
+import { loadDocsConfig, loadDocsSchema } from './load-docs-config.mjs';
+
+const packageRoot = path.resolve(import.meta.dirname, '..');
+
+/** Returns the top-level keys declared by the public config schema. */
+export function getSchemaKeys(schema) {
+  return Object.keys(schema.properties || {});
+}
+
+function levenshtein(a, b) {
+  const rows = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+
+  for (let j = 1; j <= b.length; j++) {
+    rows[0][j] = j;
+  }
+
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      rows[i][j] = Math.min(rows[i - 1][j] + 1, rows[i][j - 1] + 1, rows[i - 1][j - 1] + cost);
+    }
+  }
+
+  return rows[a.length][b.length];
+}
+
+/** Nearest known key, when it is close enough that a typo is the likely cause. */
+export function suggestKey(unknownKey, knownKeys) {
+  let best = null;
+  let bestDistance = Infinity;
+
+  for (const key of knownKeys) {
+    const distance = levenshtein(unknownKey.toLowerCase(), key.toLowerCase());
+
+    if (distance < bestDistance) {
+      best = key;
+      bestDistance = distance;
+    }
+  }
+
+  const threshold = Math.max(2, Math.floor(unknownKey.length / 3));
+
+  return bestDistance <= threshold ? best : null;
+}
+
+export function validateConfig(config, schema) {
+  const ajv = new Ajv({ allErrors: true, allowUnionTypes: true });
+
+  const validate = ajv.compile(schema);
+  const knownKeys = getSchemaKeys(schema);
+
+  if (!validate(config)) {
+    const errors = (validate.errors ?? []).map(error => {
+      const location = error.instancePath || '(root)';
+      const extra = error.params?.additionalProperty;
+
+      if (extra) {
+        const suggestion = !error.instancePath && suggestKey(extra, knownKeys);
+
+        return `${location} has unknown key "${extra}"${suggestion ? ` — did you mean "${suggestion}"?` : ''}`;
+      }
+
+      return `${location} ${error.message}`;
+    });
+
+    return { valid: false, errors };
+  }
+
+  return { valid: true, errors: [] };
+}
+
+/** Validates one consuming project against the schema bundled with this Shiso version. */
+export async function validateProject({ root = process.cwd() } = {}) {
+  const [{ schema }, { config }] = await Promise.all([
+    loadDocsSchema({ root: packageRoot }),
+    loadDocsConfig({ root }),
+  ]);
+
+  return validateConfig(config, schema);
+}
+
+// CLI entry point. Skipped when imported by tests.
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(import.meta.filename)) {
+  const { valid, errors } = await validateProject();
+
+  if (!valid) {
+    console.error('docs.json failed schema validation:\n');
+    for (const error of errors) {
+      console.error(`  ${error}`);
+    }
+    process.exit(1);
+  }
+
+  console.log('docs.json is valid.');
+}

package/scripts/vite-docs-config.mjs

@@ -0,0 +1,60 @@
+import path from 'node:path';
+import { loadDocsConfig } from './load-docs-config.mjs';
+
+export const VIRTUAL_DOCS_CONFIG_ID = 'virtual:shiso-docs-config';
+const RESOLVED_DOCS_CONFIG_ID = `\0${VIRTUAL_DOCS_CONFIG_ID}`;
+
+function renderConfigModule(config) {
+  return `export default ${JSON.stringify(config)};`;
+}
+
+/**
+ * Creates the single docs-config state shared by a Vite build and application
+ * modules. The virtual module keeps Node-only file loading out of the browser
+ * bundle and gives the later `$ref` resolver one integration point.
+ */
+export async function createDocsConfigModule({
+  root = process.cwd(),
+  configFile = 'docs.json',
+} = {}) {
+  const options = { root, configFile };
+  let loaded = await loadDocsConfig(options);
+
+  return {
+    getConfig: () => loaded.config,
+    getSourcePaths: () => loaded.sourcePaths,
+    sourcePath: loaded.sourcePath,
+    plugin: {
+      name: 'shiso-docs-config',
+      enforce: 'pre',
+      resolveId(id) {
+        return id === VIRTUAL_DOCS_CONFIG_ID ? RESOLVED_DOCS_CONFIG_ID : undefined;
+      },
+      load(id) {
+        if (id !== RESOLVED_DOCS_CONFIG_ID) {
+          return undefined;
+        }
+
+        for (const sourcePath of loaded.sourcePaths) {
+          this.addWatchFile(sourcePath);
+        }
+        return renderConfigModule(loaded.config);
+      },
+      async handleHotUpdate(context) {
+        if (!loaded.sourcePaths.includes(path.resolve(context.file))) {
+          return;
+        }
+
+        loaded = await loadDocsConfig(options);
+
+        const configModule = context.server.moduleGraph.getModuleById(RESOLVED_DOCS_CONFIG_ID);
+
+        if (configModule) {
+          context.server.moduleGraph.invalidateModule(configModule);
+        }
+
+        context.server.ws.send({ type: 'full-reload' });
+      },
+    },
+  };
+}

package/src/App.tsx

@@ -0,0 +1,39 @@
+import '@fontsource/inter/400.css';
+import '@fontsource/inter/700.css';
+import '@fontsource/inter/800.css';
+import '@fontsource/jetbrains-mono/400.css';
+import 'highlight.js/styles/github.css';
+import '@/styles/global.css';
+
+import { MDXProvider } from '@mdx-js/react';
+import { Navigate, Route, Routes } from 'react-router';
+import { CodeBlock } from '@/components/CodeBlock';
+import * as docsComponents from '@/components/docs/index';
+import { Layout } from '@/components/Layout';
+import { TooltipProvider } from '@/components/ui/tooltip';
+import { DOCS_PREFIX } from '@/lib/paths';
+import { siteModel } from '@/lib/site-config';
+import { DocPage } from '@/pages/DocPage';
+
+const mdxComponents = {
+  ...docsComponents,
+  pre: CodeBlock,
+};
+
+export function App() {
+  return (
+    <TooltipProvider>
+      <MDXProvider components={mdxComponents}>
+        <Layout site={siteModel}>
+          <Routes>
+            {/* When docs are mounted at the site root there is nothing to redirect. */}
+            {DOCS_PREFIX ? (
+              <Route path="/" element={<Navigate to={DOCS_PREFIX} replace />} />
+            ) : null}
+            <Route path="*" element={<DocPage site={siteModel} />} />
+          </Routes>
+        </Layout>
+      </MDXProvider>
+    </TooltipProvider>
+  );
+}

package/src/components/Banner.tsx

@@ -0,0 +1,69 @@
+import { useEffect, useState } from 'react';
+import { X } from '@/components/icons';
+import { Button } from '@/components/ui/button';
+import { renderInlineMarkdown } from '@/lib/inline-markdown';
+import type { BannerConfig } from '@/lib/types';
+
+const STORAGE_KEY = 'shiso-banner-dismissed';
+
+/**
+ * Site-wide banner from the `banner` config key. Dismissal stores the banner
+ * content, not just a flag, so publishing a new banner shows it again.
+ * The banner renders during prerender and hides after hydration when it was
+ * previously dismissed.
+ */
+export function Banner({
+  banner,
+  dismissLabel,
+}: {
+  banner: BannerConfig | null;
+  dismissLabel: string;
+}) {
+  const [dismissed, setDismissed] = useState(false);
+
+  useEffect(() => {
+    if (!banner?.dismissible) {
+      return;
+    }
+
+    try {
+      setDismissed(localStorage.getItem(STORAGE_KEY) === banner.content);
+    } catch {
+      // Ignore storage failures (private mode, etc).
+    }
+  }, [banner?.dismissible, banner?.content]);
+
+  if (!banner || dismissed) {
+    return null;
+  }
+
+  const handleDismiss = () => {
+    setDismissed(true);
+
+    try {
+      localStorage.setItem(STORAGE_KEY, banner.content);
+    } catch {
+      // Ignore storage failures (private mode, etc).
+    }
+  };
+
+  return (
+    <div className="relative flex shrink-0 items-center justify-center gap-2 bg-primary px-10 py-2 text-center text-sm text-primary-foreground">
+      <div className="[&_a:hover]:opacity-[0.85] [&_a]:text-inherit [&_a]:underline [&_a]:underline-offset-2 [&_code]:rounded-sm [&_code]:bg-black/20 [&_code]:px-1 [&_code]:py-[0.0625rem] [&_code]:text-[0.8125rem] [&_code]:font-mono">
+        {renderInlineMarkdown(banner.content)}
+      </div>
+      {banner.dismissible && (
+        <Button
+          type="button"
+          variant="ghost"
+          size="icon-xs"
+          className="absolute top-1/2 right-3 inline-flex size-6 -translate-y-1/2 items-center justify-center rounded-sm text-inherit opacity-80 hover:bg-black/15 hover:opacity-100"
+          onClick={handleDismiss}
+          aria-label={dismissLabel}
+        >
+          <X size={16} />
+        </Button>
+      )}
+    </div>
+  );
+}

package/src/components/CodeBlock.tsx

@@ -0,0 +1,46 @@
+import { type ReactNode, useRef, useState } from 'react';
+import { CheckIcon, Copy } from '@/components/icons';
+import { Button } from '@/components/ui/button';
+import { ScrollArea } from '@/components/ui/scroll-area';
+
+export interface CodeBlockProps {
+  children?: ReactNode;
+  className?: string;
+}
+
+export function CodeBlock({ children, className }: CodeBlockProps) {
+  const textInput = useRef<HTMLPreElement>(null);
+  const [copied, setCopied] = useState(false);
+
+  const handleCopy = () => {
+    setCopied(true);
+    navigator?.clipboard?.writeText(textInput.current?.textContent || '');
+
+    setTimeout(() => {
+      setCopied(false);
+    }, 1000);
+  };
+
+  return (
+    <div data-slot="code-block" className="relative my-5 overflow-hidden rounded-lg bg-muted/50">
+      <ScrollArea scrollbars="horizontal" className="w-full">
+        <pre
+          ref={textInput}
+          className={`code-block p-3 pr-12 text-sm text-foreground leading-[1.6] font-mono ${className || ''}`}
+        >
+          {children}
+        </pre>
+      </ScrollArea>
+      <Button
+        type="button"
+        variant="ghost"
+        size="icon-sm"
+        className="absolute top-2.5 right-3 inline-flex size-7 items-center justify-center rounded-sm text-muted-foreground hover:bg-accent hover:text-accent-foreground"
+        onClick={handleCopy}
+        aria-label="Copy code"
+      >
+        {copied ? <CheckIcon className="size-3.5 text-primary" /> : <Copy className="size-3.5" />}
+      </Button>
+    </div>
+  );
+}

package/src/components/ConfiguredIcon.tsx

@@ -0,0 +1,15 @@
+import { isKnownPlatform, SocialIcon } from '@/components/SocialIcon';
+import { getIcon } from '@/lib/icons';
+
+export function ConfiguredIcon({ icon, size = 14 }: { icon?: string; size?: number }) {
+  if (!icon) {
+    return null;
+  }
+
+  if (isKnownPlatform(icon)) {
+    return <SocialIcon platform={icon} size={size} />;
+  }
+
+  const Icon = getIcon(icon);
+  return Icon ? <Icon size={size} aria-hidden="true" /> : null;
+}

package/src/components/ContextualMenu.tsx

@@ -0,0 +1,93 @@
+import { useState } from 'react';
+import { ConfiguredIcon } from '@/components/ConfiguredIcon';
+import { Check, ChevronRight } from '@/components/icons';
+import { Button } from '@/components/ui/button';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import type { ResolvedContextualOption, ThemeLabels } from '@/lib/types';
+
+export function ContextualMenu({
+  options,
+  labels,
+}: {
+  options: ResolvedContextualOption[];
+  labels: ThemeLabels;
+}) {
+  const [copied, setCopied] = useState(false);
+  const primary = options[0];
+
+  if (!primary) {
+    return null;
+  }
+
+  const runOption = async (option: ResolvedContextualOption) => {
+    if (option.action === 'copy') {
+      try {
+        const response = await fetch(option.href);
+        const text = response.ok ? await response.text() : window.location.href;
+        await navigator.clipboard.writeText(text);
+        setCopied(true);
+        setTimeout(() => setCopied(false), 1500);
+      } catch {
+        // Clipboard unavailable; leave the control unchanged.
+      }
+      return;
+    }
+
+    window.open(option.href, option.target, option.target === '_blank' ? 'noreferrer' : undefined);
+  };
+
+  const optionIcon = (option: ResolvedContextualOption, showCopied = false) =>
+    showCopied && copied ? <Check className="size-3.5" /> : <ConfiguredIcon icon={option.icon} />;
+
+  return (
+    <div className="inline-flex shrink-0 items-stretch">
+      <Button
+        variant="outline"
+        size="sm"
+        className="rounded-r-none bg-card text-foreground only:rounded-md"
+        onClick={() => runOption(primary)}
+      >
+        {optionIcon(primary, primary.action === 'copy')}
+        {primary.action === 'copy' && copied ? labels.copied : primary.title}
+      </Button>
+      {options.length > 1 && (
+        <DropdownMenu>
+          <DropdownMenuTrigger
+            render={
+              <Button
+                variant="outline"
+                size="icon-sm"
+                className="rounded-l-none border-l-0 bg-card"
+                aria-label={labels.moreOptions}
+              />
+            }
+          >
+            <ChevronRight className="size-3.5 rotate-90" />
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end" className="w-60">
+            {options.map(option => (
+              <DropdownMenuItem
+                key={option.key}
+                className="flex-row items-start gap-2 px-2.5 py-1.5"
+                onClick={() => runOption(option)}
+              >
+                <span className="mt-0.5">{optionIcon(option)}</span>
+                <span className="flex flex-col gap-0.5">
+                  <span className="text-[0.85rem] font-medium text-foreground">{option.title}</span>
+                  {option.description ? (
+                    <span className="text-xs text-muted-foreground">{option.description}</span>
+                  ) : null}
+                </span>
+              </DropdownMenuItem>
+            ))}
+          </DropdownMenuContent>
+        </DropdownMenu>
+      )}
+    </div>
+  );
+}

package/src/components/DocContent.tsx

@@ -0,0 +1,100 @@
+import { Link } from 'react-router';
+import { ContextualMenu } from '@/components/ContextualMenu';
+import { ChevronRight } from '@/components/icons';
+import { getLastModified } from '@/lib/content';
+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) {
+  const pagerPages = site.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);
+  const dateFormat = new Intl.DateTimeFormat(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,126 @@
+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 { 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 { renderInlineMarkdown } from '@/lib/inline-markdown';
+import { DOCS_PREFIX } from '@/lib/paths';
+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(DOCS_PREFIX || '/', { 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);
+  const { tabs, navigation } = site.docs;
+
+  // 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">
+            <SideNav
+              tabs={tabs}
+              navigation={navigation}
+              anchors={site.docs.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={site.docs.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>
+  );
+}