@terrafirmagreg-team/ui 0.0.0-stage → 0.1.0

package/src/hooks/use-tree.ts

@@ -0,0 +1,102 @@
+'use client';
+import { useMemo, createContext, use } from 'react';
+import type * as PageTree from '@terrafirmagreg-team/translate/types/tree';
+import type { TabOption, TreeContextValue } from '@terrafirmagreg-team/ui/types/tree';
+import { findProjection } from '@terrafirmagreg-team/ui/lib/tree';
+
+export const TreeContext = createContext<TreeContextValue | null>(null);
+export const PathContext = createContext<PageTree.Node[]>([]);
+
+export function useTreePath(): PageTree.Node[] {
+  return use(PathContext);
+}
+
+export function useTreeContext(): TreeContextValue {
+  const ctx = use(TreeContext);
+  if (!ctx)
+    throw new Error('You must wrap this component under <DocsLayout />');
+  return ctx;
+}
+
+
+export function useTabsGroups(tabs: TabOption[]): {
+  active?: PageTree.Folder;
+  options: TabOption[];
+}[] {
+  const { full: tree } = useTreeContext();
+  const path = use(PathContext);
+
+  return useMemo(() => {
+    const out: { active?: PageTree.Folder; options: TabOption[] }[] = [];
+    const last = path[path.length - 1];
+    const page = last?.type === 'page' ? last : undefined;
+    let scope = tree.fallback
+      ? [...tree.children, ...tree.fallback.children]
+      : tree.children;
+
+    for (const node of path) {
+      if (node.type !== 'folder' || !node.root) continue;
+      const group = { active: node, options: [] as TabOption[] };
+      collectTabs(scope, node, page, tabs, group.options);
+      if (group.options.length > 0) out.push(group);
+      scope = node.children;
+    }
+
+    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]);
+}
+
+
+function collectTabs(
+  scope: PageTree.Node[],
+  active: PageTree.Folder,
+  page: PageTree.Item | undefined,
+  tabs: TabOption[],
+  out: TabOption[],
+): void {
+  for (const node of scope) {
+    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 && findProjection(active, node, page);
+      out.push(projection ? { ...tab, url: projection.url } : tab);
+    } else if (!node.root) {
+      collectTabs(node.children, active, page, tabs, out);
+    }
+  }
+}
+
+const footerCache = new WeakMap<PageTree.Root | PageTree.Folder, PageTree.Item[]>();
+
+
+export function useFooterItems(): PageTree.Item[] {
+  const { root } = useTreeContext();
+  const cached = footerCache.get(root);
+  if (cached) return cached;
+
+  const list: PageTree.Item[] = [];
+  function onNode(node: PageTree.Node): void {
+    if (node.type === 'folder') {
+      if (node.index) onNode(node.index);
+      for (const child of node.children) onNode(child);
+    } else if (node.type === 'page' && !node.external) {
+      list.push(node);
+    }
+  }
+  for (const child of root.children) onNode(child);
+
+  footerCache.set(root, list);
+  return list;
+}

package/src/hooks/viewer/use-in-float-bar.ts

@@ -0,0 +1,6 @@
+'use client';
+import { createContext, useContext } from 'react';
+
+export const FloatBarContext = createContext(false);
+
+export const useInFloatBar = () => useContext(FloatBarContext);

package/src/hooks/viewer/use-viewer-prefs.ts

