@terrafirmagreg-team/ui 0.0.0-stage → 0.1.0

package/src/components/ui/tooltip.tsx

@@ -0,0 +1,65 @@
+"use client"
+
+import { Tooltip as TooltipPrimitive } from "@base-ui/react/tooltip"
+import { cn } from "cn"
+
+function TooltipProvider({
+  delay = 0,
+  ...props
+}: TooltipPrimitive.Provider.Props) {
+  return (
+    <TooltipPrimitive.Provider
+      data-slot="tooltip-provider"
+      delay={delay}
+      {...props}
+    />
+  )
+}
+
+function Tooltip({ ...props }: TooltipPrimitive.Root.Props) {
+  return <TooltipPrimitive.Root data-slot="tooltip" {...props} />
+}
+
+function TooltipTrigger({ ...props }: TooltipPrimitive.Trigger.Props) {
+  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />
+}
+
+function TooltipContent({
+  className,
+  side = "top",
+  sideOffset = 4,
+  align = "center",
+  alignOffset = 0,
+  children,
+  ...props
+}: TooltipPrimitive.Popup.Props &
+  Pick<
+    TooltipPrimitive.Positioner.Props,
+    "align" | "alignOffset" | "side" | "sideOffset"
+  >) {
+  return (
+    <TooltipPrimitive.Portal>
+      <TooltipPrimitive.Positioner
+        align={align}
+        alignOffset={alignOffset}
+        side={side}
+        sideOffset={sideOffset}
+        className="isolate z-overlay"
+      >
+        <TooltipPrimitive.Popup
+          data-slot="tooltip-content"
+          className={cn(
+            "z-overlay inline-flex w-fit max-w-xs origin-(--transform-origin) items-center gap-1.5 rounded-md bg-foreground px-3 py-1.5 text-xs text-background has-data-[slot=kbd]:pr-1.5 data-[side=bottom]:slide-in-from-top-2 data-[side=inline-end]:slide-in-from-left-2 data-[side=inline-start]:slide-in-from-right-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 **:data-[slot=kbd]:relative **:data-[slot=kbd]:isolate **:data-[slot=kbd]:z-overlay **:data-[slot=kbd]:rounded-sm data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+            className
+          )}
+          {...props}
+        >
+          {children}
+          <TooltipPrimitive.Arrow className="z-overlay size-2.5 translate-y-[calc(-50%-2px)] rotate-45 rounded-[2px] bg-foreground fill-foreground data-[side=bottom]:top-1 data-[side=inline-end]:top-1/2! data-[side=inline-end]:-left-1 data-[side=inline-end]:-translate-y-1/2 data-[side=inline-start]:top-1/2! data-[side=inline-start]:-right-1 data-[side=inline-start]:-translate-y-1/2 data-[side=left]:top-1/2! data-[side=left]:-right-1 data-[side=left]:-translate-y-1/2 data-[side=right]:top-1/2! data-[side=right]:-left-1 data-[side=right]:-translate-y-1/2 data-[side=top]:-bottom-2.5" />
+        </TooltipPrimitive.Popup>
+      </TooltipPrimitive.Positioner>
+    </TooltipPrimitive.Portal>
+  )
+}
+
+export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider }

package/src/hooks/canvas/use-flow-hover.ts

@@ -0,0 +1,18 @@
+'use client';
+
+import { createContext, useContext, useMemo, useState } from 'react';
+import type { FlowHoverValue } from '@terrafirmagreg-team/ui/types/canvas';
+
+export const FlowHoverContext = createContext<FlowHoverValue>({
+  id: null,
+  setId: () => {},
+});
+
+export function useFlowHover(): FlowHoverValue {
+  const [id, setId] = useState<string | null>(null);
+  return useMemo(() => ({ id, setId }), [id]);
+}
+
+export function useFlowHoverState(): FlowHoverValue {
+  return useContext(FlowHoverContext);
+}

package/src/hooks/canvas/use-flow-viewport-persist.ts

@@ -0,0 +1,33 @@
+'use client';
+
+import { useCallback, useEffect, useRef } from 'react';
+import { VIEWPORT_SAVE_MS, writeStoredViewport } from '@terrafirmagreg-team/ui/lib/canvas/viewport';
+import type { StoredViewport } from '@terrafirmagreg-team/ui/types/canvas';
+
+export function useFlowViewportPersist(storageKey: string, resetKey: string) {
+  const ready = useRef(false);
+  const timer = useRef(0);
+
+  useEffect(() => {
+    ready.current = false;
+  }, [resetKey]);
+
+  useEffect(() => () => window.clearTimeout(timer.current), [storageKey]);
+
+  const markReady = useCallback(() => {
+    ready.current = true;
+  }, []);
+
+  const persist = useCallback(
+    (viewport: StoredViewport) => {
+      if (!ready.current) return;
+      window.clearTimeout(timer.current);
+      timer.current = window.setTimeout(() => {
+        writeStoredViewport(storageKey, viewport);
+      }, VIEWPORT_SAVE_MS);
+    },
+    [storageKey],
+  );
+
+  return { markReady, persist };
+}

