@umami/shiso 1.12.0 → 1.14.0

package/dist/components.js

@@ -1,3 +1,3 @@
-import { At as Danger, Bt as AccordionGroup, Dt as CardGroup, Et as Card, Ft as WarningBanner, It as Button, Lt as Badge, Mt as Note, Nt as Tip, Ot as Callout, Pt as Warning, St as CodeGroup, _ as Tooltip, at as Tabs, bt as Column, ct as ResponseField, dt as ParamField, ft as Link, gt as Expandable, it as Tab, jt as Info, kt as Check, lt as PropertiesTable, mt as Frame, n as ZoomableImage, ot as Step, pt as Icon, st as Steps, ut as Param, xt as Columns, zt as Accordion } from "./chunks/docs.js";
+import { At as Column, Bt as Callout, C as Tooltip, Ct as Icon, Et as Expandable, Gt as Tip, Ht as Danger, It as Changelog, Jt as Button, Kt as Warning, Lt as Update, Mt as CodeGroup, Qt as AccordionGroup, Rt as Card, S as TreeFolder, St as Link, Ut as Info, Vt as Check, Wt as Note, Yt as Badge, Zt as Accordion, _ as FileTree, _t as Param, b as Tree, bn as mermaidSource, bt as usePanelContent, dt as Tiles, ft as Tab, gt as PropertiesTable, ht as Steps, jt as Columns, mt as Step, n as ZoomableImage, pt as Tabs, qt as WarningBanner, ut as Tile, v as FileTreeFile, vt as Panel, wt as Frame, x as TreeFile, xt as useSetPanelContent, y as FileTreeFolder, yn as Mermaid, yt as PanelProvider, zt as CardGroup } from "./chunks/docs.js";
 
-export { Accordion, AccordionGroup, Badge, Button, Callout, Card, CardGroup, Check, CodeGroup, Column, Columns, Danger, Expandable, Frame, Icon, Info, Link, Note, Param, ParamField, PropertiesTable, ResponseField, Step, Steps, Tab, Tabs, Tip, Tooltip, Warning, WarningBanner, ZoomableImage };
+export { Accordion, AccordionGroup, Badge, Button, Callout, Card, CardGroup, Changelog, Check, CodeGroup, Column, Columns, Danger, Expandable, FileTree, FileTreeFile, FileTreeFolder, Frame, Icon, Info, Link, Mermaid, Note, Panel, PanelProvider, Param, PropertiesTable, Step, Steps, Tab, Tabs, Tile, Tiles, Tip, Tooltip, Tree, TreeFile, TreeFolder, Update, Warning, WarningBanner, ZoomableImage, mermaidSource, usePanelContent, useSetPanelContent };

package/dist/entry-client.js

@@ -1,4 +1,4 @@
-import { ar as BrowserRouter } from "./chunks/docs.js";
+import { yr as BrowserRouter } from "./chunks/docs.js";
 import { h as BASE_URL, t as App } from "./chunks/App.js";
 import { jsx } from "react/jsx-runtime";
 

package/dist/entry-server.js

@@ -1,10 +1,10 @@
-import { hr as ABSOLUTE_URL_REGEX, lr as Router, mr as parsePath, pr as createPath } from "./chunks/docs.js";
+import { Cr as Router, Dr as createPath, Or as parsePath, kr as ABSOLUTE_URL_REGEX } from "./chunks/docs.js";
 import { a as docsSite, c as getSeo, d as standalonePages, f as getDocModule, g as toAbsoluteUrl, h as BASE_URL, i as docsHomeUrl, l as siteConfig, m as getScopeForPage, n as buildHead, o as getLocaleByPathname, p as getLastModified, r as renderHeadToString, s as getRedirects, t as App, u as siteName } from "./chunks/App.js";
 import * as React$1 from "react";
 import { jsx } from "react/jsx-runtime";
 import { renderToString } from "react-dom/server";
 