@@ -0,0 +1,77 @@
+'use client';
+
+import {
+  boolCodec,
+  createStoredValue,
+  numberCodec,
+} from '@terrafirmagreg-team/ui/lib/utils/stored-value';
+
+export const AUTOPLAY_SPEED_MIN = 1;
+export const AUTOPLAY_SPEED_MAX = 10;
+export const ROTATE_MIN = 0;
+export const ROTATE_MAX = 4;
+export const SCENE_WIDTH_MIN = 50;
+export const SCENE_WIDTH_MAX = 100;
+export const SCENE_HEIGHT_MIN = 160;
+export const SCENE_HEIGHT_MAX = 640;
+
+export const useAutoplay = createStoredValue(
+  'wiki.viewer.autoplay',
+  boolCodec(true),
+);
+
+export const useAutoplaySpeed = createStoredValue(
+  'wiki.viewer.autoplaySpeed',
+  numberCodec(4, AUTOPLAY_SPEED_MIN, AUTOPLAY_SPEED_MAX),
+);
+
+const useAutoRotate = createStoredValue(
+  'wiki.viewer.glb.autoRotate',
+  boolCodec(true),
+);
+
+const useRotateSpeed = createStoredValue(
+  'wiki.viewer.glb.rotateSpeed',
+  numberCodec(1, ROTATE_MIN, ROTATE_MAX),
+);
+
+const useDotGrid = createStoredValue(
+  'wiki.viewer.glb.dotGrid',
+  boolCodec(true),
+);
+
+const useSceneWidth = createStoredValue(
+  'wiki.viewer.glb.width',
+  numberCodec(SCENE_WIDTH_MAX, SCENE_WIDTH_MIN, SCENE_WIDTH_MAX),
+);
+
+const useSceneHeight = createStoredValue(
+  'wiki.viewer.glb.height',
+  numberCodec(288, SCENE_HEIGHT_MIN, SCENE_HEIGHT_MAX),
+);
+
+export function useViewerPrefs() {
+  const [autoplay, setAutoplay] = useAutoplay();
+  const [autoplaySpeed, setAutoplaySpeed] = useAutoplaySpeed();
+  const [autoRotate, setAutoRotate] = useAutoRotate();
+  const [rotateSpeed, setRotateSpeed] = useRotateSpeed();
+  const [dotGrid, setDotGrid] = useDotGrid();
+  const [sceneWidth, setSceneWidth] = useSceneWidth();
+  const [sceneHeight, setSceneHeight] = useSceneHeight();
+  return {
+    autoplay,
+    setAutoplay,
+    autoplaySpeed,
+    setAutoplaySpeed,
+    autoRotate,
+    setAutoRotate,
+    rotateSpeed,
+    setRotateSpeed,
+    dotGrid,
+    setDotGrid,
+    sceneWidth,
+    setSceneWidth,
+    sceneHeight,
+    setSceneHeight,
+  };
+}

package/src/lib/canvas/edge.ts

