@hanzo/ui 5.3.26 → 5.3.29

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

@@ -0,0 +1,375 @@
+'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>
+  );
+}

package/docs/layouts/notebook/page/index.tsx

@@ -0,0 +1,251 @@
+import type { ComponentProps, ReactNode } from 'react';
+import { cn } from '@/utils/cn';
+import { buttonVariants } from '@/components/ui/button';
+import { Edit, Text } from '@icons';
+import { I18nLabel } from '@/contexts/i18n';
+import {
+  type BreadcrumbProps,
+  type FooterProps,
+  PageBreadcrumb,
+  PageFooter,
+  PageTOCPopover,
+  PageTOCPopoverContent,
+  PageTOCPopoverTrigger,
+} from './client';
+import type { AnchorProviderProps, TOCItemType } from '@hanzo/docs-core/toc';
+import * as TocDefault from '@/components/toc/default';
+import * as TocClerk from '@/components/toc/clerk';
+import { TOCProvider, TOCScrollArea } from '@/components/toc';
+
+interface BreadcrumbOptions extends BreadcrumbProps {
+  enabled: boolean;
+  component: ReactNode;
+}
+
+interface FooterOptions extends FooterProps {
+  enabled: boolean;
+  component: ReactNode;
+}
+
+export interface DocsPageProps {
+  toc?: TOCItemType[];
+  tableOfContent?: Partial<TableOfContentOptions>;
+  tableOfContentPopover?: Partial<TableOfContentPopoverOptions>;
+
+  /**
+   * Extend the page to fill all available space
+   *
+   * @defaultValue false
+   */
+  full?: boolean;
+
+  /**
+   * Replace or disable breadcrumb
+   */
+  breadcrumb?: Partial<BreadcrumbOptions>;
+
+  /**
+   * Footer navigation, you can disable it by passing `false`
+   */
+  footer?: Partial<FooterOptions>;
+
+  children?: ReactNode;
+}
+
+type TableOfContentOptions = Pick<AnchorProviderProps, 'single'> & {
+  /**
+   * Custom content in TOC container, before the main TOC
+   */
+  header?: ReactNode;
+
+  /**
+   * Custom content in TOC container, after the main TOC
+   */
+  footer?: ReactNode;
+
+  enabled: boolean;
+  component: ReactNode;
+
+  /**
+   * @defaultValue 'normal'
+   */
+  style?: 'normal' | 'clerk';
+};
+
+type TableOfContentPopoverOptions = Omit<TableOfContentOptions, 'single'>;
+
+export function DocsPage({
+  breadcrumb: {
+    enabled: breadcrumbEnabled = true,
+    component: breadcrumb,
+    ...breadcrumbProps
+  } = {},
+  footer = {},
+  full = false,
+  tableOfContentPopover: {
+    enabled: tocPopoverEnabled,
+    component: tocPopover,
+    ...tocPopoverOptions
+  } = {},
+  tableOfContent: {
+    enabled: tocEnabled,
+    component: tocReplace,
+    ...tocOptions
+  } = {},
+  toc = [],
+  children,
+}: DocsPageProps) {
+  // disable TOC on full mode, you can still enable it with `enabled` option.
+  tocEnabled ??=
+    !full &&
+    (toc.length > 0 ||
+      tocOptions.footer !== undefined ||
+      tocOptions.header !== undefined);
+
+  tocPopoverEnabled ??=
+    toc.length > 0 ||
+    tocPopoverOptions.header !== undefined ||
+    tocPopoverOptions.footer !== undefined;
+
+  let wrapper = (children: ReactNode) => children;
+
+  if (tocEnabled || tocPopoverEnabled) {
+    wrapper = (children) => (
+      <TOCProvider single={tocOptions.single} toc={toc}>
+        {children}
+      </TOCProvider>
+    );
+  }
+
+  return wrapper(
+    <>
+      {tocPopoverEnabled &&
+        (tocPopover ?? (
+          <PageTOCPopover>
+            <PageTOCPopoverTrigger />
+            <PageTOCPopoverContent>
+              {tocPopoverOptions.header}
+              <TOCScrollArea>
+                {tocPopoverOptions.style === 'clerk' ? (
+                  <TocClerk.TOCItems />
+                ) : (
+                  <TocDefault.TOCItems />
+                )}
+              </TOCScrollArea>
+              {tocPopoverOptions.footer}
+            </PageTOCPopoverContent>
+          </PageTOCPopover>
+        ))}
+      <article
+        id="nd-page"
+        data-full={full}
+        className={cn(
+          'flex flex-col [grid-area:main] px-4 py-6 gap-4 md:px-6 md:pt-8 xl:px-8 xl:pt-14 *:max-w-[900px]',
+          full && '*:max-w-[1285px]',
+        )}
+      >
+        {breadcrumbEnabled &&
+          (breadcrumb ?? <PageBreadcrumb {...breadcrumbProps} />)}
+        {children}
+        {footer.enabled !== false &&
+          (footer.component ?? <PageFooter items={footer.items} />)}
+      </article>
+      {tocEnabled &&
+        (tocReplace ?? (
+          <div
+            id="nd-toc"
+            className="sticky top-(--fd-docs-row-3) [grid-area:toc] h-[calc(var(--fd-docs-height)-var(--fd-docs-row-3))] flex flex-col w-(--fd-toc-width) pt-12 pe-4 pb-2 xl:layout:[--fd-toc-width:268px] max-xl:hidden"
+          >
+            {tocOptions.header}
+            <h3
+              id="toc-title"
+              className="inline-flex items-center gap-1.5 text-sm text-fd-muted-foreground"
+            >
+              <Text className="size-4" />
+              <I18nLabel label="toc" />
+            </h3>
+            <TOCScrollArea>
+              {tocOptions.style === 'clerk' ? (
+                <TocClerk.TOCItems />
+              ) : (
+                <TocDefault.TOCItems />
+              )}
+            </TOCScrollArea>
+            {tocOptions.footer}
+          </div>
+        ))}
+    </>,
+  );
+}
+
+export function EditOnGitHub(props: ComponentProps<'a'>) {
+  return (
+    <a
+      target="_blank"
+      rel="noreferrer noopener"
+      {...props}
+      className={cn(
+        buttonVariants({
+          color: 'secondary',
+          size: 'sm',
+          className: 'gap-1.5 not-prose',
+        }),
+        props.className,
+      )}
+    >
+      {props.children ?? (
+        <>
+          <Edit className="size-3.5" />
+          <I18nLabel label="editOnGithub" />
+        </>
+      )}
+    </a>
+  );
+}
+
+/**
+ * Add typography styles
+ */
+export function DocsBody({
+  children,
+  className,
+  ...props
+}: ComponentProps<'div'>) {
+  return (
+    <div {...props} className={cn('prose flex-1', className)}>
+      {children}
+    </div>
+  );
+}
+
+export function DocsDescription({
+  children,
+  className,
+  ...props
+}: ComponentProps<'p'>) {
+  // Don't render if no description provided
+  if (children === undefined) return null;
+
+  return (
+    <p
+      {...props}
+      className={cn('mb-8 text-lg text-fd-muted-foreground', className)}
+    >
+      {children}
+    </p>
+  );
+}
+
+export function DocsTitle({
+  children,
+  className,
+  ...props
+}: ComponentProps<'h1'>) {
+  return (
+    <h1 {...props} className={cn('text-[1.75em] font-semibold', className)}>
+      {children}
+    </h1>
+  );
+}
+
+export { PageLastUpdate, PageBreadcrumb } from './client';