@terrafirmagreg-team/ui 0.0.0-stage → 1.2.0

package/src/hooks/use-cycle-index.ts

@@ -0,0 +1,76 @@
+'use client';
+
+import {
+  useCallback,
+  useState,
+  useSyncExternalStore,
+} from 'react';
+
+const INTERVAL_MS = 4000;
+const TICK_MS = 250;
+
+const listeners = new Set<() => void>();
+let timer: number | undefined;
+let ticks = 0;
+
+function subscribeTick(listener: () => void) {
+  listeners.add(listener);
+  timer ??= window.setInterval(() => {
+    ticks += 1;
+    for (const listener of listeners) listener();
+  }, TICK_MS);
+  return () => {
+    listeners.delete(listener);
+    if (!listeners.size && timer !== undefined) {
+      window.clearInterval(timer);
+      timer = undefined;
+    }
+  };
+}
+
+const readTickServer = () => 0;
+
+export function useCycleIndex(
+  length: number,
+  {
+    enabled = true,
+    paused = false,
+    intervalMs = INTERVAL_MS,
+  }: { enabled?: boolean; paused?: boolean; intervalMs?: number } = {},
+) {
+  const running = enabled && !paused && length > 1;
+  const interval = intervalMs > 0 ? intervalMs : INTERVAL_MS;
+  const span = Math.max(1, Math.round(interval / TICK_MS));
+  const [offset, setOffset] = useState(0);
+
+  const subscribe = useCallback(
+    (listener: () => void) =>
+      running ? subscribeTick(listener) : () => {},
+    [running],
+  );
+  const readStep = useCallback(
+    () => Math.floor(ticks / span),
+    [span],
+  );
+  const base = useSyncExternalStore(
+    subscribe,
+    readStep,
+    readTickServer,
+  );
+  const index =
+    length > 0
+      ? (((base + offset) % length) + length) % length
+      : 0;
+
+  const setIndex = useCallback(
+    (next: number | ((current: number) => number)) => {
+      const size = Math.max(length, 1);
+      const target = typeof next === 'function' ? next(index) : next;
+      setOffset((((target - base) % size) + size) % size);
+    },
+    [index, base, length],
+  );
+
+  return [index, setIndex] as const;
+}
+

package/src/hooks/use-document-title.ts

@@ -0,0 +1,10 @@
+'use client';
+
+import { useEffect } from 'react';
+
+export function useDocumentTitle(title: string): void {
+  useEffect(() => {
+    document.title = title;
+  }, [title]);
+}
+

package/src/hooks/use-element-size.ts

@@ -0,0 +1,36 @@
+'use client';
+
+import { useEffect, useRef, useState, type RefObject } from 'react';
+
+export function useElementSize(ref: RefObject<HTMLElement | null>) {
+  const [size, setSize] = useState({ w: 0, h: 0 });
+  const observed = useRef<{ el: Element; ro: ResizeObserver } | null>(null);
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el || observed.current?.el === el) return;
+    observed.current?.ro.disconnect();
+    const apply = (width: number, height: number) =>
+      setSize((prev) =>
+        prev.w === width && prev.h === height ? prev : { w: width, h: height },
+      );
+    const ro = new ResizeObserver((entries) => {
+      const rect = entries[0]?.contentRect;
+      if (rect) apply(rect.width, rect.height);
+    });
+    ro.observe(el);
+    observed.current = { el, ro };
+    apply(el.clientWidth, el.clientHeight);
+  });
+
+  useEffect(
+    () => () => {
+      observed.current?.ro.disconnect();
+      observed.current = null;
+    },
+    [],
+  );
+
+  return size;
+}
+

package/src/hooks/use-external-meta.ts

