@hanzo/ui 5.3.26 → 5.3.29

package/docs/components/sidebar/tabs/dropdown.tsx

@@ -0,0 +1,109 @@
+'use client';
+import { Check, ChevronsUpDown } from '@icons';
+import { type ComponentProps, type ReactNode, useMemo, useState } from 'react';
+import Link from '@hanzo/docs-core/link';
+import { usePathname } from '@hanzo/docs-core/framework';
+import { cn } from '@/utils/cn';
+import { isTabActive } from '@/utils/is-active';
+import { useSidebar } from '@/components/sidebar/base';
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from '@/components/ui/popover';
+import type { SidebarTab } from '.';
+
+export interface SidebarTabWithProps extends SidebarTab {
+  props?: ComponentProps<'a'>;
+}
+
+export function SidebarTabsDropdown({
+  options,
+  placeholder,
+  ...props
+}: {
+  placeholder?: ReactNode;
+  options: SidebarTabWithProps[];
+} & ComponentProps<'button'>) {
+  const [open, setOpen] = useState(false);
+  const { closeOnRedirect } = useSidebar();
+  const pathname = usePathname();
+
+  const selected = useMemo(() => {
+    return options.findLast((item) => isTabActive(item, pathname));
+  }, [options, pathname]);
+
+  const onClick = () => {
+    closeOnRedirect.current = false;
+    setOpen(false);
+  };
+
+  const item = selected ? (
+    <>
+      <div className="size-9 shrink-0 empty:hidden md:size-5">
+        {selected.icon}
+      </div>
+      <div>
+        <p className="text-sm font-medium">{selected.title}</p>
+        <p className="text-sm text-fd-muted-foreground empty:hidden md:hidden">
+          {selected.description}
+        </p>
+      </div>
+    </>
+  ) : (
+    placeholder
+  );
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      {item && (
+        <PopoverTrigger
+          {...props}
+          className={cn(
+            'flex items-center gap-2 rounded-lg p-2 border bg-fd-secondary/50 text-start text-fd-secondary-foreground transition-colors hover:bg-fd-accent data-[state=open]:bg-fd-accent data-[state=open]:text-fd-accent-foreground',
+            props.className,
+          )}
+        >
+          {item}
+          <ChevronsUpDown className="shrink-0 ms-auto size-4 text-fd-muted-foreground" />
+        </PopoverTrigger>
+      )}
+      <PopoverContent className="flex flex-col gap-1 w-(--radix-popover-trigger-width) p-1 fd-scroll-container">
+        {options.map((item) => {
+          const isActive = selected && item.url === selected.url;
+          if (!isActive && item.unlisted) return;
+
+          return (
+            <Link
+              key={item.url}
+              href={item.url}
+              onClick={onClick}
+              {...item.props}
+              className={cn(
+                'flex items-center gap-2 rounded-lg p-1.5 hover:bg-fd-accent hover:text-fd-accent-foreground',
+                item.props?.className,
+              )}
+            >
+              <div className="shrink-0 size-9 md:mt-1 md:mb-auto md:size-5 empty:hidden">
+                {item.icon}
+              </div>
+              <div>
+                <p className="text-sm font-medium">{item.title}</p>
+                <p className="text-[0.8125rem] text-fd-muted-foreground empty:hidden">
+                  {item.description}
+                </p>
+              </div>
+
+              <Check
+                className={cn(
+                  'shrink-0 ms-auto size-3.5 text-fd-primary',
+                  !isActive && 'invisible',
+                )}
+              />
+            </Link>
+          );
+        })}
+      </PopoverContent>
+    </Popover>
+  );
+}

package/docs/components/sidebar/tabs/index.tsx

