@hanzo/ui 5.3.25 → 5.3.28

package/docs/layouts/docs/index.tsx

@@ -0,0 +1,321 @@
+import type * as PageTree from '@hanzo/docs-core/page-tree';
+import {
+  type ComponentProps,
+  type HTMLAttributes,
+  type ReactNode,
+  useMemo,
+} from 'react';
+import { Languages, Sidebar as SidebarIcon } from '@icons';
+import { cn } from '@/utils/cn';
+import { buttonVariants } from '@/components/ui/button';
+import {
+  Sidebar,
+  SidebarCollapseTrigger,
+  SidebarContent,
+  SidebarDrawer,
+  SidebarLinkItem,
+  SidebarPageTree,
+  SidebarTrigger,
+  SidebarViewport,
+} from './sidebar';
+import { type BaseLayoutProps, resolveLinkItems } from '@/layouts/shared';
+import { LinkItem } from '@/layouts/shared/link-item';
+import {
+  LanguageToggle,
+  LanguageToggleText,
+} from '@/layouts/shared/language-toggle';
+import {
+  LayoutBody,
+  LayoutContextProvider,
+  LayoutHeader,
+  LayoutTabs,
+} from './client';
+import { TreeContextProvider } from '@/contexts/tree';
+import { ThemeToggle } from '../shared/theme-toggle';
+import Link from '@hanzo/docs-core/link';
+import {
+  LargeSearchToggle,
+  SearchToggle,
+} from '@/layouts/shared/search-toggle';
+import {
+  getSidebarTabs,
+  type GetSidebarTabsOptions,
+} from '@/components/sidebar/tabs';
+import type { SidebarPageTreeComponents } from '@/components/sidebar/page-tree';
+import {
+  SidebarTabsDropdown,
+  type SidebarTabWithProps,
+} from '@/components/sidebar/tabs/dropdown';
+
+export interface DocsLayoutProps extends BaseLayoutProps {
+  tree: PageTree.Root;
+
+  sidebar?: SidebarOptions;
+
+  tabMode?: 'top' | 'auto';
+
+  /**
+   * Props for the `div` container
+   */
+  containerProps?: HTMLAttributes<HTMLDivElement>;
+}
+
+interface SidebarOptions
+  extends
+    ComponentProps<'aside'>,
+    Pick<ComponentProps<typeof Sidebar>, 'defaultOpenLevel' | 'prefetch'> {
+  enabled?: boolean;
+  component?: ReactNode;
+  components?: Partial<SidebarPageTreeComponents>;
+
+  /**
+   * Root Toggle options
+   */
+  tabs?: SidebarTabWithProps[] | GetSidebarTabsOptions | false;
+
+  banner?: ReactNode;
+  footer?: ReactNode;
+
+  /**
+   * Support collapsing the sidebar on desktop mode
+   *
+   * @defaultValue true
+   */
+  collapsible?: boolean;
+}
+
+export function DocsLayout({
+  nav: { transparentMode, ...nav } = {},
+  sidebar: {
+    tabs: sidebarTabs,
+    enabled: sidebarEnabled = true,
+    defaultOpenLevel,
+    prefetch,
+    ...sidebarProps
+  } = {},
+  searchToggle = {},
+  themeSwitch = {},
+  tabMode = 'auto',
+  i18n = false,
+  children,
+  tree,
+  ...props
+}: DocsLayoutProps) {
+  const tabs = useMemo(() => {
+    if (Array.isArray(sidebarTabs)) {
+      return sidebarTabs;
+    }
+    if (typeof sidebarTabs === 'object') {
+      return getSidebarTabs(tree, sidebarTabs);
+    }
+    if (sidebarTabs !== false) {
+      return getSidebarTabs(tree);
+    }
+    return [];
+  }, [tree, sidebarTabs]);
+  const links = resolveLinkItems(props);
+
+  function sidebar() {
+    const {
+      footer,
+      banner,
+      collapsible = true,
+      component,
+      components,
+      ...rest
+    } = sidebarProps;
+    if (component) return component;
+
+    const iconLinks = links.filter((item) => item.type === 'icon');
+    const viewport = (
+      <SidebarViewport>
+        {links
+          .filter((v) => v.type !== 'icon')
+          .map((item, i, list) => (
+            <SidebarLinkItem
+              key={i}
+              item={item}
+              className={cn(i === list.length - 1 && 'mb-4')}
+            />
+          ))}
+        <SidebarPageTree {...components} />
+      </SidebarViewport>
+    );
+
+    return (
+      <>
+        <SidebarContent {...rest}>
+          <div className="flex flex-col gap-3 p-4 pb-2">
+            <div className="flex">
+              <Link
+                href={nav.url ?? '/'}
+                className="inline-flex text-[0.9375rem] items-center gap-2.5 font-medium me-auto"
+              >
+                {nav.title}
+              </Link>
+              {nav.children}
+              {collapsible && (
+                <SidebarCollapseTrigger
+                  className={cn(
+                    buttonVariants({
+                      color: 'ghost',
+                      size: 'icon-sm',
+                      className: 'mb-auto text-fd-muted-foreground',
+                    }),
+                  )}
+                >
+                  <SidebarIcon />
+                </SidebarCollapseTrigger>
+              )}
+            </div>
+            {searchToggle.enabled !== false &&
+              (searchToggle.components?.lg ?? (
+                <LargeSearchToggle hideIfDisabled />
+              ))}
+            {tabs.length > 0 && tabMode === 'auto' && (
+              <SidebarTabsDropdown options={tabs} />
+            )}
+            {banner}
+          </div>
+          {viewport}
+          {(i18n ||
+            iconLinks.length > 0 ||
+            themeSwitch?.enabled !== false ||
+            footer) && (
+            <div className="flex flex-col border-t p-4 pt-2 empty:hidden">
+              <div className="flex text-fd-muted-foreground items-center empty:hidden">
+                {i18n && (
+                  <LanguageToggle>
+                    <Languages className="size-4.5" />
+                  </LanguageToggle>
+                )}
+                {iconLinks.map((item, i) => (
+                  <LinkItem
+                    key={i}
+                    item={item}
+                    className={cn(
+                      buttonVariants({ size: 'icon-sm', color: 'ghost' }),
+                    )}
+                    aria-label={item.label}
+                  >
+                    {item.icon}
+                  </LinkItem>
+                ))}
+                {themeSwitch.enabled !== false &&
+                  (themeSwitch.component ?? (
+                    <ThemeToggle
+                      className="ms-auto p-0"
+                      mode={themeSwitch.mode}
+                    />
+                  ))}
+              </div>
+              {footer}
+            </div>
+          )}
+        </SidebarContent>
+        <SidebarDrawer>
+          <div className="flex flex-col gap-3 p-4 pb-2">
+            <div className="flex text-fd-muted-foreground items-center gap-1.5">
+              <div className="flex flex-1">
+                {iconLinks.map((item, i) => (
+                  <LinkItem
+                    key={i}
+                    item={item}
+                    className={cn(
+                      buttonVariants({
+                        size: 'icon-sm',
+                        color: 'ghost',
+                        className: 'p-2',
+                      }),
+                    )}
+                    aria-label={item.label}
+                  >
+                    {item.icon}
+                  </LinkItem>
+                ))}
+              </div>
+              {i18n && (
+                <LanguageToggle>
+                  <Languages className="size-4.5" />
+                  <LanguageToggleText />
+                </LanguageToggle>
+              )}
+              {themeSwitch.enabled !== false &&
+                (themeSwitch.component ?? (
+                  <ThemeToggle className="p-0" mode={themeSwitch.mode} />
+                ))}
+              <SidebarTrigger
+                className={cn(
+                  buttonVariants({
+                    color: 'ghost',
+                    size: 'icon-sm',
+                    className: 'p-2',
+                  }),
+                )}
+              >
+                <SidebarIcon />
+              </SidebarTrigger>
+            </div>
+            {tabs.length > 0 && <SidebarTabsDropdown options={tabs} />}
+            {banner}
+          </div>
+          {viewport}
+          <div className="flex flex-col border-t p-4 pt-2 empty:hidden">
+            {footer}
+          </div>
+        </SidebarDrawer>
+      </>
+    );
+  }
+
+  return (
+    <TreeContextProvider tree={tree}>
+      <LayoutContextProvider navTransparentMode={transparentMode}>
+        <Sidebar defaultOpenLevel={defaultOpenLevel} prefetch={prefetch}>
+          <LayoutBody {...props.containerProps}>
+            {nav.enabled !== false &&
+              (nav.component ?? (
+                <LayoutHeader
+                  id="nd-subnav"
+                  className="[grid-area:header] sticky top-(--fd-docs-row-1) z-30 flex items-center ps-4 pe-2.5 border-b transition-colors backdrop-blur-sm h-(--fd-header-height) md:hidden max-md:layout:[--fd-header-height:--spacing(14)] data-[transparent=false]:bg-fd-background/80"
+                >
+                  <Link
+                    href={nav.url ?? '/'}
+                    className="inline-flex items-center gap-2.5 font-semibold"
+                  >
+                    {nav.title}
+                  </Link>
+                  <div className="flex-1">{nav.children}</div>
+                  {searchToggle.enabled !== false &&
+                    (searchToggle.components?.sm ?? (
+                      <SearchToggle className="p-2" hideIfDisabled />
+                    ))}
+                  {sidebarEnabled && (
+                    <SidebarTrigger
+                      className={cn(
+                        buttonVariants({
+                          color: 'ghost',
+                          size: 'icon-sm',
+                          className: 'p-2',
+                        }),
+                      )}
+                    >
+                      <SidebarIcon />
+                    </SidebarTrigger>
+                  )}
+                </LayoutHeader>
+              ))}
+            {sidebarEnabled && sidebar()}
+            {tabMode === 'top' && tabs.length > 0 && (
+              <LayoutTabs
+                options={tabs}
+                className="z-10 bg-fd-background border-b px-6 pt-3 xl:px-8 max-md:hidden"
+              />
+            )}
+            {children}
+          </LayoutBody>
+        </Sidebar>
+      </LayoutContextProvider>
+    </TreeContextProvider>
+  );
+}