@@ -0,0 +1,133 @@
+'use client';
+import { useEffect, useState } from 'react';
+import {
+  DEFAULT_EXTERNAL_META_PROVIDERS,
+  uiConfig,
+  type ExternalMetaProvider,
+} from '@terrafirmagreg-team/ui/lib/config';
+import { createAsyncCache } from '@terrafirmagreg-team/data/lib/async-cache';
+
+export interface ExternalMeta {
+  title: string;
+  description?: string;
+  host: string;
+}
+
+const metaCache = createAsyncCache((href: string) =>
+  resolveMeta(new URL(href), AbortSignal.timeout(6000)),
+);
+
+function pick(data: unknown, path: string): unknown {
+  return path
+    .split('.')
+    .reduce<unknown>(
+      (acc, key) =>
+        acc && typeof acc === 'object'
+          ? (acc as Record<string, unknown>)[key]
+          : undefined,
+      data,
+    );
+}
+
+function pickText(data: unknown, path?: string): string | undefined {
+  const value = path ? pick(data, path) : undefined;
+  const text = typeof value === 'string' ? value.trim() : '';
+  return text || undefined;
+}
+
+function buildUrl(
+  template: string,
+  url: URL,
+  match: RegExpMatchArray | null,
+): string {
+  return template.replace(/\{(\w+)\}/g, (_, key: string) => {
+    if (key === 'href') return encodeURIComponent(url.href);
+    if (key === 'host') return url.hostname;
+    const group = match?.[Number(key)];
+    return group !== undefined ? encodeURIComponent(group) : '';
+  });
+}
+
+async function fetchMeta(
+  provider: ExternalMetaProvider,
+  url: URL,
+  match: RegExpMatchArray | null,
+  signal: AbortSignal,
+): Promise<ExternalMeta> {
+  const res = await fetch(buildUrl(provider.url, url, match), { signal });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  const host = url.hostname;
+  if (provider.kind === 'html') {
+    const doc = new DOMParser().parseFromString(await res.text(), 'text/html');
+    return {
+      title:
+        doc
+          .querySelector("meta[property='og:title']")
+          ?.getAttribute('content')
+          ?.trim() ||
+        doc.title ||
+        host,
+      description:
+        doc
+          .querySelector(
+            "meta[property='og:description'], meta[name='description']",
+          )
+          ?.getAttribute('content') || undefined,
+      host,
+    };
+  }
+  const data = await res.json();
+  let title = pickText(data, provider.title) || host;
+  for (const [pattern, to] of provider.replace ?? []) {
+    title = title.replace(pattern, to);
+  }
+  return { title, description: pickText(data, provider.description), host };
+}
+
+async function resolveMeta(url: URL, signal: AbortSignal): Promise<ExternalMeta> {
+  const host = url.hostname;
+  for (const provider of uiConfig().externalMetaProviders ??
+    DEFAULT_EXTERNAL_META_PROVIDERS) {
+    if (!provider.host.test(host)) continue;
+    const match = provider.path ? url.pathname.match(provider.path) : null;
+    if (provider.path && !match) continue;
+    try {
+      return await fetchMeta(provider, url, match, signal);
+    } catch {
+
+    }
+  }
+  return { title: host, host };
+}
+
+export function loadExternalMeta(href: string): Promise<ExternalMeta> {
+  let url: URL;
+  try {
+    url = new URL(href);
+  } catch {
+    return Promise.resolve({ title: href, host: '' });
+  }
+  if (!/^https?:$/i.test(url.protocol)) {
+    return Promise.resolve({ title: href, host: url.hostname });
+  }
+  return metaCache(href);
+}
+
+export function useExternalMeta(
+  href: string,
+  active: boolean,
+): ExternalMeta | null {
+  const [meta, setMeta] = useState<ExternalMeta | null>(null);
+  useEffect(() => {
+    if (!active) return;
+    let mounted = true;
+    void loadExternalMeta(href).then((m) => {
+      if (mounted) setMeta(m);
+    });
+    return () => {
+      mounted = false;
+    };
+  }, [href, active]);
+  return meta;
+}
+

package/src/hooks/use-hot-key.ts

@@ -0,0 +1,34 @@
+import { useEffect, useEffectEvent } from 'react';
+
+export function useHotKey(
+  onKeyDown: (e: KeyboardEvent) => void,
+  {
+    enabled = true,
+    ignoreTyping = false,
+  }: {
+    enabled?: boolean;
+
+    ignoreTyping?: boolean;
+  } = {},
+) {
+  const listener = useEffectEvent((e: KeyboardEvent) => {
+    if (e.defaultPrevented || e.isComposing || e.keyCode === 229) return;
+    if (ignoreTyping && isTypingTarget(e.target)) return;
+    onKeyDown(e);
+  });
+
+  useEffect(() => {
+    if (!enabled) return;
+    window.addEventListener('keydown', listener);
+    return () => window.removeEventListener('keydown', listener);
+  }, [enabled]);
+}
+
+function isTypingTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false;
+  if (target.isContentEditable) return true;
+  if (['INPUT', 'TEXTAREA', 'SELECT'].includes(target.tagName)) return true;
+
+  return target.closest('[role="dialog"]') !== null;
+}
+

package/src/hooks/use-hover-follow.ts

