@umami/shiso 0.55.0 → 1.0.0

package/src/components/TopNav.tsx

@@ -0,0 +1,127 @@
+import classNames from 'classnames';
+import { Link, useLocation, useNavigate } from 'react-router';
+import { ConfiguredIcon } from '@/components/ConfiguredIcon';
+import { ChevronRight } from '@/components/icons';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import type { DocsTab, LinkTarget, NavNode, NormalizedDocsConfig } from '@/lib/types';
+
+interface MenuLink {
+  label: string;
+  href: string;
+  target: LinkTarget;
+  routed: boolean;
+}
+
+function collectMenuLinks(nodes: NavNode[]): MenuLink[] {
+  const links: MenuLink[] = [];
+
+  for (const node of nodes) {
+    if (node.kind === 'page') {
+      if (!node.page.hidden) {
+        links.push({ label: node.page.label, href: node.page.url, target: '_self', routed: true });
+      }
+    } else if (node.kind === 'link') {
+      if (!node.hidden) {
+        links.push({ label: node.label, href: node.href, target: node.target, routed: false });
+      }
+    } else if (!node.hidden) {
+      if (node.root && !node.root.page.hidden) {
+        links.push({
+          label: node.root.page.label,
+          href: node.root.page.url,
+          target: '_self',
+          routed: true,
+        });
+      }
+      links.push(...collectMenuLinks(node.children));
+    }
+  }
+
+  return links;
+}
+
+export function TopNav({ docs, label }: { docs: NormalizedDocsConfig; label: string }) {
+  const { pathname } = useLocation();
+  const navigate = useNavigate();
+  const tabs = docs.tabs.filter(tab => !tab.hidden);
+
+  if (!tabs.length) {
+    return null;
+  }
+
+  const page = docs.pages.find(item => item.url === pathname);
+  const selected =
+    page?.tabId ||
+    [...tabs]
+      .sort((a, b) => b.url.length - a.url.length)
+      .find(tab => pathname === tab.url || pathname.startsWith(`${tab.url}/`))?.id ||
+    tabs[0]?.id;
+  const tabClass = (tab: DocsTab) =>
+    classNames(
+      'flex h-full items-center gap-1 whitespace-nowrap border-transparent border-b-2 font-medium',
+      {
+        'border-b-primary text-foreground': tab.id === selected,
+        'text-muted-foreground hover:text-foreground': tab.id !== selected,
+      },
+    );
+
+  return (
+    <nav
+      className="hidden h-[calc(100%+1px)] max-w-screen self-start items-center gap-7 overflow-x-auto text-sm [scrollbar-width:none] lg:flex [&::-webkit-scrollbar]:hidden"
+      aria-label={label}
+    >
+      {tabs.map(tab => {
+        if (tab.presentation === 'dropdown') {
+          const menuLinks = collectMenuLinks(docs.navigation[tab.id] || []);
+
+          return (
+            <DropdownMenu key={tab.id}>
+              <DropdownMenuTrigger render={<button type="button" className={tabClass(tab)} />}>
+                <ConfiguredIcon icon={tab.icon} />
+                {tab.label}
+                <ChevronRight className="size-3.5 rotate-90" />
+              </DropdownMenuTrigger>
+              <DropdownMenuContent align="start" className="min-w-48">
+                {menuLinks.map(item => (
+                  <DropdownMenuItem
+                    key={item.href}
+                    onClick={() => {
+                      if (item.routed) {
+                        navigate(item.href);
+                      } else {
+                        window.open(
+                          item.href,
+                          item.target,
+                          item.target === '_blank' ? 'noreferrer' : undefined,
+                        );
+                      }
+                    }}
+                  >
+                    {item.label}
+                  </DropdownMenuItem>
+                ))}
+              </DropdownMenuContent>
+            </DropdownMenu>
+          );
+        }
+
+        return (
+          <Link
+            key={tab.id}
+            to={tab.url}
+            className={tabClass(tab)}
+            aria-current={tab.id === selected ? 'page' : undefined}
+          >
+            <ConfiguredIcon icon={tab.icon} />
+            {tab.label}
+          </Link>
+        );
+      })}
+    </nav>
+  );
+}