@@ -0,0 +1,89 @@
+import type * as PageTree from '@hanzo/docs-core/page-tree';
+import type { ReactNode } from 'react';
+
+export interface SidebarTab {
+  /**
+   * Redirect URL of the folder, usually the index page
+   */
+  url: string;
+
+  icon?: ReactNode;
+  title: ReactNode;
+  description?: ReactNode;
+
+  /**
+   * Detect from a list of urls
+   */
+  urls?: Set<string>;
+  unlisted?: boolean;
+}
+
+export interface GetSidebarTabsOptions {
+  transform?: (option: SidebarTab, node: PageTree.Folder) => SidebarTab | null;
+}
+
+const defaultTransform: GetSidebarTabsOptions['transform'] = (option, node) => {
+  if (!node.icon) return option;
+
+  return {
+    ...option,
+    icon: (
+      <div className="size-full [&_svg]:size-full max-md:p-1.5 max-md:rounded-md max-md:border max-md:bg-fd-secondary">
+        {node.icon}
+      </div>
+    ),
+  };
+};
+
+export function getSidebarTabs(
+  tree: PageTree.Root,
+  { transform = defaultTransform }: GetSidebarTabsOptions = {},
+): SidebarTab[] {
+  const results: SidebarTab[] = [];
+
+  function scanOptions(
+    node: PageTree.Root | PageTree.Folder,
+    unlisted?: boolean,
+  ) {
+    if ('root' in node && node.root) {
+      const urls = getFolderUrls(node);
+
+      if (urls.size > 0) {
+        const option: SidebarTab = {
+          url: urls.values().next().value ?? '',
+          title: node.name,
+          icon: node.icon,
+          unlisted,
+          description: node.description,
+          urls,
+        };
+
+        const mapped = transform ? transform(option, node) : option;
+        if (mapped) results.push(mapped);
+      }
+    }
+
+    for (const child of node.children) {
+      if (child.type === 'folder') scanOptions(child, unlisted);
+    }
+  }
+
+  scanOptions(tree);
+  if (tree.fallback) scanOptions(tree.fallback, true);
+
+  return results;
+}
+
+function getFolderUrls(
+  folder: PageTree.Folder,
+  output: Set<string> = new Set(),
+): Set<string> {
+  if (folder.index) output.add(folder.index.url);
+
+  for (const child of folder.children) {
+    if (child.type === 'page' && !child.external) output.add(child.url);
+    if (child.type === 'folder') getFolderUrls(child, output);
+  }
+
+  return output;
+}

package/docs/components/steps.tsx

@@ -0,0 +1,9 @@
+import type { ReactNode } from 'react';
+
+export function Steps({ children }: { children: ReactNode }) {
+  return <div className="fd-steps">{children}</div>;
+}
+
+export function Step({ children }: { children: ReactNode }) {
+  return <div className="fd-step">{children}</div>;
+}

package/docs/components/tabs.tsx

