@umami/shiso 1.12.0 → 1.14.0

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;

package/src/components/docs/Update.tsx

@@ -0,0 +1,72 @@
+import type { ReactNode } from 'react';
+import { Badge } from './Badge';
+import { styles } from './styles';
+import { slugify } from './utils';
+
+export interface UpdateRss {
+  title?: string;
+  description?: string;
+}
+
+export interface UpdateProps {
+  /** Left-hand label. Also creates the anchor id (slugified, like headings). */
+  label: string;
+  description?: ReactNode;
+  tags?: string[];
+  /**
+   * Mintlify compatibility: custom RSS title/description for this entry.
+   * Shiso does not generate an RSS feed yet; the prop is accepted and ignored.
+   */
+  rss?: UpdateRss;
+  children?: ReactNode;
+}
+
+function normalizeTags(tags: UpdateProps['tags']): string[] {
+  if (!Array.isArray(tags)) {
+    return [];
+  }
+
+  const seen = new Set<string>();
+  for (const tag of tags) {
+    if (typeof tag !== 'string') {
+      continue;
+    }
+    const trimmed = tag.trim();
+    if (trimmed && !seen.has(trimmed)) {
+      seen.add(trimmed);
+    }
+  }
+
+  return [...seen];
+}
+
+export function Update({ label, description, tags, rss: _rss, children }: UpdateProps) {
+  const id = slugify(label, 'update');
+  const normalizedTags = normalizeTags(tags);
+
+  return (
+    <section
+      id={id}
+      aria-label={label}
+      className={styles.update}
+      data-tags={normalizedTags.join(',')}
+    >
+      <div className={styles.updateMeta}>
+        <a href={`#${id}`} className={styles.updateLabel}>
+          {label}
+        </a>
+        {description ? <div className={styles.updateDescription}>{description}</div> : null}
+        {normalizedTags.length > 0 ? (
+          <div className={styles.updateTags}>
+            {normalizedTags.map(tag => (
+              <Badge key={tag} size="sm">
+                {tag}
+              </Badge>
+            ))}
+          </div>
+        ) : null}
+      </div>
+      <div className={styles.updateBody}>{children}</div>
+    </section>
+  );
+}

package/src/components/docs/index.ts

@@ -3,16 +3,22 @@ export * from './Badge';
 export * from './Button';
 export * from './Callout';
 export * from './Card';
+export * from './Changelog';
 export * from './CodeGroup';
 export * from './Columns';
 export * from './Expandable';
 export * from './Frame';
 export * from './Icon';
 export * from './Link';
-export * from './ParamField';
+export * from './Mermaid';
+export * from './Panel';
+export * from './Param';
 export * from './PropertiesTable';
-export * from './ResponseField';
+export * from './panel-context';
 export * from './Steps';
 export * from './Tabs';
+export * from './Tiles';
 export * from './Tooltip';
+export * from './Tree';
+export * from './Update';
 export * from './ZoomableImage';

package/src/components/docs/panel-context.tsx

@@ -0,0 +1,25 @@
+import { createContext, type ReactNode, useContext, useState } from 'react';
+
+interface PanelContextValue {
+  content: ReactNode;
+  setContent: (content: ReactNode) => void;
+}
+
+const PanelContext = createContext<PanelContextValue>({
+  content: null,
+  setContent: () => {},
+});
+
+export function PanelProvider({ children }: { children: ReactNode }) {
+  const [content, setContent] = useState<ReactNode>(null);
+
+  return <PanelContext.Provider value={{ content, setContent }}>{children}</PanelContext.Provider>;
+}
+
+export function usePanelContent(): ReactNode {
+  return useContext(PanelContext).content;
+}
+
+export function useSetPanelContent(): (content: ReactNode) => void {
+  return useContext(PanelContext).setContent;
+}

package/src/components/docs/styles.ts

