@umami/shiso 1.17.0 → 1.19.0

package/scripts/lib/request-samples.mjs

@@ -0,0 +1,323 @@
+/**
+ * Request building shared by the build-time sample generator and the browser
+ * API playground. This module is deliberately free of Node imports: it is
+ * bundled into the client runtime as well as executed by the build scripts.
+ *
+ * `buildRequest` turns an operation plus user-supplied values into a concrete
+ * HTTP request description; `buildCodeSamples` renders that description as
+ * cURL, JavaScript, and Python. Values that are missing fall back to the
+ * spec's examples or to angle-bracket placeholders such as `<token>`, so the
+ * static samples and the live playground always agree on the request shape.
+ */
+
+const PLACEHOLDER = /^<[^<>]+>$/;
+
+/** Percent-encodes a value unless it is a documentation placeholder. */
+function encodeValue(value) {
+  return PLACEHOLDER.test(value) ? value : encodeURIComponent(value);
+}
+
+function toBase64(value) {
+  if (typeof btoa === 'function') return btoa(value);
+  return Buffer.from(value, 'utf8').toString('base64');
+}
+
+function capitalize(value) {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
+
+/** Placeholder credential text shown in samples when no value is supplied. */
+export function securityPlaceholder(scheme) {
+  if (scheme.type === 'http') {
+    return scheme.scheme === 'basic' ? '<credentials>' : '<token>';
+  }
+  if (scheme.type === 'apiKey') return '<api-key>';
+  return '<access-token>';
+}
+
+/**
+ * Applies one security scheme to the request. `value` is a string for token
+ * and API key schemes, `{ username, password }` for HTTP basic, or undefined
+ * to emit a placeholder.
+ */
+export function applySecurity(scheme, value, target) {
+  const placeholder = securityPlaceholder(scheme);
+
+  if (scheme.type === 'apiKey') {
+    const credential = typeof value === 'string' && value ? value : placeholder;
+    const name = scheme.paramName || scheme.name;
+    if (scheme.in === 'query') target.query[name] = credential;
+    else if (scheme.in === 'cookie') target.cookies[name] = credential;
+    else target.headers[name] = credential;
+    return;
+  }
+
+  if (scheme.type === 'http' && scheme.scheme === 'basic') {
+    const credential =
+      value && typeof value === 'object' && (value.username || value.password)
+        ? toBase64(`${value.username || ''}:${value.password || ''}`)
+        : typeof value === 'string' && value
+          ? value
+          : placeholder;
+    target.headers.Authorization = `Basic ${credential}`;
+    return;
+  }
+
+  const prefix =
+    scheme.type === 'http' && scheme.scheme && scheme.scheme !== 'bearer'
+      ? capitalize(scheme.scheme)
+      : 'Bearer';
+  const credential = typeof value === 'string' && value ? value : placeholder;
+  target.headers.Authorization = `${prefix} ${credential}`;
+}
+
+/** Content categories the sample renderers and playground understand. */
+export function bodyKind(contentType) {
+  if (!contentType) return 'none';
+  if (/[+/]json\b/i.test(contentType)) return 'json';
+  if (/x-www-form-urlencoded/i.test(contentType)) return 'form';
+  if (/multipart\/form-data/i.test(contentType)) return 'multipart';
+  return 'raw';
+}
+
+function parseFields(body) {
+  if (!body) return {};
+  try {
+    const parsed = JSON.parse(body);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+    return Object.fromEntries(
+      Object.entries(parsed).map(([key, value]) => [
+        key,
+        typeof value === 'string' ? value : JSON.stringify(value),
+      ]),
+    );
+  } catch {
+    return {};
+  }
+}
+
+function parameterValue(node, supplied) {
+  if (supplied !== undefined && supplied !== null && supplied !== '') return String(supplied);
+  return node.example;
+}
+
+/**
+ * Builds a concrete request from an operation and optional user values:
+ * `{ server, path, query, header, cookie, auth, body }`. Without values, the
+ * spec's examples fill required parameters and credentials become
+ * placeholders, which is the shape rendered in the static code samples.
+ */
+export function buildRequest(operation, values = {}) {
+  const live = values.live === true;
+  const target = { headers: {}, query: {}, cookies: {} };
+
+  for (const scheme of operation.security || []) {
+    applySecurity(scheme, values.auth?.[scheme.name], target);
+  }
+
+  const params = operation.parameters;
+  const pathValues = {};
+  for (const node of params.path) {
+    const value = parameterValue(node, values.path?.[node.name]);
+    // Static samples keep `{id}` placeholders so readers recognize the slot.
+    if (live && value !== undefined) pathValues[node.name] = value;
+  }
+  for (const node of params.query) {
+    const value = parameterValue(node, values.query?.[node.name]);
+    if (value !== undefined && (live || node.required || values.query?.[node.name])) {
+      target.query[node.name] = value;
+    }
+  }
+  for (const node of params.header) {
+    const value = parameterValue(node, values.header?.[node.name]);
+    if (value !== undefined && (live || node.required || values.header?.[node.name])) {
+      target.headers[node.name] = value;
+    }
+  }
+  for (const node of params.cookie) {
+    const value = parameterValue(node, values.cookie?.[node.name]);
+    if (value !== undefined && (live || node.required || values.cookie?.[node.name])) {
+      target.cookies[node.name] = value;
+    }
+  }
+
+  const server = (values.server || operation.servers?.[0]?.url || operation.serverUrl || '')
+    .trim()
+    .replace(/\/+$/, '');
+  const pathname = operation.path.replace(/\{([^}]+)\}/g, (match, name) =>
+    pathValues[name] !== undefined ? encodeURIComponent(pathValues[name]) : match,
+  );
+  const query = Object.entries(target.query)
+    .map(([key, value]) => `${encodeURIComponent(key)}=${encodeValue(value)}`)
+    .join('&');
+  const url = `${server}${pathname}${query ? `?${query}` : ''}`;
+
+  const cookieHeader = Object.entries(target.cookies)
+    .map(([key, value]) => `${key}=${value}`)
+    .join('; ');
+  if (cookieHeader) target.headers.Cookie = cookieHeader;
+
+  const contentType = operation.requestBody?.contentType;
+  const kind = operation.requestBody ? bodyKind(contentType) : 'none';
+  const body = values.body !== undefined ? values.body : operation.requestBody?.example;
+
+  return {
+    method: operation.method,
+    url,
+    headers: target.headers,
+    contentType,
+    bodyKind: kind,
+    body: kind === 'none' ? undefined : body,
+    fields: kind === 'form' || kind === 'multipart' ? parseFields(body) : undefined,
+  };
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+function jsString(value) {
+  return `'${String(value).replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\n/g, '\\n')}'`;
+}
+
+function jsKey(key) {
+  return /^[A-Za-z_$][\w$]*$/.test(key) ? key : jsString(key);
+}
+
+function pythonString(value) {
+  return jsString(value);
+}
+
+function pythonLiteral(json) {
+  // Request bodies are JSON strings; the Python sample shows them as dict
+  // literals, which differ from JSON only in quoting and keyword spelling.
+  return json
+    .replace(/"/g, "'")
+    .replace(/\btrue\b/g, 'True')
+    .replace(/\bfalse\b/g, 'False')
+    .replace(/\bnull\b/g, 'None');
+}
+
+function indentLines(text, indent) {
+  return text
+    .split('\n')
+    .map((line, index) => (index === 0 ? line : `${indent}${line}`))
+    .join('\n');
+}
+
+export function curlSample(request) {
+  const { method, url, headers, bodyKind: kind, body, fields, contentType } = request;
+  const lines = [`curl -X ${method} ${shellQuote(url)}`];
+
+  for (const [key, value] of Object.entries(headers)) {
+    lines.push(`  -H ${shellQuote(`${key}: ${value}`)}`);
+  }
+
+  if (kind === 'json' && body) {
+    lines.push(`  -H ${shellQuote(`Content-Type: ${contentType}`)}`, `  -d ${shellQuote(body)}`);
+  } else if (kind === 'form') {
+    for (const [key, value] of Object.entries(fields || {})) {
+      lines.push(`  --data-urlencode ${shellQuote(`${key}=${value}`)}`);
+    }
+  } else if (kind === 'multipart') {
+    for (const [key, value] of Object.entries(fields || {})) {
+      lines.push(`  -F ${shellQuote(`${key}=${value}`)}`);
+    }
+  } else if (kind === 'raw' && body) {
+    lines.push(`  -H ${shellQuote(`Content-Type: ${contentType}`)}`, `  -d ${shellQuote(body)}`);
+  }
+
+  return lines.join(' \\\n');
+}
+
+export function javascriptSample(request) {
+  const { method, url, headers, bodyKind: kind, body, fields, contentType } = request;
+  const headerLines = Object.entries(headers).map(
+    ([key, value]) => `    ${jsKey(key)}: ${jsString(value)},`,
+  );
+  if ((kind === 'json' || kind === 'raw') && body) {
+    headerLines.unshift(`    'Content-Type': ${jsString(contentType)},`);
+  }
+
+  const preamble = [];
+  let bodyLine;
+  if (kind === 'json' && body) {
+    bodyLine = `  body: JSON.stringify(${indentLines(body, '  ')}),`;
+  } else if (kind === 'form') {
+    const entries = Object.entries(fields || {})
+      .map(([key, value]) => `    ${jsKey(key)}: ${jsString(value)},`)
+      .join('\n');
+    bodyLine = entries
+      ? `  body: new URLSearchParams({\n${entries}\n  }),`
+      : '  body: new URLSearchParams(),';
+  } else if (kind === 'multipart') {
+    preamble.push('const body = new FormData();');
+    for (const [key, value] of Object.entries(fields || {})) {
+      preamble.push(`body.append(${jsString(key)}, ${jsString(value)});`);
+    }
+    preamble.push('');
+    bodyLine = '  body,';
+  } else if (kind === 'raw' && body) {
+    bodyLine = `  body: ${jsString(body)},`;
+  }
+
+  return [
+    ...preamble,
+    `const response = await fetch(${jsString(url)}, {`,
+    `  method: ${jsString(method)},`,
+    ...(headerLines.length ? ['  headers: {', ...headerLines, '  },'] : []),
+    ...(bodyLine ? [bodyLine] : []),
+    '});',
+    'const data = await response.json();',
+  ].join('\n');
+}
+
+export function pythonSample(request) {
+  const { method, url, headers, bodyKind: kind, body, fields, contentType } = request;
+  const headerEntries = Object.entries(headers);
+  if (kind === 'raw' && body) headerEntries.unshift(['Content-Type', contentType]);
+  const headerLine = headerEntries.length
+    ? `    headers={${headerEntries
+        .map(([key, value]) => `${pythonString(key)}: ${pythonString(value)}`)
+        .join(', ')}},`
+    : undefined;
+
+  let bodyLine;
+  if (kind === 'json' && body) {
+    bodyLine = `    json=${indentLines(pythonLiteral(body), '    ')},`;
+  } else if (kind === 'form') {
+    const entries = Object.entries(fields || {})
+      .map(([key, value]) => `${pythonString(key)}: ${pythonString(value)}`)
+      .join(', ');
+    bodyLine = `    data={${entries}},`;
+  } else if (kind === 'multipart') {
+    const entries = Object.entries(fields || {})
+      .map(([key, value]) => `${pythonString(key)}: (None, ${pythonString(value)})`)
+      .join(', ');
+    bodyLine = `    files={${entries}},`;
+  } else if (kind === 'raw' && body) {
+    bodyLine = `    data=${pythonString(body)},`;
+  }
+
+  return [
+    'import requests',
+    '',
+    `response = requests.${method.toLowerCase()}(`,
+    `    ${pythonString(url)},`,
+    ...(headerLine ? [headerLine] : []),
+    ...(bodyLine ? [bodyLine] : []),
+    ')',
+    'print(response.json())',
+  ].join('\n');
+}
+
+/** Builds cURL, JavaScript, and Python request samples for an operation. */
+export function buildCodeSamples(operation, values) {
+  const request = buildRequest(operation, values);
+
+  return [
+    { language: 'bash', label: 'cURL', source: curlSample(request) },
+    { language: 'javascript', label: 'JavaScript', source: javascriptSample(request) },
+    { language: 'python', label: 'Python', source: pythonSample(request) },
+  ];
+}

package/scripts/load-docs-config.mjs

@@ -2,12 +2,8 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { expandNavigationGlobs, hasNavigationGlobs } from './expand-navigation-globs.mjs';
 import { expandOpenApiNavigation, hasOpenApiItems } from './expand-openapi-navigation.mjs';
-import {
-  generateOpenApiStubs,
-  loadOpenApiSpec,
-  normalizeOperations,
-  resolveApiDirectory,
-} from './lib/openapi.mjs';
+import { generateOpenApiStubs } from './lib/openapi.mjs';
+import { loadApiProject } from './lib/openapi-project.mjs';
 import { loadShisoConfig } from './load-shiso-config.mjs';
 
 /** Error raised while locating, reading, or parsing a Shiso configuration file. */
@@ -244,24 +240,27 @@ export async function loadDocsConfig({
   const sourcePath = sourcePaths[0] || requestedSourcePath;
   const hasGlobs = hasNavigationGlobs(sourceConfig.navigation);
   let working = sourceConfig;
-  let specPath;
+  let specPaths = [];
 
   // OpenAPI expansion runs before glob expansion so generated stub pages are
   // visible to navigation globs and every downstream consumer.
   if (expandGlobs && working.api?.spec) {
-    const loadedSpec = await loadOpenApiSpec({ root: projectRoot, specPath: working.api.spec });
-    specPath = loadedSpec.specPath;
-    const operations = normalizeOperations(loadedSpec.spec);
-    const directory = resolveApiDirectory(working.api);
+    const project = await loadApiProject({ root: projectRoot, api: working.api });
+    specPaths = project.specPaths;
     const { config: shisoConfig } = await loadShisoConfig({ root: projectRoot });
 
     await generateOpenApiStubs({
       root: projectRoot,
       contentDir: shisoConfig.contentDir,
-      directory,
-      operations,
+      directory: project.directory,
+      operations: project.operations,
+      prefixSpec: project.multi,
+    });
+    working = expandOpenApiNavigation(working, {
+      operations: project.operations,
+      directory: project.directory,
+      specs: project.specs,
     });
-    working = expandOpenApiNavigation(working, { operations, directory });
   } else if (expandGlobs && hasOpenApiItems(working.navigation)) {
     throw new Error(
       'Navigation contains an { "openapi" } entry but docs.json has no "api.spec" setting.',
@@ -275,7 +274,16 @@ export async function loadDocsConfig({
       })
     : working;
 
-  return { config, projectRoot, sourcePath, sourcePaths, hasGlobs, specPath };
+  return {
+    config,
+    projectRoot,
+    sourcePath,
+    sourcePaths,
+    hasGlobs,
+    specPaths,
+    /** @deprecated use specPaths */
+    specPath: specPaths[0],
+  };
 }
 
 export async function loadDocsSchema({

package/scripts/load-shiso-config.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { createJiti } from 'jiti';
+import englishLabels from '../src/lib/translations/en.json' with { type: 'json' };
 
 /**
  * Loads the optional project code config (shiso.config.ts/.mjs/.js).
@@ -16,7 +17,7 @@ import { createJiti } from 'jiti';
 export const SHISO_CONFIG_FILES = ['shiso.config.ts', 'shiso.config.mjs', 'shiso.config.js'];
 
 const STRING_KEYS = ['docsPrefix', 'contentDir', 'siteUrl', 'locale'];
-const KNOWN_KEYS = [...STRING_KEYS, 'mdx'];
+const KNOWN_KEYS = [...STRING_KEYS, 'mdx', 'translations'];
 const MDX_KEYS = ['remarkPlugins', 'rehypePlugins'];
 
 let importGeneration = 0;
@@ -88,6 +89,31 @@ function resolveMdxConfig(value, sourcePath) {
   };
 }
 
+function resolveTranslations(value, sourcePath) {
+  if (value === undefined) return undefined;
+  const invalid = message => {
+    throw new ShisoConfigLoadError(message, { code: 'INVALID_OPTION', sourcePath });
+  };
+  if (!isPlainObject(value)) invalid('Shiso config option "translations" must be an object.');
+  const result = {};
+  for (const [locale, labels] of Object.entries(value)) {
+    let canonical;
+    try {
+      canonical = Intl.getCanonicalLocales(locale)[0];
+    } catch {
+      invalid(`Invalid translations locale "${locale}". Use a BCP 47 tag such as "fr" or "pt-BR".`);
+    }
+    if (!isPlainObject(labels)) invalid(`translations.${locale} must be an object.`);
+    for (const [key, label] of Object.entries(labels)) {
+      if (!Object.hasOwn(englishLabels, key))
+        invalid(`Unknown UI label "translations.${locale}.${key}".`);
+      if (typeof label !== 'string') invalid(`translations.${locale}.${key} must be a string.`);
+    }
+    result[canonical] = { ...result[canonical], ...labels };
+  }
+  return result;
+}
+
 /**
  * Applies defaults and normalization. Single source of truth for resolved
  * values, so runtime and build-time consumers never re-implement defaulting.
@@ -103,6 +129,9 @@ export function resolveShisoConfig(raw = {}, sourcePath = null) {
     siteUrl: raw.siteUrl?.trim().replace(/\/+$/, '') || undefined,
     locale: raw.locale?.trim() || 'en-US',
     mdx: resolveMdxConfig(raw.mdx, sourcePath),
+    ...(raw.translations === undefined
+      ? {}
+      : { translations: resolveTranslations(raw.translations, sourcePath) }),
   };
 }
 

package/scripts/prerender.mjs

@@ -16,12 +16,8 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import process from 'node:process';
 import { pathToFileURL } from 'node:url';
-import {
-  loadOpenApiSpec,
-  normalizeOperationKey,
-  normalizeOperations,
-  operationToMarkdown,
-} from './lib/openapi.mjs';
+import { operationToMarkdown, schemaToMarkdown } from './lib/openapi.mjs';
+import { loadApiProject, lookupOperation, lookupSchema } from './lib/openapi-project.mjs';
 import { loadDocsConfig } from './load-docs-config.mjs';
 
 const DEFAULT_HEAD_OPEN = '<!--shiso-default-head-->';
@@ -122,21 +118,28 @@ if (docsHomeUrl && docsHomeUrl !== '/' && !routes.includes('/')) {
 
 // Pages bound to an API operation publish the generated reference as markdown
 // too, so the .md copies and llms-full.txt stay useful to AI tools.
-let openApiByKey;
+let apiProject;
 {
   const docsConfig = (await loadDocsConfig({ root, expandGlobs: false })).config;
   if (docsConfig.api?.spec) {
-    const { spec } = await loadOpenApiSpec({ root, specPath: docsConfig.api.spec });
-    openApiByKey = new Map(normalizeOperations(spec).map(operation => [operation.key, operation]));
+    apiProject = await loadApiProject({ root, api: docsConfig.api });
   }
 }
 
-function withOperationMarkdown(source) {
-  if (!openApiByKey) return source;
+function frontmatterValue(source, name) {
   const frontmatter = source.match(/^---\s*\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1] || '';
-  const key = normalizeOperationKey(frontmatter.match(/^openapi:\s*(.+)$/m)?.[1]);
-  const operation = key ? openApiByKey.get(key) : undefined;
-  return operation ? `${source.trimEnd()}\n\n${operationToMarkdown(operation)}\n` : source;
+  return frontmatter
+    .match(new RegExp(`^${name}:\\s*(.+)$`, 'm'))?.[1]
+    ?.trim()
+    .replace(/^["']|["']$/g, '');
+}
+
+function withOperationMarkdown(source) {
+  if (!apiProject) return source;
+  const operation = lookupOperation(apiProject, frontmatterValue(source, 'openapi'));
+  if (operation) return `${source.trimEnd()}\n\n${operationToMarkdown(operation)}\n`;
+  const schema = lookupSchema(apiProject, frontmatterValue(source, 'openapi-schema'));
+  return schema ? `${source.trimEnd()}\n\n${schemaToMarkdown(schema)}\n` : source;
 }
 
 // Raw markdown next to every page: "/docs/installation" -> "docs/installation.md".

package/scripts/vite-docs-config.mjs

@@ -43,6 +43,7 @@ export async function createDocsConfigModule({
     getConfig: () => loaded.config,
     getShisoConfig: () => loadedShiso.config,
     getSpecPath: () => loaded.specPath,
+    getSpecPaths: () => loaded.specPaths || [],
     getSourcePaths: () => [...loaded.sourcePaths, ...loadedShiso.sourcePaths],
     sourcePath: loaded.sourcePath,
     shisoSourcePath: loadedShiso.sourcePath,

package/src/App.tsx

@@ -3,12 +3,18 @@ import '@fontsource/jetbrains-mono/400.css';
 import '@umami/shiso/styles.css';
 
 import { MDXProvider } from '@mdx-js/react';
-import { Navigate, Route, Routes } from 'react-router';
+import { Navigate, Route, Routes, useLocation } 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, hasRootStandalonePage, siteModel, standalonePages } from '@/lib/site-config';
+import { LabelContext } from '@/lib/label-context';
+import {
+  docsHomeUrl,
+  getSiteModelByPathname,
+  hasRootStandalonePage,
+  standalonePages,
+} from '@/lib/site-config';
 import { DocPage } from '@/pages/DocPage';
 import { StandalonePageView } from '@/pages/StandalonePage';
 
@@ -27,27 +33,31 @@ const mdxComponents = {
 };
 
 export function App() {
+  const { pathname } = useLocation();
+  const siteModel = getSiteModelByPathname(pathname);
   return (
-    <TooltipProvider>
-      <MDXProvider components={mdxComponents}>
-        <Layout site={siteModel}>
-          <Routes>
-            {standalonePages.map(page => (
-              <Route
-                key={page.path}
-                path={page.path}
-                element={<StandalonePageView page={page} site={siteModel} />}
-              />
-            ))}
-            {/* When the default scope's landing page is the root, or a
+    <LabelContext.Provider value={siteModel.labels}>
+      <TooltipProvider>
+        <MDXProvider components={mdxComponents}>
+          <Layout site={siteModel}>
+            <Routes>
+              {standalonePages.map(page => (
+                <Route
+                  key={page.path}
+                  path={page.path}
+                  element={<StandalonePageView page={page} site={siteModel} />}
+                />
+              ))}
+              {/* When the default scope's landing page is the root, or a
                 standalone page owns "/", there is nothing to redirect. */}
-            {docsHomeUrl !== '/' && !hasRootStandalonePage ? (
-              <Route path="/" element={<Navigate to={docsHomeUrl} replace />} />
-            ) : null}
-            <Route path="*" element={<DocPage site={siteModel} />} />
-          </Routes>
-        </Layout>
-      </MDXProvider>
-    </TooltipProvider>
+              {docsHomeUrl !== '/' && !hasRootStandalonePage ? (
+                <Route path="/" element={<Navigate to={docsHomeUrl} replace />} />
+              ) : null}
+              <Route path="*" element={<DocPage site={siteModel} />} />
+            </Routes>
+          </Layout>
+        </MDXProvider>
+      </TooltipProvider>
+    </LabelContext.Provider>
   );
 }