@@ -0,0 +1,203 @@
+'use client';
+
+import * as React from 'react';
+import {
+  type ComponentProps,
+  createContext,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useState,
+} from 'react';
+import { cn } from '@/utils/cn';
+import * as Unstyled from './ui/tabs';
+
+type CollectionKey = string | symbol;
+
+export interface TabsProps extends Omit<
+  ComponentProps<typeof Unstyled.Tabs>,
+  'value' | 'onValueChange'
+> {
+  /**
+   * Use simple mode instead of advanced usage as documented in https://radix-ui.com/primitives/docs/components/tabs.
+   */
+  items?: string[];
+
+  /**
+   * Shortcut for `defaultValue` when `items` is provided.
+   *
+   * @defaultValue 0
+   */
+  defaultIndex?: number;
+
+  /**
+   * Additional label in tabs list when `items` is provided.
+   */
+  label?: ReactNode;
+}
+
+const TabsContext = createContext<{
+  items?: string[];
+  collection: CollectionKey[];
+} | null>(null);
+
+function useTabContext() {
+  const ctx = useContext(TabsContext);
+  if (!ctx) throw new Error('You must wrap your component in <Tabs>');
+  return ctx;
+}
+
+export const TabsList = React.forwardRef<
+  React.ComponentRef<typeof Unstyled.TabsList>,
+  React.ComponentPropsWithoutRef<typeof Unstyled.TabsList>
+>((props, ref) => (
+  <Unstyled.TabsList
+    ref={ref}
+    {...props}
+    className={cn(
+      'flex gap-3.5 text-fd-secondary-foreground overflow-x-auto px-4 not-prose',
+      props.className,
+    )}
+  />
+));
+TabsList.displayName = 'TabsList';
+
+export const TabsTrigger = React.forwardRef<
+  React.ComponentRef<typeof Unstyled.TabsTrigger>,
+  React.ComponentPropsWithoutRef<typeof Unstyled.TabsTrigger>
+>((props, ref) => (
+  <Unstyled.TabsTrigger
+    ref={ref}
+    {...props}
+    className={cn(
+      'inline-flex items-center gap-2 whitespace-nowrap text-fd-muted-foreground border-b border-transparent py-2 text-sm font-medium transition-colors [&_svg]:size-4 hover:text-fd-accent-foreground disabled:pointer-events-none disabled:opacity-50 data-[state=active]:border-fd-primary data-[state=active]:text-fd-primary',
+      props.className,
+    )}
+  />
+));
+TabsTrigger.displayName = 'TabsTrigger';
+
+export function Tabs({
+  ref,
+  className,
+  items,
+  label,
+  defaultIndex = 0,
+  defaultValue = items ? escapeValue(items[defaultIndex]) : undefined,
+  ...props
+}: TabsProps) {
+  const [value, setValue] = useState(defaultValue);
+  const collection = useMemo<CollectionKey[]>(() => [], []);
+
+  return (
+    <Unstyled.Tabs
+      ref={ref}
+      className={cn(
+        'flex flex-col overflow-hidden rounded-xl border bg-fd-secondary my-4',
+        className,
+      )}
+      value={value}
+      onValueChange={(v: string) => {
+        if (items && !items.some((item) => escapeValue(item) === v)) return;
+        setValue(v);
+      }}
+      {...props}
+    >
+      {items && (
+        <TabsList>
+          {label && (
+            <span className="text-sm font-medium my-auto me-auto">{label}</span>
+          )}
+          {items.map((item) => (
+            <TabsTrigger key={item} value={escapeValue(item)}>
+              {item}
+            </TabsTrigger>
+          ))}
+        </TabsList>
+      )}
+      <TabsContext.Provider
+        value={useMemo(() => ({ items, collection }), [collection, items])}
+      >
+        {props.children}
+      </TabsContext.Provider>
+    </Unstyled.Tabs>
+  );
+}
+
+export interface TabProps extends Omit<
+  ComponentProps<typeof Unstyled.TabsContent>,
+  'value'
+> {
+  /**
+   * Value of tab, detect from index if unspecified.
+   */
+  value?: string;
+}
+
+export function Tab({ value, ...props }: TabProps) {
+  const { items } = useTabContext();
+  const resolved =
+    value ??
+    // eslint-disable-next-line react-hooks/rules-of-hooks -- `value` is not supposed to change
+    items?.at(useCollectionIndex());
+  if (!resolved)
+    throw new Error(
+      'Failed to resolve tab `value`, please pass a `value` prop to the Tab component.',
+    );
+
+  return (
+    <TabsContent value={escapeValue(resolved)} {...props}>
+      {props.children}
+    </TabsContent>
+  );
+}
+
+export function TabsContent({
+  value,
+  className,
+  ...props
+}: ComponentProps<typeof Unstyled.TabsContent>) {
+  return (
+    <Unstyled.TabsContent
+      value={value}
+      forceMount
+      className={cn(
+        'p-4 text-[0.9375rem] bg-fd-background rounded-xl outline-none prose-no-margin data-[state=inactive]:hidden [&>figure:only-child]:-m-4 [&>figure:only-child]:border-none',
+        className,
+      )}
+      {...props}
+    >
+      {props.children}
+    </Unstyled.TabsContent>
+  );
+}
+
+/**
+ * Inspired by Headless UI.
+ *
+ * Return the index of children, this is made possible by registering the order of render from children using React context.
+ * This is supposed by work with pre-rendering & pure client-side rendering.
+ */
+function useCollectionIndex() {
+  const key = useId();
+  const { collection } = useTabContext();
+
+  useEffect(() => {
+    return () => {
+      const idx = collection.indexOf(key);
+      if (idx !== -1) collection.splice(idx, 1);
+    };
+  }, [key, collection]);
+
+  if (!collection.includes(key)) collection.push(key);
+  return collection.indexOf(key);
+}
+
+/**
+ * only escape whitespaces in values in simple mode
+ */
+function escapeValue(v: string): string {
+  return v.toLowerCase().replace(/\s/, '-');
+}