-//#region ../../node_modules/.pnpm/react-router@8.3.0_react-do_c27277bcf657dc321048682bd02ab633/node_modules/react-router/dist/production/lib/dom/server.js
+//#region ../../node_modules/.pnpm/react-router@8.3.0_react-dom@19.2.8_react@19.2.8__react@19.2.8/node_modules/react-router/dist/production/lib/dom/server.js
 /**
 * react-router v8.3.0
 *

package/docs.schema.json

@@ -807,7 +807,7 @@
       "properties": {
         "glob": {
           "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }],
-          "description": "Glob relative to contentDir. Matching Markdown and MDX files are expanded into page entries."
+          "description": "Glob relative to contentDir. Matching Markdown and MDX files are expanded into page entries; explicit page references take precedence."
         },
         "exclude": {
           "anyOf": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umami/shiso",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "description": "Open-source documentation framework for Markdown and MDX sites.",
   "type": "module",
   "bin": {
@@ -83,6 +83,7 @@
     "github-slugger": "^2.0.0",
     "jiti": "^2.4.0",
     "lucide-react": "^1.28.0",
+    "mermaid": "^11.17.2",
     "react-router": "^8.3.0",
     "rehype-autolink-headings": "^7.1.0",
     "rehype-slug": "^6.0.0",

package/scripts/expand-navigation-globs.mjs

@@ -111,12 +111,47 @@ function pageCandidate(contentRoot, filePath) {
   return { filePath, relativeFile, fileSlug };
 }
 
+function normalizePageReference(value) {
+  return String(value || '')
+    .trim()
+    .replace(/\\/g, '/')
+    .replace(/^\/+/, '')
+    .replace(/^docs\//, '')
+    .replace(/\.mdx?$/i, '')
+    .replace(/\/+$/, '');
+}
+
+/** Collects manual page references without crossing a version/language scope boundary. */
+function collectExplicitPages(value, pages = new Set()) {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      if (typeof item === 'string') {
+        pages.add(normalizePageReference(item));
+      } else {
+        collectExplicitPages(item, pages);
+      }
+    }
+    return pages;
+  }
+
+  if (!value || typeof value !== 'object' || isGlobItem(value)) return pages;
+
+  if (typeof value.page === 'string') pages.add(normalizePageReference(value.page));
+  if (typeof value.root === 'string') pages.add(normalizePageReference(value.root));
+
+  for (const key of ['pages', 'groups', 'tabs', 'dropdowns']) {
+    if (Array.isArray(value[key])) collectExplicitPages(value[key], pages);
+  }
+
+  return pages;
+}
+
 function matches(candidate, pattern) {
   const target = /\.mdx?$/i.test(pattern) ? candidate.relativeFile : candidate.fileSlug;
   return globRegex(pattern).test(target);
 }
 
