@vx-oss/docs-react 1.0.3

package/dist/contexts/search.d.ts

@@ -0,0 +1,64 @@
+import { DefaultSearchDialogProps } from "../components/dialog/search-default.js";
+import { ComponentType, ReactNode } from "react";
+//#region src/contexts/search.d.ts
+interface HotKey {
+  display: ReactNode;
+  /**
+   * Key code or a function determining whether the key is pressed.
+   */
+  key: string | ((e: KeyboardEvent) => boolean);
+}
+interface SharedProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}
+type SearchLink = [name: string, href: string];
+interface TagItem {
+  name: string;
+  value: string;
+}
+interface SearchProviderProps<DialogProps extends SharedProps = DefaultSearchDialogProps> {
+  /**
+   * Preload search dialog before opening it
+   *
+   * @defaultValue `true`
+   */
+  preload?: boolean;
+  /**
+   * Custom links to be displayed if search is empty
+   */
+  links?: SearchLink[];
+  /**
+   * Hotkeys for triggering search dialog
+   *
+   * @defaultValue Meta/Ctrl + K
+   */
+  hotKey?: HotKey[];
+  /**
+   * Replace default search dialog, allowing you to use other solutions such as Algolia Search
+   *
+   * It receives the `open` and `onOpenChange` prop, can be lazy loaded with `React.lazy()`
+   */
+  SearchDialog?: ComponentType<DialogProps>;
+  /**
+   * Additional props to the dialog
+   */
+  options?: Partial<DialogProps>;
+  children?: ReactNode;
+}
+interface SearchContextType {
+  enabled: boolean;
+  open: boolean;
+  hotKey: HotKey[];
+  setOpenSearch: (value: boolean) => void;
+}
+declare function useSearchContext(): SearchContextType;
+declare function SearchProvider<DialogProps extends SharedProps = DefaultSearchDialogProps>({ SearchDialog, children, preload, options, hotKey, links }: SearchProviderProps<DialogProps>): import("react").JSX.Element;
+/**
+ * Show children only when search is enabled via React Context
+ */
+declare function SearchOnly({ children }: {
+  children: ReactNode;
+}): ReactNode;
+//#endregion
+export { SearchLink, SearchOnly, SearchProvider, SearchProviderProps, SharedProps, TagItem, useSearchContext };

package/dist/contexts/search.js

@@ -0,0 +1,68 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Suspense, createContext, lazy, use, useEffect, useEffectEvent, useMemo, useState } from "react";
+//#region src/contexts/search.tsx
+const SearchContext = createContext({
+	enabled: false,
+	open: false,
+	hotKey: [],
+	setOpenSearch: () => void 0
+});
+function useSearchContext() {
+	return use(SearchContext);
+}
+function MetaOrControl() {
+	const [key, setKey] = useState("⌘");
+	useEffect(() => {
+		if (/Windows|Linux/i.test(window.navigator.userAgent)) setKey("Ctrl");
+	}, []);
+	return key;
+}
+const DEFAULT_HOT_KEYS = [{
+	key: (e) => e.metaKey || e.ctrlKey,
+	display: /* @__PURE__ */ jsx(MetaOrControl, {})
+}, {
+	key: "k",
+	display: "K"
+}];
+const DefaultSearchDialog = lazy(() => import("../components/dialog/search-default.js"));
+function SearchProvider({ SearchDialog = DefaultSearchDialog, children, preload = true, options, hotKey = DEFAULT_HOT_KEYS, links }) {
+	const [isOpen, setIsOpen] = useState(preload ? false : void 0);
+	const onKeyDown = useEffectEvent((e) => {
+		if (hotKey.every((v) => typeof v.key === "string" ? e.key === v.key : v.key(e))) {
+			setIsOpen((open) => !open);
+			e.preventDefault();
+		}
+	});
+	useEffect(() => {
+		window.addEventListener("keydown", onKeyDown);
+		return () => {
+			window.removeEventListener("keydown", onKeyDown);
+		};
+	}, []);
+	return /* @__PURE__ */ jsxs(SearchContext, {
+		value: useMemo(() => ({
+			enabled: true,
+			open: isOpen ?? false,
+			hotKey,
+			setOpenSearch: setIsOpen
+		}), [isOpen, hotKey]),
+		children: [/* @__PURE__ */ jsx(Suspense, {
+			fallback: null,
+			children: isOpen !== void 0 && /* @__PURE__ */ jsx(SearchDialog, {
+				open: isOpen,
+				onOpenChange: setIsOpen,
+				links,
+				...options
+			})
+		}), children]
+	});
+}
+/**
+* Show children only when search is enabled via React Context
+*/
+function SearchOnly({ children }) {
+	if (useSearchContext().enabled) return children;
+}
+//#endregion
+export { SearchOnly, SearchProvider, useSearchContext };

