@terrafirmagreg-team/ui 0.0.0-stage → 1.2.0

package/package.json

@@ -1,6 +1,96 @@
 {
   "name": "@terrafirmagreg-team/ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.2.0",
+  "type": "module",
+  "description": "Shared UI kit",
+  "license": "LGPL-3.0-only",
+  "exports": {
+    "./styles.css": "./styles.css",
+    "./styles/*": "./styles/*",
+    "./provider": "./src/components/provider.tsx",
+    "./components/ui/*": [
+      "./src/components/ui/*.tsx",
+      "./src/components/ui/*/index.tsx"
+    ],
+    "./components/blocks/*": [
+      "./src/components/blocks/*.tsx",
+      "./src/components/blocks/*/index.tsx"
+    ],
+    "./components/layouts/*": [
+      "./src/components/layouts/*.tsx",
+      "./src/components/layouts/*/index.tsx",
+      "./src/components/layouts/*/index.ts"
+    ],
+    "./hooks/*": [
+      "./src/hooks/*.ts",
+      "./src/hooks/*/index.ts"
+    ],
+    "./lib/*": [
+      "./src/lib/*.ts",
+      "./src/lib/*/index.ts"
+    ],
+    "./types/*": [
+      "./src/types/*.ts",
+      "./src/types/*/index.ts"
+    ],
+    "./components/mdx/*": [
+      "./src/components/mdx/*.tsx",
+      "./src/components/mdx/*/index.tsx"
+    ],
+    "./locales": "./src/locales.ts"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.9.0",
+    "@icons-pack/react-simple-icons": "13.15.1",
+    "@react-three/drei": "10.7.9",
+    "@react-three/fiber": "9.8.2",
+    "@shadcn/react": "^0.3.1",
+    "@terrafirmagreg-team/translate": "1.2.0",
+    "@xyflow/react": "12.12.0",
+    "beautiful-mermaid": "^1.1.3",
+    "class-variance-authority": "^0.7.1",
+    "cmdk": "^1.1.1",
+    "cn": "^0.5.0",
+    "embla-carousel-react": "^8.6.0",
+    "flag-icons": "^7.6.0",
+    "hast-util-to-jsx-runtime": "^2.3.6",
+    "input-otp": "^1.5.0",
+    "katex": "^0.19.1",
+    "lucide-react": "^0.577.0",
+    "next-themes": "^0.4.6",
+    "react-day-picker": "^10.0.2",
+    "react-medium-image-zoom": "^5.4.9",
+    "react-resizable-panels": "^4.18.0",
+    "recharts": "3.10.1",
+    "scroll-into-view-if-needed": "^3.1.0",
+    "tailwindcss": "^4.3.4",
+    "three": "^0.186.1",
+    "three-stdlib": "2.36.1",
+    "@terrafirmagreg-team/data": "1.2.0"
+  },
+  "peerDependencies": {
+    "next": ">=15",
+    "react": ">=19",
+    "react-dom": ">=19"
+  },
+  "devDependencies": {
+    "@types/hast": "^3.0.5",
+    "@types/node": "^26.6.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@types/three": "^0.187.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TerraFirmaGreg-Team/Web-Foundation.git",
+    "directory": "packages/ui"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "styles",
+    "styles.css"
+  ]
 }

package/src/components/blocks/button/icon-button.tsx

@@ -0,0 +1,49 @@
+'use client';
+import type { ComponentProps } from 'react';
+import { Button } from '@terrafirmagreg-team/ui/components/ui/button';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '@terrafirmagreg-team/ui/components/ui/tooltip';
+import { useInFloatBar } from '@terrafirmagreg-team/ui/hooks/viewer/use-in-float-bar';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+
+export function IconButton({
+  label,
+  tooltip = true,
+  overlay,
+  variant = 'outline',
+  size = 'icon-sm',
+  className,
+  ...props
+}: ComponentProps<typeof Button> & {
+  label: string;
+  tooltip?: boolean;
+  overlay?: boolean;
+}) {
+  const inFloatBar = useInFloatBar();
+  const button = (
+    <Button
+      variant={overlay && variant === 'outline' ? 'ghost' : variant}
+      size={size}
+      aria-label={label}
+      className={cn(
+        overlay &&
+          (inFloatBar
+            ? 'rounded-none'
+            : 'bg-float/92 backdrop-blur-md hover:bg-float'),
+        className,
+      )}
+      {...props}
+    />
+  );
+  if (!tooltip) return button;
+  return (
+    <Tooltip>
+      <TooltipTrigger render={button} />
+      <TooltipContent>{label}</TooltipContent>
+    </Tooltip>
+  );
+}
+