@@ -0,0 +1,173 @@
+import type {
+  ChevronEdgeHighlight,
+  FlowPoint,
+} from '@terrafirmagreg-team/ui/types/canvas';
+
+const CHEVRON_SPACING = 10;
+const CHEVRON_SIZE = 3.5;
+
+const RUN_COS = Math.cos(Math.PI / 7);
+
+export type ChevronRun = { d: string; shiftX: number; shiftY: number };
+
+export function chevronTicksAlongPath(
+  points: readonly FlowPoint[],
+): ChevronRun[] {
+  if (points.length < 2) return [];
+  const lens: number[] = [];
+  let total = 0;
+  for (let i = 0; i + 1 < points.length; i += 1) {
+    const len = Math.hypot(
+      points[i + 1]!.x - points[i]!.x,
+      points[i + 1]!.y - points[i]!.y,
+    );
+    lens.push(len);
+    total += len;
+  }
+  if (total < 2) return [];
+  const size = CHEVRON_SIZE;
+  const back = size * 0.45;
+  const wing = size * 0.9;
+  const runs: { ux: number; uy: number; parts: string[] }[] = [];
+  let run: (typeof runs)[0] | null = null;
+  let seg = 0;
+  let segStart = 0;
+  for (let d = CHEVRON_SPACING; d <= total; d += CHEVRON_SPACING) {
+    while (seg < lens.length && segStart + lens[seg]! < d) {
+      segStart += lens[seg]!;
+      seg += 1;
+    }
+    if (seg >= lens.length) break;
+    const len = lens[seg]!;
+    if (len < 0.001) continue;
+    const p0 = points[seg]!;
+    const p1 = points[seg + 1]!;
+    const t = (d - segStart) / len;
+    const ux = (p1.x - p0.x) / len;
+    const uy = (p1.y - p0.y) / len;
+    const cx = p0.x + (p1.x - p0.x) * t;
+    const cy = p0.y + (p1.y - p0.y) * t;
+    if (!run || ux * run.ux + uy * run.uy < RUN_COS) {
+      run = { ux, uy, parts: [] };
+      runs.push(run);
+    }
+    const px = -uy;
+    const py = ux;
+    run.parts.push(
+      `M${cx - ux * back + px * wing} ${cy - uy * back + py * wing}L${cx + ux * size} ${cy + uy * size}L${cx - ux * back - px * wing} ${cy - uy * back - py * wing}`,
+    );
+  }
+  return runs.map((entry) => ({
+    d: entry.parts.join(''),
+    shiftX: entry.ux * CHEVRON_SPACING,
+    shiftY: entry.uy * CHEVRON_SPACING,
+  }));
+}
+
+export function svgPathToPoints(d: string, samples = 12): FlowPoint[] {
+  const out: FlowPoint[] = [];
+  const re = /([MLCQ])([^MLCQ]*)/g;
+  let match: RegExpExecArray | null;
+  let cur: FlowPoint = { x: 0, y: 0 };
+  while ((match = re.exec(d))) {
+    const nums = match[2]!.trim().split(/[\s,]+/).map(Number);
+    if (match[1] === 'M' || match[1] === 'L') {
+      for (let i = 0; i + 1 < nums.length; i += 2) {
+        cur = { x: nums[i]!, y: nums[i + 1]! };
+        out.push(cur);
+      }
+    } else if (match[1] === 'C') {
+      for (let i = 0; i + 5 < nums.length; i += 6) {
+        const p0 = cur;
+        const c1 = { x: nums[i]!, y: nums[i + 1]! };
+        const c2 = { x: nums[i + 2]!, y: nums[i + 3]! };
+        const p1 = { x: nums[i + 4]!, y: nums[i + 5]! };
+        for (let s = 1; s <= samples; s += 1) {
+          const t = s / samples;
+          const mt = 1 - t;
+          out.push({
+            x:
+              mt * mt * mt * p0.x +
+              3 * mt * mt * t * c1.x +
+              3 * mt * t * t * c2.x +
+              t * t * t * p1.x,
+            y:
+              mt * mt * mt * p0.y +
+              3 * mt * mt * t * c1.y +
+              3 * mt * t * t * c2.y +
+              t * t * t * p1.y,
+          });
+        }
+        cur = p1;
+      }
+    } else if (match[1] === 'Q') {
+      for (let i = 0; i + 3 < nums.length; i += 4) {
+        const p0 = cur;
+        const c = { x: nums[i]!, y: nums[i + 1]! };
+        const p1 = { x: nums[i + 2]!, y: nums[i + 3]! };
+        for (let s = 1; s <= samples; s += 1) {
+          const t = s / samples;
+          const mt = 1 - t;
+          out.push({
+            x: mt * mt * p0.x + 2 * mt * t * c.x + t * t * p1.x,
+            y: mt * mt * p0.y + 2 * mt * t * c.y + t * t * p1.y,
+          });
+        }
+        cur = p1;
+      }
+    }
+  }
+  return out;
+}
+
+export function chamferedPolylinePath(
+  points: readonly FlowPoint[],
+  cut = 8,
+): string {
+  if (!points.length) return '';
+  if (points.length < 3) {
+    return `M${points[0]!.x} ${points[0]!.y}${points
+      .slice(1)
+      .map((p) => `L${p.x} ${p.y}`)
+      .join('')}`;
+  }
+  let d = `M${points[0]!.x} ${points[0]!.y}`;
+  let cursor = points[0]!;
+  for (let i = 1; i + 1 < points.length; i += 1) {
+    const corner = points[i]!;
+    const next = points[i + 1]!;
+    const inLen = Math.hypot(corner.x - cursor.x, corner.y - cursor.y);
+    const outLen = Math.hypot(next.x - corner.x, next.y - corner.y);
+    const take = Math.min(cut, inLen / 2, outLen / 2);
+    if (take < 0.5) {
+      d += `L${corner.x} ${corner.y}`;
+      cursor = corner;
+      continue;
+    }
+    const ax = corner.x - ((corner.x - cursor.x) / inLen) * take;
+    const ay = corner.y - ((corner.y - cursor.y) / inLen) * take;
+    const bx = corner.x + ((next.x - corner.x) / outLen) * take;
+    const by = corner.y + ((next.y - corner.y) / outLen) * take;
+    d += `L${ax} ${ay}L${bx} ${by}`;
+    cursor = { x: bx, y: by };
+  }
+  const last = points[points.length - 1]!;
+  return `${d}L${last.x} ${last.y}`;
+}
+
+export function chevronHighlightClass(
+  highlight: ChevronEdgeHighlight,
+): string {
+  switch (highlight) {
+    case 'incoming':
+      return 'chevron-edge--incoming';
+    case 'outgoing':
+      return 'chevron-edge--outgoing';
+    case undefined:
+      return '';
+    default: {
+      const _never: never = highlight;
+      return _never;
+    }
+  }
+}