package/dist/contexts/tree.d.ts

@@ -0,0 +1,29 @@
+import { LayoutTab } from "../layouts/shared/index.js";
+import { ReactNode } from "react";
+import * as PageTree from "@vx-oss/docs-core/page-tree";
+//#region src/contexts/tree.d.ts
+type MakeRequired<O, K extends keyof O> = Omit<O, K> & Pick<Required<O>, K>;
+interface TreeContextType {
+  root: MakeRequired<PageTree.Root | PageTree.Folder, '$id'>;
+  full: PageTree.Root;
+}
+declare function TreeContextProvider({ tree: rawTree, children }: {
+  tree: PageTree.Root;
+  children: ReactNode;
+}): import("react").JSX.Element;
+declare function useTreePath(): PageTree.Node[];
+declare function useTreeContext(): TreeContextType;
+interface TabsGroup {
+  /** the root folder on the current page's path, undefined for tabs not bound to the page tree */
+  active?: PageTree.Folder;
+  options: LayoutTab[];
+}
+/**
+ * Group tabs by the root folders on the current page's path (outermost first): each tab is
+ * matched to its root folder, linking to the projection of current page when possible.
+ *
+ * Tabs not bound to the page tree are appended to the group of `root: true` folders.
+ */
+declare function useTabsGroups(tabs: LayoutTab[]): TabsGroup[];
+//#endregion
+export { TabsGroup, TreeContextProvider, useTabsGroups, useTreeContext, useTreePath };

package/dist/contexts/tree.js

@@ -0,0 +1,91 @@
+"use client";
+import { usePathname } from "@vx-oss/docs-core/framework";
+import { jsx } from "react/jsx-runtime";
+import { createContext, use, useMemo, useRef } from "react";
+import * as PageTree from "@vx-oss/docs-core/page-tree";
+import { searchPath } from "@vx-oss/docs-core/breadcrumb";
+//#region src/contexts/tree.tsx
+const TreeContext = createContext(null);
+const PathContext = createContext([]);
+function TreeContextProvider({ tree: rawTree, children }) {
+	const nextIdRef = useRef(0);
+	const pathname = usePathname();
+	const tree = useMemo(() => rawTree, [rawTree.$id]);
+	const path = useMemo(() => {
+		return searchPath(tree.children, pathname) ?? (tree.fallback ? searchPath(tree.fallback.children, pathname) : null) ?? [];
+	}, [tree, pathname]);
+	const root = path.findLast((item) => item.type === "folder" && item.root) ?? tree;
+	root.$id ??= String(nextIdRef.current++);
+	return /* @__PURE__ */ jsx(TreeContext, {
+		value: useMemo(() => ({
+			root,
+			full: tree
+		}), [root, tree]),
+		children: /* @__PURE__ */ jsx(PathContext, {
+			value: path,
+			children
+		})
+	});
+}
+function useTreePath() {
+	return use(PathContext);
+}
+function useTreeContext() {
+	const ctx = use(TreeContext);
+	if (!ctx) throw new Error("You must wrap this component under <DocsLayout />");
+	return ctx;
+}
+/**
+* Group tabs by the root folders on the current page's path (outermost first): each tab is
+* matched to its root folder, linking to the projection of current page when possible.
+*
+* Tabs not bound to the page tree are appended to the group of `root: true` folders.
+*/
+function useTabsGroups(tabs) {
+	const { full: tree } = useTreeContext();
+	const path = use(PathContext);
+	return useMemo(() => {
+		const out = [];
+		const last = path[path.length - 1];
+		const page = last?.type === "page" ? last : void 0;
+		let scope = tree.fallback && !tree.children.includes(path[0]) ? tree.fallback : tree;
+		for (const node of path) {
+			if (node.type !== "folder" || !node.root) continue;
+			const group = {
+				active: node,
+				options: []
+			};
+			collectTabs(scope, node, page, tabs, group.options);
+			if (group.options.length > 0) out.push(group);
+			scope = node;
+		}
+		const custom = tabs.filter((tab) => !tab.$folder);
+		if (custom.length > 0) {
+			const group = out.findLast((group) => group.active?.root === true);
+			if (group) group.options.push(...custom);
+			else out.push({ options: custom });
+		}
+		return out;
+	}, [
+		tabs,
+		tree,
+		path
+	]);
+}
+/** collect the tabs of root folders with the same type as `active` within a scope */
+function collectTabs(scope, active, page, tabs, out) {
+	for (const node of scope.children) {
+		if (node.type !== "folder") continue;
+		if (node.root === active.root) {
+			const tab = tabs.find((tab) => tab.$folder && (tab.$folder === node || tab.$folder.$id === node.$id));
+			if (!tab) continue;
+			const projection = page && PageTree.findProjection(active, node, page);
+			out.push(projection ? {
+				...tab,
+				url: projection.url
+			} : tab);
+		} else if (!node.root) collectTabs(node, active, page, tabs, out);
+	}
+}
+//#endregion
+export { TreeContextProvider, useTabsGroups, useTreeContext, useTreePath };