-async function expandGlob(item, candidates, projectRoot) {
+async function expandGlob(item, candidates, projectRoot, explicitPages) {
   assertGlobItem(item);
   const pattern = globPattern(item.glob);
   const exclusions = (item.exclude || []).map(globPattern);
@@ -129,8 +164,12 @@ async function expandGlob(item, candidates, projectRoot) {
     throw new Error(`Navigation glob "${pattern}" matched no Markdown or MDX files.`);
   }
 
+  // Manual entries own their page's placement and presentation, regardless of
+  // whether they appear before or after the glob that would otherwise include it.
+  const discovered = matched.filter(candidate => !explicitPages.has(candidate.fileSlug));
+
   const entries = await Promise.all(
-    matched.map(async candidate => {
+    discovered.map(async candidate => {
       const source = await fs.readFile(candidate.filePath, 'utf8');
       const sourcePath = path.relative(projectRoot, candidate.filePath).replace(/\\/g, '/');
       const frontmatter = navigationFrontmatter(source, sourcePath);
@@ -181,8 +220,10 @@ export async function expandNavigationGlobs(config, { root, contentDir }) {
     );
   }
 
-  async function expandObject(value) {
-    if (Array.isArray(value)) return Promise.all(value.map(expandObject));
+  async function expandObject(value, explicitPages) {
+    if (Array.isArray(value)) {
+      return Promise.all(value.map(item => expandObject(item, explicitPages)));
+    }
     if (!value || typeof value !== 'object') return value;
 
     const entries = await Promise.all(
@@ -191,18 +232,46 @@ export async function expandNavigationGlobs(config, { root, contentDir }) {
           const expanded = [];
           for (const item of child) {
             if (isGlobItem(item)) {
-              expanded.push(...(await expandGlob(item, candidates, projectRoot)));
+              expanded.push(...(await expandGlob(item, candidates, projectRoot, explicitPages)));
             } else {
-              expanded.push(await expandObject(item));
+              expanded.push(await expandObject(item, explicitPages));
             }
           }
           return [key, expanded];
         }
-        return [key, await expandObject(child)];
+        return [key, await expandObject(child, explicitPages)];
       }),
     );
     return Object.fromEntries(entries);
   }
 
-  return { ...config, navigation: await expandObject(config.navigation) };
+  async function expandScope(scope) {
+    return expandObject(scope, collectExplicitPages(scope));
+  }
+
+  async function expandNavigation(navigation) {
+    if (Array.isArray(navigation.languages)) {
+      const languages = await Promise.all(
+        navigation.languages.map(async language => {
+          if (!Array.isArray(language.versions)) return expandScope(language);
+          return {
+            ...language,
+            versions: await Promise.all(language.versions.map(expandScope)),
+          };
+        }),
+      );
+      return { ...navigation, languages };
+    }
+
+    if (Array.isArray(navigation.versions)) {
+      return {
+        ...navigation,
+        versions: await Promise.all(navigation.versions.map(expandScope)),
+      };
+    }
+
+    return expandScope(navigation);
+  }
+
+  return { ...config, navigation: await expandNavigation(config.navigation) };
 }

package/scripts/lib/openapi.mjs

@@ -588,13 +588,26 @@ export function hasOperationParameters(operation) {
   );
 }
 
+function operationParameterSections(operation) {
+  return [
+    { location: 'header', heading: 'Headers', id: 'headers' },
+    { location: 'path', heading: 'Path parameters', id: 'path-parameters' },
+    { location: 'query', heading: 'Query parameters', id: 'query-parameters' },
+    { location: 'cookie', heading: 'Cookie parameters', id: 'cookie-parameters' },
+  ].filter(
+    ({ location }) =>
+      operation.parameters[location].length > 0 ||
+      (location === 'header' && operation.security.length > 0),
+  );
+}
+
 /**
  * Anchor ids for the generated sections, in render order. Mirrors
  * operationSections in src/lib/openapi.ts (asserted by tests/openapi.test.mjs).
  */
 export function operationAnchors(operation) {
   return [
-    ...(hasOperationParameters(operation) ? ['parameters'] : []),
+    ...operationParameterSections(operation).map(section => section.id),
     ...(operation.requestBody ? ['request-body'] : []),
     ...(operation.responses.length ? ['responses'] : []),
     ...(operation.samples.length ? ['code-samples'] : []),
@@ -617,13 +630,6 @@ export function normalizeOperationKey(value) {
 
 /** Search-index sections for an operation, matching operationAnchors ids. */
 export function operationSearchSections(operation) {
-  const allParameters = [
-    ...operation.parameters.path,
-    ...operation.parameters.query,
-    ...operation.parameters.header,
-    ...operation.parameters.cookie,
-  ];
-
   return [
     {
       heading: undefined,
@@ -632,11 +638,16 @@ export function operationSearchSections(operation) {
         .filter(Boolean)
         .join(' '),
     },
-    {
-      heading: 'Parameters',
-      id: 'parameters',
-      text: allParameters.map(schemaText).join(' '),
-    },
+    ...operationParameterSections(operation).map(({ location, heading, id }) => ({
+      heading,
+      id,
+      text: [
+        ...operation.parameters[location].map(schemaText),
+        ...(location === 'header' && operation.security.length > 0
+          ? ['Authorization Authentication credentials']
+          : []),
+      ].join(' '),
+    })),
     {
       heading: 'Request body',
       id: 'request-body',

package/src/components/CodeBlock.tsx

@@ -1,8 +1,10 @@
+import type { ReactNode } from 'react';
 import { type ComponentProps, type CSSProperties, useRef, useState } from 'react';
 import { CheckIcon, Copy } from '@/components/icons';
 import { Button } from '@/components/ui/button';
 import { ScrollArea } from '@/components/ui/scroll-area';
 import { cn } from '@/lib/utils';
+import { Mermaid, type MermaidPlacement } from './docs/Mermaid';
 
 /**
  * Renders a fenced code block. The `data-*` props are produced at build time by
@@ -15,6 +17,25 @@ export interface CodeBlockProps extends ComponentProps<'pre'> {
   'data-line-start'?: string;
   'data-line-count'?: string;
   'data-diff-markers'?: string;
+  'data-placement'?: MermaidPlacement;
+  'data-actions'?: string;
+}
+
+function reactChildrenToText(node: ReactNode): string {
+  if (typeof node === 'string' || typeof node === 'number') {
+    return String(node);
+  }
+  if (Array.isArray(node)) {
+    return node.map(reactChildrenToText).join('');
+  }
+  if (node && typeof node === 'object' && 'props' in (node as object)) {
+    const props = (node as { props?: { children?: ReactNode; value?: unknown } }).props;
+    if (typeof props?.value === 'string') {
+      return props.value;
+    }
+    return reactChildrenToText(props?.children);
+  }
+  return '';
 }
 
 /**
@@ -44,11 +65,26 @@ export function CodeBlock({ children, className, style, ...rest }: CodeBlockProp
     'data-language': language,
     'data-line-start': lineStart,
     'data-line-count': lineCount,
+    'data-placement': placement,
+    'data-actions': actions,
     ...preProps
   } = rest;
   const textInput = useRef<HTMLPreElement>(null);
   const [copied, setCopied] = useState(false);
 
+  // ```mermaid fences render as diagrams; the raw definition stays in the
+  // markup for search indexing and no-JS fallbacks.
+  if (language === 'mermaid') {
+    return (
+      <Mermaid
+        chart={reactChildrenToText(children).replace(/\n$/, '')}
+        title={title}
+        placement={placement}
+        actions={actions === undefined ? undefined : actions !== 'false'}
+      />
+    );
+  }
+
   const start = Number(lineStart) || 1;
   const lastLine = start + Math.max(Number(lineCount) || 1, 1) - 1;
   const gutter = `${String(lastLine).length}ch`;

package/src/components/Docs.tsx

@@ -1,6 +1,7 @@
 import { useEffect, useState } from 'react';
 import { useLocation, useNavigate } from 'react-router';
 import { DocContent } from '@/components/DocContent';
+import { PanelProvider, usePanelContent } from '@/components/docs/panel-context';
 import { Footer } from '@/components/Footer';
 import { Menu } from '@/components/icons';
 import { LanguageSwitcher } from '@/components/LanguageSwitcher';
@@ -13,7 +14,7 @@ import { VersionSwitcher } from '@/components/VersionSwitcher';
 import { renderInlineMarkdown } from '@/lib/inline-markdown';
 import { getOperation, operationSections } from '@/lib/openapi';
 import { docsHomeUrl, getScopeByPathname } from '@/lib/site-config';
-import type { DocModule, NormalizedDocsPage, SiteModel } from '@/lib/types';
+import type { DocModule, NormalizedDocsPage, SiteModel, TocEntry } from '@/lib/types';
 
 /**
  * 404 view driven by the `errors.404` config key. The standard defaults to
@@ -46,11 +47,46 @@ export interface DocsProps {
 }
 
 export function Docs({ page, doc, site }: DocsProps) {
+  if (!page || !doc) {
+    return (
+      <div className="flex min-h-full flex-col">
+        <div className="grow">
+          <NotFound site={site} />
+        </div>
+        <Footer footer={site.footer} />
+      </div>
+    );
+  }
+
+  // API reference pages append their generated section anchors to the TOC.
+  const operation = getOperation(doc.frontmatter?.openapi);
+  const toc = operation ? [...(doc.toc || []), ...operationSections(operation)] : doc.toc;
+
+  return (
+    <PanelProvider>
+      <DocsBody page={page} doc={doc} site={site} toc={toc} />
+    </PanelProvider>
+  );
+}
+
+function DocsBody({
+  page,
+  doc,
+  site,
+  toc,
+}: {
+  page: NormalizedDocsPage;
+  doc: DocModule;
+  site: SiteModel;
+  toc: TocEntry[] | undefined;
+}) {
   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;
+  // A <Panel> in the page replaces the table of contents in the right rail.
+  const panel = usePanelContent();
 
   // Close the mobile menu and start each newly loaded page at the top. Hash
   // links keep their native section-scrolling behavior.
@@ -62,21 +98,6 @@ export function Docs({ page, doc, site }: DocsProps) {
     }
   }, [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>
-    );
-  }
-
-  // API reference pages append their generated section anchors to the TOC.
-  const operation = getOperation(doc.frontmatter?.openapi);
-  const toc = operation ? [...(doc.toc || []), ...operationSections(operation)] : doc.toc;
-
   return (
     <div className="flex min-h-full flex-col gap-6 lg:gap-0">
       <Sheet open={menuOpen} onOpenChange={setMenuOpen}>
@@ -128,11 +149,13 @@ export function Docs({ page, doc, site }: DocsProps) {
           <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={toc}
-                title={site.labels.tableOfContents}
-                navigationLabel={site.labels.tableOfContentsNavigation}
-              />
+              {panel ?? (
+                <PageLinks
+                  items={toc}
+                  title={site.labels.tableOfContents}
+                  navigationLabel={site.labels.tableOfContentsNavigation}
+                />
+              )}
             </div>
           </div>
           <Footer footer={site.footer} className="lg:mr-72" />

package/src/components/OpenApiOperation.tsx

@@ -2,15 +2,10 @@ import { CodeBlock } from '@/components/CodeBlock';
 import { Badge } from '@/components/docs/Badge';
 import { CodeGroup } from '@/components/docs/CodeGroup';
 import { Expandable } from '@/components/docs/Expandable';
-import { ParamField } from '@/components/docs/ParamField';
-import { ResponseField } from '@/components/docs/ResponseField';
-import { operationSections, statusColor } from '@/lib/openapi';
+import { PropertiesTable } from '@/components/docs/PropertiesTable';
+import { operationParameterSections, operationSections, statusColor } from '@/lib/openapi';
 import type { NormalizedOperation, SchemaNode } from '@/lib/types';
 
-type ParamLocation = 'path' | 'query' | 'header' | 'cookie';
-
-const PARAM_LOCATIONS: ParamLocation[] = ['path', 'query', 'header', 'cookie'];
-
 function FieldChildren({ node }: { node: SchemaNode }) {
   return (
     <>
@@ -28,42 +23,35 @@ function FieldChildren({ node }: { node: SchemaNode }) {
       )}
       {node.children && node.children.length > 0 && (
         <Expandable title="properties">
-          {node.children.map(child => (
-            <SchemaField key={child.name || child.type} node={child} />
-          ))}
+          <SchemaTable nodes={node.children} />
         </Expandable>
       )}
     </>
   );
 }
 
-function SchemaField({ node }: { node: SchemaNode }) {
+function SchemaTable({ nodes }: { nodes: SchemaNode[] }) {
   return (
-    <ResponseField
-      name={node.name || node.type}
-      type={node.name ? node.type : undefined}
-      required={node.required}
-      deprecated={node.deprecated}
-      default={node.default}
-    >
-      <FieldChildren node={node} />
-    </ResponseField>
+    <PropertiesTable>
+      {nodes.map(node => (
+        <PropertiesTable.Row
+          key={node.name || node.type}
+          name={node.name || node.type}
+          type={node.type}
+          required={node.required}
+          deprecated={node.deprecated}
+          default={node.default}
+        >
+          <FieldChildren node={node} />
+        </PropertiesTable.Row>
+      ))}
+    </PropertiesTable>
   );
 }
 
 /** Renders a schema tree: a root object's properties, or the node itself. */
 function SchemaFields({ node }: { node: SchemaNode }) {
-  if (!node.name && node.children?.length) {
-    return (
-      <>
-        {node.children.map(child => (
-          <SchemaField key={child.name || child.type} node={child} />
-        ))}
-      </>
-    );
-  }
-
-  return <SchemaField node={node} />;
+  return <SchemaTable nodes={!node.name && node.children?.length ? node.children : [node]} />;
 }
 
 function HighlightedCode({
@@ -107,34 +95,33 @@ export interface OpenApiOperationProps {
 /** The generated reference for one API operation, rendered under the page body. */
 export function OpenApiOperation({ operation }: OpenApiOperationProps) {
   const sections = new Map(operationSections(operation).map(entry => [entry.name, entry.id]));
-  const showParameters = sections.has('Parameters');
 
   return (
     <div className="docs-markdown">
-      {showParameters && (
-        <section>
-          <h2 id={sections.get('Parameters')}>Parameters</h2>
-          {operation.security.length > 0 && (
-            <ParamField header="Authorization" type="string" required>
-              Authentication credentials, e.g. <code>Bearer &lt;token&gt;</code> (
-              {operation.security.join(', ')}).
-            </ParamField>
-          )}
-          {PARAM_LOCATIONS.map(location =>
-            operation.parameters[location].map(parameter => (
-              <ParamField
-                key={`${location}-${parameter.name}`}
-                {...{ [location]: parameter.name }}
+      {operationParameterSections(operation).map(({ location, name }) => (
+        <section key={location}>
+          <h2 id={sections.get(name)}>{name}</h2>
+          <PropertiesTable>
+            {location === 'header' && operation.security.length > 0 && (
+              <PropertiesTable.Row name="Authorization" type="string" required>
+                Authentication credentials, e.g. <code>Bearer &lt;token&gt;</code>.
+              </PropertiesTable.Row>
+            )}
+            {operation.parameters[location].map(parameter => (
+              <PropertiesTable.Row
+                key={parameter.name}
+                name={parameter.name || parameter.type}
                 type={parameter.type}
                 required={parameter.required}
+                deprecated={parameter.deprecated}
+                default={parameter.default}
               >
-                <FieldChildren node={{ ...parameter, name: undefined, description: undefined }} />
-                {parameter.description}
-              </ParamField>
-            )),
-          )}
+                <FieldChildren node={parameter} />
+              </PropertiesTable.Row>
+            ))}
+          </PropertiesTable>
         </section>
-      )}
+      ))}
       {operation.requestBody && (
         <section>
           <h2 id={sections.get('Request body')}>Request body</h2>

package/src/components/SideNav.tsx

@@ -275,12 +275,17 @@ function NavNodes({
           )}
         >
           {resolveIcon(icon)}
-          {label}
           {method ? (
-            <MethodBadge color={methodColor(method)} size="xs" className="ml-auto font-mono">
+            <MethodBadge
+              color={methodColor(method)}
+              size="xs"
+              className="w-10 shrink-0 justify-center whitespace-nowrap font-mono"
+            >
               {method === 'DELETE' ? 'DEL' : method}
             </MethodBadge>
-          ) : tag ? (
+          ) : null}
+          {label}
+          {!method && tag ? (
             <Badge
               variant="secondary"
               className="ml-auto h-auto rounded-sm px-[0.35rem] py-[0.05rem] text-[0.7rem] text-muted-foreground uppercase"