@umami/shiso 1.12.0 → 1.14.0

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/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/Param.tsx

@@ -0,0 +1,6 @@
+import type { ReactNode } from 'react';
+import { styles } from './styles';
+
+export function Param({ children }: { children?: ReactNode }) {
+  return <code className={styles.code}>{children}</code>;
+}

package/src/components/docs/PropertiesTable.tsx

@@ -1,13 +1,23 @@
 import type { ReactNode } from 'react';
 import { Badge } from './Badge';
-import type { ResponseFieldProps } from './ResponseField';
 import { decodeHtmlEntities, toElementArray } from './utils';
 
+type FieldValue = string | number | boolean | null | undefined;
+
+export interface PropertiesTableRowProps {
+  name: string;
+  type?: FieldValue;
+  default?: FieldValue;
+  required?: boolean;
+  deprecated?: boolean;
+  children?: ReactNode;
+}
+
 export interface PropertiesTableProps {
   children?: ReactNode;
 }
 
-function displayValue(value: ResponseFieldProps['type']): string | undefined {
+function displayValue(value: PropertiesTableRowProps['type']): string | undefined {
   if (typeof value === 'string') {
     return decodeHtmlEntities(value);
   }
@@ -16,7 +26,7 @@ function displayValue(value: ResponseFieldProps['type']): string | undefined {
 }
 
 export function PropertiesTable({ children }: PropertiesTableProps) {
-  const rows = toElementArray<ResponseFieldProps>(children);
+  const rows = toElementArray<PropertiesTableRowProps>(children);
 
   if (!rows.length) {
     return null;
@@ -29,43 +39,49 @@ export function PropertiesTable({ children }: PropertiesTableProps) {
       <table className="m-0 min-w-[40rem] table-fixed">
         <thead>
           <tr>
-            <th className="w-1/5">Name</th>
-            <th className="w-1/4">Type</th>
+            <th className="w-[30%]">Name</th>
+            <th className="w-[15%]">Type</th>
             <th>Description</th>
           </tr>
         </thead>
-        <tbody>
-          {rows.map(row => {
-            const { name, type, required, deprecated, children: description } = row.props;
-            const defaultValue = displayValue(row.props.default);
-
-            return (
-              <tr key={row.key ?? name}>
-                <td>
-                  <span className="inline-flex flex-wrap items-center gap-2">
-                    {name}
-                    {required ? (
-                      <Badge size="xs" tone="primary">
-                        required
-                      </Badge>
-                    ) : null}
-                    {deprecated ? <Badge size="xs">deprecated</Badge> : null}
-                  </span>
-                </td>
-                <td>{displayValue(type)}</td>
-                <td className="[&_p]:m-0">
-                  {description}
-                  {defaultValue ? (
-                    <span className="mt-1 block text-muted-foreground">
-                      Default: {defaultValue}
-                    </span>
-                  ) : null}
-                </td>
-              </tr>
-            );
-          })}
-        </tbody>
+        <tbody>{rows}</tbody>
       </table>
     </div>
   );
 }
+
+function PropertiesTableRow({
+  name,
+  type,
+  required,
+  deprecated,
+  default: value,
+  children,
+}: PropertiesTableRowProps) {
+  const defaultValue = displayValue(value);
+
+  return (
+    <tr>
+      <td>
+        <span className="inline-flex flex-wrap items-center gap-2">
+          {name}
+          {required ? (
+            <Badge size="sm" tone="primary">
+              required
+            </Badge>
+          ) : null}
+          {deprecated ? <Badge size="sm">deprecated</Badge> : null}
+        </span>
+      </td>
+      <td>{displayValue(type)}</td>
+      <td className="[&_p]:m-0">
+        {children}
+        {defaultValue ? (
+          <span className="mt-1 block text-muted-foreground">Default: {defaultValue}</span>
+        ) : null}
+      </td>
+    </tr>
+  );
+}
+
+PropertiesTable.Row = PropertiesTableRow;

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>;
+}