@endfield-ui/react 0.0.0-stage → 0.2.0

package/src/components/toc/Toc.tsx

@@ -0,0 +1,263 @@
+import {
+  Children,
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentProps,
+  type MouseEvent,
+  type ReactNode,
+  type RefObject,
+} from "react";
+import {
+  useScrollPosition,
+  type ScrollMetrics,
+} from "../../hooks/useScrollPosition";
+import { cn } from "../../lib/cn";
+import { focusRingInset } from "../../lib/focus-ring";
+import { mergeRefs } from "../../lib/merge-refs";
+import { LinkElement, type LinkRender } from "../link-element/LinkElement";
+
+export type TocLevel = 1 | 2 | 3;
+
+const TocContext = createContext<{
+  active: string | null;
+  pick: (section: string) => void;
+}>({ active: null, pick: () => {} });
+
+type TocOwnProps = {
+  /** 列表上面的一行小标。有它时目录以它命名 */
+  title?: ReactNode;
+  /**
+   * 视口上沿往下让多少像素才算"到了"。页面有吸顶的页头时传页头的高度，
+   * 并给各节的标题加同样大小的 `scroll-mt-*`
+   */
+  offset?: number;
+  /** 内容在哪个滚动容器里。不传就是整个页面 */
+  target?: RefObject<HTMLElement | null>;
+  /** 当前的小节变了：拿到它的 `id`，一节都还没到时是 `null` */
+  onActiveChange?: (section: string | null) => void;
+  /** `TocItem` */
+  children: ReactNode;
+};
+
+export type TocProps = TocOwnProps &
+  Omit<ComponentProps<"nav">, keyof TocOwnProps>;
+
+/** 点了一项之后，多久没有滚动事件算这一次滚动停下了 */
+const SETTLE_MS = 150;
+
+/**
+ * 页内目录：这一页有哪几节、现在看到了哪一节。里面放 `TocItem`。
+ *
+ * 位置由使用方给，通常是 `className="sticky top-6"`。点一项就是点一个锚点链接：
+ * 滚不滚、平不平滑是浏览器和页面 CSS 的事，它不接管滚动。
+ */
+export function Toc({
+  title,
+  offset = 0,
+  target,
+  onActiveChange,
+  "aria-label": ariaLabel,
+  className,
+  ref,
+  children,
+  ...props
+}: TocProps) {
+  const navRef = useRef<HTMLElement>(null);
+  const titleId = useId();
+  // 目录的项数变了（内容是后来才到的）要重新算一次，不等下一次滚动
+  const count = Children.count(children);
+
+  // 哪一节是当前的：最后一个顶边已经到了上沿的；滚到底时是最后一节
+  const read = useCallback(
+    ({ scrolled, room }: ScrollMetrics) => {
+      const nav = navRef.current;
+      if (!nav) return null;
+      const container = target?.current;
+      const top = container ? container.getBoundingClientRect().top : 0;
+
+      let active: string | null = null;
+      let last: string | null = null;
+      for (const link of nav.querySelectorAll<HTMLElement>(
+        "[data-toc-section]",
+      )) {
+        const id = link.dataset.tocSection!;
+        const section = document.getElementById(id);
+        if (!section) continue;
+        last = id;
+        if (section.getBoundingClientRect().top - top <= offset + 1) {
+          active = id;
+        }
+      }
+      // 最后一节往往很短，顶边永远到不了上沿
+      if (room > 0 && scrolled >= room - 1) return last;
+      return active;
+    },
+    // count 没在里面用到：它变了这个函数就换一个，滚动的监听跟着重新接、重新算一次
+    // oxlint-disable-next-line react-hooks/exhaustive-deps
+    [target, offset, count],
+  );
+  const spied = useScrollPosition<string | null>(target, read, null);
+
+  // 点了一项：它立刻是当前项，保持到这一次滚动停下、使用者自己再滚为止。
+  // 否则点倒数第二节、它到不了上沿，亮起来的会是别的
+  const [pinned, setPinned] = useState<string | null>(null);
+  useEffect(() => {
+    if (pinned === null) return;
+    const source = target?.current ?? window;
+    let settled = false;
+    let timer = setTimeout(() => {
+      settled = true;
+    }, SETTLE_MS);
+    const onScroll = () => {
+      if (settled) {
+        setPinned(null);
+        return;
+      }
+      clearTimeout(timer);
+      timer = setTimeout(() => {
+        settled = true;
+      }, SETTLE_MS);
+    };
+    source.addEventListener("scroll", onScroll, { passive: true });
+    return () => {
+      clearTimeout(timer);
+      source.removeEventListener("scroll", onScroll);
+    };
+  }, [pinned, target]);
+
+  const active = pinned ?? spied;
+
+  const report = useRef(onActiveChange);
+  report.current = onActiveChange;
+  const reported = useRef<string | null>(null);
+  useEffect(() => {
+    if (reported.current === active) return;
+    reported.current = active;
+    report.current?.(active);
+  }, [active]);
+
+  // 目录自己能滚的时候（使用方给了高度上限），当前项保持在看得见的范围里。
+  // 只动目录自己的滚动位置，不碰页面
+  useEffect(() => {
+    const nav = navRef.current;
+    if (!nav || active === null) return;
+    if (nav.scrollHeight <= nav.clientHeight + 1) return;
+    const link = nav.querySelector<HTMLElement>("[aria-current]");
+    if (!link) return;
+    const box = nav.getBoundingClientRect();
+    const rect = link.getBoundingClientRect();
+    if (rect.top < box.top) nav.scrollTop -= box.top - rect.top + 8;
+    else if (rect.bottom > box.bottom) {
+      nav.scrollTop += rect.bottom - box.bottom + 8;
+    }
+  }, [active]);
+
+  const context = useMemo(() => ({ active, pick: setPinned }), [active]);
+  const hasTitle = title !== undefined && title !== null && title !== false;
+
+  return (
+    <nav
+      {...props}
+      ref={mergeRefs(navRef, ref)}
+      aria-label={ariaLabel ?? (hasTitle ? undefined : "本页目录")}
+      aria-labelledby={
+        ariaLabel === undefined && hasTitle ? titleId : undefined
+      }
+      className={cn("text-sm text-ink", className)}
+    >
+      {hasTitle && (
+        <p
+          id={titleId}
+          className="mb-2 pl-4 font-tech text-xs text-ink-secondary"
+        >
+          {title}
+        </p>
+      )}
+      {/* 引线：从头贯到尾的一条细线，当前项那一段由那一项自己换成粗条 */}
+      <ul className="relative before:absolute before:inset-y-0 before:left-0 before:w-px before:bg-line before:content-['']">
+        <TocContext value={context}>{children}</TocContext>
+      </ul>
+    </nav>
+  );
+}
+
+type TocItemOwnProps = {
+  /** `#小节的 id`。小节就是按 `#` 后面这一段找的 */
+  href?: string;
+  /** 小节的 `id`。地址在 `render` 那个元素手里时用它 */
+  section?: string;
+  /** 第几级，只影响缩进。默认 1 */
+  level?: TocLevel;
+  /** 用这个元素代替 `<a>`（路由库的链接组件） */
+  render?: LinkRender;
+  onClick?: (event: MouseEvent<HTMLElement>) => void;
+  children: ReactNode;
+};
+
+export type TocItemProps = TocItemOwnProps &
+  Omit<ComponentProps<"li">, keyof TocItemOwnProps>;
+
+const levelPadding: Record<TocLevel, string> = {
+  1: "pl-4",
+  2: "pl-7",
+  3: "pl-10",
+};
+
+const sectionOf = (href: string | undefined) => {
+  const hash = href?.split("#")[1];
+  if (!hash) return undefined;
+  try {
+    return decodeURIComponent(hash);
+  } catch {
+    return hash;
+  }
+};
+
+/** 目录里的一项：一个指向小节的锚点链接。 */
+export function TocItem({
+  href,
+  section = sectionOf(href),
+  level = 1,
+  render,
+  onClick,
+  children,
+  ...props
+}: TocItemProps) {
+  const { active, pick } = useContext(TocContext);
+  const current = section !== undefined && section === active;
+
+  return (
+    <li {...props}>
+      <LinkElement
+        render={render}
+        href={href}
+        data-toc-section={section}
+        data-level={level}
+        aria-current={current ? "location" : undefined}
+        onClick={(event) => {
+          onClick?.(event);
+          if (!event.defaultPrevented && section !== undefined) pick(section);
+        }}
+        className={cn(
+          "relative block py-2 pr-2 leading-snug wrap-anywhere",
+          "transition-colors duration-(--duration-fast) ease-standard",
+          // 目录自己可能在一个会滚动的容器里：环画在里面
+          focusRingInset,
+          levelPadding[level],
+          current
+            ? // 不加粗：加粗会让折行变掉，整列目录跟着跳。靠的是引线上的这一段粗条
+              "text-ink before:absolute before:inset-y-1 before:left-0 before:w-[3px] before:bg-ink before:content-['']"
+            : "text-ink-secondary hover:text-ink",
+        )}
+      >
+        {children}
+      </LinkElement>
+    </li>
+  );
+}