package/dist/i18n.d.ts

@@ -0,0 +1,15 @@
+import { I18nProviderProps } from "./contexts/i18n.js";
+import { Translations } from "./.translations/index.js";
+import { I18nConfig, SingularTranslationsAPI, TranslationExtension, TranslationsAPI } from "@vx-oss/docs-core/i18n";
+//#region src/i18n.d.ts
+declare function uiTranslations(): TranslationExtension<keyof Translations>;
+declare function i18nProvider(translations: SingularTranslationsAPI): I18nProviderProps;
+declare function i18nProvider<Languages extends string>(translations: TranslationsAPI<Languages>, lang?: NoInfer<Languages> | (string & {})): I18nProviderProps;
+interface I18nUIConfig<Languages extends string> extends I18nConfig<Languages> {
+  provider: (locale?: Languages | (string & {})) => I18nProviderProps;
+}
+declare function defineI18nUI<Languages extends string>(config: I18nConfig<Languages>, localeTranslations?: Partial<Record<Languages, Record<string, string> & {
+  displayName?: string;
+}>>): I18nUIConfig<Languages>;
+//#endregion
+export { I18nUIConfig, type Translations, defineI18nUI, i18nProvider, uiTranslations };

package/dist/i18n.js

@@ -0,0 +1,38 @@
+import keys_default from "./.translations/keys.js";
+//#region src/i18n.tsx
+function uiTranslations() {
+	return { keys: keys_default };
+}
+function i18nProvider(translations, lang) {
+	const t = translations.extend(uiTranslations());
+	if ("config" in t) {
+		const { defaultLanguage, languages } = t.config;
+		const locale = lang ?? defaultLanguage;
+		return {
+			locale: lang,
+			translations: t.get(locale) ?? t.get(defaultLanguage),
+			locales: languages.map((code) => ({
+				locale: code,
+				name: t.get(code).displayName ?? "English"
+			}))
+		};
+	}
+	return { translations: t.get() };
+}
+function defineI18nUI(config, localeTranslations = {}) {
+	return {
+		...config,
+		provider(locale = config.defaultLanguage) {
+			return {
+				locale,
+				translations: localeTranslations[locale],
+				locales: config.languages.map((code) => ({
+					locale: code,
+					name: localeTranslations[code]?.displayName ?? code
+				}))
+			};
+		}
+	};
+}
+//#endregion
+export { defineI18nUI, i18nProvider, uiTranslations };

package/dist/layouts/docs/client.d.ts

