@endfield-ui/react 0.0.0-stage → 0.2.0

package/src/components/tooltip/Tooltip.tsx

@@ -0,0 +1,175 @@
+import { Tooltip as BaseTooltip } from "@base-ui/react/tooltip";
+import {
+  cloneElement,
+  createContext,
+  useContext,
+  useId,
+  useSyncExternalStore,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import { createPortal } from "react-dom";
+import { usePortalScope } from "../../hooks/usePortalScope";
+import { cn } from "../../lib/cn";
+
+export type TooltipSide = "top" | "bottom" | "left" | "right";
+export type TooltipAlign = "start" | "center" | "end";
+
+/* 规范：出现前约 300ms，消失不延迟 */
+const DEFAULT_DELAY = 300;
+
+const InProviderContext = createContext(false);
+
+export type TooltipProviderProps = {
+  /** 这一组提示统一的延迟，毫秒 */
+  delay?: number;
+  /** 一个提示消失后多久之内，旁边的提示不用再等延迟，毫秒。默认 400 */
+  timeout?: number;
+  children: ReactNode;
+};
+
+/**
+ * 可选。包住一组相邻的提示（工具栏）：第一个出现之后，移到旁边的不用再等延迟。
+ */
+export function TooltipProvider({
+  delay = DEFAULT_DELAY,
+  timeout,
+  children,
+}: TooltipProviderProps) {
+  return (
+    <BaseTooltip.Provider delay={delay} timeout={timeout}>
+      <InProviderContext value={true}>{children}</InProviderContext>
+    </BaseTooltip.Provider>
+  );
+}
+
+export type TooltipProps = {
+  /** 提示的内容：一句话，不放交互元素 */
+  content: ReactNode;
+  /** 触发元素：一个能接收 `ref` 与事件的元素（按钮、链接） */
+  children: ReactElement<Record<string, unknown>>;
+  /** 出现在触发元素的哪一侧，放不下时自动翻到对面。默认 `top` */
+  side?: TooltipSide;
+  align?: TooltipAlign;
+  /**
+   * 悬停多久后出现，毫秒，默认 300。键盘聚焦时立刻出现；消失不延迟。
+   * 在 `TooltipProvider` 里不传时跟随它的 `delay`。
+   */
+  delay?: number;
+  /** 指向触发元素的小三角，默认有。关掉后提示贴着触发元素 */
+  arrow?: boolean;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** 不再出现 */
+  disabled?: boolean;
+  /** 给提示本身 */
+  className?: string;
+};
+
+const subscribeNever = () => () => {};
+
+/** 常驻的隐藏文字，给 `aria-describedby` 用。挂在 `<body>` 下，不影响触发元素周围的排版 */
+function Description({ id, children }: { id: string; children: ReactNode }) {
+  // 服务端与水合时没有 document，挂载后才渲染
+  const mounted = useSyncExternalStore(
+    subscribeNever,
+    () => true,
+    () => false,
+  );
+  if (!mounted) return null;
+  return createPortal(
+    <span id={id} hidden>
+      {children}
+    </span>,
+    document.body,
+  );
+}
+
+/**
+ * 悬停或键盘聚焦时出现的一句说明。触屏上不出现：必要的信息不要只放在这里。
+ *
+ * 触发元素要有自己的可访问名称（图标按钮的 `aria-label`）。提示的内容会作为
+ * 补充说明关联给读屏；它和 `aria-label` 一字不差时不再重复关联。
+ */
+export function Tooltip({
+  content,
+  children,
+  side = "top",
+  align = "center",
+  delay,
+  arrow = true,
+  open,
+  defaultOpen,
+  onOpenChange,
+  disabled = false,
+  className,
+}: TooltipProps) {
+  const descriptionId = useId();
+  const inProvider = useContext(InProviderContext);
+  // 提示是一块和页面相反的颜色。做成相反主题的局部主题，而不是直接用反转色：
+  // 里面的键位提示、着色词因此也按这块底色取值，不会和底融在一起
+  const { anchorRef, portalRef } = usePortalScope({ invertTheme: true });
+
+  const label = children.props["aria-label"];
+  const repeatsLabel =
+    typeof content === "string" &&
+    typeof label === "string" &&
+    content.trim() === label.trim();
+  const described = !disabled && !repeatsLabel;
+
+  const existing = children.props["aria-describedby"];
+  const trigger = described
+    ? cloneElement(children, {
+        "aria-describedby":
+          typeof existing === "string"
+            ? `${existing} ${descriptionId}`
+            : descriptionId,
+      })
+    : children;
+
+  return (
+    <BaseTooltip.Root
+      open={open}
+      defaultOpen={defaultOpen}
+      onOpenChange={onOpenChange && ((next) => onOpenChange(next))}
+      disabled={disabled}
+    >
+      <BaseTooltip.Trigger
+        ref={anchorRef}
+        render={trigger}
+        delay={delay ?? (inProvider ? undefined : DEFAULT_DELAY)}
+      />
+      {described && <Description id={descriptionId}>{content}</Description>}
+      <BaseTooltip.Portal ref={portalRef}>
+        <BaseTooltip.Positioner
+          side={side}
+          align={align}
+          sideOffset={arrow ? 8 : 2}
+          className="z-(--z-overlay)"
+        >
+          <BaseTooltip.Popup
+            className={cn(
+              // 透明的边线：高对比模式下背景色被系统覆盖，边线会自己显形
+              "relative max-w-64 border border-transparent bg-surface-raised px-2.5 py-1.5 text-sm wrap-anywhere text-ink",
+              "origin-(--transform-origin) transition-opacity duration-(--duration-fast) ease-standard",
+              "data-ending-style:opacity-0 data-instant:transition-none data-starting-style:opacity-0",
+              className,
+            )}
+          >
+            {arrow && (
+              <BaseTooltip.Arrow
+                aria-hidden="true"
+                className={cn(
+                  "size-2 rotate-45 bg-surface-raised forced-colors:hidden",
+                  "data-[side=bottom]:-top-1 data-[side=left]:-right-1 data-[side=right]:-left-1 data-[side=top]:-bottom-1",
+                )}
+              />
+            )}
+            {content}
+          </BaseTooltip.Popup>
+        </BaseTooltip.Positioner>
+      </BaseTooltip.Portal>
+    </BaseTooltip.Root>
+  );
+}

package/src/components/tooltip/index.ts

@@ -0,0 +1,8 @@
+export {
+  Tooltip,
+  TooltipProvider,
+  type TooltipAlign,
+  type TooltipProps,
+  type TooltipProviderProps,
+  type TooltipSide,
+} from "./Tooltip";

package/src/components/top-bar/TopBar.tsx

@@ -0,0 +1,47 @@
+import type { ComponentProps, ReactNode } from "react";
+import { cn } from "../../lib/cn";
+import { NavActionContext } from "../nav-action/NavAction";
+
+export type TopBarProps = ComponentProps<"header"> & {
+  /** 最左边的标志。本库不带标志，传你自己的 */
+  brand?: ReactNode;
+  /** 工具图标钮：几个 `IconButton` */
+  tools?: ReactNode;
+  /** 主行动：放一个 `NavAction` */
+  action?: ReactNode;
+  /** 最右边的菜单钮：放一个 `NavMenu`（它自己带着触发按钮） */
+  menu?: ReactNode;
+};
+
+/**
+ * 顶栏：窄屏上的主导航。从左到右是标志、空白、工具图标钮、主行动、菜单钮；
+ * 栏目本身不排在这一条里，收进 `NavMenu`。
+ *
+ * 默认 `sticky` 贴在顶上。它只管排版，各格放什么由使用方给。
+ */
+export function TopBar({
+  brand,
+  tools,
+  action,
+  menu,
+  className,
+  children,
+  ...props
+}: TopBarProps) {
+  return (
+    <header
+      {...props}
+      className={cn(
+        // 环境阴影在暗色页面上看不出来，所以另有一条边线
+        "sticky top-0 z-(--z-nav) flex h-14 shrink-0 items-center gap-2 border-b border-line bg-surface px-4 text-ink shadow-lg",
+        className,
+      )}
+    >
+      {brand && <div className="flex min-w-0 items-center">{brand}</div>}
+      <div className="min-w-0 flex-1">{children}</div>
+      {tools && <div className="flex shrink-0 items-center gap-1">{tools}</div>}
+      {action && <NavActionContext value="inline">{action}</NavActionContext>}
+      {menu}
+    </header>
+  );
+}

package/src/components/top-bar/index.ts

@@ -0,0 +1 @@
+export { TopBar, type TopBarProps } from "./TopBar";

package/src/components/viewfinder/Viewfinder.tsx

@@ -0,0 +1,97 @@
+import type { ComponentProps, ReactNode } from "react";
+import { cn } from "../../lib/cn";
+import { decor } from "../../lib/decor";
+
+export type ViewfinderSize = "sm" | "md";
+
+export type ViewfinderReadouts = {
+  topLeft?: ReactNode;
+  topRight?: ReactNode;
+  bottomLeft?: ReactNode;
+  bottomRight?: ReactNode;
+};
+
+export type ViewfinderProps = ComponentProps<"div"> & {
+  /** 取景角的臂长：16px 或 24px */
+  size?: ViewfinderSize;
+  /** 正中放一个小准星，标出焦点 */
+  crosshair?: boolean;
+  /**
+   * 四个角上的读数：坐标、比例、版本、时间码。
+   * 必须是真实的数据；没有就不放。
+   */
+  readouts?: ViewfinderReadouts;
+};
+
+const armClass: Record<ViewfinderSize, string> = {
+  sm: "[--bracket-arm:16px]",
+  md: "[--bracket-arm:24px]",
+};
+
+const readoutPosition: Record<keyof ViewfinderReadouts, string> = {
+  topLeft: "top-5 left-5",
+  topRight: "top-5 right-5 text-right",
+  bottomLeft: "bottom-5 left-5",
+  bottomRight: "right-5 bottom-5 text-right",
+};
+
+/**
+ * 取景角：框住一张图、一片地图区域、一个焦点，标的是"范围"，不是选中。
+ * 里面放被框住的内容；压在深色画面上时给它加 `data-theme="dark"`。
+ *
+ * 只用在展示性的画面上，一屏一处。取景角与准星是装饰，读数是真实信息、读屏读得到。
+ */
+export function Viewfinder({
+  size = "sm",
+  crosshair = false,
+  readouts,
+  className,
+  children,
+  ...props
+}: ViewfinderProps) {
+  return (
+    <div {...props} className={cn("relative text-ink", className)}>
+      {children}
+      <span
+        aria-hidden="true"
+        className={cn(
+          decor,
+          "corner-brackets absolute inset-3 [--bracket-color:currentColor] [--bracket-offset:0px] [--bracket-width:1.5px]",
+          armClass[size],
+        )}
+      />
+      {crosshair && (
+        <svg
+          aria-hidden="true"
+          focusable="false"
+          viewBox="0 0 12 12"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth={1.5}
+          className={cn(
+            decor,
+            "absolute top-1/2 left-1/2 size-3 -translate-1/2 text-accent-ink",
+          )}
+        >
+          <path d="M6 0v12M0 6h12" />
+        </svg>
+      )}
+      {readouts &&
+        (Object.keys(readoutPosition) as (keyof ViewfinderReadouts)[]).map(
+          (corner) =>
+            readouts[corner] !== undefined && (
+              <span
+                key={corner}
+                data-corner={corner}
+                className={cn(
+                  "pointer-events-none absolute font-tech text-xs leading-none text-ink-secondary tabular-nums",
+                  readoutPosition[corner],
+                )}
+              >
+                {readouts[corner]}
+              </span>
+            ),
+        )}
+    </div>
+  );
+}

package/src/components/viewfinder/index.ts

@@ -0,0 +1,6 @@
+export {
+  Viewfinder,
+  type ViewfinderProps,
+  type ViewfinderReadouts,
+  type ViewfinderSize,
+} from "./Viewfinder";

package/src/hooks/README.md

@@ -0,0 +1,14 @@
+# hooks
+
+只放不依赖具体组件的逻辑。只服务于单个组件的 hook 放在该组件目录内。
+
+| hook | 作用 |
+| --- | --- |
+| `useTheme` | 读写 `<html data-theme>`；支持 `light` / `dark` / `system`，选择记在 `localStorage` |
+| `useControllableState` | 受控 / 非受控状态合并；值没变时不触发 `onChange` |
+| `useInView` | 元素第一次进入视口后返回 `true`，之后不再变回去——入场动画只播一次 |
+| `useOverflowing` | 容器里的内容是不是比容器宽、比容器高。给"只有真的能滚动时才是一个能聚焦的区域"用（表格、排期）。不对外导出 |
+| `useScrollPosition` | 盯着一个滚动容器（不传就是整个页面），由滚动位置算出一个值：滚动、窗口尺寸变了、内容晚到都会重新算，值没变不重新渲染。滚动提示和回到顶部共用。不对外导出 |
+| `usePortalScope` | 浮层挂到 `<body>` 下之后拿不到局部容器上的 `data-theme` / `data-choice`：返回 `anchorRef`（给触发元素）和 `portalRef`（给浮层的容器），容器挂载时把最近的开关抄过去。`invertTheme` 抄相反的主题（文字提示）。最近的是反转块（`data-theme="inverse"`）时，抄的是它实际算出来的亮或暗 |
+
+还没有 `useReducedMotion`：目前的动效都是 CSS 动画与过渡，由 [theme.css](../styles/theme.css) 末尾的全局规则统一降级。等出现用 JS 驱动的动效时再加。

package/src/hooks/index.ts

@@ -0,0 +1,4 @@
+export { useControllableState } from "./useControllableState";
+export { useInView } from "./useInView";
+export { useTheme, type Theme, type ThemePreference } from "./useTheme";
+export { usePortalScope } from "./usePortalScope";

package/src/hooks/useControllableState.ts

@@ -0,0 +1,30 @@
+import { useCallback, useState } from "react";
+
+type Options<T> = {
+  /** 传入即为受控 */
+  value?: T;
+  defaultValue: T;
+  onChange?: (value: T) => void;
+};
+
+/** 合并受控与非受控两种用法；值没有变化时不触发 `onChange`。 */
+export function useControllableState<T>({
+  value,
+  defaultValue,
+  onChange,
+}: Options<T>): [T, (next: T) => void] {
+  const [inner, setInner] = useState(defaultValue);
+  const controlled = value !== undefined;
+  const current = controlled ? value : inner;
+
+  const set = useCallback(
+    (next: T) => {
+      if (Object.is(next, current)) return;
+      if (!controlled) setInner(next);
+      onChange?.(next);
+    },
+    [controlled, current, onChange],
+  );
+
+  return [current, set];
+}

package/src/hooks/useInView.ts

@@ -0,0 +1,44 @@
+import { useEffect, useRef, useState, type RefObject } from "react";
+
+type Options = {
+  /** 为 true 时不观察，始终返回 false */
+  disabled?: boolean;
+  rootMargin?: string;
+  threshold?: number;
+};
+
+/**
+ * 元素第一次进入视口后返回 true，之后不再变回 false——入场动画只播一次。
+ */
+export function useInView<T extends Element = Element>({
+  disabled = false,
+  rootMargin = "0px",
+  threshold = 0,
+}: Options = {}): [RefObject<T | null>, boolean] {
+  const ref = useRef<T>(null);
+  const [inView, setInView] = useState(false);
+
+  useEffect(() => {
+    const node = ref.current;
+    if (disabled || inView || !node) return;
+
+    if (typeof IntersectionObserver === "undefined") {
+      setInView(true);
+      return;
+    }
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        if (entries.some((entry) => entry.isIntersecting)) {
+          setInView(true);
+          observer.disconnect();
+        }
+      },
+      { rootMargin, threshold },
+    );
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, [disabled, inView, rootMargin, threshold]);
+
+  return [ref, inView];
+}