package/docs/components/toc/clerk.tsx

@@ -0,0 +1,173 @@
+'use client';
+import * as Primitive from '@hanzo/docs-core/toc';
+import { type ComponentProps, useEffect, useRef, useState } from 'react';
+import { cn } from '@/utils/cn';
+import { useTOCItems, TocThumb } from '.';
+import { mergeRefs } from '@/utils/merge-refs';
+import { useI18n } from '@/contexts/i18n';
+
+export function TOCItems({ ref, className, ...props }: ComponentProps<'div'>) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const items = useTOCItems();
+  const { text } = useI18n();
+
+  const [svg, setSvg] = useState<{
+    path: string;
+    width: number;
+    height: number;
+  }>();
+
+  useEffect(() => {
+    if (!containerRef.current) return;
+    const container = containerRef.current;
+
+    function onResize(): void {
+      if (container.clientHeight === 0) return;
+      let w = 0,
+        h = 0;
+      const d: string[] = [];
+      for (let i = 0; i < items.length; i++) {
+        const element: HTMLElement | null = container.querySelector(
+          `a[href="#${items[i].url.slice(1)}"]`,
+        );
+        if (!element) continue;
+
+        const styles = getComputedStyle(element);
+        const offset = getLineOffset(items[i].depth) + 1,
+          top = element.offsetTop + parseFloat(styles.paddingTop),
+          bottom =
+            element.offsetTop +
+            element.clientHeight -
+            parseFloat(styles.paddingBottom);
+
+        w = Math.max(offset, w);
+        h = Math.max(h, bottom);
+
+        d.push(`${i === 0 ? 'M' : 'L'}${offset} ${top}`);
+        d.push(`L${offset} ${bottom}`);
+      }
+
+      setSvg({
+        path: d.join(' '),
+        width: w + 1,
+        height: h,
+      });
+    }
+
+    const observer = new ResizeObserver(onResize);
+    onResize();
+
+    observer.observe(container);
+    return () => {
+      observer.disconnect();
+    };
+  }, [items]);
+
+  if (items.length === 0)
+    return (
+      <div className="rounded-lg border bg-fd-card p-3 text-xs text-fd-muted-foreground">
+        {text.tocNoHeadings}
+      </div>
+    );
+
+  return (
+    <>
+      {svg && (
+        <div
+          className="absolute start-0 top-0 rtl:-scale-x-100"
+          style={{
+            width: svg.width,
+            height: svg.height,
+            maskImage: `url("data:image/svg+xml,${
+              // Inline SVG
+              encodeURIComponent(
+                `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${svg.width} ${svg.height}"><path d="${svg.path}" stroke="black" stroke-width="1" fill="none" /></svg>`,
+              )
+            }")`,
+          }}
+        >
+          <TocThumb
+            containerRef={containerRef}
+            className="mt-(--fd-top) h-(--fd-height) bg-fd-primary transition-all"
+          />
+        </div>
+      )}
+      <div
+        ref={mergeRefs(containerRef, ref)}
+        className={cn('flex flex-col', className)}
+        {...props}
+      >
+        {items.map((item, i) => (
+          <TOCItem
+            key={item.url}
+            item={item}
+            upper={items[i - 1]?.depth}
+            lower={items[i + 1]?.depth}
+          />
+        ))}
+      </div>
+    </>
+  );
+}
+
+function getItemOffset(depth: number): number {
+  if (depth <= 2) return 14;
+  if (depth === 3) return 26;
+  return 36;
+}
+
+function getLineOffset(depth: number): number {
+  return depth >= 3 ? 10 : 0;
+}
+
+function TOCItem({
+  item,
+  upper = item.depth,
+  lower = item.depth,
+}: {
+  item: Primitive.TOCItemType;
+  upper?: number;
+  lower?: number;
+}) {
+  const offset = getLineOffset(item.depth),
+    upperOffset = getLineOffset(upper),
+    lowerOffset = getLineOffset(lower);
+
+  return (
+    <Primitive.TOCItem
+      href={item.url}
+      style={{
+        paddingInlineStart: getItemOffset(item.depth),
+      }}
+      className="prose relative py-1.5 text-sm text-fd-muted-foreground hover:text-fd-accent-foreground transition-colors wrap-anywhere first:pt-0 last:pb-0 data-[active=true]:text-fd-primary"
+    >
+      {offset !== upperOffset && (
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          viewBox="0 0 16 16"
+          className="absolute -top-1.5 start-0 size-4 rtl:-scale-x-100"
+        >
+          <line
+            x1={upperOffset}
+            y1="0"
+            x2={offset}
+            y2="12"
+            className="stroke-fd-foreground/10"
+            strokeWidth="1"
+          />
+        </svg>
+      )}
+      <div
+        className={cn(
+          'absolute inset-y-0 w-px bg-fd-foreground/10',
+          offset !== upperOffset && 'top-1.5',
+          offset !== lowerOffset && 'bottom-1.5',
+        )}
+        style={{
+          insetInlineStart: offset,
+        }}
+      />
+      {item.title}
+    </Primitive.TOCItem>
+  );
+}

