@umami/shiso 0.55.0 → 1.0.0

package/scripts/prerender.mjs

@@ -0,0 +1,194 @@
+/**
+ * Prerenders every docs page to static HTML.
+ *
+ * Runs after `vite build` (client) and `vite build --ssr` (server):
+ * 1. Loads the SSR bundle from dist/server.
+ * 2. Renders each route from the normalized docs.json navigation.
+ * 3. Injects the rendered HTML and per-page head tags into the client
+ *    dist/client/index.html template.
+ * 4. Writes dist/client/<base>/<route>/index.html plus a root entry and 404 page.
+ *
+ * Routes from the SSR bundle are base-relative; the deploy base is applied here
+ * so the output directory layout matches the URLs the router will produce.
+ */
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { pathToFileURL } from 'node:url';
+
+const DEFAULT_HEAD_OPEN = '<!--shiso-default-head-->';
+const DEFAULT_HEAD_CLOSE = '<!--/shiso-default-head-->';
+
+const root = process.cwd();
+const clientDir = path.join(root, 'dist', 'client');
+const template = await readFile(path.join(clientDir, 'index.html'), 'utf8');
+
+if (!template.includes('<!--app-html-->')) {
+  throw new Error(
+    'dist/client/index.html is missing the <!--app-html--> placeholder. ' +
+      'Run "vite build" again before prerendering (prerender consumes the template in place).',
+  );
+}
+
+const { render, getRoutes, getRedirects, getSitemapEntries, getMarkdownPages, docsHomeUrl } =
+  await import(pathToFileURL(path.join(root, 'dist', 'server', 'entry-server.js')).href);
+
+/** Vite's `base`, normalized to "" or "/prefix". */
+function readBase() {
+  const match = template.match(/<script[^>]+src="([^"]*)\/assets\//);
+  const base = match?.[1] ?? '';
+  return base === '/' ? '' : base;
+}
+
+const base = readBase();
+
+function withBase(routePath) {
+  return `${base}${routePath}`.replace(/\/{2,}/g, '/') || '/';
+}
+
+function fillTemplate(head, html, htmlAttrs) {
+  // Per-page head tags supersede the site-level defaults injected at build time.
+  let output = head
+    ? template.replace(new RegExp(`${DEFAULT_HEAD_OPEN}[\\s\\S]*?${DEFAULT_HEAD_CLOSE}`), '')
+    : template;
+
+  // Per-page document language and direction, replacing the template's own.
+  if (htmlAttrs) {
+    output = output.replace(/<html([^>]*)>/, (_match, attrs) => {
+      const kept = attrs.replace(/\s+lang="[^"]*"/, '').replace(/\s+dir="[^"]*"/, '');
+      const dir = htmlAttrs.dir === 'rtl' ? ' dir="rtl"' : '';
+      return `<html${kept} lang="${htmlAttrs.lang}"${dir}>`;
+    });
+  }
+
+  return output.replace('<!--app-head-->', head).replace('<!--app-html-->', html);
+}
+
+async function writePage(outputPath, contents) {
+  await mkdir(path.dirname(outputPath), { recursive: true });
+  await writeFile(outputPath, contents, 'utf8');
+}
+
+/** Maps a base-relative route to its output file, e.g. "/docs/a" -> "docs/a/index.html". */
+function outputPathFor(routePath) {
+  const relative = withBase(routePath).replace(/^\//, '');
+  return path.join(clientDir, relative, 'index.html');
+}
+
+const routes = getRoutes();
+
+for (const route of routes) {
+  const { html, head, htmlAttrs } = render(route);
+  await writePage(outputPathFor(route), fillTemplate(head, html, htmlAttrs));
+}
+
+// Root entry. When the default scope's landing page is not the root itself the
+// root is a redirect; a meta refresh alone is slow and SEO-hostile, so pair it
+// with a canonical link and an immediate history-replacing navigation.
+if (docsHomeUrl && docsHomeUrl !== '/') {
+  const target = withBase(`${docsHomeUrl}/`);
+
+  await writePage(
+    path.join(clientDir, 'index.html'),
+    fillTemplate(
+      [
+        `<link rel="canonical" href="${target}" />`,
+        `<meta http-equiv="refresh" content="0;url=${target}" />`,
+        `<script>location.replace(${JSON.stringify(target)});</script>`,
+      ].join('\n    '),
+      '',
+    ),
+  );
+}
+
+// Raw markdown next to every page: "/docs/installation" -> "docs/installation.md".
+// Served for the contextual menu's copy/view options and for AI tools.
+const markdownPages = getMarkdownPages();
+
+for (const { route, filePath } of markdownPages) {
+  const source = await readFile(path.join(root, ...filePath.split('/').filter(Boolean)), 'utf8');
+  const relative = withBase(route).replace(/^\//, '') || 'index';
+  await writePage(path.join(clientDir, `${relative}.md`), source);
+}
+
+// Redirect pages. Static hosting cannot serve real 301s, so each redirect
+// gets the same canonical + meta refresh + immediate replace treatment as
+// the root entry. Real pages always win over redirect rules.
+const routeSet = new Set(routes.map(withBase));
+const redirects = getRedirects();
+
+function redirectTarget(destination) {
+  return /^[a-z][a-z0-9+.-]*:/i.test(destination) ? destination : withBase(destination);
+}
+
+for (const { source, destination } of redirects) {
+  if (routeSet.has(withBase(source))) {
+    console.warn(`Redirect source "${source}" is an existing page — skipped.`);
+    continue;
+  }
+
+  const target = redirectTarget(destination);
+
+  await writePage(
+    outputPathFor(source),
+    fillTemplate(
+      [
+        `<link rel="canonical" href="${target}" />`,
+        `<meta name="robots" content="noindex" />`,
+        `<meta http-equiv="refresh" content="0;url=${target}" />`,
+        `<script>location.replace(${JSON.stringify(target)});</script>`,
+      ].join('\n    '),
+      '',
+    ),
+  );
+}
+
+// Sitemap, only when $shiso.siteUrl provides an absolute origin.
+const sitemapEntries = getSitemapEntries();
+
+if (sitemapEntries.length) {
+  const urls = sitemapEntries
+    .map(({ url, lastmod }) =>
+      [
+        '  <url>',
+        `    <loc>${url}</loc>`,
+        lastmod ? `    <lastmod>${lastmod}</lastmod>` : null,
+        '  </url>',
+      ]
+        .filter(Boolean)
+        .join('\n'),
+    )
+    .join('\n');
+
+  await writePage(
+    path.join(clientDir, 'sitemap.xml'),
+    `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls}\n</urlset>\n`,
+  );
+}
+
+// 404 fallback renders the app shell so client routing can take over
+// on hosts that serve 404.html for unknown paths (e.g. GitHub Pages).
+const notFound = render('/404');
+await writePage(
+  path.join(clientDir, '404.html'),
+  fillTemplate(notFound.head, notFound.html, notFound.htmlAttrs),
+);
+
+// Guard against a base/route mismatch silently producing unreachable files.
+const stray = routes.filter(route => !withBase(route).startsWith(base || '/'));
+
+if (stray.length) {
+  throw new Error(`Routes fall outside the deploy base "${base}": ${stray.join(', ')}`);
+}
+
+const extras = [
+  redirects.length ? `${redirects.length} redirects` : null,
+  sitemapEntries.length ? 'sitemap.xml' : null,
+]
+  .filter(Boolean)
+  .join(', ');
+
+console.log(
+  `Prerendered ${routes.length} pages to ${path.relative(root, clientDir)}${extras ? ` (+ ${extras})` : ''}`,
+);

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,38 @@
+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 { docsHomeUrl, 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 the default scope's landing page is the root there is nothing to redirect. */}
+            {docsHomeUrl !== '/' ? (
+              <Route path="/" element={<Navigate to={docsHomeUrl} 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>
+  );
+}