@umami/shiso 1.11.0 → 1.13.0

package/src/components/OpenApiOperation.tsx

@@ -0,0 +1,205 @@
+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 { styles } from '@/components/docs/styles';
+import { 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 (
+    <>
+      {node.description}
+      {node.enum && node.enum.length > 0 && (
+        <div className="mt-1">
+          Options:{' '}
+          {node.enum.map((value, index) => (
+            <span key={value}>
+              {index > 0 && ', '}
+              <code>{value}</code>
+            </span>
+          ))}
+        </div>
+      )}
+      {node.children && node.children.length > 0 && (
+        <Expandable title="properties">
+          {node.children.map(child => (
+            <SchemaField key={child.name || child.type} node={child} />
+          ))}
+        </Expandable>
+      )}
+    </>
+  );
+}
+
+function SchemaField({ node }: { node: SchemaNode }) {
+  const hasDetails = Boolean(node.description || node.enum?.length || node.children?.length);
+
+  return (
+    <ResponseField
+      name={node.name || node.type}
+      type={node.name ? node.type : undefined}
+      required={node.required}
+      deprecated={node.deprecated}
+      default={node.default}
+    >
+      {hasDetails ? <FieldChildren node={node} /> : null}
+    </ResponseField>
+  );
+}
+
+/** 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} />;
+}
+
+function HighlightedCode({
+  language,
+  title,
+  html,
+  source,
+  lineCount,
+}: {
+  language: string;
+  title?: string;
+  html?: string;
+  source: string;
+  lineCount?: number;
+}) {
+  return (
+    <CodeBlock
+      data-language={language}
+      data-title={title}
+      data-line-count={lineCount ? String(lineCount) : undefined}
+    >
+      {html ? (
+        // Highlighted at build time by the openapi generator; same markup as
+        // the rehype-shiki pipeline produces for fenced code blocks.
+        <code
+          className={`language-${language}`}
+          // biome-ignore lint/security/noDangerouslySetInnerHtml: build-time generated markup from the project's own OpenAPI spec.
+          dangerouslySetInnerHTML={{ __html: html }}
+        />
+      ) : (
+        <code className={`language-${language}`}>{source}</code>
+      )}
+    </CodeBlock>
+  );
+}
+
+export interface OpenApiOperationProps {
+  operation: NormalizedOperation;
+}
+
+/** 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>
+          <div className={styles.fieldGroup}>
+            {operation.security.length > 0 && (
+              <ParamField header="Authorization" type="string" required>
+                Authentication credentials, e.g. <code>Bearer &lt;token&gt;</code>.
+              </ParamField>
+            )}
+            {PARAM_LOCATIONS.map(location =>
+              operation.parameters[location].map(parameter => (
+                <ParamField
+                  key={`${location}-${parameter.name}`}
+                  {...{ [location]: parameter.name }}
+                  type={parameter.type}
+                  required={parameter.required}
+                >
+                  <FieldChildren node={{ ...parameter, name: undefined, description: undefined }} />
+                  {parameter.description}
+                </ParamField>
+              )),
+            )}
+          </div>
+        </section>
+      )}
+      {operation.requestBody && (
+        <section>
+          <h2 id={sections.get('Request body')}>Request body</h2>
+          <SchemaFields node={operation.requestBody.schema} />
+          {operation.requestBody.example && (
+            <HighlightedCode
+              language="json"
+              title="Example request"
+              html={operation.requestBody.exampleHtml}
+              source={operation.requestBody.example}
+            />
+          )}
+        </section>
+      )}
+      {operation.responses.length > 0 && (
+        <section>
+          <h2 id={sections.get('Responses')}>Responses</h2>
+          {operation.responses.map(response => (
+            <div key={response.status} className="mt-6 first:mt-0">
+              <div className="flex items-center gap-2">
+                <Badge color={statusColor(response.status)} size="sm">
+                  {response.status}
+                </Badge>
+                {response.description && (
+                  <span className="text-muted-foreground text-sm">{response.description}</span>
+                )}
+              </div>
+              {response.schema && (
+                <div className={styles.fieldGroup}>
+                  <SchemaFields node={response.schema} />
+                </div>
+              )}
+              {response.example && (
+                <HighlightedCode
+                  language="json"
+                  title={`${response.status} example`}
+                  html={response.exampleHtml}
+                  source={response.example}
+                />
+              )}
+            </div>
+          ))}
+        </section>
+      )}
+      {operation.samples.length > 0 && (
+        <section>
+          <h2 id={sections.get('Code samples')}>Code samples</h2>
+          <CodeGroup>
+            {operation.samples.map(sample => (
+              <HighlightedCode
+                key={sample.language}
+                language={sample.language}
+                title={sample.label}
+                html={sample.html}
+                source={sample.source}
+                lineCount={sample.lineCount}
+              />
+            ))}
+          </CodeGroup>
+        </section>
+      )}
+    </div>
+  );
+}

package/src/components/SideNav.tsx

@@ -1,5 +1,6 @@
 import { type ReactNode, useEffect, useState } from 'react';
 import { Link, useLocation, useNavigate } from 'react-router';
+import { Badge as MethodBadge } from '@/components/docs/Badge';
 import { resolveIcon } from '@/components/docs/utils';
 import { ChevronRight, ExternalLink } from '@/components/icons';
 import { Badge } from '@/components/ui/badge';
@@ -7,6 +8,7 @@ import { Button } from '@/components/ui/button';
 import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@/components/ui/collapsible';
 import { ScrollArea } from '@/components/ui/scroll-area';
 import { flattenNav, isNodeHidden } from '@/lib/docs-config';
+import { methodColor } from '@/lib/openapi';
 import type { DocsTab, NavGroupNode, NavNode } from '@/lib/types';
 import { cn } from '@/lib/utils';
 
@@ -256,7 +258,7 @@ function NavNodes({
     }
 
     if (node.kind === 'page') {
-      const { url, label, icon, tag } = node.page;
+      const { url, label, icon, tag, method } = node.page;
       const isSelected = url === pathname;
 
       rendered.push(
@@ -273,8 +275,17 @@ function NavNodes({
           )}
         >
           {resolveIcon(icon)}
+          {method ? (
+            <MethodBadge
+              color={methodColor(method)}
+              size="xs"
+              className="w-10 shrink-0 justify-center whitespace-nowrap font-mono"
+            >
+              {method === 'DELETE' ? 'DEL' : method}
+            </MethodBadge>
+          ) : null}
           {label}
-          {tag ? (
+          {!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"

package/src/components/docs/Changelog.tsx

@@ -0,0 +1,163 @@
+import { Children, Fragment, isValidElement, type ReactElement, useMemo } from 'react';
+import { useSearchParams } from 'react-router';
+import { Badge } from './Badge';
+import { styles } from './styles';
+import { Update } from './Update';
+
+export interface ChangelogProps {
+  children?: React.ReactNode;
+}
+
+interface UpdateChildInfo {
+  key: string;
+  tags: string[];
+}
+
+/** Flattens fragments so <Update> entries are found however MDX nests them. */
+function flatElements(children: React.ReactNode): ReactElement<{ tags?: unknown }>[] {
+  const flat: ReactElement<{ tags?: unknown }>[] = [];
+
+  Children.forEach(children, child => {
+    if (!isValidElement<{ tags?: unknown }>(child)) {
+      return;
+    }
+    if (child.type === Fragment) {
+      flat.push(...flatElements(child.props.children));
+    } else {
+      flat.push(child);
+    }
+  });
+
+  return flat;
+}
+
+/** Reads `tags` off <Update> children without rendering them. */
+function updateInfo(children: React.ReactNode): Map<string, UpdateChildInfo> {
+  const info = new Map<string, UpdateChildInfo>();
+
+  flatElements(children).forEach((child, index) => {
+    if (child.type !== Update) {
+      return;
+    }
+
+    const key = String(child.key ?? `update-${index}`);
+    const raw = child.props.tags;
+    const tags = Array.isArray(raw)
+      ? [...new Set(raw.filter((tag): tag is string => typeof tag === 'string' && tag.trim()))].map(
+          tag => tag.trim(),
+        )
+      : [];
+    info.set(key, { key, tags });
+  });
+
+  return info;
+}
+
+/**
+ * Groups <Update> entries with Mintlify-style tag filtering.
+ * Selected tags sync to `?tags=a,b` so filtered views are shareable.
+ * Pages without any tagged updates render as a plain list.
+ */
+export function Changelog({ children }: ChangelogProps) {
+  const [searchParams, setSearchParams] = useSearchParams();
+
+  const allTags = useMemo(() => {
+    const seen = new Map<string, string>();
+    for (const { tags } of updateInfo(children).values()) {
+      for (const tag of tags) {
+        const key = tag.toLowerCase();
+        if (!seen.has(key)) {
+          seen.set(key, tag);
+        }
+      }
+    }
+    return [...seen.values()];
+  }, [children]);
+
+  const selected = useMemo(() => {
+    const param = searchParams.get('tags');
+    if (!param) {
+      return [];
+    }
+    const wanted = new Set(
+      param
+        .split(',')
+        .map(tag => tag.trim().toLowerCase())
+        .filter(Boolean),
+    );
+    return allTags.filter(tag => wanted.has(tag.toLowerCase()));
+  }, [searchParams, allTags]);
+
+  const infoByKey = useMemo(() => updateInfo(children), [children]);
+
+  if (allTags.length === 0) {
+    return <div className={styles.changelog}>{children}</div>;
+  }
+
+  const toggle = (tag: string) => {
+    const lower = tag.toLowerCase();
+    const next = selected.some(item => item.toLowerCase() === lower)
+      ? selected.filter(item => item.toLowerCase() !== lower)
+      : [...selected, tag];
+
+    setSearchParams(next.length ? { tags: next.join(',') } : {}, { preventScrollReset: true });
+  };
+
+  const clear = () => {
+    setSearchParams({}, { preventScrollReset: true });
+  };
+
+  const selectedSet = new Set(selected.map(tag => tag.toLowerCase()));
+
+  const filtered = flatElements(children).map((child, index) => {
+    if (child.type !== Update) {
+      return child;
+    }
+    const key = String(child.key ?? `update-${index}`);
+    const tags = infoByKey.get(key)?.tags ?? [];
+    if (selectedSet.size === 0) {
+      return child;
+    }
+    const lower = tags.map(tag => tag.toLowerCase());
+    const matches = [...selectedSet].every(tag => lower.includes(tag));
+    return matches ? child : null;
+  });
+
+  const visibleUpdates = filtered.filter(
+    child => child && (child as React.ReactElement).type === Update,
+  ).length;
+
+  return (
+    <div className={styles.changelog}>
+      {/* biome-ignore lint/a11y/useSemanticElements: toggle-button group labelled for the filter */}
+      <div className={styles.changelogFilters} role="group" aria-label="Filter updates by tag">
+        {allTags.map(tag => {
+          const active = selectedSet.has(tag.toLowerCase());
+          return (
+            <button
+              key={tag}
+              type="button"
+              onClick={() => toggle(tag)}
+              aria-pressed={active}
+              className={styles.changelogFilterButton}
+              data-active={active ? '' : undefined}
+            >
+              <Badge size="sm" color={active ? 'primary' : undefined}>
+                {tag}
+              </Badge>
+            </button>
+          );
+        })}
+        {selected.length > 0 ? (
+          <button type="button" onClick={clear} className={styles.changelogClear}>
+            Clear
+          </button>
+        ) : null}
+      </div>
+      {visibleUpdates === 0 ? (
+        <p className={styles.changelogEmpty}>No updates match the selected tags.</p>
+      ) : null}
+      {filtered}
+    </div>
+  );
+}