package/docs/components/toc/default.tsx

@@ -0,0 +1,57 @@
+'use client';
+import { useI18n } from '@/contexts/i18n';
+import { cn } from '@/utils/cn';
+import { mergeRefs } from '@/utils/merge-refs';
+import { type ComponentProps, useRef } from 'react';
+import { useTOCItems, TocThumb } from '.';
+import * as Primitive from '@hanzo/docs-core/toc';
+
+export function TOCItems({ ref, className, ...props }: ComponentProps<'div'>) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const items = useTOCItems();
+  const { text } = useI18n();
+
+  if (items.length === 0)
+    return (
+      <div className="rounded-lg border bg-fd-card p-3 text-xs text-fd-muted-foreground">
+        {text.tocNoHeadings}
+      </div>
+    );
+
+  return (
+    <>
+      <TocThumb
+        containerRef={containerRef}
+        className="absolute top-(--fd-top) h-(--fd-height) w-px bg-fd-primary transition-all"
+      />
+      <div
+        ref={mergeRefs(ref, containerRef)}
+        className={cn(
+          'flex flex-col border-s border-fd-foreground/10',
+          className,
+        )}
+        {...props}
+      >
+        {items.map((item) => (
+          <TOCItem key={item.url} item={item} />
+        ))}
+      </div>
+    </>
+  );
+}
+
+function TOCItem({ item }: { item: Primitive.TOCItemType }) {
+  return (
+    <Primitive.TOCItem
+      href={item.url}
+      className={cn(
+        'prose py-1.5 text-sm text-fd-muted-foreground transition-colors wrap-anywhere first:pt-0 last:pb-0 data-[active=true]:text-fd-primary',
+        item.depth <= 2 && 'ps-3',
+        item.depth === 3 && 'ps-6',
+        item.depth >= 4 && 'ps-8',
+      )}
+    >
+      {item.title}
+    </Primitive.TOCItem>
+  );
+}