package/src/hooks/useOverflowing.ts

@@ -0,0 +1,28 @@
+import { useEffect, useRef, useState } from "react";
+
+/**
+ * 容器里的内容是不是比容器宽、比容器高。
+ * 给"只有真的能滚动时才是一个能聚焦的区域"用：表格、排期。
+ * 盯着容器和它的第一个子元素的尺寸变化
+ */
+export function useOverflowing<T extends HTMLElement = HTMLDivElement>() {
+  const ref = useRef<T>(null);
+  const [x, setX] = useState(false);
+  const [y, setY] = useState(false);
+
+  useEffect(() => {
+    const node = ref.current;
+    if (!node || typeof ResizeObserver === "undefined") return;
+    const measure = () => {
+      setX(node.scrollWidth > node.clientWidth + 1);
+      setY(node.scrollHeight > node.clientHeight + 1);
+    };
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(node);
+    if (node.firstElementChild) observer.observe(node.firstElementChild);
+    return () => observer.disconnect();
+  }, []);
+
+  return [ref, { x, y }] as const;
+}

package/src/hooks/usePortalScope.ts

@@ -0,0 +1,68 @@
+import { useCallback, useRef } from "react";
+
+const opposite = (theme: "light" | "dark") =>
+  theme === "dark" ? "light" : "dark";
+
+type PortalScopeOptions = {
+  /**
+   * 浮层用和声明处相反的主题：亮色页面上是一块深色，暗色页面上是一块浅色
+   * （文字提示）。里面的控件因此也按相反的底色取值。
+   */
+  invertTheme?: boolean;
+};
+
+/**
+ * 浮层挂在 `<body>` 下，离开了声明它的那棵子树，拿不到局部容器上的
+ * `data-theme` / `data-choice`。把 `anchorRef` 交给触发元素、`portalRef`
+ * 交给浮层的容器：容器每次挂载时，从触发元素往上找最近的开关，抄到容器上。
+ *
+ * 最近的就是 `<html>` 时不抄——浮层本来就继承它，抄了反而会在切换主题后留下旧值。
+ * 没有触发元素（纯受控的弹窗）时什么都不做，浮层跟随 `<html>`。
+ *
+ * 最近的是 `data-theme="inverse"`（反转块）时不能照抄：`inverse` 是相对的，
+ * 到了 `<body>` 下它反的就成了页面。所以先算出它实际是亮还是暗，抄算出来的那个。
+ */
+export function usePortalScope({
+  invertTheme = false,
+}: PortalScopeOptions = {}) {
+  const anchor = useRef<Element | null>(null);
+
+  // 两个都是回调 ref：不管对方要的是哪种元素的 ref 都能接上
+  const anchorRef = useCallback((node: Element | null) => {
+    anchor.current = node;
+  }, []);
+
+  const portalRef = useCallback(
+    (portal: HTMLElement | null) => {
+      if (!portal) return;
+      const root = document.documentElement;
+
+      const themed =
+        anchor.current?.closest<HTMLElement>("[data-theme]") ?? null;
+      const inverted = themed?.dataset.theme === "inverse";
+      // 反转块反的是谁：再往上找第一个写明亮 / 暗的容器
+      let base = themed;
+      while (base?.dataset.theme === "inverse") {
+        base = base.parentElement?.closest<HTMLElement>("[data-theme]") ?? null;
+      }
+      // 没有任何地方写主题时，页面是默认的亮色
+      const baseTheme =
+        (base ?? root).dataset.theme === "dark" ? "dark" : "light";
+      const theme = inverted ? opposite(baseTheme) : baseTheme;
+
+      if (invertTheme) {
+        portal.dataset.theme = opposite(theme);
+      } else if (inverted || (themed && themed !== root)) {
+        portal.dataset.theme = theme;
+      }
+
+      const choice = anchor.current?.closest<HTMLElement>("[data-choice]");
+      if (choice && choice !== root) {
+        portal.dataset.choice = choice.dataset.choice;
+      }
+    },
+    [invertTheme],
+  );
+
+  return { anchorRef, portalRef };
+}