package/docs/layouts/docs/page/client.tsx

@@ -0,0 +1,376 @@
+'use client';
+
+import {
+  type ComponentProps,
+  createContext,
+  Fragment,
+  use,
+  useEffect,
+  useEffectEvent,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { ChevronDown, ChevronLeft, ChevronRight } from '@icons';
+import Link from '@hanzo/docs-core/link';
+import { cn } from '@/utils/cn';
+import { useI18n } from '@/contexts/i18n';
+import { useTreeContext, useTreePath } from '@/contexts/tree';
+import type * as PageTree from '@hanzo/docs-core/page-tree';
+import { usePathname } from '@hanzo/docs-core/framework';
+import {
+  type BreadcrumbOptions,
+  getBreadcrumbItemsFromPath,
+} from '@hanzo/docs-core/breadcrumb';
+import { isActive } from '@/utils/is-active';
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from '@/components/ui/collapsible';
+import { useTOCItems } from '@/components/toc';
+import { useActiveAnchor } from '@hanzo/docs-core/toc';
+import { LayoutContext } from '../client';
+import { useFooterItems } from '@/utils/use-footer-items';
+
+const TocPopoverContext = createContext<{
+  open: boolean;
+  setOpen: (open: boolean) => void;
+} | null>(null);
+
+export function PageTOCPopover({
+  className,
+  children,
+  ...rest
+}: ComponentProps<'div'>) {
+  const ref = useRef<HTMLElement>(null);
+  const [open, setOpen] = useState(false);
+  const { isNavTransparent } = use(LayoutContext)!;
+
+  const onClick = useEffectEvent((e: Event) => {
+    if (!open) return;
+
+    if (ref.current && !ref.current.contains(e.target as HTMLElement))
+      setOpen(false);
+  });
+
+  useEffect(() => {
+    window.addEventListener('click', onClick);
+
+    return () => {
+      window.removeEventListener('click', onClick);
+    };
+  }, []);
+
+  return (
+    <TocPopoverContext
+      value={useMemo(
+        () => ({
+          open,
+          setOpen,
+        }),
+        [setOpen, open],
+      )}
+    >
+      <Collapsible
+        open={open}
+        onOpenChange={setOpen}
+        data-toc-popover=""
+        className={cn(
+          'sticky top-(--fd-docs-row-2) z-10 [grid-area:toc-popover] h-(--fd-toc-popover-height) xl:hidden max-xl:layout:[--fd-toc-popover-height:--spacing(10)]',
+          className,
+        )}
+        {...rest}
+      >
+        <header
+          ref={ref}
+          className={cn(
+            'border-b backdrop-blur-sm transition-colors',
+            (!isNavTransparent || open) && 'bg-fd-background/80',
+            open && 'shadow-lg',
+          )}
+        >
+          {children}
+        </header>
+      </Collapsible>
+    </TocPopoverContext>
+  );
+}
+
+export function PageTOCPopoverTrigger({
+  className,
+  ...props
+}: ComponentProps<'button'>) {
+  const { text } = useI18n();
+  const { open } = use(TocPopoverContext)!;
+  const items = useTOCItems();
+  const active = useActiveAnchor();
+  const selected = useMemo(
+    () => items.findIndex((item) => active === item.url.slice(1)),
+    [items, active],
+  );
+  const path = useTreePath().at(-1);
+  const showItem = selected !== -1 && !open;
+
+  return (
+    <CollapsibleTrigger
+      className={cn(
+        'flex w-full h-10 items-center text-sm text-fd-muted-foreground gap-2.5 px-4 py-2.5 text-start focus-visible:outline-none [&_svg]:size-4 md:px-6',
+        className,
+      )}
+      data-toc-popover-trigger=""
+      {...props}
+    >
+      <ProgressCircle
+        value={(selected + 1) / Math.max(1, items.length)}
+        max={1}
+        className={cn('shrink-0', open && 'text-fd-primary')}
+      />
+      <span className="grid flex-1 *:my-auto *:row-start-1 *:col-start-1">
+        <span
+          className={cn(
+            'truncate transition-all',
+            open && 'text-fd-foreground',
+            showItem && 'opacity-0 -translate-y-full pointer-events-none',
+          )}
+        >
+          {path?.name ?? text.toc}
+        </span>
+        <span
+          className={cn(
+            'truncate transition-all',
+            !showItem && 'opacity-0 translate-y-full pointer-events-none',
+          )}
+        >
+          {items[selected]?.title}
+        </span>
+      </span>
+      <ChevronDown
+        className={cn(
+          'shrink-0 transition-transform mx-0.5',
+          open && 'rotate-180',
+        )}
+      />
+    </CollapsibleTrigger>
+  );
+}
+
+interface ProgressCircleProps extends Omit<
+  React.ComponentProps<'svg'>,
+  'strokeWidth'
+> {
+  value: number;
+  strokeWidth?: number;
+  size?: number;
+  min?: number;
+  max?: number;
+}
+
+function clamp(input: number, min: number, max: number): number {
+  if (input < min) return min;
+  if (input > max) return max;
+  return input;
+}
+
+function ProgressCircle({
+  value,
+  strokeWidth = 2,
+  size = 24,
+  min = 0,
+  max = 100,
+  ...restSvgProps
+}: ProgressCircleProps) {
+  const normalizedValue = clamp(value, min, max);
+  const radius = (size - strokeWidth) / 2;
+  const circumference = 2 * Math.PI * radius;
+  const progress = (normalizedValue / max) * circumference;
+  const circleProps = {
+    cx: size / 2,
+    cy: size / 2,
+    r: radius,
+    fill: 'none',
+    strokeWidth,
+  };
+
+  return (
+    <svg
+      role="progressbar"
+      viewBox={`0 0 ${size} ${size}`}
+      aria-valuenow={normalizedValue}
+      aria-valuemin={min}
+      aria-valuemax={max}
+      {...restSvgProps}
+    >
+      <circle {...circleProps} className="stroke-current/25" />
+      <circle
+        {...circleProps}
+        stroke="currentColor"
+        strokeDasharray={circumference}
+        strokeDashoffset={circumference - progress}
+        strokeLinecap="round"
+        transform={`rotate(-90 ${size / 2} ${size / 2})`}
+        className="transition-all"
+      />
+    </svg>
+  );
+}
+
+export function PageTOCPopoverContent(props: ComponentProps<'div'>) {
+  return (
+    <CollapsibleContent
+      data-toc-popover-content=""
+      {...props}
+      className={cn('flex flex-col px-4 max-h-[50vh] md:px-6', props.className)}
+    >
+      {props.children}
+    </CollapsibleContent>
+  );
+}
+
+export function PageLastUpdate({
+  date: value,
+  ...props
+}: Omit<ComponentProps<'p'>, 'children'> & { date: Date }) {
+  const { text } = useI18n();
+  const [date, setDate] = useState('');
+
+  useEffect(() => {
+    // to the timezone of client
+    setDate(value.toLocaleDateString());
+  }, [value]);
+
+  return (
+    <p
+      {...props}
+      className={cn('text-sm text-fd-muted-foreground', props.className)}
+    >
+      {text.lastUpdate} {date}
+    </p>
+  );
+}
+
+type Item = Pick<PageTree.Item, 'name' | 'description' | 'url'>;
+export interface FooterProps extends ComponentProps<'div'> {
+  /**
+   * Items including information for the next and previous page
+   */
+  items?: {
+    previous?: Item;
+    next?: Item;
+  };
+}
+
+export function PageFooter({ items, ...props }: FooterProps) {
+  const footerList = useFooterItems();
+  const pathname = usePathname();
+
+  const { previous, next } = useMemo(() => {
+    if (items) return items;
+
+    const idx = footerList.findIndex((item) =>
+      isActive(item.url, pathname, false),
+    );
+
+    if (idx === -1) return {};
+    return {
+      previous: footerList[idx - 1],
+      next: footerList[idx + 1],
+    };
+  }, [footerList, items, pathname]);
+
+  return (
+    <div
+      {...props}
+      className={cn(
+        '@container grid gap-4',
+        previous && next ? 'grid-cols-2' : 'grid-cols-1',
+        props.className,
+      )}
+    >
+      {previous ? <FooterItem item={previous} index={0} /> : null}
+      {next ? <FooterItem item={next} index={1} /> : null}
+    </div>
+  );
+}
+
+function FooterItem({ item, index }: { item: Item; index: 0 | 1 }) {
+  const { text } = useI18n();
+  const Icon = index === 0 ? ChevronLeft : ChevronRight;
+
+  return (
+    <Link
+      href={item.url}
+      className={cn(
+        'flex flex-col gap-2 rounded-lg border p-4 text-sm transition-colors hover:bg-fd-accent/80 hover:text-fd-accent-foreground @max-lg:col-span-full',
+        index === 1 && 'text-end',
+      )}
+    >
+      <div
+        className={cn(
+          'inline-flex items-center gap-1.5 font-medium',
+          index === 1 && 'flex-row-reverse',
+        )}
+      >
+        <Icon className="-mx-1 size-4 shrink-0 rtl:rotate-180" />
+        <p>{item.name}</p>
+      </div>
+      <p className="text-fd-muted-foreground truncate">
+        {item.description ?? (index === 0 ? text.previousPage : text.nextPage)}
+      </p>
+    </Link>
+  );
+}
+
+export type BreadcrumbProps = BreadcrumbOptions & ComponentProps<'div'>;
+
+export function PageBreadcrumb({
+  includeRoot,
+  includeSeparator,
+  includePage,
+  ...props
+}: BreadcrumbProps) {
+  const path = useTreePath();
+  const { root } = useTreeContext();
+  const items = useMemo(() => {
+    return getBreadcrumbItemsFromPath(root, path, {
+      includePage,
+      includeSeparator,
+      includeRoot,
+    });
+  }, [includePage, includeRoot, includeSeparator, path, root]);
+
+  if (items.length === 0) return null;
+
+  return (
+    <div
+      {...props}
+      className={cn(
+        'flex items-center gap-1.5 text-sm text-fd-muted-foreground',
+        props.className,
+      )}
+    >
+      {items.map((item, i) => {
+        const className = cn(
+          'truncate',
+          i === items.length - 1 && 'text-fd-primary font-medium',
+        );
+
+        return (
+          <Fragment key={i}>
+            {i !== 0 && <ChevronRight className="size-3.5 shrink-0" />}
+            {item.url ? (
+              <Link
+                href={item.url}
+                className={cn(className, 'transition-opacity hover:opacity-80')}
+              >
+                {item.name}
+              </Link>
+            ) : (
+              <span className={className}>{item.name}</span>
+            )}
+          </Fragment>
+        );
+      })}
+    </div>
+  );
+}