@@ -0,0 +1,55 @@
+'use client';
+import { useCallback, type RefCallback } from 'react';
+
+export function useHoverFollow(): RefCallback<HTMLElement> {
+  return useCallback<RefCallback<HTMLElement>>((area) => {
+    const block = area?.firstElementChild;
+    if (!area || !(block instanceof HTMLElement)) return;
+    let current: Element | null = null;
+    const show = (item: Element | null) => {
+      if (item === current) return;
+      block.style.transitionProperty = current ? '' : 'opacity';
+      current = item;
+      if (!item) {
+        block.style.opacity = '0';
+        return;
+      }
+      const rect = item.getBoundingClientRect();
+      const origin = area.getBoundingClientRect();
+      block.style.translate = `${rect.left - origin.left}px ${rect.top - origin.top}px`;
+      block.style.width = `${rect.width}px`;
+      block.style.height = `${rect.height}px`;
+      block.style.opacity = item.matches('[data-active=true]') ? '0' : '1';
+    };
+    const itemOf = (target: unknown) =>
+      target instanceof Element ? target.closest('a[href], button') : null;
+    const controller = new AbortController();
+    const { signal } = controller;
+    area.addEventListener(
+      'pointerover',
+      (e) => {
+        const item = itemOf(e.target);
+        if (item && e.pointerType === 'mouse') show(item);
+      },
+      { signal },
+    );
+    area.addEventListener('pointerleave', () => show(null), { signal });
+    area.addEventListener(
+      'focusin',
+      (e) => {
+        if (e.target instanceof Element && e.target.matches(':focus-visible'))
+          show(itemOf(e.target));
+      },
+      { signal },
+    );
+    area.addEventListener(
+      'focusout',
+      () => {
+        if (!area.matches(':hover')) show(null);
+      },
+      { signal },
+    );
+    return () => controller.abort();
+  }, []);
+}
+

package/src/hooks/use-in-view.ts

@@ -0,0 +1,31 @@
+'use client';
+
+import { useEffect, useState, type RefObject } from 'react';
+
+export function useInView<T extends Element>(
+  ref: RefObject<T | null>,
+  rootMargin = '240px',
+): boolean {
+  const [inView, setInView] = useState(false);
+  useEffect(() => {
+    const el = ref.current;
+    if (!el || inView) return;
+    if (typeof IntersectionObserver === 'undefined') {
+      const id = requestAnimationFrame(() => setInView(true));
+      return () => cancelAnimationFrame(id);
+    }
+    const io = new IntersectionObserver(
+      ([entry]) => {
+        if (entry?.isIntersecting) {
+          setInView(true);
+          io.disconnect();
+        }
+      },
+      { rootMargin },
+    );
+    io.observe(el);
+    return () => io.disconnect();
+  }, [ref, rootMargin, inView]);
+  return inView;
+}
+

package/src/hooks/use-lang.ts

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

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

@@ -0,0 +1,16 @@
+'use client';
+
+import { useState } from 'react';
+
+export function useLastValue<T>(
+  value: T | undefined,
+  key?: string,
+): T | undefined {
+  const [held, setHeld] = useState<{ key?: string; value: T } | undefined>();
+  const stale = held === undefined || held.key !== key;
+  if (value !== undefined && (stale || !Object.is(held?.value, value))) {
+    setHeld({ key, value });
+  }
+  return value ?? (stale ? undefined : held?.value);
+}
+

package/src/hooks/use-layout.ts

@@ -0,0 +1,19 @@
+'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/use-marquee.ts

@@ -0,0 +1,52 @@
+'use client';
+import { useEffect, useRef, type RefObject } from 'react';
+
+export function useMarquee<T extends HTMLElement>(): RefObject<T | null> {
+  const ref = useRef<T>(null);
+
+  useEffect(() => {
+    const outer = ref.current;
+    const inner = outer?.firstElementChild;
+    if (!outer || !(inner instanceof HTMLElement)) return;
+    const target =
+      outer.closest(
+        'a, button, [role="menuitem"], [role="menuitemradio"], [role="menuitemcheckbox"], [role="option"]',
+      ) ?? outer;
+
+    const measure = () => {
+      const overflow = inner.scrollWidth - outer.clientWidth;
+      outer.classList.toggle('marquee', overflow > 1);
+      if (overflow > 1) {
+        inner.style.setProperty('--marquee-x', `${-overflow}px`);
+        inner.style.setProperty(
+          '--marquee-duration',
+          `${Math.max(1.5, overflow / 30)}s`,
+        );
+      }
+    };
+    const start = () => {
+      measure();
+      outer.classList.add('marquee-run');
+    };
+    const stop = () => outer.classList.remove('marquee-run');
+
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(outer);
+    observer.observe(inner);
+    target.addEventListener('pointerenter', start);
+    target.addEventListener('pointerleave', stop);
+    target.addEventListener('focusin', start);
+    target.addEventListener('focusout', stop);
+    return () => {
+      observer.disconnect();
+      target.removeEventListener('pointerenter', start);
+      target.removeEventListener('pointerleave', stop);
+      target.removeEventListener('focusin', start);
+      target.removeEventListener('focusout', stop);
+    };
+  }, []);
+
+  return ref;
+}
+