package/src/components/docs/CodeGroup.tsx

@@ -39,14 +39,18 @@ export function CodeGroup({ children }: CodeGroupProps) {
   }
 
   if (blocks.length === 1) {
-    return <div className={styles.tabs}>{blocks[0].content}</div>;
+    return (
+      <div className={`${styles.tabs} [&_[data-slot=code-block-header]]:hidden`}>
+        {blocks[0].content}
+      </div>
+    );
   }
 
   return (
     <TabsPrimitive
       value={selected}
       onValueChange={setSelectedKey}
-      className="my-4 gap-0 overflow-hidden rounded-lg bg-card [&_[data-slot=code-block]]:my-0 [&_[data-slot=code-block]]:rounded-none [&_[data-slot=code-block]]:border-0 [&_[data-slot=code-block]]:bg-transparent"
+      className="my-4 gap-0 overflow-hidden rounded-lg bg-card [&_[data-slot=code-block]]:my-0 [&_[data-slot=code-block]]:rounded-none [&_[data-slot=code-block]]:border-0 [&_[data-slot=code-block]]:bg-transparent [&_[data-slot=code-block-header]]:hidden"
     >
       <TabsList
         variant="line"

package/src/components/docs/Mermaid.tsx

@@ -0,0 +1,164 @@
+import { type ReactNode, useEffect, useId, useRef, useState } from 'react';
+import { styles } from './styles';
+
+export type MermaidPlacement = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
+export interface MermaidProps {
+  /** Diagram definition. Falls back to string children when omitted. */
+  chart?: string;
+  title?: ReactNode;
+  /**
+   * Show zoom/pan/reset controls. Defaults to true when the diagram exceeds
+   * 120px in height (Mintlify behavior). Pass false to hide.
+   */
+  actions?: boolean;
+  /** Corner for the controls. Defaults to "bottom-right". */
+  placement?: MermaidPlacement;
+  children?: ReactNode;
+}
+
+function childrenToText(node: ReactNode): string {
+  if (typeof node === 'string' || typeof node === 'number') {
+    return String(node);
+  }
+  if (Array.isArray(node)) {
+    return node.map(childrenToText).join('');
+  }
+  if (node && typeof node === 'object' && 'props' in (node as object)) {
+    const props = (node as { props?: { children?: ReactNode } }).props;
+    return childrenToText(props?.children);
+  }
+  return '';
+}
+
+/** Extracts raw diagram source from MDX children (string or <code> element). */
+export function mermaidSource(chart: string | undefined, children: ReactNode): string {
+  const raw = typeof chart === 'string' && chart.trim() ? chart : childrenToText(children);
+  return raw.replace(/^\n+|\n+$/g, '').replace(/\\n$/, '');
+}
+
+function isDarkMode(): boolean {
+  if (typeof document === 'undefined') {
+    return false;
+  }
+  return document.documentElement.classList.contains('dark');
+}
+
+const PLACEMENT_CLASS: Record<MermaidPlacement, string> = {
+  'top-left': 'top-2 left-2',
+  'top-right': 'top-2 right-2',
+  'bottom-left': 'bottom-2 left-2',
+  'bottom-right': 'bottom-2 right-2',
+};
+
+/**
+ * Renders a Mermaid diagram. Server/prerender output is the raw definition in
+ * a <pre> so search indexing and no-JS still see the content; the client
+ * replaces it with SVG via a lazy `mermaid` import (kept out of the SSR bundle).
+ */
+export function Mermaid({
+  chart,
+  title,
+  actions,
+  placement = 'bottom-right',
+  children,
+}: MermaidProps) {
+  const source = mermaidSource(chart, children);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const svgHostRef = useRef<HTMLDivElement>(null);
+  const diagramId = useId().replace(/[^a-zA-Z0-9]/g, '');
+  const [svg, setSvg] = useState<string | null>(null);
+  const [error, setError] = useState(false);
+  const [zoom, setZoom] = useState(1);
+  const [dark, setDark] = useState(false);
+
+  useEffect(() => {
+    setDark(isDarkMode());
+    const observer = new MutationObserver(() => setDark(isDarkMode()));
+    observer.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] });
+    return () => observer.disconnect();
+  }, []);
+
+  useEffect(() => {
+    if (!source.trim() || typeof window === 'undefined') {
+      return;
+    }
+
+    let cancelled = false;
+    setError(false);
+    setSvg(null);
+    (async () => {
+      try {
+        const { default: mermaid } = await import('mermaid');
+        if (cancelled) {
+          return;
+        }
+        mermaid.initialize({
+          startOnLoad: false,
+          theme: dark ? 'dark' : 'neutral',
+          securityLevel: 'strict',
+        });
+        const { svg: rendered } = await mermaid.render(`shiso-mermaid-${diagramId}`, source);
+        if (!cancelled) {
+          setSvg(rendered);
+        }
+      } catch {
+        if (!cancelled) {
+          setError(true);
+        }
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [source, diagramId, dark]);
+
+  // Pan is native scroll; zoom controls scale the SVG host.
+  const showControls = actions ?? true;
+
+  return (
+    <figure className={styles.mermaid} data-dark={dark ? '' : undefined}>
+      {title ? <figcaption className={styles.mermaidTitle}>{title}</figcaption> : null}
+      <div ref={containerRef} className={styles.mermaidViewport}>
+        {svg && !error ? (
+          <div
+            ref={svgHostRef}
+            className={styles.mermaidSvg}
+            style={{ transform: `scale(${zoom})` }}
+            // biome-ignore lint/security/noDangerouslySetInnerHtml: mermaid generates this SVG from the page's own diagram source.
+            dangerouslySetInnerHTML={{ __html: svg }}
+            role="img"
+            aria-label={title ? String(title) : 'Diagram'}
+          />
+        ) : (
+          <pre className={styles.mermaidFallback} title="Diagram source">
+            {source}
+          </pre>
+        )}
+        {error ? <p className={styles.mermaidError}>Could not render this diagram.</p> : null}
+        {showControls && svg && !error ? (
+          <div className={`${styles.mermaidControls} ${PLACEMENT_CLASS[placement]}`}>
+            <button
+              type="button"
+              aria-label="Zoom out"
+              onClick={() => setZoom(z => Math.max(0.5, +(z - 0.25).toFixed(2)))}
+            >
+              −
+            </button>
+            <button type="button" aria-label="Reset view" onClick={() => setZoom(1)}>
+              ⟳
+            </button>
+            <button
+              type="button"
+              aria-label="Zoom in"
+              onClick={() => setZoom(z => Math.min(2.5, +(z + 0.25).toFixed(2)))}
+            >
+              +
+            </button>
+          </div>
+        ) : null}
+      </div>
+    </figure>
+  );
+}

package/src/components/docs/Panel.tsx

@@ -0,0 +1,23 @@
+import { type ReactNode, useEffect } from 'react';
+import { useSetPanelContent } from './panel-context';
+import { styles } from './styles';
+
+export interface PanelProps {
+  children?: ReactNode;
+}
+
+/**
+ * Pins supplementary content to the right rail (replacing the table of
+ * contents on desktop). On small screens the content renders inline where it
+ * is written. Only one Panel per page is supported; the last one wins.
+ */
+export function Panel({ children }: PanelProps) {
+  const setContent = useSetPanelContent();
+
+  useEffect(() => {
+    setContent(children ? <div className={styles.panel}>{children}</div> : null);
+    return () => setContent(null);
+  }, [children, setContent]);
+
+  return <div className={styles.panelInline}>{children}</div>;
+}

package/src/components/docs/ParamField.tsx

@@ -28,14 +28,26 @@ export function ParamField({
   const location = query ? 'query' : path ? 'path' : header ? 'header' : body ? 'body' : undefined;
 
   return (
-    <div className={styles.paramField}>
+    <div className={styles.paramField} data-slot="field-group-item">
       <div className={styles.fieldHeader}>
         <span className={styles.fieldName}>{label}</span>
-        {location ? <Badge>{location}</Badge> : null}
-        {type ? <span className={styles.fieldType}>{decodeHtmlEntities(type)}</span> : null}
-        {required ? <Badge tone="primary">required</Badge> : null}
+        {location ? <Badge size="sm">{location}</Badge> : null}
+        {type ? (
+          <span className={styles.fieldType} data-slot="field-group-type">
+            {decodeHtmlEntities(type)}
+          </span>
+        ) : null}
+        {required ? (
+          <Badge size="sm" tone="primary">
+            required
+          </Badge>
+        ) : null}
       </div>
-      {children ? <div className={styles.fieldBody}>{children}</div> : null}
+      {children ? (
+        <div className={styles.fieldBody} data-slot="field-group-body">
+          {children}
+        </div>
+      ) : null}
     </div>
   );
 }

package/src/components/docs/PropertiesTable.tsx

@@ -45,11 +45,11 @@ export function PropertiesTable({ children }: PropertiesTableProps) {
                   <span className="inline-flex flex-wrap items-center gap-2">
                     {name}
                     {required ? (
-                      <Badge size="xs" tone="primary">
+                      <Badge size="sm" tone="primary">
                         required
                       </Badge>
                     ) : null}
-                    {deprecated ? <Badge size="xs">deprecated</Badge> : null}
+                    {deprecated ? <Badge size="sm">deprecated</Badge> : null}
                   </span>
                 </td>
                 <td>{displayValue(type)}</td>