package/src/hooks/useScrollPosition.ts

@@ -0,0 +1,57 @@
+import { useEffect, useState, type RefObject } from "react";
+
+export type ScrollMetrics = {
+  /** 已经往下滚了多少 */
+  scrolled: number;
+  /** 一共能滚多少：内容的高度减去容器的高度 */
+  room: number;
+};
+
+/**
+ * 盯着一个滚动容器（不传就是整个页面），由滚动位置算出一个值。
+ * 滚动、窗口尺寸变了、内容晚到（图片加载完）都会重新算；算出来的值没变就不重新渲染，
+ * 所以 `read` 要返回布尔或数字这样的原始值，并且用 `useCallback` 固定住。
+ *
+ * 指定了容器但它还没挂上时，值停在 `initial`。
+ */
+export function useScrollPosition<T>(
+  target: RefObject<HTMLElement | null> | undefined,
+  read: (metrics: ScrollMetrics) => T,
+  initial: T,
+): T {
+  const [value, setValue] = useState(initial);
+
+  useEffect(() => {
+    const element = target ? target.current : null;
+    if (target && !element) return;
+
+    const measure = () => {
+      const box = element ?? document.documentElement;
+      setValue(
+        read({
+          scrolled: element ? element.scrollTop : window.scrollY,
+          room: box.scrollHeight - box.clientHeight,
+        }),
+      );
+    };
+
+    measure();
+    const source = element ?? window;
+    source.addEventListener("scroll", measure, { passive: true });
+    window.addEventListener("resize", measure);
+
+    let observer: ResizeObserver | undefined;
+    if (typeof ResizeObserver !== "undefined") {
+      observer = new ResizeObserver(measure);
+      observer.observe(element ?? document.body);
+    }
+
+    return () => {
+      source.removeEventListener("scroll", measure);
+      window.removeEventListener("resize", measure);
+      observer?.disconnect();
+    };
+  }, [target, read]);
+
+  return value;
+}