package/src/lib/canvas/geometry.ts

@@ -0,0 +1,53 @@
+import { FLOW_MAX_ZOOM, FLOW_MIN_ZOOM } from '@terrafirmagreg-team/ui/lib/canvas/viewport';
+import type {
+  FlowContentBox,
+  FlowRect,
+  FlowSizedNode,
+} from '@terrafirmagreg-team/ui/types/canvas';
+
+const FIT_VIEW_PAD = 0.12;
+
+export function flowContentBox(
+  nodes: FlowSizedNode[],
+  rects: FlowRect[] = [],
+): FlowContentBox | null {
+  let minX = Number.POSITIVE_INFINITY;
+  let minY = Number.POSITIVE_INFINITY;
+  let maxX = Number.NEGATIVE_INFINITY;
+  let maxY = Number.NEGATIVE_INFINITY;
+  for (const node of nodes) {
+    const halfW = (node.width ?? 0) / 2;
+    const halfH = (node.height ?? 0) / 2;
+    minX = Math.min(minX, node.position.x - halfW);
+    minY = Math.min(minY, node.position.y - halfH);
+    maxX = Math.max(maxX, node.position.x + halfW);
+    maxY = Math.max(maxY, node.position.y + halfH);
+  }
+  for (const rect of rects) {
+    minX = Math.min(minX, rect.x - rect.width / 2);
+    minY = Math.min(minY, rect.y - rect.height / 2);
+    maxX = Math.max(maxX, rect.x + rect.width / 2);
+    maxY = Math.max(maxY, rect.y + rect.height / 2);
+  }
+  if (!Number.isFinite(minX)) return null;
+  return {
+    midX: (minX + maxX) / 2,
+    midY: (minY + maxY) / 2,
+    width: Math.max(1, maxX - minX),
+    height: Math.max(1, maxY - minY),
+  };
+}
+
+export function zoomToFitBox(
+  box: { width: number; height: number },
+  viewW: number,
+  viewH: number,
+  minZoom = FLOW_MIN_ZOOM,
+  maxZoom = FLOW_MAX_ZOOM,
+): number {
+  const zoom = Math.min(
+    (viewW * (1 - 2 * FIT_VIEW_PAD)) / box.width,
+    (viewH * (1 - 2 * FIT_VIEW_PAD)) / box.height,
+  );
+  return Math.min(maxZoom, Math.max(minZoom, zoom));
+}