@@ -0,0 +1,33 @@
+import { BaseSlots, BaseSlotsProps } from "../shared/client.js";
+import { LayoutTab, LinkItemType } from "../shared/index.js";
+import { SidebarProps, SidebarProviderProps } from "./slots/sidebar.js";
+import { DocsLayoutProps } from "./index.js";
+import { ComponentProps, FC } from "react";
+//#region src/layouts/docs/client.d.ts
+interface DocsSlots extends BaseSlots {
+  container: FC<ComponentProps<'div'>>;
+  header: FC<ComponentProps<'header'>>;
+  sidebar: {
+    provider: FC<SidebarProviderProps>;
+    root: FC<SidebarProps>;
+    trigger: FC<ComponentProps<'button'>>;
+    useSidebar: () => {
+      collapsed: boolean;
+      open: boolean;
+      setOpen: (v: boolean) => void;
+    };
+  };
+}
+interface SlotsProps extends BaseSlotsProps<DocsLayoutProps> {
+  tabs: LayoutTab[];
+  tabMode: NonNullable<DocsLayoutProps['tabMode']>;
+}
+declare function useDocsLayout(): {
+  props: SlotsProps;
+  isNavTransparent: boolean;
+  navItems: LinkItemType[];
+  menuItems: LinkItemType[];
+  slots: DocsSlots;
+};
+//#endregion
+export { DocsSlots, useDocsLayout };

package/dist/layouts/docs/client.js

@@ -0,0 +1,94 @@
+"use client";
+import { cn } from "../../utils/cn.js";
+import { TreeContextProvider, useTabsGroups } from "../../contexts/tree.js";
+import { baseSlots } from "../shared/client.js";
+import { isLayoutTabActive, useLinkItems } from "../shared/index.js";
+import { useIsScrollTop } from "../../utils/use-is-scroll-top.js";
+import { Sidebar, SidebarProvider, SidebarTrigger, useSidebar } from "./slots/sidebar.js";
+import { Header } from "./slots/header.js";
+import { Container } from "./slots/container.js";
+import Link from "@vx-oss/docs-core/link";
+import { usePathname } from "@vx-oss/docs-core/framework";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { createContext, use, useMemo } from "react";
+//#region src/layouts/docs/client.tsx
+const { useBaseSlots } = baseSlots({ useProps() {
+	return useDocsLayout().props;
+} });
+const LayoutContext = createContext(null);
+function useIsDocsLayout() {
+	return use(LayoutContext) !== null;
+}
+function useDocsLayout() {
+	const context = use(LayoutContext);
+	if (!context) throw new Error("Please use <DocsPage /> (`@vx-oss/docs-react/layouts/docs/page`) under <DocsLayout /> (`@vx-oss/docs-react/layouts/docs`).");
+	return context;
+}
+function LayoutBody(props) {
+	const { nav: { enabled: navEnabled = true, transparentMode: navTransparentMode = "none" } = {}, sidebar: { enabled: sidebarEnabled = true, defaultOpenLevel, prefetch, ...sidebarProps } = {}, slots: defaultSlots, tabs, tabMode = "auto", tree, containerProps, children } = props;
+	const isTop = useIsScrollTop({ enabled: navTransparentMode === "top" }) ?? true;
+	const isNavTransparent = navTransparentMode === "top" ? isTop : navTransparentMode === "always";
+	const { baseSlots, baseProps } = useBaseSlots(props);
+	const linkItems = useLinkItems(props);
+	const slots = {
+		...baseSlots,
+		header: defaultSlots?.header ?? Header,
+		container: defaultSlots?.container ?? Container,
+		sidebar: defaultSlots?.sidebar ?? {
+			provider: SidebarProvider,
+			root: Sidebar,
+			trigger: SidebarTrigger,
+			useSidebar
+		}
+	};
+	return /* @__PURE__ */ jsx(TreeContextProvider, {
+		tree,
+		children: /* @__PURE__ */ jsx(LayoutContext, {
+			value: {
+				props: {
+					tabMode,
+					tabs,
+					...baseProps
+				},
+				isNavTransparent,
+				slots,
+				...linkItems
+			},
+			children: /* @__PURE__ */ jsx(slots.sidebar.provider, {
+				defaultOpenLevel,
+				prefetch,
+				children: /* @__PURE__ */ jsxs(slots.container, {
+					...containerProps,
+					children: [
+						navEnabled && /* @__PURE__ */ jsx(slots.header, {}),
+						sidebarEnabled && /* @__PURE__ */ jsx(slots.sidebar.root, { ...sidebarProps }),
+						tabMode === "top" && tabs.length > 0 && /* @__PURE__ */ jsx(LayoutTabs, {
+							tabs,
+							className: "z-10 bg-fd-background border-b px-6 pt-3 xl:px-8 max-md:hidden"
+						}),
+						children
+					]
+				})
+			})
+		})
+	});
+}
+function LayoutTabs({ tabs: allTabs, ...props }) {
+	const pathname = usePathname();
+	const group = useTabsGroups(allTabs).findLast((group) => typeof group.active?.root !== "string");
+	const selected = useMemo(() => {
+		return group?.options.findLast((option) => isLayoutTabActive(option, pathname));
+	}, [group, pathname]);
+	if (!group) return;
+	return /* @__PURE__ */ jsx("div", {
+		...props,
+		className: cn("flex flex-row items-end gap-6 overflow-auto [grid-area:main]", props.className),
+		children: group.options.map((tab, i) => /* @__PURE__ */ jsx(Link, {
+			href: tab.url,
+			className: cn("inline-flex border-b-2 border-transparent transition-colors items-center pb-1.5 font-medium gap-2 text-fd-muted-foreground text-sm text-nowrap hover:text-fd-accent-foreground", tab.unlisted && selected !== tab && "hidden", selected === tab && "border-fd-primary text-fd-primary"),
+			children: tab.title
+		}, i))
+	});
+}
+//#endregion
+export { LayoutBody, useDocsLayout, useIsDocsLayout };

