@hanzo/ui 5.3.25 → 5.3.28

package/docs/layouts/docs/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 w-full max-w-[900px] mx-auto [grid-area:main] px-4 py-6 gap-4 md:px-6 md:pt-8 xl:px-8 xl:pt-14',
+          full ? 'max-w-[1200px]' : 'xl:layout:[--fd-toc-width:268px]',
+        )}
+      >
+        {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-1) h-[calc(var(--fd-docs-height)-var(--fd-docs-row-1))] flex flex-col [grid-area:toc] w-(--fd-toc-width) pt-12 pe-4 pb-2 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';

package/docs/layouts/docs/sidebar.tsx

@@ -0,0 +1,265 @@
+'use client';
+import * as Base from '@/components/sidebar/base';
+import { cn } from '@/utils/cn';
+import { type ComponentProps, useRef } from 'react';
+import { cva } from 'class-variance-authority';
+import { createPageTreeRenderer } from '@/components/sidebar/page-tree';
+import { createLinkItemRenderer } from '@/components/sidebar/link-item';
+import { buttonVariants } from '@/components/ui/button';
+import { SearchToggle } from '@/layouts/shared/search-toggle';
+import { Sidebar as SidebarIcon } from '@icons';
+import { mergeRefs } from '@/utils/merge-refs';
+
+const itemVariants = cva(
+  'relative flex flex-row items-center gap-2 rounded-lg p-2 text-start text-fd-muted-foreground wrap-anywhere [&_svg]:size-4 [&_svg]:shrink-0',
+  {
+    variants: {
+      variant: {
+        link: 'transition-colors hover:bg-fd-accent/50 hover:text-fd-accent-foreground/80 hover:transition-none data-[active=true]:bg-fd-primary/10 data-[active=true]:text-fd-primary data-[active=true]:hover:transition-colors',
+        button:
+          'transition-colors hover:bg-fd-accent/50 hover:text-fd-accent-foreground/80 hover:transition-none',
+      },
+      highlight: {
+        true: "data-[active=true]:before:content-[''] data-[active=true]:before:bg-fd-primary data-[active=true]:before:absolute data-[active=true]:before:w-px data-[active=true]:before:inset-y-2.5 data-[active=true]:before:start-2.5",
+      },
+    },
+  },
+);
+
+function getItemOffset(depth: number) {
+  return `calc(${2 + 3 * depth} * var(--spacing))`;
+}
+
+// Explicit exports instead of destructured re-exports for webpack compatibility
+export const Sidebar = Base.SidebarProvider;
+export const SidebarFolder = Base.SidebarFolder;
+export const SidebarCollapseTrigger = Base.SidebarCollapseTrigger;
+export const SidebarViewport = Base.SidebarViewport;
+export const SidebarTrigger = Base.SidebarTrigger;
+
+export function SidebarContent({
+  ref: refProp,
+  className,
+  children,
+  ...props
+}: ComponentProps<'aside'>) {
+  const ref = useRef<HTMLElement>(null);
+
+  return (
+    <Base.SidebarContent>
+      {({ collapsed, hovered, ref: asideRef, ...rest }) => (
+        <>
+          <div
+            data-sidebar-placeholder=""
+            className="sticky top-(--fd-docs-row-1) z-20 [grid-area:sidebar] pointer-events-none *:pointer-events-auto h-[calc(var(--fd-docs-height)-var(--fd-docs-row-1))] md:layout:[--fd-sidebar-width:268px] max-md:hidden"
+          >
+            {collapsed && (
+              <div className="absolute start-0 inset-y-0 w-4" {...rest} />
+            )}
+            <aside
+              id="nd-sidebar"
+              ref={mergeRefs(ref, refProp, asideRef)}
+              data-collapsed={collapsed}
+              data-hovered={collapsed && hovered}
+              className={cn(
+                'absolute flex flex-col w-full start-0 inset-y-0 items-end bg-fd-card text-sm border-e duration-250 *:w-(--fd-sidebar-width)',
+                collapsed && [
+                  'inset-y-2 rounded-xl transition-transform border w-(--fd-sidebar-width)',
+                  hovered
+                    ? 'shadow-lg translate-x-2 rtl:-translate-x-2'
+                    : '-translate-x-(--fd-sidebar-width) rtl:translate-x-full',
+                ],
+                ref.current &&
+                  (ref.current.getAttribute('data-collapsed') === 'true') !==
+                    collapsed &&
+                  'transition-[width,inset-block,translate,background-color]',
+                className,
+              )}
+              {...props}
+              {...rest}
+            >
+              {children}
+            </aside>
+          </div>
+          <div
+            data-sidebar-panel=""
+            className={cn(
+              'fixed flex top-[calc(--spacing(4)+var(--fd-toc-popover-height))] start-4 shadow-lg transition-opacity rounded-xl p-0.5 border bg-fd-muted text-fd-muted-foreground z-10',
+              (!collapsed || hovered) && 'pointer-events-none opacity-0',
+            )}
+          >
+            <SidebarCollapseTrigger
+              className={cn(
+                buttonVariants({
+                  color: 'ghost',
+                  size: 'icon-sm',
+                  className: 'rounded-lg',
+                }),
+              )}
+            >
+              <SidebarIcon />
+            </SidebarCollapseTrigger>
+            <SearchToggle className="rounded-lg" hideIfDisabled />
+          </div>
+        </>
+      )}
+    </Base.SidebarContent>
+  );
+}
+
+export function SidebarDrawer({
+  children,
+  className,
+  ...props
+}: ComponentProps<typeof Base.SidebarDrawerContent>) {
+  return (
+    <>
+      <Base.SidebarDrawerOverlay className="fixed z-40 inset-0 backdrop-blur-xs data-[state=open]:animate-fd-fade-in data-[state=closed]:animate-fd-fade-out" />
+      <Base.SidebarDrawerContent
+        className={cn(
+          'fixed text-[0.9375rem] flex flex-col shadow-lg border-s end-0 inset-y-0 w-[85%] max-w-[380px] z-40 bg-fd-background data-[state=open]:animate-fd-sidebar-in data-[state=closed]:animate-fd-sidebar-out',
+          className,
+        )}
+        {...props}
+      >
+        {children}
+      </Base.SidebarDrawerContent>
+    </>
+  );
+}
+
+export function SidebarSeparator({
+  className,
+  style,
+  children,
+  ...props
+}: ComponentProps<'p'>) {
+  const depth = Base.useFolderDepth();
+
+  return (
+    <Base.SidebarSeparator
+      className={cn('[&_svg]:size-4 [&_svg]:shrink-0', className)}
+      style={{
+        paddingInlineStart: getItemOffset(depth),
+        ...style,
+      }}
+      {...props}
+    >
+      {children}
+    </Base.SidebarSeparator>
+  );
+}
+
+export function SidebarItem({
+  className,
+  style,
+  children,
+  ...props
+}: ComponentProps<typeof Base.SidebarItem>) {
+  const depth = Base.useFolderDepth();
+
+  return (
+    <Base.SidebarItem
+      className={cn(
+        itemVariants({ variant: 'link', highlight: depth >= 1 }),
+        className,
+      )}
+      style={{
+        paddingInlineStart: getItemOffset(depth),
+        ...style,
+      }}
+      {...props}
+    >
+      {children}
+    </Base.SidebarItem>
+  );
+}
+
+export function SidebarFolderTrigger({
+  className,
+  style,
+  ...props
+}: ComponentProps<typeof Base.SidebarFolderTrigger>) {
+  const { depth, collapsible } = Base.useFolder()!;
+
+  return (
+    <Base.SidebarFolderTrigger
+      className={cn(
+        itemVariants({ variant: collapsible ? 'button' : null }),
+        'w-full',
+        className,
+      )}
+      style={{
+        paddingInlineStart: getItemOffset(depth - 1),
+        ...style,
+      }}
+      {...props}
+    >
+      {props.children}
+    </Base.SidebarFolderTrigger>
+  );
+}
+
+export function SidebarFolderLink({
+  className,
+  style,
+  ...props
+}: ComponentProps<typeof Base.SidebarFolderLink>) {
+  const depth = Base.useFolderDepth();
+
+  return (
+    <Base.SidebarFolderLink
+      className={cn(
+        itemVariants({ variant: 'link', highlight: depth > 1 }),
+        'w-full',
+        className,
+      )}
+      style={{
+        paddingInlineStart: getItemOffset(depth - 1),
+        ...style,
+      }}
+      {...props}
+    >
+      {props.children}
+    </Base.SidebarFolderLink>
+  );
+}
+
+export function SidebarFolderContent({
+  className,
+  children,
+  ...props
+}: ComponentProps<typeof Base.SidebarFolderContent>) {
+  const depth = Base.useFolderDepth();
+
+  return (
+    <Base.SidebarFolderContent
+      className={cn(
+        'relative',
+        depth === 1 &&
+          "before:content-[''] before:absolute before:w-px before:inset-y-1 before:bg-fd-border before:start-2.5",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </Base.SidebarFolderContent>
+  );
+}
+
+export const SidebarPageTree = createPageTreeRenderer({
+  SidebarFolder,
+  SidebarFolderContent,
+  SidebarFolderLink,
+  SidebarFolderTrigger,
+  SidebarItem,
+  SidebarSeparator,
+});
+
+export const SidebarLinkItem = createLinkItemRenderer({
+  SidebarFolder,
+  SidebarFolderContent,
+  SidebarFolderLink,
+  SidebarFolderTrigger,
+  SidebarItem,
+});