package/src/lib/canvas/state.ts

@@ -0,0 +1,47 @@
+import type { Edge, Node } from '@terrafirmagreg-team/ui/lib/canvas/xyflow';
+import type { ChevronEdgeHighlight } from '@terrafirmagreg-team/ui/types/canvas';
+
+export function applyNodeSelection<N extends Node>(
+  nodes: N[],
+  selectedId: string | null,
+  type?: string,
+): N[] {
+  let changed = false;
+  const next = nodes.map((node) => {
+    if (type && node.type !== type) return node;
+    const selected = selectedId != null && node.id === selectedId;
+    if (node.selected === selected) return node;
+    changed = true;
+    return { ...node, selected };
+  });
+  return changed ? next : nodes;
+}
+
+export function decorateFlowEdges<E extends Edge>(
+  edges: E[],
+  hoverId: string | null,
+  selectedId: string | null,
+): E[] {
+  return edges.map((edge) => {
+    const outgoing = hoverId != null && edge.source === hoverId;
+    const incoming = hoverId != null && edge.target === hoverId;
+    const selected =
+      selectedId != null &&
+      (edge.source === selectedId || edge.target === selectedId);
+    const sourceEngaged = outgoing || selectedId === edge.source;
+    const targetEngaged = incoming || selectedId === edge.target;
+    const flags = edge.data as
+      | { hideTarget?: boolean; hideSource?: boolean }
+      | undefined;
+    const hidden =
+      (flags?.hideTarget === true && !targetEngaged) ||
+      (flags?.hideSource === true && !sourceEngaged);
+    const highlight: ChevronEdgeHighlight =
+      outgoing || (selected && edge.source === selectedId)
+        ? 'outgoing'
+        : incoming || (selected && edge.target === selectedId)
+          ? 'incoming'
+          : undefined;
+    return { ...edge, data: { hidden, highlight } };
+  });
+}

package/src/lib/canvas/viewport.ts

@@ -0,0 +1,37 @@
+import type { StoredViewport } from '@terrafirmagreg-team/ui/types/canvas';
+
+export const VIEWPORT_SAVE_MS = 300;
+export const FLOW_MIN_ZOOM = 0.25;
+export const FLOW_MAX_ZOOM = 2;
+
+export function readStoredViewport(key: string): StoredViewport | null {
+  try {
+    const raw = localStorage.getItem(key);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as Partial<StoredViewport>;
+    if (
+      typeof parsed.x !== 'number' ||
+      typeof parsed.y !== 'number' ||
+      typeof parsed.zoom !== 'number' ||
+      !Number.isFinite(parsed.x) ||
+      !Number.isFinite(parsed.y) ||
+      !Number.isFinite(parsed.zoom)
+    ) {
+      return null;
+    }
+    return { x: parsed.x, y: parsed.y, zoom: parsed.zoom };
+  } catch {
+    return null;
+  }
+}
+
+export function writeStoredViewport(
+  key: string,
+  viewport: StoredViewport,
+): void {
+  try {
+    localStorage.setItem(key, JSON.stringify(viewport));
+  } catch {
+
+  }
+}

package/src/lib/canvas/xyflow.ts

@@ -0,0 +1 @@
+export * from '@xyflow/react';

package/src/lib/config.ts

