@umami/shiso 1.12.0 → 1.13.0

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>

package/src/components/docs/ResponseField.tsx

@@ -23,14 +23,26 @@ export function ResponseField({ name, type, required, deprecated, children }: Re
         : String(type);
 
   return (
-    <div className={styles.field}>
+    <div className={styles.field} data-slot="field-group-item">
       <div className={styles.fieldHeader}>
         <span className={styles.fieldName}>{name}</span>
-        {normalizedType ? <span className={styles.fieldType}>{normalizedType}</span> : null}
-        {required ? <Badge tone="primary">required</Badge> : null}
-        {deprecated ? <Badge>deprecated</Badge> : null}
+        {normalizedType ? (
+          <span className={styles.fieldType} data-slot="field-group-type">
+            {normalizedType}
+          </span>
+        ) : null}
+        {required ? (
+          <Badge size="sm" tone="primary">
+            required
+          </Badge>
+        ) : null}
+        {deprecated ? <Badge size="sm">deprecated</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/Tiles.tsx

@@ -0,0 +1,59 @@
+import type { ReactNode } from 'react';
+import { Link } from 'react-router';
+import { styles } from './styles';
+import { gridColsClass } from './utils';
+
+export interface TileProps {
+  /** URL to navigate to when the tile is clicked. */
+  href: string;
+  title?: ReactNode;
+  description?: ReactNode;
+  /** Preview content, typically light/dark image variants. */
+  children: ReactNode;
+  target?: '_self' | '_blank';
+}
+
+export function Tile({ href, title, description, children, target }: TileProps) {
+  const external = /^https?:\/\//i.test(href);
+  const resolvedTarget = target ?? (external ? '_blank' : undefined);
+
+  const content = (
+    <>
+      <div className={styles.tilePreview} data-slot="tile-preview">
+        {children}
+      </div>
+      {title || description ? (
+        <div className={styles.tileBody} data-slot="tile-body">
+          {title ? <div className={styles.tileTitle}>{title}</div> : null}
+          {description ? <div className={styles.tileDescription}>{description}</div> : null}
+        </div>
+      ) : null}
+    </>
+  );
+
+  const className = `${styles.tile} no-underline hover:no-underline active:no-underline`;
+
+  if (external) {
+    return (
+      <a href={href} className={className} target={resolvedTarget} rel="noreferrer">
+        {content}
+      </a>
+    );
+  }
+
+  return (
+    <Link to={href} className={className} target={resolvedTarget}>
+      {content}
+    </Link>
+  );
+}
+
+export interface TilesProps {
+  children?: ReactNode;
+  cols?: 1 | 2 | 3 | 4;
+}
+
+/** Grid wrapper for <Tile> when <Columns> is not used directly. */
+export function Tiles({ children, cols = 2 }: TilesProps) {
+  return <div className={`${styles.grid} ${styles[gridColsClass(cols)]}`}>{children}</div>;
+}

package/src/components/docs/Tree.tsx

@@ -0,0 +1,359 @@
+import {
+  Children,
+  type CSSProperties,
+  isValidElement,
+  type KeyboardEvent,
+  type ReactElement,
+  type ReactNode,
+  useRef,
+  useState,
+} from 'react';
+import {
+  ChevronRight,
+  File as FileIcon,
+  Folder as FolderIcon,
+  FolderOpen,
+} from '@/components/icons';
+import { styles } from './styles';
+
+export interface TreeFolderProps {
+  name: string;
+  defaultOpen?: boolean;
+  /** When false the folder renders statically (no toggle). Defaults to true. */
+  openable?: boolean;
+  highlight?: boolean;
+  children?: ReactNode;
+}
+
+export interface TreeFileProps {
+  name: string;
+  highlight?: boolean;
+}
+
+export interface TreeProps {
+  children?: ReactNode;
+  style?: CSSProperties;
+  className?: string;
+}
+
+function elementText(node: ReactNode): string {
+  if (typeof node === 'string' || typeof node === 'number') {
+    return String(node);
+  }
+  if (Array.isArray(node)) {
+    return node.map(elementText).join('');
+  }
+  if (isValidElement<{ children?: ReactNode }>(node)) {
+    return elementText(node.props.children);
+  }
+  return '';
+}
+
+function isListElement(node: ReactNode): node is ReactElement<{ children?: ReactNode }> {
+  return isValidElement(node) && (node.type === 'ul' || node.type === 'ol');
+}
+
+/** Stable key for MDX-generated list wrappers (static content, never reordered). */
+function listFingerprint(node: ReactNode): string {
+  const text = elementText(node).replace(/\s+/g, ' ').trim().slice(0, 64);
+  let hash = 0;
+  for (let i = 0; i < text.length; i += 1) {
+    hash = (hash * 31 + text.charCodeAt(i)) | 0;
+  }
+  return `mdx-list-${text.length}-${hash}`;
+}
+
+/** Split an MDX <li> into its label (inline content) and an optional nested list. */
+function splitListItem(li: ReactElement<{ children?: ReactNode }>): {
+  label: string;
+  nested: ReactNode;
+} {
+  let nested: ReactNode = null;
+  const labelParts: ReactNode[] = [];
+
+  Children.forEach(li.props.children, child => {
+    if (isListElement(child)) {
+      nested = child;
+    } else {
+      labelParts.push(child);
+    }
+  });
+
+  return { label: elementText(labelParts).trim(), nested };
+}
+
+function ListItemsAsNodes({ items }: { items: ReactNode }): ReactNode {
+  const nodes: ReactNode[] = [];
+  let index = 0;
+
+  Children.forEach(items, li => {
+    if (!isValidElement<{ children?: ReactNode }>(li) || li.type !== 'li') {
+      return;
+    }
+    const { label, nested } = splitListItem(li);
+    if (!label && !nested) {
+      return;
+    }
+    const name = label || 'untitled';
+    const isFolder = name.endsWith('/') || Boolean(nested);
+    index += 1;
+
+    if (isFolder) {
+      nodes.push(
+        <TreeFolder key={`${name}-${index}`} name={name} defaultOpen={Boolean(nested)}>
+          {nested ? (
+            <ListItemsAsNodes
+              items={(nested as ReactElement<{ children?: ReactNode }>).props.children}
+            />
+          ) : null}
+        </TreeFolder>,
+      );
+    } else {
+      nodes.push(<TreeFile key={`${name}-${index}`} name={name} />);
+    }
+  });
+
+  return <>{nodes}</>;
+}
+
+function containsList(children: ReactNode): boolean {
+  let found = false;
+  Children.forEach(children, child => {
+    if (isListElement(child)) {
+      found = true;
+    }
+  });
+  return found;
+}
+
+export function TreeFolder({
+  name,
+  defaultOpen = false,
+  openable = true,
+  highlight = false,
+  children,
+}: TreeFolderProps) {
+  const [open, setOpen] = useState(defaultOpen);
+  const expanded = openable ? open : true;
+  const Icon = expanded ? FolderOpen : FolderIcon;
+
+  return (
+    // biome-ignore lint/a11y/useFocusableInteractive: keyboard focus is delegated to the row button inside this treeitem
+    <li
+      role="treeitem"
+      aria-expanded={openable ? expanded : undefined}
+      data-highlight={highlight ? '' : undefined}
+      className={styles.treeItem}
+    >
+      {openable ? (
+        <button
+          type="button"
+          data-tree-focus
+          onClick={() => setOpen(value => !value)}
+          className={`${styles.treeRow} ${highlight ? styles.treeHighlight : ''}`}
+        >
+          <ChevronRight
+            size={14}
+            className={styles.treeChevron}
+            data-open={expanded ? '' : undefined}
+            aria-hidden={true}
+          />
+          <Icon size={15} className={styles.treeIcon} aria-hidden={true} />
+          <span className={styles.treeName}>{name}</span>
+        </button>
+      ) : (
+        <span
+          data-tree-focus
+          tabIndex={-1}
+          className={`${styles.treeRow} ${highlight ? styles.treeHighlight : ''}`}
+        >
+          <Icon size={15} className={styles.treeIcon} aria-hidden={true} />
+          <span className={styles.treeName}>{name}</span>
+        </span>
+      )}
+      {children ? (
+        // biome-ignore lint/a11y/useSemanticElements: group is the required ARIA role for nested tree levels
+        <ul
+          role="group"
+          hidden={openable && !expanded ? true : undefined}
+          className={styles.treeGroup}
+        >
+          {children}
+        </ul>
+      ) : null}
+    </li>
+  );
+}
+
+export function TreeFile({ name, highlight = false }: TreeFileProps) {
+  return (
+    // biome-ignore lint/a11y/useFocusableInteractive: file rows are arrow-key targets in the tree widget
+    <li role="treeitem" data-highlight={highlight ? '' : undefined} className={styles.treeItem}>
+      <span
+        data-tree-focus
+        tabIndex={-1}
+        className={`${styles.treeRow} ${highlight ? styles.treeHighlight : ''}`}
+      >
+        <FileIcon size={15} className={styles.treeIcon} aria-hidden={true} />
+        <span className={styles.treeName}>{name}</span>
+      </span>
+    </li>
+  );
+}
+
+function visibleFocusables(root: HTMLElement): HTMLElement[] {
+  return [...root.querySelectorAll<HTMLElement>('[data-tree-focus]')].filter(
+    element => !element.closest('[hidden]'),
+  );
+}
+
+function TreeRoot({ children, style, className }: TreeProps) {
+  const rootRef = useRef<HTMLDivElement>(null);
+  const searchRef = useRef({ text: '', timer: 0 });
+
+  const onKeyDown = (event: KeyboardEvent) => {
+    const root = rootRef.current;
+    const target = event.target as HTMLElement;
+    if (!root || !target.closest('[data-tree-focus]')) {
+      return;
+    }
+
+    const items = visibleFocusables(root);
+    const index = items.indexOf(target as HTMLElement);
+
+    const focusAt = (next: number) => {
+      event.preventDefault();
+      items[(next + items.length) % items.length]?.focus();
+    };
+
+    switch (event.key) {
+      case 'ArrowDown':
+        focusAt(index + 1);
+        break;
+      case 'ArrowUp':
+        focusAt(index - 1);
+        break;
+      case 'Home':
+        focusAt(0);
+        break;
+      case 'End':
+        focusAt(items.length - 1);
+        break;
+      case 'ArrowRight': {
+        const row = target.closest('[role="treeitem"]');
+        const toggle = row?.querySelector<HTMLElement>(':scope > [data-tree-focus]');
+        if (
+          toggle &&
+          toggle.tagName === 'BUTTON' &&
+          toggle.getAttribute('aria-expanded') === 'false'
+        ) {
+          event.preventDefault();
+          toggle.click();
+        } else {
+          const firstChild = row?.querySelector<HTMLElement>(':scope > ul [data-tree-focus]');
+          if (firstChild) {
+            event.preventDefault();
+            firstChild.focus();
+          }
+        }
+        break;
+      }
+      case 'ArrowLeft': {
+        const row = target.closest('[role="treeitem"]');
+        const toggle = row?.querySelector<HTMLElement>(':scope > [data-tree-focus]');
+        if (
+          toggle &&
+          toggle.tagName === 'BUTTON' &&
+          toggle.getAttribute('aria-expanded') === 'true'
+        ) {
+          event.preventDefault();
+          toggle.click();
+        } else {
+          const parent = row?.parentElement?.closest('[role="treeitem"]');
+          const parentFocus = parent?.querySelector<HTMLElement>(':scope > [data-tree-focus]');
+          if (parentFocus) {
+            event.preventDefault();
+            parentFocus.focus();
+          }
+        }
+        break;
+      }
+      case '*': {
+        // Expand all sibling folders at the current level.
+        const group = target.closest('ul');
+        group
+          ?.querySelectorAll<HTMLElement>(
+            ':scope > [role="treeitem"] > button[aria-expanded="false"]',
+          )
+          .forEach(button => {
+            button.click();
+          });
+        break;
+      }
+      default: {
+        if (event.key.length === 1 && !event.ctrlKey && !event.metaKey) {
+          const state = searchRef.current;
+          window.clearTimeout(state.timer);
+          state.text += event.key.toLowerCase();
+          state.timer = window.setTimeout(() => {
+            state.text = '';
+          }, 500);
+          const match = items.find(item =>
+            (item.textContent || '').trim().toLowerCase().startsWith(state.text),
+          );
+          if (match) {
+            event.preventDefault();
+            (match as HTMLElement).focus();
+          }
+        }
+      }
+    }
+  };
+
+  const content = containsList(children)
+    ? Children.map(children, child =>
+        isListElement(child) ? (
+          <ListItemsAsNodes
+            key={listFingerprint(child)}
+            items={(child as ReactElement<{ children?: ReactNode }>).props.children}
+          />
+        ) : (
+          child
+        ),
+      )
+    : children;
+
+  // Buttons (folders) stay in the tab order natively; file rows are reached
+  // with arrow keys.
+  return (
+    // biome-ignore lint/a11y/noStaticElementInteractions: key handling for the tree widget lives on its root
+    <div
+      ref={rootRef}
+      style={style}
+      className={`${styles.tree} ${className || ''}`}
+      onKeyDown={onKeyDown}
+    >
+      {/* biome-ignore lint/a11y/noNoninteractiveElementToInteractiveRole: tree is the required ARIA role for this widget */}
+      <ul role="tree" aria-label="File tree" className={styles.treeList}>
+        {content}
+      </ul>
+    </div>
+  );
+}
+
+export function Tree(props: TreeProps) {
+  return <TreeRoot {...props} />;
+}
+
+/** Alias: <Tree> and <FileTree> are interchangeable, like Mintlify. */
+export function FileTree(props: TreeProps) {
+  return <TreeRoot {...props} />;
+}
+
+Tree.Folder = TreeFolder;
+Tree.File = TreeFile;
+FileTree.Folder = TreeFolder;
+FileTree.File = TreeFile;
+
+export const FileTreeFolder = TreeFolder;
+export const FileTreeFile = TreeFile;