package/dist/layouts/docs/index.d.ts

@@ -0,0 +1,32 @@
+import { BaseLayoutProps, GetLayoutTabsOptions, LayoutTab } from "../shared/index.js";
+import { SidebarProps, SidebarProviderProps } from "./slots/sidebar.js";
+import { DocsSlots, useDocsLayout } from "./client.js";
+import { HTMLAttributes, ReactNode } from "react";
+import * as PageTree from "@vx-oss/docs-core/page-tree";
+//#region src/layouts/docs/index.d.ts
+interface DocsLayoutProps extends BaseLayoutProps {
+  tree: PageTree.Root;
+  sidebar?: SidebarOptions;
+  tabMode?: 'top' | 'auto';
+  tabs?: LayoutTab[] | GetLayoutTabsOptions | false;
+  containerProps?: HTMLAttributes<HTMLDivElement>;
+  slots?: Partial<DocsSlots>;
+}
+interface SidebarOptions extends SidebarProps, SidebarProviderProps {
+  enabled?: boolean;
+  /**
+   * @deprecated use `slots.sidebar` instead.
+   */
+  component?: ReactNode;
+  /**
+   * @deprecated use layout-level `tabMode` option instead.
+   */
+  tabMode?: 'auto' | 'top';
+  /**
+   * @deprecated use layout-level `tabs` option instead.
+   */
+  tabs?: LayoutTab[] | GetLayoutTabsOptions | false;
+}
+declare function DocsLayout({ tree, sidebar: { tabs: _tabs, tabMode: _tabMode, ...sidebarProps }, tabs: layoutTabs, tabMode, children, ...props }: DocsLayoutProps): import("react").JSX.Element;
+//#endregion
+export { DocsLayout, DocsLayoutProps, type DocsSlots, useDocsLayout };

package/dist/layouts/docs/index.js