@@ -0,0 +1,81 @@
+import type { ComponentType } from 'react';
+import type { Lang } from '@terrafirmagreg-team/translate/types/locale';
+import type { PagePreviewData, PreviewIcon } from '@terrafirmagreg-team/ui/types/preview';
+
+export type ExternalMetaProvider = {
+  host: RegExp;
+  path?: RegExp;
+  url: string;
+  kind?: 'json' | 'html';
+  title?: string;
+  description?: string;
+  replace?: [RegExp, string][];
+};
+
+export const DEFAULT_EXTERNAL_META_PROVIDERS: ExternalMetaProvider[] = [
+  {
+    host: /(^|\.)wikipedia\.org$/i,
+    path: /^\/wiki\/(.+)$/,
+    url: 'https://{host}/api/rest_v1/page/summary/{1}',
+    kind: 'json',
+    title: 'titles.normalized',
+    description: 'description',
+    replace: [[/_/g, ' ']],
+  },
+  {
+    host: /^github\.com$/i,
+    path: /^\/([^/]+)\/([^/?#]+)\/?$/,
+    url: 'https://api.github.com/repos/{1}/{2}',
+    kind: 'json',
+    title: 'full_name',
+    description: 'description',
+  },
+  {
+    host: /.*/,
+    url: 'https://api.allorigins.win/raw?url={href}',
+    kind: 'html',
+  },
+];
+
+export const DEFAULT_EXTERNAL_FAVICON = 'https://{host}/favicon.ico';
+
+export type UiConfig = {
+  basePath?: string;
+
+  brand?: { name: string; icon?: string };
+
+  components?: Record<string, ComponentType<any>>;
+  externalMetaProviders?: ExternalMetaProvider[];
+  externalFavicon?: string;
+
+  loadPagePreview?: (
+    href: string,
+    ctx?: { lang?: string },
+  ) => Promise<PagePreviewData | undefined>;
+
+  loadPagePreviews?: (
+    lang: Lang,
+    langMap: Record<string, string>,
+    hrefs: Iterable<string>,
+  ) => Promise<Record<string, PagePreviewData>>;
+  pagePreviewIcon?: ComponentType<{ icon: PreviewIcon }>;
+};
+
+export function createConfigRegistry<I extends object, R = I>(
+  resolve: (overrides: I) => R = (overrides) => overrides as unknown as R,
+) {
+  let overrides = {} as I;
+  return {
+    register(input: I): void {
+      overrides = { ...overrides, ...input };
+    },
+    get(): R {
+      return resolve(overrides);
+    },
+  };
+}
+
+const { register: registerUiConfig, get: uiConfig } =
+  createConfigRegistry<UiConfig>();
+
+export { registerUiConfig, uiConfig };

package/src/lib/mdx/callout.ts

@@ -0,0 +1,20 @@
+import type { CSSProperties } from 'react';
+
+export const COLORS: Record<string, string> = {
+  info: 'var(--color-info)',
+  note: 'var(--color-note)',
+  tip: 'var(--color-tip)',
+  warn: 'var(--color-warning)',
+  warning: 'var(--color-warning)',
+  error: 'var(--color-error)',
+  danger: 'var(--color-error)',
+  success: 'var(--color-success)',
+  idea: 'var(--color-idea)',
+};
+
+export function calloutStyle(
+  type: string,
+  style: CSSProperties | undefined,
+): CSSProperties {
+  return { '--callout-color': COLORS[type] ?? COLORS.info, ...style } as CSSProperties;
+}

package/src/lib/mdx/gradient.ts

@@ -0,0 +1,15 @@
+export type GradientProps = {
+  from?: string;
+  to?: string;
+  dir?: string;
+  image?: string;
+};
+
+export function gradientImage({
+  from = '#fa18cf',
+  to = '#ff7967',
+  dir = 'to right',
+  image,
+}: GradientProps): string {
+  return image ?? `linear-gradient(${dir}, ${from}, ${to})`;
+}

package/src/lib/mdx/mermaid.ts

@@ -0,0 +1,14 @@
+import { renderMermaidSVG } from 'beautiful-mermaid';
+
+export function renderMermaidChart(chart: string): string | null {
+  try {
+    return renderMermaidSVG(chart, {
+      bg: 'var(--color-background)',
+      fg: 'var(--color-foreground)',
+      interactive: true,
+      transparent: true,
+    });
+  } catch {
+    return null;
+  }
+}