package/src/components/blocks/canvas/chevron-edge.tsx

@@ -0,0 +1,242 @@
+'use client';
+
+import {
+  memo,
+  useCallback,
+  useMemo,
+  useRef,
+  useState,
+  type FC,
+  type MouseEvent as ReactMouseEvent,
+  type ReactNode,
+} from 'react';
+import {
+  EdgeLabelRenderer,
+  useInternalNode,
+  useStore,
+  type EdgeProps,
+  type InternalNode,
+} from '@terrafirmagreg-team/ui/lib/canvas/xyflow';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+import {
+  CHEVRON_GLYPH,
+  chevronHighlightClass,
+  chevronTicksAlongPath,
+  nearestPointOnPolyline,
+} from '@terrafirmagreg-team/ui/lib/canvas/edge';
+import type {
+  ChevronEdgeHighlight,
+  FlowPoint,
+} from '@terrafirmagreg-team/ui/types/canvas';
+
+export type ChevronEdgePathContext = EdgeProps & {
+  sourceNode: InternalNode;
+  targetNode: InternalNode;
+};
+
+type ChevronEdgeResolvers = {
+  resolveCenter?: (node: InternalNode) => FlowPoint;
+  resolveBorder?: (node: InternalNode, toward: FlowPoint) => FlowPoint;
+  resolvePath?: (ctx: ChevronEdgePathContext) => FlowPoint[];
+  renderLabel?: (ctx: ChevronEdgePathContext) => ReactNode;
+  labelVisibility?: 'always' | 'hover';
+  className?: string;
+};
+
+function pathMidpoint(points: readonly FlowPoint[]): FlowPoint {
+  let total = 0;
+  for (let i = 1; i < points.length; i += 1) {
+    total += Math.hypot(
+      points[i]!.x - points[i - 1]!.x,
+      points[i]!.y - points[i - 1]!.y,
+    );
+  }
+  const half = total / 2;
+  let acc = 0;
+  for (let i = 1; i < points.length; i += 1) {
+    const a = points[i - 1]!;
+    const b = points[i]!;
+    const len = Math.hypot(b.x - a.x, b.y - a.y);
+    if (acc + len >= half && len > 0) {
+      const t = (half - acc) / len;
+      return { x: a.x + (b.x - a.x) * t, y: a.y + (b.y - a.y) * t };
+    }
+    acc += len;
+  }
+  return points[points.length - 1]!;
+}
+
+const CHEVRON_TICK_MIN_ZOOM = 0.25;
+
+export function createChevronEdge({
+  resolveCenter,
+  resolveBorder,
+  resolvePath,
+  renderLabel,
+  labelVisibility = 'always',
+  className,
+}: ChevronEdgeResolvers): FC<EdgeProps> {
+  return memo(function ChevronEdge(props: EdgeProps) {
+    const { source, target, data } = props;
+    const [hover, setHover] = useState(false);
+    const [hoverPt, setHoverPt] = useState<FlowPoint | null>(null);
+    const hoverTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const enter = useCallback(() => {
+      if (hoverTimer.current) clearTimeout(hoverTimer.current);
+      setHover(true);
+    }, []);
+    const leave = useCallback(() => {
+      hoverTimer.current = setTimeout(() => {
+        setHover(false);
+        setHoverPt(null);
+      }, 120);
+    }, []);
+    const sourceNode = useInternalNode(source);
+    const targetNode = useInternalNode(target);
+    const farZoom = useStore(
+      (state) => state.transform[2] < CHEVRON_TICK_MIN_ZOOM,
+    );
+    const tx = useStore((state) => state.transform[0]);
+    const ty = useStore((state) => state.transform[1]);
+    const tz = useStore((state) => state.transform[2]);
+    const sAbs = sourceNode?.internals.positionAbsolute;
+    const tAbs = targetNode?.internals.positionAbsolute;
+    const sSize = sourceNode?.measured;
+    const tSize = targetNode?.measured;
+    const {
+      sourceX,
+      sourceY,
+      sourcePosition,
+      targetX,
+      targetY,
+      targetPosition,
+    } = props;
+
+    const points = useMemo(() => {
+      if (!sAbs || !tAbs || !sourceNode || !targetNode) return null;
+      return resolvePath
+        ? resolvePath({ ...props, sourceNode, targetNode })
+        : resolveCenter && resolveBorder
+          ? [
+              resolveBorder(sourceNode, resolveCenter(targetNode)),
+              resolveBorder(targetNode, resolveCenter(sourceNode)),
+            ]
+          : [
+              { x: sourceX, y: sourceY },
+              { x: targetX, y: targetY },
+            ];
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [
+      data,
+      sAbs?.x,
+      sAbs?.y,
+      sSize?.width,
+      sSize?.height,
+      tAbs?.x,
+      tAbs?.y,
+      tSize?.width,
+      tSize?.height,
+      sourceX,
+      sourceY,
+      sourcePosition,
+      targetX,
+      targetY,
+      targetPosition,
+    ]);
+    const ticks = useMemo(
+      () =>
+        points && !farZoom
+          ? chevronTicksAlongPath(points)
+          : { offsets: [], total: 0 },
+      [points, farZoom],
+    );
+    const highlight = data?.highlight as ChevronEdgeHighlight;
+    const mid = useMemo(
+      () => (points ? pathMidpoint(points) : null),
+      [points],
+    );
+    if (data?.hidden === true) return null;
+    if (!points || points.length < 2 || !mid) return null;
+    const base = `M${points[0]!.x} ${points[0]!.y}${points
+      .slice(1)
+      .map((p) => `L${p.x} ${p.y}`)
+      .join('')}`;
+    const move = useCallback(
+      (e: ReactMouseEvent<Element>) => {
+        if (!points || tz === 0) return;
+        const pane = e.currentTarget.closest('.react-flow');
+        if (!pane) return;
+        const rect = pane.getBoundingClientRect();
+        const p = {
+          x: (e.clientX - rect.left - tx) / tz,
+          y: (e.clientY - rect.top - ty) / tz,
+        };
+        setHoverPt(nearestPointOnPolyline(points, p));
+      },
+      [points, tx, ty, tz],
+    );
+    const hoverTrack =
+      labelVisibility === 'hover'
+        ? { onMouseEnter: enter, onMouseLeave: leave, onMouseMove: move }
+        : {};
+    const labelOn =
+      labelVisibility !== 'hover' || hover || props.selected === true;
+    const labelAt = hoverPt ?? mid;
+    return (
+      <>
+      <g
+        className={cn(
+          'chevron-edge',
+          className,
+          chevronHighlightClass(highlight),
+        )}
+        {...hoverTrack}
+      >
+        <path
+          className="chevron-edge__interaction"
+          d={base}
+          fill="none"
+          stroke="transparent"
+          strokeWidth={props.interactionWidth ?? 20}
+        />
+        <path
+          className="chevron-edge__stroke chevron-edge__base"
+          d={base}
+          aria-hidden="true"
+        />
+        <g className="chevron-edge__ticks" aria-hidden="true">
+          {ticks.offsets.map((offset) => (
+            <path
+              key={offset}
+              className="chevron-edge__stroke chevron-edge__stroke--main chevron-edge__tick"
+              d={CHEVRON_GLYPH}
+              style={{
+                offsetPath: `path("${base}")`,
+                ['--chevron-o' as string]: `${offset}px`,
+              }}
+            />
+          ))}
+        </g>
+      </g>
+      {renderLabel && labelOn ? (
+        <EdgeLabelRenderer>
+          <div
+            className="chevron-edge__label nodrag nopan"
+            {...hoverTrack}
+            style={{
+              transform: `translate(-50%, -50%) translate(${labelAt.x}px, ${labelAt.y}px)`,
+            }}
+          >
+            {renderLabel({
+              ...props,
+              sourceNode: sourceNode!,
+              targetNode: targetNode!,
+            })}
+          </div>
+        </EdgeLabelRenderer>
+      ) : null}
+      </>
+    );
+  });
+}
+

package/src/components/blocks/canvas/flow-canvas.tsx

@@ -0,0 +1,181 @@
+'use client';
+
+import {
+  useCallback,
+  useMemo,
+  useRef,
+  type ComponentProps,
+  type ReactNode,
+} from 'react';
+import {
+  Background,
+  ReactFlow,
+  useReactFlow,
+  type Edge,
+  type Node,
+  type ReactFlowProps,
+} from '@terrafirmagreg-team/ui/lib/canvas/xyflow';
+import { useTheme } from 'next-themes';
+import { useElementSize } from '@terrafirmagreg-team/ui/hooks/use-element-size';
+import { useFlowViewportPersist } from '@terrafirmagreg-team/ui/hooks/canvas/use-flow-viewport-persist';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+import {
+  flowContentBox,
+  zoomToFitBox,
+} from '@terrafirmagreg-team/ui/lib/canvas/geometry';
+import {
+  FLOW_MAX_ZOOM,
+  FLOW_MIN_ZOOM,
+} from '@terrafirmagreg-team/ui/lib/canvas/viewport';
+import { FlowViewport } from '@terrafirmagreg-team/ui/components/blocks/canvas/flow-viewport';
+import type {
+  FlowCanvasViewport,
+  FlowRect,
+} from '@terrafirmagreg-team/ui/types/canvas';
+
+export type FlowCanvasFit = { onFit: () => void };
+
+export type FlowCanvasProps<
+  N extends Node = Node,
+  E extends Edge = Edge,
+> = Omit<ReactFlowProps<N, E>, 'nodes' | 'children'> & {
+  nodes: N[];
+  viewportConfig: FlowCanvasViewport;
+
+  extraRects?: FlowRect[];
+
+  fitNodes?: (node: N) => boolean;
+  backgroundGap?: number;
+  className?: string;
+  shellProps?: ComponentProps<'div'> &
+    Record<`data-${string}`, unknown>;
+
+  children?: ReactNode | ((fit: FlowCanvasFit) => ReactNode);
+};
+
+export function FlowCanvas<N extends Node = Node, E extends Edge = Edge>({
+  nodes,
+  viewportConfig,
+  extraRects,
+  fitNodes,
+  backgroundGap = 16,
+  className,
+  shellProps,
+  children,
+  onMoveEnd,
+  ...flowProps
+}: FlowCanvasProps<N, E>) {
+  const canvasRef = useRef<HTMLDivElement>(null);
+  const viewSize = useElementSize(canvasRef);
+  const { setCenter } = useReactFlow();
+  const { resolvedTheme } = useTheme();
+  const { markReady, persist } = useFlowViewportPersist(
+    viewportConfig.storageKey,
+    viewportConfig.resetKey,
+  );
+  const contentBox = useMemo(
+    () => flowContentBox(nodes, extraRects),
+    [nodes, extraRects],
+  );
+  const scoped = useMemo(
+    () => (fitNodes ? nodes.filter(fitNodes) : nodes),
+    [nodes, fitNodes],
+  );
+  const fitBox = useMemo(() => {
+    if (!fitNodes || !scoped.length) return contentBox;
+    return flowContentBox(scoped, extraRects);
+  }, [scoped, extraRects, fitNodes, contentBox]);
+  const { focusZoom = 1, persist: _persist, ...viewportRest } = viewportConfig;
+  const onFit = useCallback(() => {
+    if (!fitBox || viewSize.w < 1 || viewSize.h < 1) return;
+    const fitZoom = zoomToFitBox(
+      fitBox,
+      viewSize.w,
+      viewSize.h,
+      flowProps.minZoom,
+      flowProps.maxZoom,
+    );
+
+    const pool = scoped.length ? scoped : nodes;
+    let anchor: { x: number; y: number } = {
+      x: fitBox.midX,
+      y: fitBox.midY,
+    };
+    let best = Infinity;
+    for (const node of pool) {
+      const dx = node.position.x - fitBox.midX;
+      const dy = node.position.y - fitBox.midY;
+      const dist = dx * dx + dy * dy;
+      if (dist < best) {
+        best = dist;
+        anchor = node.position;
+      }
+    }
+
+    void setCenter(anchor.x, anchor.y, {
+      zoom: Math.max(fitZoom, focusZoom * 0.3),
+      duration: 200,
+    });
+  }, [
+    fitBox,
+    scoped,
+    nodes,
+    setCenter,
+    viewSize,
+    flowProps.minZoom,
+    flowProps.maxZoom,
+    focusZoom,
+  ]);
+  const handleMoveEnd = useCallback<
+    NonNullable<ReactFlowProps<N, E>['onMoveEnd']>
+  >(
+    (event, vp) => {
+      if (viewportConfig.persist) persist(vp);
+      onMoveEnd?.(event, vp);
+    },
+    [viewportConfig.persist, persist, onMoveEnd],
+  );
+
+  return (
+    <div
+      ref={canvasRef}
+      suppressHydrationWarning
+      {...shellProps}
+      className={cn(
+        'flex-1 min-h-0 h-full not-prose relative w-full overflow-hidden',
+        className,
+        shellProps?.className,
+      )}
+    >
+      {viewSize.w > 0 && viewSize.h > 0 ? (
+        <ReactFlow<N, E>
+          nodes={nodes}
+          nodeOrigin={[0.5, 0.5]}
+          nodesConnectable={false}
+          elementsSelectable
+          panOnDrag
+          zoomOnPinch
+          minZoom={FLOW_MIN_ZOOM}
+          maxZoom={FLOW_MAX_ZOOM}
+          proOptions={{ hideAttribution: true }}
+          colorMode={resolvedTheme === 'dark' ? 'dark' : 'light'}
+          className="h-full bg-card"
+          onMoveEnd={handleMoveEnd}
+          {...flowProps}
+        >
+          <Background gap={backgroundGap} size={1} />
+          {typeof children === 'function' ? children({ onFit }) : children}
+          <FlowViewport
+            {...viewportRest}
+            nodes={nodes}
+            contentBox={contentBox}
+            viewSize={viewSize}
+            focusZoom={focusZoom}
+            onReady={markReady}
+          />
+        </ReactFlow>
+      ) : null}
+    </div>
+  );
+}
+

package/src/components/blocks/canvas/flow-toolbar.tsx

@@ -0,0 +1,33 @@
+'use client';
+
+import { useReactFlow } from '@terrafirmagreg-team/ui/lib/canvas/xyflow';
+import { Search } from 'lucide-react';
+import {
+  ViewerToolbar,
+  ViewerControls,
+} from '@terrafirmagreg-team/ui/components/blocks/viewer/controls';
+import { IconButton } from '@terrafirmagreg-team/ui/components/blocks/button/icon-button';
+import type { FlowToolbarProps } from '@terrafirmagreg-team/ui/types/canvas';
+
+export function FlowToolbar({ onFit, search }: FlowToolbarProps) {
+  const { zoomIn, zoomOut } = useReactFlow();
+  return (
+    <ViewerToolbar>
+      <ViewerControls
+        start={
+          search ? (
+            <IconButton overlay label={search.label} onClick={search.onOpen}>
+              <Search className="size-3.5" />
+            </IconButton>
+          ) : null
+        }
+        zoom={{
+          onZoomIn: () => void zoomIn({ duration: 150 }),
+          onZoomOut: () => void zoomOut({ duration: 150 }),
+          onFit,
+        }}
+      />
+    </ViewerToolbar>
+  );
+}
+