package/src/hooks/lang.ts

@@ -0,0 +1,8 @@
+'use client';
+import { createContext, useContext } from 'react';
+
+export const UntranslatedContext = createContext(false);
+
+export function useUntranslated(): boolean {
+  return useContext(UntranslatedContext);
+}

package/src/hooks/layout.ts

@@ -0,0 +1,18 @@
+'use client';
+import {
+  createContext,
+  use,
+  type ComponentProps,
+  type ComponentType,
+} from 'react';
+
+export const LayoutContext = createContext<{
+  navTitle: ComponentType<ComponentProps<'a'>>;
+} | null>(null);
+
+export function useLayout() {
+  const context = use(LayoutContext);
+  if (!context)
+    throw new Error('Missing LayoutContext, expected under <Layout />.');
+  return context;
+}

package/src/hooks/page/use-fit-pages.ts

@@ -0,0 +1,91 @@
+'use client';
+
+import { useMemo, type RefObject } from 'react';
+import { useElementSize } from '@terrafirmagreg-team/ui/hooks/use-element-size';
+
+export type FitDim = { w: number; h: number };
+
+type FitPageList<T> = {
+  page: number;
+  pages: number;
+  shown: T[];
+  to: number;
+  total: number;
+  measured: boolean;
+  box: FitDim;
+};
+
+export function useFitPages<T>(
+  boxRef: RefObject<HTMLElement | null>,
+  items: readonly T[],
+  dim: (item: T, box: FitDim) => FitDim,
+  urlPage: number,
+  gap = 8,
+  focus?: number,
+  vertical = false,
+): FitPageList<T> {
+  const { w, h } = useElementSize(boxRef);
+  return useMemo(() => {
+    const measured = w > 0 && h > 0;
+    const box: FitDim = { w, h };
+    if (!measured) {
+      return {
+        page: 0,
+        pages: 1,
+        shown: [],
+        to: 0,
+        total: items.length,
+        measured,
+        box,
+      };
+    }
+
+    const packed: T[][] = [];
+    let page: T[] = [];
+    let shelfW = 0;
+    let shelfH = 0;
+    let usedH = 0;
+    let focusPage = -1;
+    items.forEach((item, i) => {
+      const d = dim(item, box);
+      const iw = vertical ? w : Math.max(1, d.w);
+      const ih = Math.max(1, d.h);
+      if (shelfW > 0 && shelfW + gap + iw > w) {
+        usedH += shelfH + (usedH > 0 ? gap : 0);
+        shelfW = 0;
+        shelfH = 0;
+        if (usedH + ih > h && page.length) {
+          packed.push(page);
+          page = [];
+          usedH = 0;
+        }
+      }
+      shelfW = shelfW === 0 ? iw : shelfW + gap + iw;
+      shelfH = Math.max(shelfH, ih);
+      if (focus === i) focusPage = packed.length;
+      page.push(item);
+    });
+    if (page.length) packed.push(page);
+    if (!packed.length) packed.push([]);
+
+    const raw = Number.isFinite(urlPage) ? Math.floor(urlPage) : 0;
+    const clamped =
+      focusPage >= 0
+        ? focusPage
+        : Math.max(0, Math.min(raw, packed.length - 1));
+    let to = 0;
+    for (let i = 0; i <= clamped && i < packed.length; i += 1) {
+      to += packed[i].length;
+    }
+    return {
+      page: clamped,
+      pages: packed.length,
+      shown: packed[clamped],
+      to,
+      total: items.length,
+      measured,
+      box,
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- dim is item-keyed
+  }, [items, w, h, urlPage, gap, focus, vertical]);
+}

package/src/hooks/page/use-location-search.ts

@@ -0,0 +1,25 @@
+'use client';
+
+import { useSyncExternalStore } from 'react';
+
+let search = '';
+const listeners = new Set<() => void>();
+
+export function publishLocationSearch(value: string) {
+  if (search === value) return;
+  search = value;
+  for (const listener of listeners) listener();
+}
+
+function subscribe(listener: () => void) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function useLocationSearch(): string {
+  return useSyncExternalStore(
+    subscribe,
+    () => search,
+    () => '',
+  );
+}

package/src/hooks/page/use-page-preview.ts

@@ -0,0 +1,40 @@
+'use client';
+import { useEffect, useState } from 'react';
+import { uiConfig } from '@terrafirmagreg-team/ui/lib/config';
+import { createAsyncCache } from '@terrafirmagreg-team/ui/lib/utils/async-cache';
+import type { PagePreviewData } from '@terrafirmagreg-team/ui/types/preview';
+
+const previewCache = createAsyncCache(
+  async (key: string): Promise<PagePreviewData | undefined> => {
+    const [href, lang] = key.split(' ');
+    return uiConfig().loadPagePreview?.(href ?? '', { lang: lang || undefined });
+  },
+);
+
+export function loadPagePreview(
+  href: string,
+  lang?: string,
+): Promise<PagePreviewData | undefined> {
+  return previewCache(`${href} ${lang ?? ''}`);
+}
+
+export function usePagePreview(
+  href: string,
+  active: boolean,
+  lang?: string,
+): PagePreviewData | null | undefined {
+  const [preview, setPreview] = useState<PagePreviewData | null | undefined>(
+    null,
+  );
+  useEffect(() => {
+    if (!active) return;
+    let mounted = true;
+    void loadPagePreview(href, lang).then((data) => {
+      if (mounted) setPreview(data);
+    });
+    return () => {
+      mounted = false;
+    };
+  }, [href, active, lang]);
+  return preview;
+}

package/src/hooks/page/use-paged-list.ts

@@ -0,0 +1,20 @@
+'use client';
+
+import { useMemo } from 'react';
+
+export function usePagedList<T>(
+  items: readonly T[],
+  pageIndex: number,
+  pageSize: number,
+) {
+  return useMemo(() => {
+    const size = Math.max(1, Math.floor(pageSize) || 1);
+    const pages = Math.max(1, Math.ceil(items.length / size));
+    const raw = Number.isFinite(pageIndex) ? Math.floor(pageIndex) : 0;
+    const page = Math.max(0, Math.min(raw, pages - 1));
+    const shown = items.slice(page * size, (page + 1) * size);
+    const from = items.length ? page * size + 1 : 0;
+    const to = Math.min(items.length, (page + 1) * size);
+    return { page, pages, shown, from, to, total: items.length };
+  }, [items, pageIndex, pageSize]);
+}

package/src/hooks/readability/provider.ts

@@ -0,0 +1,86 @@
+'use client';
+import { useMediaQuery } from '@terrafirmagreg-team/ui/hooks/use-media-query';
+import {
+  createContext,
+  createElement,
+  useCallback,
+  useContext,
+  useLayoutEffect,
+  useMemo,
+  useSyncExternalStore,
+  type ReactNode,
+} from 'react';
+import {
+  applyState,
+  clampWidth,
+  clearState,
+  getServerSnapshot,
+  readState,
+  subscribe,
+  writeState,
+} from '@terrafirmagreg-team/ui/lib/readability/store';
+import type {
+  ReadabilityLayout,
+  ReadabilityValue,
+  SpotlightStyle,
+} from '@terrafirmagreg-team/ui/types/readability';
+
+const ReadabilityContext = createContext<ReadabilityValue | null>(null);
+
+export function useReadability(): ReadabilityValue {
+  const context = useContext(ReadabilityContext);
+  if (!context) throw new Error('Missing ReadabilityProvider');
+  return context;
+}
+
+export function ReadabilityProvider({ children }: { children: ReactNode }) {
+  const state = useSyncExternalStore(subscribe, readState, getServerSnapshot);
+  const coarsePointer = useMediaQuery('(pointer: coarse)') === true;
+  const smallScreen = useMediaQuery('(min-width: 768px)') !== true;
+
+  useLayoutEffect(() => {
+    applyState(state);
+  }, [state]);
+  useLayoutEffect(() => clearState, []);
+
+  const setLayout = useCallback((layout: ReadabilityLayout) => {
+    writeState({ layout });
+  }, []);
+  const setPageWidth = useCallback((pageWidth: number) => {
+    writeState({ pageWidth: clampWidth(pageWidth, 100) });
+  }, []);
+  const setContentWidth = useCallback((contentWidth: number) => {
+    writeState({ contentWidth: clampWidth(contentWidth, 100) });
+  }, []);
+  const setSpotlight = useCallback((spotlight: boolean) => {
+    writeState({ spotlight });
+  }, []);
+  const setSpotlightStyle = useCallback((spotlightStyle: SpotlightStyle) => {
+    writeState({ spotlightStyle });
+  }, []);
+
+  const value = useMemo(
+    () => ({
+      ...state,
+      coarsePointer,
+      smallScreen,
+      setLayout,
+      setPageWidth,
+      setContentWidth,
+      setSpotlight,
+      setSpotlightStyle,
+    }),
+    [
+      state,
+      coarsePointer,
+      smallScreen,
+      setLayout,
+      setPageWidth,
+      setContentWidth,
+      setSpotlight,
+      setSpotlightStyle,
+    ],
+  );
+
+  return createElement(ReadabilityContext.Provider, { value }, children);
+}

package/src/hooks/search/dialog.ts

@@ -0,0 +1,41 @@
+'use client';
+import { createContext, use } from 'react';
+import type {
+  SearchItemType,
+  SearchResult,
+} from '@terrafirmagreg-team/ui/types/search';
+
+export const SearchDialogContext = createContext<{
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  search: string;
+  onSearchChange: (v: string) => void;
+  onSelect: (item: SearchItemType) => void;
+  isLoading: boolean;
+  data?: SearchResult;
+  error?: Error;
+
+  query: string;
+
+  getActive: () => string | null;
+  setActive: (id: string | null) => void;
+  subscribeActive: (listener: () => void) => () => void;
+} | null>(null);
+
+export const SearchTagsListContext = createContext<{
+  value?: string;
+  onValueChange: (value: string | undefined) => void;
+  allowClear: boolean;
+} | null>(null);
+
+export function useSearch() {
+  const ctx = use(SearchDialogContext);
+  if (!ctx) throw new Error('Missing <SearchDialog />');
+  return ctx;
+}
+
+export function useSearchTagsList() {
+  const ctx = use(SearchTagsListContext);
+  if (!ctx) throw new Error('Missing <SearchTagsList />');
+  return ctx;
+}

package/src/hooks/search/provider.ts

@@ -0,0 +1,25 @@
+'use client';
+import { Dialog } from '@base-ui/react/dialog';
+import { createContext, use } from 'react';
+
+export const dialogHandle = Dialog.createHandle();
+
+export interface SearchContextType {
+  enabled: boolean;
+  open: boolean;
+  hotKey: { display: React.ReactNode; key: string | ((e: KeyboardEvent) => boolean) }[];
+  setOpenSearch: (value: boolean) => void;
+  dialogHandle: Dialog.Handle<unknown>;
+}
+
+export const SearchContext = createContext<SearchContextType>({
+  enabled: false,
+  open: false,
+  hotKey: [],
+  setOpenSearch: () => undefined,
+  dialogHandle,
+});
+
+export function useSearchContext(): SearchContextType {
+  return use(SearchContext);
+}

package/src/hooks/search/use-highlight-query.ts

@@ -0,0 +1,51 @@
+'use client';
+import { useCallback } from 'react';
+
+function buildRegexFromQuery(query: string): RegExp | null {
+  const source = query
+    .trim()
+    .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    .replace(/\s+/g, '|');
+  return source ? new RegExp(source, 'gi') : null;
+}
+
+export function useHighlightQuery(query: string) {
+  return useCallback(
+    (element: Element | null) => {
+      const regex = buildRegexFromQuery(query);
+      if (!element || !regex || typeof Highlight === 'undefined')
+        return () => {};
+      let highlight = CSS.highlights.get('search-hit');
+      if (!highlight)
+        CSS.highlights.set('search-hit', (highlight = new Highlight()));
+      const walker = document.createTreeWalker(
+        element,
+        NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT,
+        (node) => {
+          if (!(node instanceof Element)) return NodeFilter.FILTER_ACCEPT;
+          return node.hasAttribute('data-highlight-ignore')
+            ? NodeFilter.FILTER_REJECT
+            : NodeFilter.FILTER_SKIP;
+        },
+      );
+      const ranges: StaticRange[] = [];
+      while (walker.nextNode()) {
+        const node = walker.currentNode as Text;
+        for (const match of node.data.matchAll(regex)) {
+          const range = new StaticRange({
+            startContainer: node,
+            startOffset: match.index,
+            endContainer: node,
+            endOffset: match.index + match[0].length,
+          });
+          highlight.add(range);
+          ranges.push(range);
+        }
+      }
+      return () => {
+        for (const range of ranges) highlight.delete(range);
+      };
+    },
+    [query],
+  );
+}

package/src/hooks/sidebar.ts

@@ -0,0 +1,63 @@
+'use client';
+import {
+  createContext,
+  use,
+  useEffect,
+  type RefObject,
+} from 'react';
+import scrollIntoView from 'scroll-into-view-if-needed';
+
+export interface SidebarContextValue {
+  open: boolean;
+  setOpen: (v: boolean) => void;
+  collapsed: boolean;
+  setCollapsed: React.Dispatch<React.SetStateAction<boolean>>;
+
+  closeOnRedirect: RefObject<boolean>;
+  defaultOpenLevel: number;
+  prefetch?: boolean;
+  mode: 'drawer' | 'full';
+}
+
+export interface FolderContextValue {
+  open: boolean;
+  setOpen: (v: boolean) => void;
+  depth: number;
+  collapsible: boolean;
+}
+
+export const SidebarContext = createContext<SidebarContextValue | null>(null);
+export const FolderContext = createContext<FolderContextValue | null>(null);
+
+export function useSidebar(): SidebarContextValue {
+  const ctx = use(SidebarContext);
+  if (!ctx)
+    throw new Error(
+      'Missing SidebarContext, make sure you have wrapped the component in <DocsLayout /> and the context is available.',
+    );
+  return ctx;
+}
+
+export function useFolder(): FolderContextValue | null {
+  return use(FolderContext);
+}
+
+export function useFolderDepth(): number {
+  return use(FolderContext)?.depth ?? 0;
+}
+
+export function useAutoScroll(
+  active: boolean,
+  ref: RefObject<HTMLElement | null>,
+): void {
+  const { mode } = useSidebar();
+  useEffect(() => {
+    if (active && ref.current)
+      scrollIntoView(ref.current, {
+        boundary: document.getElementById(
+          mode === 'drawer' ? 'sidebar-mobile' : 'sidebar',
+        ),
+        scrollMode: 'if-needed',
+      });
+  }, [active, mode, ref]);
+}

package/src/hooks/use-async-value.ts

@@ -0,0 +1,57 @@
+'use client';
+
+import { useEffect, useState, type DependencyList } from 'react';
+
+type AsyncEffectBody = (
+  isCancelled: () => boolean,
+) => void | Promise<unknown> | (() => void);
+
+export function useAsyncEffect(
+  effect: AsyncEffectBody | false | null | undefined,
+  deps: DependencyList,
+): void {
+  useEffect(() => {
+    if (!effect) return;
+    let cancelled = false;
+    const cleanup = effect(() => cancelled);
+    return () => {
+      cancelled = true;
+      if (typeof cleanup === 'function') cleanup();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- deps owned by caller
+  }, deps);
+}
+
+export function useAsyncValue<T>(
+  factory: (() => Promise<T>) | false | null | undefined,
+  deps: DependencyList,
+): T | undefined {
+  return useAsyncResult(factory, deps).value;
+}
+
+export function useAsyncResult<T>(
+  factory: (() => Promise<T>) | false | null | undefined,
+  deps: DependencyList,
+): { value: T | undefined; pending: boolean } {
+  const [entry, setEntry] = useState<{
+    deps: DependencyList;
+    value: T | undefined;
+  }>();
+  useAsyncEffect(async (isCancelled) => {
+    if (!factory) return;
+    try {
+      const next = await factory();
+      if (!isCancelled()) setEntry({ deps, value: next });
+    } catch {
+      if (!isCancelled()) setEntry({ deps, value: undefined });
+    }
+  }, deps);
+  const resolved =
+    entry !== undefined &&
+    entry.deps.length === deps.length &&
+    entry.deps.every((dep, i) => Object.is(dep, deps[i]));
+  return {
+    value: factory && resolved ? entry?.value : undefined,
+    pending: Boolean(factory) && !resolved,
+  };
+}

package/src/hooks/use-close-on-scroll.ts

@@ -0,0 +1,23 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+
+const IGNORE = '[role="menu"],[role="listbox"],[role="dialog"]';
+
+export function useCloseOnScroll(open: boolean, close: () => void): void {
+  const closeRef = useRef(close);
+  useEffect(() => {
+    closeRef.current = close;
+  }, [close]);
+
+  useEffect(() => {
+    if (!open) return;
+    const onScroll = (event: Event) => {
+      if (event.target instanceof Element && event.target.closest(IGNORE))
+        return;
+      closeRef.current();
+    };
+    window.addEventListener('scroll', onScroll, true);
+    return () => window.removeEventListener('scroll', onScroll, true);
+  }, [open]);
+}