package/src/components/toc/index.ts

@@ -0,0 +1,7 @@
+export {
+  Toc,
+  TocItem,
+  type TocItemProps,
+  type TocLevel,
+  type TocProps,
+} from "./Toc";

package/src/components/toolbar/Toolbar.tsx

@@ -0,0 +1,389 @@
+import { Toggle as BaseToggle } from "@base-ui/react/toggle";
+import { ToggleGroup as BaseToggleGroup } from "@base-ui/react/toggle-group";
+import { Toolbar as BaseToolbar } from "@base-ui/react/toolbar";
+import {
+  createContext,
+  useContext,
+  useMemo,
+  type ComponentProps,
+  type KeyboardEvent,
+  type MouseEvent,
+  type ReactNode,
+} from "react";
+import { cn } from "../../lib/cn";
+import { focusRing } from "../../lib/focus-ring";
+import type { LinkRender } from "../link-element/LinkElement";
+
+export type ToolbarSize = "sm" | "md";
+export type ToolbarVariant = "sunken" | "outline";
+export type ToolbarOrientation = "horizontal" | "vertical";
+
+const ToolbarContext = createContext<{
+  size: ToolbarSize;
+  orientation: ToolbarOrientation;
+}>({ size: "md", orientation: "horizontal" });
+
+export type ToolbarProps = Omit<
+  ComponentProps<"div">,
+  "aria-label" | "style"
+> & {
+  /** 这条工具栏管的是什么："表格工具" */
+  "aria-label": string;
+  /** 带子高 32 / 40px（里面的钮 28 / 36px），默认 `md`。触屏上用 `md` */
+  size?: ToolbarSize;
+  /**
+   * - `sunken` 凹陷的底，默认；
+   * - `outline` 四边描边，放在凹陷底色的区域里时用。
+   */
+  variant?: ToolbarVariant;
+  /** 竖排时方向键换成上下 */
+  orientation?: ToolbarOrientation;
+  /** 整条禁用 */
+  disabled?: boolean;
+};
+
+/* 带子的总高和输入框同档：2px 的内边距（描边时是 1px 的边 + 1px）加里面的钮 */
+const barVariant: Record<ToolbarVariant, string> = {
+  sunken: "bg-surface-sunken p-0.5",
+  outline: "border border-line-strong bg-surface p-px",
+};
+
+/**
+ * 工具栏：一排作用于同一个对象的小工具，收在一条带子里。整条只占一个 Tab 停靠点，
+ * 方向键在各项之间走。里面放 `ToolbarButton`、`ToolbarToggle`、`ToolbarToggleGroup`、
+ * `ToolbarGroup`、`ToolbarSeparator`。
+ *
+ * 不在里面放输入框：左右方向键在输入框里是移光标。
+ */
+export function Toolbar({
+  size = "md",
+  variant = "sunken",
+  orientation = "horizontal",
+  disabled = false,
+  className,
+  onKeyDown,
+  ...props
+}: ToolbarProps) {
+  const context = useMemo(() => ({ size, orientation }), [size, orientation]);
+
+  // 基元只管方向键，Home / End 在这里补上：到第一个、最后一个
+  const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    // 禁用的钮会把按键拦下（除了 Tab），到这里已经是"被拦下的"了：
+    // 只认使用方在这一层自己拦的
+    const already = event.defaultPrevented;
+    onKeyDown?.(event);
+    if (!already && event.defaultPrevented) return;
+    if (event.key !== "Home" && event.key !== "End") return;
+    // 工具栏里的每一项都带 tabindex（当前那个是 0，其余是 -1）
+    const items = event.currentTarget.querySelectorAll<HTMLElement>(
+      "button[tabindex], a[tabindex]",
+    );
+    const target = event.key === "Home" ? items[0] : items[items.length - 1];
+    if (!target) return;
+    event.preventDefault();
+    target.focus();
+  };
+
+  return (
+    <ToolbarContext value={context}>
+      <BaseToolbar.Root
+        {...props}
+        orientation={orientation}
+        disabled={disabled}
+        onKeyDown={handleKeyDown}
+        data-size={size}
+        data-variant={variant}
+        className={cn(
+          "inline-flex max-w-full gap-0.5 text-ink",
+          // 放不下就换行，不出横向滚动条
+          orientation === "vertical" ? "flex-col" : "flex-wrap items-center",
+          barVariant[variant],
+          className,
+        )}
+      />
+    </ToolbarContext>
+  );
+}
+
+/*
+ * 钮的点击区用伪元素补出去。`md` 四周各 2px，正好盖住钮之间的缝和带子的内边距，
+ * 到 40 × 40px；`sm` 横向只能补到缝为止（再多就盖到旁边的钮上了），是 32 × 40px。
+ */
+const itemSize: Record<ToolbarSize, string> = {
+  sm: "h-7 min-w-7 after:absolute after:-inset-x-0.5 after:-inset-y-1.5 after:content-['']",
+  md: "h-9 min-w-9 after:absolute after:-inset-0.5 after:content-['']",
+};
+
+const itemPadding: Record<ToolbarSize, string> = {
+  sm: "px-2",
+  md: "px-2.5",
+};
+
+/* 只有图标时图标跟着档位走；旁边有字时都是 16px，和 `text-sm` 的字配 */
+const iconOnlySize: Record<ToolbarSize, string> = {
+  sm: "[&_svg]:size-4",
+  md: "[&_svg]:size-5",
+};
+
+const itemBase = [
+  "group/item relative inline-flex shrink-0 items-center justify-center gap-1.5",
+  "text-sm leading-none font-medium whitespace-nowrap text-ink-secondary select-none",
+  "transition-colors duration-(--duration-fast) ease-standard",
+  "hover:bg-ink/5 hover:text-ink active:bg-ink/10",
+  // 按下的开关钮、还开着的菜单的触发钮：填充反转。字是反转的墨色，图标是黄记号（见 itemIcon）
+  "data-pressed:bg-surface-inverse data-pressed:text-ink-inverse",
+  "data-popup-open:bg-surface-inverse data-popup-open:text-ink-inverse",
+  "data-disabled:cursor-not-allowed data-disabled:bg-transparent data-disabled:text-ink-disabled",
+  "data-disabled:data-pressed:bg-disabled data-disabled:data-pressed:text-on-disabled",
+  // 焦点环压在旁边的钮上面
+  "focus-visible:z-1",
+  focusRing,
+].join(" ");
+
+/* 墨底黄记号，和 inverse 图标钮同一个样子；按下又禁用时跟着字一起降下去 */
+const itemIcon = [
+  "flex shrink-0",
+  "group-data-pressed/item:text-accent-ink-inverse",
+  "group-data-popup-open/item:text-accent-ink-inverse",
+  "group-data-disabled/item:group-data-pressed/item:text-on-disabled",
+].join(" ");
+
+function useItemClass(iconOnly: boolean, className: string | undefined) {
+  const { size } = useContext(ToolbarContext);
+  return cn(
+    itemBase,
+    itemSize[size],
+    iconOnly ? iconOnlySize[size] : [itemPadding[size], "[&_svg]:size-4"],
+    className,
+  );
+}
+
+function ItemContent({
+  icon,
+  children,
+}: {
+  icon: ReactNode;
+  children: ReactNode;
+}) {
+  return (
+    <>
+      {icon && <span className={itemIcon}>{icon}</span>}
+      {children}
+    </>
+  );
+}
+
+/** 有字的钮名称就是字；只有图标的必须另给名称 */
+type ItemContentProps =
+  | { children: ReactNode; "aria-label"?: string }
+  | { children?: undefined; "aria-label": string };
+
+const hasText = (children: ReactNode) =>
+  children !== undefined && children !== null && children !== false;
+
+type ButtonOwnProps = {
+  /** 图标，在文字左边 */
+  icon?: ReactNode;
+  disabled?: boolean;
+  /** 传了就渲染成链接 */
+  href?: string;
+  target?: string;
+  rel?: string;
+  /** 用这个元素代替 `<a>`（路由库的链接组件）。传了就按链接处理 */
+  render?: LinkRender;
+  onClick?: (event: MouseEvent<HTMLElement>) => void;
+};
+
+export type ToolbarButtonProps = ButtonOwnProps &
+  ItemContentProps &
+  Omit<
+    ComponentProps<"button">,
+    keyof ButtonOwnProps | "children" | "aria-label" | "style"
+  >;
+
+/**
+ * 工具栏里的一个钮。只有图标时是方的，必须有 `aria-label`。
+ * 可以交给 `Menu` / `Popover` 的 `trigger`，也可以用 `Tooltip` 包住。
+ */
+export function ToolbarButton({
+  icon,
+  disabled = false,
+  href,
+  target,
+  rel,
+  render,
+  onClick,
+  type = "button",
+  className,
+  children,
+  ...props
+}: ToolbarButtonProps) {
+  const classes = useItemClass(!hasText(children), className);
+  const content = <ItemContent icon={icon}>{children}</ItemContent>;
+
+  if (href !== undefined || render !== undefined) {
+    return (
+      <BaseToolbar.Link
+        {...(props as ComponentProps<"a">)}
+        render={render}
+        // 禁用的链接去掉地址；用了 render 时地址在那个元素手里，只能拦下点击
+        href={disabled ? undefined : href}
+        target={target}
+        rel={rel}
+        role={disabled && render === undefined ? "link" : undefined}
+        aria-disabled={disabled || undefined}
+        data-disabled={disabled ? "" : undefined}
+        onClick={disabled ? (event) => event.preventDefault() : onClick}
+        className={classes}
+      >
+        {content}
+      </BaseToolbar.Link>
+    );
+  }
+
+  return (
+    <BaseToolbar.Button
+      {...props}
+      type={type}
+      disabled={disabled}
+      onClick={onClick}
+      className={classes}
+    >
+      {content}
+    </BaseToolbar.Button>
+  );
+}
+
+type ToggleOwnProps = {
+  /** 图标，在文字左边 */
+  icon?: ReactNode;
+  /** 受控的按下状态。放在 `ToolbarToggleGroup` 里时不用它，用 `value` */
+  pressed?: boolean;
+  /** 非受控时一开始是不是按下的 */
+  defaultPressed?: boolean;
+  onPressedChange?: (pressed: boolean) => void;
+  /** 在 `ToolbarToggleGroup` 里是这一个钮的标识：组的 `value` 里放的就是它 */
+  value?: string;
+  disabled?: boolean;
+};
+
+export type ToolbarToggleProps = ToggleOwnProps &
+  ItemContentProps &
+  Omit<
+    ComponentProps<"button">,
+    keyof ToggleOwnProps | "children" | "aria-label" | "aria-pressed" | "style"
+  >;
+
+/** 开关钮：按下是墨底黄记号。单独用，或者几个放进 `ToolbarToggleGroup`。 */
+export function ToolbarToggle({
+  icon,
+  pressed,
+  defaultPressed,
+  onPressedChange,
+  value,
+  disabled = false,
+  type = "button",
+  className,
+  children,
+  ...props
+}: ToolbarToggleProps) {
+  const classes = useItemClass(!hasText(children), className);
+
+  return (
+    <BaseToolbar.Button
+      {...props}
+      type={type}
+      disabled={disabled}
+      render={
+        <BaseToggle
+          pressed={pressed}
+          defaultPressed={defaultPressed}
+          onPressedChange={onPressedChange && ((next) => onPressedChange(next))}
+          value={value}
+        />
+      }
+      className={classes}
+    >
+      <ItemContent icon={icon}>{children}</ItemContent>
+    </BaseToolbar.Button>
+  );
+}
+
+const groupClass =
+  "flex gap-0.5 data-[orientation=horizontal]:flex-wrap data-[orientation=horizontal]:items-center data-[orientation=vertical]:flex-col";
+
+export type ToolbarToggleGroupProps = Omit<
+  ComponentProps<"div">,
+  "aria-label" | "defaultValue" | "onChange" | "style"
+> & {
+  /** 这一组管的是什么："行高" */
+  "aria-label": string;
+  /** 按下的那几个钮的 `value` */
+  value?: string[];
+  defaultValue?: string[];
+  onValueChange?: (value: string[]) => void;
+  /** 可以同时按下几个。默认按下这个，那个就弹起来；一个都不按也可以 */
+  multiple?: boolean;
+  disabled?: boolean;
+};
+
+/** 一组开关钮。值是数组：没有按下的就是空的。 */
+export function ToolbarToggleGroup({
+  value,
+  defaultValue,
+  onValueChange,
+  multiple = false,
+  disabled,
+  className,
+  ...props
+}: ToolbarToggleGroupProps) {
+  const { orientation } = useContext(ToolbarContext);
+
+  return (
+    <BaseToggleGroup
+      {...props}
+      value={value}
+      defaultValue={defaultValue}
+      onValueChange={onValueChange && ((next) => onValueChange(next))}
+      multiple={multiple}
+      disabled={disabled}
+      orientation={orientation}
+      className={cn(groupClass, className)}
+    />
+  );
+}
+
+export type ToolbarGroupProps = Omit<
+  ComponentProps<"div">,
+  "aria-label" | "style"
+> & {
+  /** 这一组管的是什么 */
+  "aria-label": string;
+  /** 整组禁用 */
+  disabled?: boolean;
+};
+
+/** 把几个钮在读屏里算成一组。看上去没有区别；要分开看，中间放 `ToolbarSeparator`。 */
+export function ToolbarGroup({ className, ...props }: ToolbarGroupProps) {
+  return <BaseToolbar.Group {...props} className={cn(groupClass, className)} />;
+}
+
+export type ToolbarSeparatorProps = Omit<ComponentProps<"div">, "style">;
+
+/** 分隔：一条短线，方向和工具栏垂直。 */
+export function ToolbarSeparator({
+  className,
+  ...props
+}: ToolbarSeparatorProps) {
+  return (
+    <BaseToolbar.Separator
+      {...props}
+      className={cn(
+        "shrink-0 self-center bg-line-strong",
+        "data-[orientation=vertical]:mx-1 data-[orientation=vertical]:h-4 data-[orientation=vertical]:w-px",
+        "data-[orientation=horizontal]:my-1 data-[orientation=horizontal]:h-px data-[orientation=horizontal]:w-4",
+        className,
+      )}
+    />
+  );
+}

package/src/components/toolbar/index.ts

@@ -0,0 +1,17 @@
+export {
+  Toolbar,
+  ToolbarButton,
+  ToolbarGroup,
+  ToolbarSeparator,
+  ToolbarToggle,
+  ToolbarToggleGroup,
+  type ToolbarButtonProps,
+  type ToolbarGroupProps,
+  type ToolbarOrientation,
+  type ToolbarProps,
+  type ToolbarSeparatorProps,
+  type ToolbarSize,
+  type ToolbarToggleGroupProps,
+  type ToolbarToggleProps,
+  type ToolbarVariant,
+} from "./Toolbar";