@umami/shiso 0.54.0 → 0.61.0

package/src/components/docs/Badge.tsx

@@ -0,0 +1,171 @@
+import type { ReactNode } from 'react';
+import { Badge as BadgePrimitive } from '@/components/ui/badge';
+import { cn } from '@/lib/utils';
+import { resolveIcon } from './utils';
+
+export type BadgeColor =
+  | 'gray'
+  | 'blue'
+  | 'green'
+  | 'yellow'
+  | 'orange'
+  | 'red'
+  | 'purple'
+  | 'white'
+  | 'surface'
+  | 'white-destructive'
+  | 'surface-destructive';
+
+export type BadgeSize = 'xs' | 'sm' | 'md' | 'lg';
+export type BadgeShape = 'rounded' | 'pill';
+
+export interface BadgeProps {
+  color?: BadgeColor;
+  size?: BadgeSize;
+  shape?: BadgeShape;
+  icon?: ReactNode;
+  stroke?: boolean;
+  disabled?: boolean;
+  className?: string;
+  /** @deprecated Use `color` instead. */
+  tone?: 'muted' | 'primary';
+  children?: ReactNode;
+}
+
+const colorClasses: Record<BadgeColor | 'primary', { filled: string; stroke: string }> = {
+  gray: {
+    filled: 'border-transparent bg-muted text-muted-foreground',
+    stroke: 'border-border bg-transparent text-muted-foreground',
+  },
+  blue: {
+    filled: 'border-transparent bg-blue-100 text-blue-800 dark:bg-blue-400/15 dark:text-blue-300',
+    stroke:
+      'border-blue-300 bg-transparent text-blue-700 dark:border-blue-400/50 dark:text-blue-300',
+  },
+  green: {
+    filled:
+      'border-transparent bg-green-100 text-green-800 dark:bg-green-400/15 dark:text-green-300',
+    stroke:
+      'border-green-300 bg-transparent text-green-700 dark:border-green-400/50 dark:text-green-300',
+  },
+  yellow: {
+    filled:
+      'border-transparent bg-yellow-100 text-yellow-800 dark:bg-yellow-400/15 dark:text-yellow-300',
+    stroke:
+      'border-yellow-300 bg-transparent text-yellow-700 dark:border-yellow-400/50 dark:text-yellow-300',
+  },
+  orange: {
+    filled:
+      'border-transparent bg-orange-100 text-orange-800 dark:bg-orange-400/15 dark:text-orange-300',
+    stroke:
+      'border-orange-300 bg-transparent text-orange-700 dark:border-orange-400/50 dark:text-orange-300',
+  },
+  red: {
+    filled: 'border-transparent bg-red-100 text-red-800 dark:bg-red-400/15 dark:text-red-300',
+    stroke: 'border-red-300 bg-transparent text-red-700 dark:border-red-400/50 dark:text-red-300',
+  },
+  purple: {
+    filled:
+      'border-transparent bg-purple-100 text-purple-800 dark:bg-purple-400/15 dark:text-purple-300',
+    stroke:
+      'border-purple-300 bg-transparent text-purple-700 dark:border-purple-400/50 dark:text-purple-300',
+  },
+  white: {
+    filled: 'border-border bg-white text-zinc-900',
+    stroke: 'border-white bg-transparent text-foreground dark:text-white',
+  },
+  surface: {
+    filled: 'border-border bg-background text-foreground',
+    stroke: 'border-border bg-transparent text-foreground',
+  },
+  'white-destructive': {
+    filled: 'border-border bg-white text-destructive',
+    stroke: 'border-white bg-transparent text-destructive',
+  },
+  'surface-destructive': {
+    filled: 'border-destructive/30 bg-background text-destructive',
+    stroke: 'border-destructive/50 bg-transparent text-destructive',
+  },
+  primary: {
+    filled: 'border-transparent bg-primary/10 text-primary',
+    stroke: 'border-primary/50 bg-transparent text-primary',
+  },
+};
+
+const sizeClasses: Record<BadgeSize, string> = {
+  xs: 'gap-1 px-1.5 py-0 text-[0.625rem] leading-4',
+  sm: 'gap-1 px-2 py-0.5 text-xs leading-4',
+  md: 'gap-1.5 px-2.5 py-0.5 text-sm leading-5',
+  lg: 'gap-1.5 px-3 py-1 text-base leading-5',
+};
+
+const iconSizes: Record<BadgeSize, number> = {
+  xs: 10,
+  sm: 12,
+  md: 14,
+  lg: 16,
+};
+
+function isImageSource(value: string): boolean {
+  return (
+    /^(?:https?:|data:image\/|\/|\.\.?\/)/i.test(value) ||
+    /\.(?:avif|gif|jpe?g|png|svg|webp)(?:[?#].*)?$/i.test(value)
+  );
+}
+
+function BadgeIcon({ icon, size }: { icon: ReactNode; size: number }) {
+  const content =
+    typeof icon === 'string' && isImageSource(icon) ? (
+      <img src={icon} alt="" width={size} height={size} />
+    ) : (
+      resolveIcon(icon, size)
+    );
+
+  if (!content) {
+    return null;
+  }
+
+  return (
+    <span
+      className="inline-flex shrink-0 items-center justify-center [&>img]:size-full [&>svg]:size-full"
+      style={{ width: size, height: size }}
+      aria-hidden="true"
+    >
+      {content}
+    </span>
+  );
+}
+
+export function Badge({
+  color,
+  size = 'md',
+  shape = 'rounded',
+  icon,
+  stroke = false,
+  disabled = false,
+  className,
+  tone,
+  children,
+}: BadgeProps) {
+  const resolvedColor = color || (tone === 'primary' ? 'primary' : 'gray');
+  const palette = colorClasses[resolvedColor];
+
+  return (
+    <BadgePrimitive
+      variant="secondary"
+      className={cn(
+        'h-auto justify-start overflow-visible whitespace-normal border align-middle transition-none',
+        sizeClasses[size],
+        stroke ? palette.stroke : palette.filled,
+        shape === 'pill' ? 'rounded-full' : 'rounded-md',
+        disabled && 'cursor-not-allowed opacity-50',
+        className,
+      )}
+      aria-disabled={disabled || undefined}
+      data-disabled={disabled ? '' : undefined}
+    >
+      {icon ? <BadgeIcon icon={icon} size={iconSizes[size]} /> : null}
+      {children}
+    </BadgePrimitive>
+  );
+}

package/src/components/docs/Callout.tsx

@@ -0,0 +1,73 @@
+import type { ReactNode } from 'react';
+import {
+  Check as CheckIcon,
+  CircleAlert,
+  InfoIcon,
+  Lightbulb,
+  TriangleAlert,
+} from '@/components/icons';
+import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert';
+import { styles } from './styles';
+import { resolveIcon } from './utils';
+
+export interface CalloutProps {
+  title?: ReactNode;
+  icon?: ReactNode | string;
+  children?: ReactNode;
+  variant?: 'note' | 'tip' | 'warning' | 'info' | 'check' | 'danger';
+}
+
+const CALLOUT_ICONS = {
+  note: <InfoIcon size={14} />,
+  info: <InfoIcon size={14} />,
+  warning: <TriangleAlert size={14} />,
+  tip: <Lightbulb size={14} />,
+  check: <CheckIcon size={14} />,
+  danger: <CircleAlert size={14} />,
+} as const;
+
+export function Callout({ title, icon, children, variant = 'note' }: CalloutProps) {
+  return (
+    <Alert role="note" className={`${styles.callout} ${styles[variant]}`}>
+      <span className={styles.calloutIcon} aria-hidden={true}>
+        {resolveIcon(icon) || CALLOUT_ICONS[variant]}
+      </span>
+      <div className={styles.calloutBody}>
+        {title ? <AlertTitle className={styles.calloutTitle}>{title}</AlertTitle> : null}
+        <AlertDescription className="text-sm text-inherit leading-6">{children}</AlertDescription>
+      </div>
+    </Alert>
+  );
+}
+
+export function Note({ children }: { children?: ReactNode }) {
+  return <Callout variant="note">{children}</Callout>;
+}
+
+export function Tip({ children }: { children?: ReactNode }) {
+  return <Callout variant="tip">{children}</Callout>;
+}
+
+export function Warning({ children }: { children?: ReactNode }) {
+  return <Callout variant="warning">{children}</Callout>;
+}
+
+export function Info({ children }: { children?: ReactNode }) {
+  return <Callout variant="info">{children}</Callout>;
+}
+
+export function Check({ children }: { children?: ReactNode }) {
+  return <Callout variant="check">{children}</Callout>;
+}
+
+export function Danger({ children }: { children?: ReactNode }) {
+  return <Callout variant="danger">{children}</Callout>;
+}
+
+export function WarningBanner({ children }: { children?: ReactNode }) {
+  return (
+    <Callout variant="warning" icon={<CircleAlert size={14} />}>
+      {children}
+    </Callout>
+  );
+}

package/src/components/docs/Card.tsx

@@ -0,0 +1,158 @@
+import type { ReactNode } from 'react';
+import { Link } from 'react-router';
+import {
+  Check as CheckIcon,
+  ChevronRight,
+  CircleAlert,
+  InfoIcon,
+  Lightbulb,
+  TriangleAlert,
+} from '@/components/icons';
+import { CardContent, Card as CardPrimitive } from '@/components/ui/card';
+import { styles } from './styles';
+import { gridColsClass, resolveIcon } from './utils';
+
+export interface CardProps {
+  title?: ReactNode;
+  href?: string;
+  icon?: ReactNode | string;
+  color?: string;
+  img?: string;
+  cta?: string;
+  horizontal?: boolean;
+  arrow?: boolean;
+  type?: CardType;
+  children?: ReactNode;
+}
+
+export type CardType = 'note' | 'info' | 'warning' | 'tip' | 'check' | 'danger';
+
+const CARD_TYPE_ICONS: Record<CardType, ReactNode> = {
+  note: <InfoIcon size={16} />,
+  info: <InfoIcon size={16} />,
+  warning: <TriangleAlert size={16} />,
+  tip: <Lightbulb size={16} />,
+  check: <CheckIcon size={16} />,
+  danger: <CircleAlert size={16} />,
+};
+
+const CARD_TYPE_HOVER: Record<CardType, string> = {
+  note: 'hover:border-border',
+  info: 'hover:border-blue-300 dark:hover:border-blue-400/40',
+  warning: 'hover:border-amber-300 dark:hover:border-amber-400/40',
+  tip: 'hover:border-green-300 dark:hover:border-green-400/40',
+  check: 'hover:border-emerald-300 dark:hover:border-emerald-400/40',
+  danger: 'hover:border-destructive/40',
+};
+
+function DocsCardContent({
+  title,
+  icon,
+  color,
+  img,
+  cta,
+  arrow,
+  type,
+  children,
+}: Omit<CardProps, 'href'>) {
+  const resolvedIcon = resolveIcon(icon, 16) || (type ? CARD_TYPE_ICONS[type] : null);
+
+  return (
+    <CardContent className="p-0">
+      {img ? <img src={img} alt="" className={styles.cardImage} /> : null}
+      <div className={styles.cardInner} data-slot="card-inner">
+        <div className={styles.cardMain} data-slot="card-main">
+          <div className={styles.cardHeader}>
+            {resolvedIcon ? (
+              <span
+                className={`${styles.cardIcon} ${type ? 'text-inherit' : 'text-primary'}`}
+                style={color ? { color } : undefined}
+              >
+                {resolvedIcon}
+              </span>
+            ) : null}
+            {title ? (
+              <div className={styles.cardTitle} data-slot="card-title">
+                {title}
+              </div>
+            ) : null}
+          </div>
+          {children ? (
+            <div className={styles.cardBody} data-slot="card-body">
+              {children}
+            </div>
+          ) : null}
+        </div>
+        {cta || arrow ? (
+          <div className={styles.cardCta} data-slot="card-cta">
+            {cta ? <span>{cta}</span> : null}
+            {arrow ? (
+              <ChevronRight size={14} className={styles.cardArrow} data-slot="card-arrow" />
+            ) : null}
+          </div>
+        ) : null}
+      </div>
+    </CardContent>
+  );
+}
+
+export function Card({
+  title,
+  href,
+  icon,
+  color,
+  img,
+  cta,
+  horizontal,
+  arrow,
+  type,
+  children,
+}: CardProps) {
+  const external = typeof href === 'string' && /^https?:\/\//i.test(href);
+  const showArrow = arrow ?? external;
+  const className = `${styles.card} ${type ? `${styles.cardTyped} ${styles[type]} ${CARD_TYPE_HOVER[type]}` : ''} ${horizontal ? styles.cardHorizontal : ''} ${img ? styles.cardImageLayout : ''}`;
+  const content = (
+    <CardPrimitive className={className}>
+      <DocsCardContent
+        title={title}
+        icon={icon}
+        color={color}
+        img={img}
+        cta={cta}
+        arrow={showArrow}
+        type={type}
+      >
+        {children}
+      </DocsCardContent>
+    </CardPrimitive>
+  );
+
+  if (!href) {
+    return content;
+  }
+
+  const linkClassName = 'block h-full no-underline hover:no-underline active:no-underline';
+
+  if (external) {
+    return (
+      <a href={href} className={linkClassName} target="_blank" rel="noreferrer">
+        {content}
+      </a>
+    );
+  }
+
+  return (
+    <Link to={href} className={linkClassName}>
+      {content}
+    </Link>
+  );
+}
+
+export interface CardGroupProps {
+  children?: ReactNode;
+  cols?: 1 | 2 | 3 | 4;
+}
+
+export function CardGroup({ children, cols = 2 }: CardGroupProps) {
+  return <div className={`${styles.grid} ${styles[gridColsClass(cols)]}`}>{children}</div>;
+}

package/src/components/docs/CodeGroup.tsx

@@ -0,0 +1,73 @@
+import type { ReactNode } from 'react';
+import { useMemo, useState } from 'react';
+import { TabsContent, TabsList, Tabs as TabsPrimitive, TabsTrigger } from '@/components/ui/tabs';
+import { styles } from './styles';
+import { findCodeLanguage, findCodeTitle, slugify, toElementArray } from './utils';
+
+export interface CodeGroupProps {
+  children?: ReactNode;
+}
+
+export function CodeGroup({ children }: CodeGroupProps) {
+  const blocks = useMemo(() => {
+    const counts = new Map<string, number>();
+
+    return toElementArray<{ title?: string }>(children).map((child, index) => {
+      const explicitTitle = child.props?.title;
+      const titleValue =
+        (typeof explicitTitle === 'string' && explicitTitle.trim()) ||
+        findCodeTitle(child) ||
+        findCodeLanguage(child) ||
+        `snippet ${index + 1}`;
+      const keyBase = slugify(titleValue, `snippet-${index + 1}`);
+      const count = counts.get(keyBase) || 0;
+      counts.set(keyBase, count + 1);
+
+      return {
+        id: count ? `${keyBase}-${count + 1}` : keyBase,
+        title: count ? `${titleValue} ${count + 1}` : titleValue,
+        content: child,
+      };
+    });
+  }, [children]);
+
+  const [selectedKey, setSelectedKey] = useState<string | undefined>(blocks[0]?.id);
+  const selected = blocks.some(block => block.id === selectedKey) ? selectedKey : blocks[0]?.id;
+
+  if (!blocks.length) {
+    return null;
+  }
+
+  if (blocks.length === 1) {
+    return <div className={styles.tabs}>{blocks[0].content}</div>;
+  }
+
+  return (
+    <TabsPrimitive
+      value={selected}
+      onValueChange={setSelectedKey}
+      className="my-4 gap-0 overflow-hidden rounded-lg bg-muted/50 [&_[data-slot=code-block]]:my-0 [&_[data-slot=code-block]]:rounded-none [&_[data-slot=code-block]]:border-0 [&_[data-slot=code-block]]:bg-transparent"
+    >
+      <TabsList
+        variant="line"
+        className="h-9 w-full justify-start gap-5 overflow-x-auto overflow-y-hidden rounded-none px-3 py-0 shadow-[inset_0_-1px_0_var(--border)] [scrollbar-width:none] [&::-webkit-scrollbar]:hidden"
+        aria-label="Code snippets"
+      >
+        {blocks.map(block => (
+          <TabsTrigger
+            key={block.id}
+            value={block.id}
+            className="flex-none px-0 text-muted-foreground after:bg-primary data-active:text-foreground"
+          >
+            {block.title}
+          </TabsTrigger>
+        ))}
+      </TabsList>
+      {blocks.map(block => (
+        <TabsContent key={block.id} value={block.id}>
+          {block.content}
+        </TabsContent>
+      ))}
+    </TabsPrimitive>
+  );
+}

package/src/components/docs/Columns.tsx

@@ -0,0 +1,20 @@
+import type { ReactNode } from 'react';
+import { styles } from './styles';
+import { gridColsClass } from './utils';
+
+export interface ColumnsProps {
+  children?: ReactNode;
+  cols?: 1 | 2 | 3 | 4;
+}
+
+export function Columns({ children, cols = 2 }: ColumnsProps) {
+  return <div className={`${styles.grid} ${styles[gridColsClass(cols)]}`}>{children}</div>;
+}
+
+export interface ColumnProps {
+  children?: ReactNode;
+}
+
+export function Column({ children }: ColumnProps) {
+  return <div className={styles.column}>{children}</div>;
+}

package/src/components/docs/Expandable.tsx

@@ -0,0 +1,28 @@
+import type { ReactNode } from 'react';
+import { ChevronRight } from '@/components/icons';
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@/components/ui/collapsible';
+import { styles } from './styles';
+
+export interface ExpandableProps {
+  title: ReactNode;
+  children?: ReactNode;
+  defaultOpen?: boolean;
+}
+
+export function Expandable({ title, children, defaultOpen = false }: ExpandableProps) {
+  return (
+    <Collapsible defaultOpen={defaultOpen} className={styles.accordion}>
+      <div className={styles.accordionItem}>
+        <CollapsibleTrigger
+          className={`${styles.expandableTrigger} group/collapsible-trigger flex w-full justify-start gap-2 text-left outline-none focus-visible:ring-3 focus-visible:ring-ring/50`}
+        >
+          <ChevronRight className="size-4 shrink-0 text-muted-foreground transition-transform group-aria-expanded/collapsible-trigger:rotate-90" />
+          {title}
+        </CollapsibleTrigger>
+        <CollapsibleContent>
+          <div className={styles.accordionContent}>{children}</div>
+        </CollapsibleContent>
+      </div>
+    </Collapsible>
+  );
+}

package/src/components/docs/Frame.tsx

@@ -0,0 +1,56 @@
+import {
+  Children,
+  cloneElement,
+  isValidElement,
+  type ReactElement,
+  type ReactNode,
+  type VideoHTMLAttributes,
+} from 'react';
+import { Hand } from '@/components/icons';
+import { renderInlineMarkdown } from '@/lib/inline-markdown';
+import { styles } from './styles';
+
+export interface FrameProps {
+  caption?: ReactNode;
+  hint?: ReactNode;
+  children?: ReactNode;
+}
+
+function renderFrameText(value: ReactNode) {
+  return typeof value === 'string' ? renderInlineMarkdown(value) : value;
+}
+
+function enhanceAutoplayVideos(children: ReactNode) {
+  return Children.map(children, child => {
+    if (!isValidElement(child) || child.type !== 'video') {
+      return child;
+    }
+
+    const video = child as ReactElement<VideoHTMLAttributes<HTMLVideoElement>, 'video'>;
+
+    return video.props.autoPlay
+      ? cloneElement(video, { playsInline: true, loop: true, muted: true })
+      : video;
+  });
+}
+
+export function Frame({ caption, hint, children }: FrameProps) {
+  return (
+    <div className={styles.frameWrapper}>
+      {hint ? (
+        <div className={styles.frameHint}>
+          <span className={styles.frameHintIcon} aria-hidden={true}>
+            <Hand />
+          </span>
+          <span>{renderFrameText(hint)}</span>
+        </div>
+      ) : null}
+      <figure className={styles.frame}>
+        <div className={styles.frameContent}>{enhanceAutoplayVideos(children)}</div>
+        {caption ? (
+          <figcaption className={styles.frameCaption}>{renderFrameText(caption)}</figcaption>
+        ) : null}
+      </figure>
+    </div>
+  );
+}

package/src/components/docs/Icon.tsx

@@ -0,0 +1,30 @@
+import { getIcon } from '@/lib/icons';
+import { styles } from './styles';
+
+export interface IconProps {
+  icon?: string;
+  src?: string;
+  color?: string;
+  size?: number;
+  className?: string;
+}
+
+export function Icon({ icon, src, color, size = 16, className }: IconProps) {
+  const classes = className ? `${styles.icon} ${className}` : styles.icon;
+
+  if (src) {
+    return <img src={src} alt="" width={size} height={size} className={classes} />;
+  }
+
+  if (!icon) {
+    return null;
+  }
+
+  const Component = getIcon(icon);
+
+  if (!Component) {
+    return null;
+  }
+
+  return <Component size={size} color={color} className={classes} />;
+}

package/src/components/docs/ParamField.tsx

@@ -0,0 +1,45 @@
+import type { ReactNode } from 'react';
+import { Badge } from './Badge';
+import { styles } from './styles';
+import { decodeHtmlEntities } from './utils';
+
+export interface ParamFieldProps {
+  name?: string;
+  query?: string;
+  path?: string;
+  header?: string;
+  body?: string;
+  type?: string;
+  required?: boolean;
+  children?: ReactNode;
+}
+
+export function ParamField({
+  name,
+  query,
+  path,
+  header,
+  body,
+  type,
+  required,
+  children,
+}: ParamFieldProps) {
+  const label = name || query || path || header || body || 'parameter';
+  const location = query ? 'query' : path ? 'path' : header ? 'header' : body ? 'body' : undefined;
+
+  return (
+    <div className={styles.paramField}>
+      <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}
+      </div>
+      {children ? <div className={styles.fieldBody}>{children}</div> : null}
+    </div>
+  );
+}
+
+export function Param({ children }: { children?: ReactNode }) {
+  return <code className={styles.code}>{children}</code>;
+}