package/src/hooks/use-media-query.ts

@@ -0,0 +1,15 @@
+'use client';
+import { useSyncExternalStore } from 'react';
+
+export function useMediaQuery(query: string): boolean {
+  return useSyncExternalStore(
+    (onChange) => {
+      const mql = window.matchMedia(query);
+      mql.addEventListener('change', onChange);
+      return () => mql.removeEventListener('change', onChange);
+    },
+    () => window.matchMedia(query).matches,
+    () => false,
+  );
+}
+

package/src/hooks/use-mobile.ts

@@ -0,0 +1,20 @@
+import * as React from "react"
+
+const MOBILE_BREAKPOINT = 768
+
+export function useIsMobile() {
+  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)
+
+  React.useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
+    const onChange = () => {
+      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    }
+    mql.addEventListener("change", onChange)
+    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    return () => mql.removeEventListener("change", onChange)
+  }, [])
+
+  return !!isMobile
+}
+

package/src/hooks/use-modifier-keys.ts

@@ -0,0 +1,32 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+export type ModifierKeys = {
+  shift: boolean;
+  ctrl: boolean;
+  alt: boolean;
+};
+
+const IDLE: ModifierKeys = { shift: false, ctrl: false, alt: false };
+
+export function useModifierKeys(active = true): ModifierKeys {
+  const [keys, setKeys] = useState<ModifierKeys>(IDLE);
+  useEffect(() => {
+    if (!active) return;
+    const update = (e: KeyboardEvent) => {
+      setKeys({ shift: e.shiftKey, ctrl: e.ctrlKey, alt: e.altKey });
+    };
+    const reset = () => setKeys(IDLE);
+    window.addEventListener('keydown', update);
+    window.addEventListener('keyup', update);
+    window.addEventListener('blur', reset);
+    return () => {
+      window.removeEventListener('keydown', update);
+      window.removeEventListener('keyup', update);
+      window.removeEventListener('blur', reset);
+    };
+  }, [active]);
+  return keys;
+}
+

package/src/hooks/use-on-change.ts

@@ -0,0 +1,36 @@
+import { useState } from 'react';
+
+function isEqualShallow(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true;
+  if (
+    !a ||
+    !b ||
+    typeof a !== 'object' ||
+    typeof b !== 'object' ||
+    Array.isArray(a) !== Array.isArray(b)
+  )
+    return false;
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  return aKeys.every((key) =>
+    Object.is(
+      (a as Record<string, unknown>)[key],
+      (b as Record<string, unknown>)[key],
+    ),
+  );
+}
+
+export function useOnChange<T>(
+  value: T,
+  onChange: (current: T, previous: T) => void,
+  isUpdated: (prev: T, current: T) => boolean = (a, b) =>
+    !isEqualShallow(a, b),
+) {
+  const [prev, setPrev] = useState(value);
+  if (isUpdated(prev, value)) {
+    onChange(value, prev);
+    setPrev(value);
+  }
+}
+

package/src/hooks/use-pane-keys.ts

@@ -0,0 +1,29 @@
+'use client';
+
+import { useEffect } from 'react';
+
+export function usePaneKeys<T extends string>(
+  picks: Partial<Record<'r' | 'u' | 't', T>>,
+  onSelect: (id: T) => void,
+) {
+  const { r, u, t } = picks;
+  useEffect(() => {
+    const map = { r, u, t };
+    const onKey = (event: KeyboardEvent) => {
+      if (event.ctrlKey || event.metaKey || event.altKey) return;
+      const target = event.target as HTMLElement | null;
+      if (
+        target?.closest(
+          'input, textarea, select, [contenteditable="true"], [role="textbox"]',
+        )
+      ) {
+        return;
+      }
+      const id = map[event.key.toLowerCase() as 'r' | 'u' | 't'];
+      if (id) onSelect(id);
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [r, u, t, onSelect]);
+}
+

package/src/hooks/use-sidebar.ts

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