@@ -0,0 +1,23 @@
+import { getLayoutTabs } from "../shared/index.js";
+import { LayoutBody, useDocsLayout } from "./client.js";
+import { jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+//#region src/layouts/docs/index.tsx
+function DocsLayout({ tree, sidebar: { tabs: _tabs, tabMode: _tabMode, ...sidebarProps } = {}, tabs: layoutTabs = _tabs, tabMode = _tabMode, children, ...props }) {
+	const tabs = useMemo(() => {
+		if (Array.isArray(layoutTabs)) return layoutTabs;
+		if (typeof layoutTabs === "object") return getLayoutTabs(tree, layoutTabs);
+		if (layoutTabs !== false) return getLayoutTabs(tree);
+		return [];
+	}, [tree, layoutTabs]);
+	return /* @__PURE__ */ jsx(LayoutBody, {
+		tree,
+		tabs,
+		tabMode,
+		sidebar: sidebarProps,
+		...props,
+		children
+	});
+}
+//#endregion
+export { DocsLayout, useDocsLayout };

package/dist/layouts/docs/page/index.d.ts

@@ -0,0 +1,76 @@
+import { TOCPopoverProps, TOCProps, TOCProviderProps } from "./slots/toc.js";
+import { Footer, FooterProps } from "./slots/footer.js";
+import { Breadcrumb, BreadcrumbProps } from "./slots/breadcrumb.js";
+import { MarkdownCopyButton, ViewOptionsPopover } from "../../shared/page-actions.js";
+import { ComponentProps, FC, ReactNode } from "react";
+import { TOCItemType } from "@vx-oss/docs-core/toc";
+//#region src/layouts/docs/page/index.d.ts
+interface DocsPageProps extends ComponentProps<'article'> {
+  toc?: TOCItemType[];
+  /**
+   * Extend the page to fill all available space
+   *
+   * @defaultValue false
+   */
+  full?: boolean | undefined;
+  slots?: Partial<DocsPageSlots>;
+  footer?: FooterOptions;
+  breadcrumb?: BreadcrumbOptions;
+  tableOfContent?: TableOfContentOptions;
+  tableOfContentPopover?: TableOfContentPopoverOptions;
+}
+interface BreadcrumbOptions extends BreadcrumbProps {
+  enabled?: boolean;
+  /**
+   * @deprecated use `slots.breadcrumb` instead.
+   */
+  component?: ReactNode;
+}
+interface FooterOptions extends FooterProps {
+  enabled?: boolean;
+  /**
+   * @deprecated use `slots.footer` instead.
+   */
+  component?: ReactNode;
+}
+type TableOfContentOptions = Pick<TOCProviderProps, 'single'> & TOCProps & {
+  enabled?: boolean;
+  /**
+   * @deprecated use `slots.toc` instead.
+   */
+  component?: ReactNode;
+};
+type TableOfContentPopoverOptions = TOCPopoverProps & {
+  enabled?: boolean;
+  /**
+   * @deprecated use `slots.tocPopover` instead.
+   */
+  component?: ReactNode;
+};
+interface DocsPageSlots {
+  toc: {
+    provider: FC<TOCProviderProps>;
+    main: FC<TOCProps>;
+    popover: FC<TOCPopoverProps>;
+  };
+  container: FC<ComponentProps<'article'>>;
+  footer: FC<FooterProps>;
+  breadcrumb: FC<BreadcrumbProps>;
+}
+declare function useDocsPage(): {
+  full: NonNullable<DocsPageProps["full"]>;
+  slots: DocsPageSlots;
+};
+declare function DocsPage({ full, tableOfContent: { enabled: tocEnabled, single, ...tocProps }, tableOfContentPopover: { enabled: tocPopoverEnabled, ...tocPopoverProps }, breadcrumb: { enabled: breadcrumbEnabled, ...breadcrumb }, footer: { enabled: footerEnabled, ...footer }, toc, slots: defaultSlots, children, ...containerProps }: DocsPageProps): import("react").JSX.Element;
+declare function EditOnGitHub(props: ComponentProps<'a'>): import("react").JSX.Element;
+/**
+ * Add typography styles
+ */
+declare function DocsBody({ children, className, ...props }: ComponentProps<'div'>): import("react").JSX.Element;
+declare function DocsDescription({ children, className, ...props }: ComponentProps<'p'>): import("react").JSX.Element | null;
+declare function DocsTitle({ children, className, ...props }: ComponentProps<'h1'>): import("react").JSX.Element;
+declare function PageLastUpdate({ date: value, ...props }: Omit<ComponentProps<'p'>, 'children'> & {
+  date: Date;
+}): import("react").JSX.Element;
+//#endregion
+export { type BreadcrumbProps, DocsBody, DocsDescription, DocsPage, DocsPageProps, DocsTitle, EditOnGitHub, type FooterProps, MarkdownCopyButton, Breadcrumb as PageBreadcrumb, Footer as PageFooter, PageLastUpdate, ViewOptionsPopover, useDocsPage };