package/src/components/VersionSwitcher.tsx

@@ -0,0 +1,60 @@
+import { useLocation, useNavigate } from 'react-router';
+import { Check, ChevronRight } from '@/components/icons';
+import { Button } from '@/components/ui/button';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { docsSite, getScopeByPathname } from '@/lib/site-config';
+
+/**
+ * Version selector for multi-version sites. Options come from the visible
+ * version scopes of the active language; selecting one navigates to that
+ * scope's first visible page. Hidden versions never appear as options, but a
+ * hidden version still shows as the current value while it is being viewed.
+ */
+export function VersionSwitcher() {
+  const { pathname } = useLocation();
+  const navigate = useNavigate();
+  const current = getScopeByPathname(pathname);
+  const options = docsSite.scopes.filter(
+    scope => scope.version && !scope.hidden && scope.language === current.language,
+  );
+
+  if (!current.version || (options.length < 2 && !current.hidden)) {
+    return null;
+  }
+
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger
+        render={
+          <Button
+            variant="outline"
+            className="h-auto gap-1.5 rounded-md bg-card px-2.5 py-1.5 text-sm font-medium text-foreground"
+          />
+        }
+      >
+        {current.version}
+        <ChevronRight className="size-3.5 rotate-90 text-muted-foreground" />
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="start" className="min-w-32">
+        {options.map(scope => (
+          <DropdownMenuItem
+            key={scope.id}
+            onClick={() => {
+              if (scope.id !== current.id) {
+                navigate(scope.firstPageUrl);
+              }
+            }}
+          >
+            <span className="grow">{scope.version}</span>
+            {scope.id === current.id ? <Check className="size-3.5" /> : null}
+          </DropdownMenuItem>
+        ))}
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}

package/src/components/docs/Accordion.tsx

@@ -0,0 +1,68 @@
+import type { ReactNode } from 'react';
+import {
+  AccordionContent,
+  AccordionItem,
+  Accordion as AccordionPrimitive,
+  AccordionTrigger,
+} from '@/components/ui/accordion';
+import { styles } from './styles';
+import { resolveIcon, toElementArray } from './utils';
+
+export interface AccordionProps {
+  title?: ReactNode;
+  icon?: ReactNode | string;
+  defaultOpen?: boolean;
+  children?: ReactNode;
+}
+
+function AccordionSection({ value, title, icon, children }: AccordionProps & { value: string }) {
+  return (
+    <AccordionItem value={value} className={styles.accordionItem}>
+      <AccordionTrigger className={styles.accordionTrigger}>
+        <span className="flex min-w-0 items-center gap-2">
+          {resolveIcon(icon)}
+          {title}
+        </span>
+      </AccordionTrigger>
+      <AccordionContent className={styles.accordionContent}>{children}</AccordionContent>
+    </AccordionItem>
+  );
+}
+
+export function Accordion({ title, icon, defaultOpen, children }: AccordionProps) {
+  const value = 'accordion-item';
+
+  return (
+    <AccordionPrimitive defaultValue={defaultOpen ? [value] : []} className={styles.accordion}>
+      <AccordionSection value={value} title={title} icon={icon}>
+        {children}
+      </AccordionSection>
+    </AccordionPrimitive>
+  );
+}
+
+export interface AccordionGroupProps {
+  children?: ReactNode;
+  defaultOpen?: boolean;
+}
+
+export function AccordionGroup({ children, defaultOpen = false }: AccordionGroupProps) {
+  const items = toElementArray<AccordionProps>(children);
+
+  if (!items.length) {
+    return null;
+  }
+
+  const values = items.map((_, index) => `accordion-${index + 1}`);
+  const defaultValue = values.filter((_, index) => {
+    return items[index].props.defaultOpen ?? (defaultOpen && index === 0);
+  });
+
+  return (
+    <AccordionPrimitive multiple defaultValue={defaultValue} className={styles.accordionGroup}>
+      {items.map((child, index) => (
+        <AccordionSection key={child.key ?? values[index]} value={values[index]} {...child.props} />
+      ))}
+    </AccordionPrimitive>
+  );
+}

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