@umami/shiso 1.11.0 → 1.13.0

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;

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,23 @@ 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 './Mermaid';
+export * from './Panel';
+export * from './panel-context';
 export * from './ParamField';
 export * from './PropertiesTable';
 export * from './ResponseField';
 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

@@ -68,6 +68,8 @@ export const styles = {
     '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',
+  fieldGroup:
+    'my-4 divide-y divide-border overflow-hidden rounded-lg border border-border text-sm leading-6 [&>[data-slot=field-group-item]]:my-0 [&>[data-slot=field-group-item]]:px-4 [&>[data-slot=field-group-item]]:py-3 [&_[data-slot=field-group-body]]:mt-2 [&_[data-slot=field-group-type]]:text-xs',
   paramField: 'my-3',
   fieldHeader: 'flex flex-wrap items-center gap-2',
   fieldBody: 'mt-3',
@@ -84,4 +86,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,