@@ -67,12 +67,6 @@ export const styles = {
   frameCaption:
     'relative mt-3 px-4 pb-1 text-center text-sm leading-5 text-muted-foreground [&_p]:m-0 [&_a]:font-semibold',
 
-  field: 'my-3',
-  paramField: 'my-3',
-  fieldHeader: 'flex flex-wrap items-center gap-2',
-  fieldBody: 'mt-3',
-  fieldType: 'text-[0.9rem] text-muted-foreground',
-  fieldName: 'font-bold text-foreground',
   code: 'rounded-sm bg-[color-mix(in_srgb,currentColor_4%,transparent)] px-[0.35rem] py-[0.1rem] text-sm text-foreground font-mono',
   steps:
     "relative my-4 flex flex-col gap-5 before:absolute before:top-4 before:bottom-4 before:left-4 before:w-px before:-translate-x-1/2 before:bg-border before:content-['']",
@@ -84,4 +78,51 @@ export const styles = {
 
   tooltipTrigger:
     'peer cursor-help border-0 border-muted-foreground border-b border-dotted bg-transparent p-0 text-inherit [font:inherit]',
+
+  update:
+    'my-8 grid scroll-mt-24 grid-cols-1 gap-4 border-border border-t pt-6 md:grid-cols-[220px_minmax(0,1fr)]',
+  updateMeta: 'flex min-w-0 flex-col items-start gap-2 md:sticky md:top-24 md:self-start',
+  updateLabel:
+    'w-fit text-lg font-semibold text-foreground hover:text-primary hover:underline [&:hover]:decoration-primary',
+  updateDescription: 'text-sm text-muted-foreground leading-6',
+  updateTags: 'flex flex-wrap gap-1.5',
+  updateBody: 'min-w-0 [&>:first-child]:mt-0 [&>:last-child]:mb-0 [&_:where(p,ul,ol)]:leading-7',
+  changelog: 'my-4 flex flex-col',
+  changelogFilters: 'mb-2 flex flex-wrap items-center gap-1',
+  changelogFilterButton:
+    'rounded-md p-0.5 outline-none focus-visible:ring-2 focus-visible:ring-ring [&>[data-slot=badge]]:cursor-pointer',
+  changelogClear:
+    'ml-1 text-xs font-medium text-muted-foreground hover:text-foreground hover:underline',
+  changelogEmpty: 'my-6 text-sm text-muted-foreground',
+
+  mermaid: 'my-4',
+  mermaidTitle: 'mb-2 text-sm font-semibold text-foreground',
+  mermaidViewport:
+    'relative overflow-auto rounded-lg border border-border bg-card p-4 [&_svg]:mx-auto [&_svg]:max-w-full [&_svg]:shrink-0',
+  mermaidSvg: 'origin-top-left transition-transform duration-150 [&_svg]:h-auto [&_svg]:max-w-none',
+  mermaidFallback: 'bg-transparent p-0 font-mono text-xs text-muted-foreground whitespace-pre-wrap',
+  mermaidError: 'mt-2 text-sm text-destructive',
+  mermaidControls:
+    'absolute flex items-center gap-1 rounded-md border border-border bg-background/90 p-1 shadow-sm [&_button]:flex [&_button]:size-6 [&_button]:items-center [&_button]:justify-center [&_button]:rounded [&_button]:text-sm [&_button]:text-muted-foreground [&_button:hover]:bg-muted [&_button:hover]:text-foreground',
+
+  panel: 'flex min-w-0 flex-col gap-4 text-sm [&>:first-child]:mt-0 [&>:last-child]:mb-0',
+  panelInline: 'my-4 lg:hidden',
+
+  tile: 'block h-full overflow-hidden rounded-lg border border-border bg-card hover:border-primary',
+  tilePreview:
+    'flex h-36 items-center justify-center gap-2 overflow-hidden border-border border-b bg-muted/40 bg-[radial-gradient(circle_at_1px_1px,var(--border)_1px,transparent_0)] bg-[size:16px_16px] p-4 [&_img]:max-h-full [&_img]:w-auto [&_img]:max-w-full [&_img]:object-contain',
+  tileBody: 'flex flex-col gap-1 p-4',
+  tileTitle: 'text-sm font-semibold text-foreground',
+  tileDescription: 'text-sm text-muted-foreground leading-6',
+
+  tree: 'not-prose my-4 overflow-hidden rounded-lg border border-border bg-card text-sm',
+  treeList: 'flex flex-col gap-0.5 p-3',
+  treeGroup: 'my-0 ml-[15px] flex list-none flex-col gap-px border-border border-l pl-1',
+  treeItem: 'my-0 min-w-0 list-none p-0 [&::marker]:content-none',
+  treeRow:
+    'flex w-full min-w-0 items-center gap-1.5 rounded-md px-2 py-1 text-left text-foreground hover:bg-muted [&:focus-visible]:bg-muted [&:focus-visible]:ring-2 [&:focus-visible]:ring-ring [&:focus-visible]:outline-none',
+  treeChevron: 'shrink-0 text-muted-foreground transition-transform [&[data-open]]:rotate-90',
+  treeIcon: 'shrink-0 text-muted-foreground',
+  treeName: 'min-w-0 flex-1 truncate font-mono text-[0.85rem]',
+  treeHighlight: 'bg-primary/10 text-primary [&_svg]:text-primary',
 } as const;

package/src/components/icons/index.ts

@@ -3,11 +3,15 @@ export {
   ArrowRight,
   Check,
   Check as CheckIcon,
+  ChevronDown,
   ChevronRight,
   CircleAlert,
   Copy,
   ExternalLink,
+  File,
   FileText,
+  Folder,
+  FolderOpen,
   Hand,
   Info as InfoIcon,
   Lightbulb,

package/src/lib/openapi.ts

@@ -45,6 +45,22 @@ export function hasParameters(operation: NormalizedOperation): boolean {
   );
 }
 
+/** Parameter groups shared by the renderer and table of contents. */
+export function operationParameterSections(operation: NormalizedOperation) {
+  const groups = [
+    { location: 'header', name: 'Headers' },
+    { location: 'path', name: 'Path parameters' },
+    { location: 'query', name: 'Query parameters' },
+    { location: 'cookie', name: 'Cookie parameters' },
+  ] as const;
+
+  return groups.filter(
+    ({ location }) =>
+      operation.parameters[location].length > 0 ||
+      (location === 'header' && operation.security.length > 0),
+  );
+}
+
 /**
  * Section headings for an operation, in render order. The single source of
  * truth for section ids: the component, the table of contents, the content
@@ -53,7 +69,7 @@ export function hasParameters(operation: NormalizedOperation): boolean {
 export function operationSections(operation: NormalizedOperation): TocEntry[] {
   const slugger = createSlugger();
   const names = [
-    hasParameters(operation) ? 'Parameters' : undefined,
+    ...operationParameterSections(operation).map(section => section.name),
     operation.requestBody ? 'Request body' : undefined,
     operation.responses.length ? 'Responses' : undefined,
     operation.samples.length ? 'Code samples' : undefined,

package/src/lib/rehype-shiki.ts

@@ -133,8 +133,25 @@ async function highlightBlock(pre: MdNode, code: MdNode, config: ResolvedCodeBlo
     ? codeProperties.className.map(String)
     : [];
   const requested = classes.map(value => value.match(/^language-(\S+)$/)?.[1]).find(Boolean);
-  const lang = resolveLanguage(requested);
   const meta = parseCodeMeta(typeof code.data?.meta === 'string' ? code.data.meta : '');
+
+  // Mermaid diagrams render client-side via the <Mermaid> component; keep the
+  // raw definition so CodeBlock can hand it over untouched.
+  if (requested === 'mermaid') {
+    const metaRaw = typeof code.data?.meta === 'string' ? code.data.meta : '';
+    const placement = metaRaw.match(/placement=["'](top-left|top-right|bottom-left|bottom-right)["']/)?.[1];
+    const actions = metaRaw.match(/actions=\{(true|false)\}/)?.[1];
+    pre.properties = {
+      ...(pre.properties as Properties),
+      'data-language': 'mermaid',
+      ...(meta.title ? { 'data-title': meta.title } : {}),
+      ...(placement ? { 'data-placement': placement } : {}),
+      ...(actions ? { 'data-actions': actions } : {}),
+    };
+    return;
+  }
+
+  const lang = resolveLanguage(requested);
   // mdast-util-to-hast appends a trailing newline to the code text.
   const source = toText(code).replace(/\n$/, '');