@endfield-ui/react 0.0.0-stage → 0.2.0

package/src/components/side-rail/SideRail.tsx

@@ -0,0 +1,317 @@
+import { Tooltip as BaseTooltip } from "@base-ui/react/tooltip";
+import {
+  createContext,
+  useContext,
+  useMemo,
+  type ComponentProps,
+  type MouseEvent,
+  type ReactNode,
+} from "react";
+import { usePortalScope } from "../../hooks/usePortalScope";
+import { cn } from "../../lib/cn";
+import { focusRingInset } from "../../lib/focus-ring";
+import { LinkElement, type LinkRender } from "../link-element/LinkElement";
+import { NavActionContext } from "../nav-action/NavAction";
+
+export const SideRailContext = createContext({ collapsed: false });
+
+/**
+ * 一行栏目的样子：普通栏目和二级的父项共用。
+ * `current` 是"显示成当前的样子"（墨色、加粗、左缘的短竖条），不管 aria-current
+ */
+export function railItemClass({
+  current,
+  disabled,
+}: {
+  current: boolean;
+  disabled: boolean;
+}) {
+  return cn(
+    // 左内边距 20px + 24px 的图标位：收起成 64px 时图标正好居中，展开收起时它不跑位
+    "relative flex h-12 w-full items-center gap-3 pr-4 pl-5 text-left text-sm font-medium",
+    "transition-colors duration-(--duration-fast) ease-standard",
+    focusRingInset,
+    disabled
+      ? "cursor-not-allowed text-ink-disabled"
+      : [
+          current ? "font-bold text-ink" : "text-ink-secondary",
+          "hover:bg-surface-muted hover:text-ink",
+          // 收起时浮出来的那块文字（或菜单）还开着：这一项保持同样的底，两块连成一条
+          "data-popup-open:bg-surface-muted data-popup-open:text-ink",
+        ],
+    current &&
+      "before:absolute before:top-1/2 before:left-0 before:h-5 before:w-1 before:-translate-y-1/2 before:bg-ink before:content-['']",
+  );
+}
+
+/** 24px 的图标位，里面的图标 20px */
+export function RailIcon({ children }: { children: ReactNode }) {
+  return (
+    <span
+      aria-hidden="true"
+      className="flex size-6 shrink-0 items-center justify-center [&_svg]:size-5"
+    >
+      {children}
+    </span>
+  );
+}
+
+export type SideRailProps = Omit<ComponentProps<"nav">, "aria-label"> & {
+  /** 这块导航的名称，比如"主导航" */
+  "aria-label": string;
+  /**
+   * 收起成只有图标的窄轨（64px）。默认是展开的（224px，图标 + 文字）。
+   * 栏目少且固定、屏幕空间紧张时才收起
+   */
+  collapsed?: boolean;
+  /** 最上面的标志。本库不带标志，传你自己的 */
+  brand?: ReactNode;
+  /** 导航项下面的工具组：几个图标按钮 */
+  tools?: ReactNode;
+  /** 主行动块：放一个 `NavAction` */
+  action?: ReactNode;
+  /** 最下面的次要入口 */
+  footer?: ReactNode;
+  /** `SideRailItem`、`SideRailGroup`、`SideRailSub` */
+  children: ReactNode;
+};
+
+/**
+ * 侧轨：桌面端贴在左边的主导航。自上而下是标志、导航项、工具组、主行动块、次要入口；
+ * 导航项放不下时在中间那一段里滚动。
+ *
+ * 默认 `sticky`、占满视口高；窄屏上不要把它缩小，换成 `TopBar` + `NavMenu`。
+ */
+export function SideRail({
+  collapsed = false,
+  brand,
+  tools,
+  action,
+  footer,
+  className,
+  children,
+  ...props
+}: SideRailProps) {
+  const context = useMemo(() => ({ collapsed }), [collapsed]);
+
+  return (
+    <SideRailContext value={context}>
+      <nav
+        {...props}
+        data-collapsed={collapsed ? "" : undefined}
+        className={cn(
+          // 环境阴影在暗色页面上看不出来，所以另有一条边线
+          "sticky top-0 z-(--z-nav) flex h-dvh shrink-0 flex-col border-r border-line bg-surface text-ink shadow-rail",
+          "transition-[width] duration-(--duration-base) ease-standard",
+          collapsed ? "w-16" : "w-56",
+          className,
+        )}
+      >
+        {brand && (
+          <div
+            className={cn(
+              "flex h-16 shrink-0 items-center overflow-hidden",
+              collapsed ? "justify-center" : "px-5",
+            )}
+          >
+            {brand}
+          </div>
+        )}
+
+        <ul className="flex min-h-0 flex-1 flex-col overflow-x-hidden overflow-y-auto overscroll-contain py-2">
+          {children}
+        </ul>
+
+        {tools && (
+          <div
+            className={cn(
+              "flex shrink-0 gap-1 p-3",
+              collapsed ? "flex-col items-center" : "flex-wrap",
+            )}
+          >
+            {tools}
+          </div>
+        )}
+
+        {action && (
+          <div
+            className={cn("flex shrink-0 p-3", collapsed && "justify-center")}
+          >
+            <NavActionContext value={collapsed ? "stacked" : "block"}>
+              {action}
+            </NavActionContext>
+          </div>
+        )}
+
+        {footer && (
+          <div
+            className={cn(
+              "flex shrink-0 flex-col gap-1 border-t border-line p-3 text-xs text-ink-secondary",
+              collapsed && "items-center",
+            )}
+          >
+            {footer}
+          </div>
+        )}
+      </nav>
+    </SideRailContext>
+  );
+}
+
+type ItemOwnProps = {
+  /** 图标。收起时只剩它，所以每一项都要有 */
+  icon: ReactNode;
+  /** 当前所在的栏目：墨色 + 左缘一条短竖条，输出 `aria-current="page"` */
+  current?: boolean;
+  /** 行尾的补充：计数、角标。收起时不显示 */
+  end?: ReactNode;
+  disabled?: boolean;
+  /** 传了就渲染成链接 */
+  href?: string;
+  target?: string;
+  rel?: string;
+  /** 用这个元素代替 `<a>`（路由库的链接组件）。传了就按链接处理 */
+  render?: LinkRender;
+  /** 没有 `href` 和 `render` 时渲染成按钮 */
+  onClick?: (event: MouseEvent<HTMLElement>) => void;
+  /** 栏目的名称。收起时看不见，但仍然是这一项的可访问名称 */
+  children: ReactNode;
+};
+
+export type SideRailItemProps = ItemOwnProps &
+  Omit<ComponentProps<"li">, keyof ItemOwnProps>;
+
+/** 侧轨里的一个栏目。 */
+export function SideRailItem({
+  icon,
+  current = false,
+  end,
+  disabled = false,
+  href,
+  target,
+  rel,
+  render,
+  onClick,
+  children,
+  ...props
+}: SideRailItemProps) {
+  const { collapsed } = useContext(SideRailContext);
+  const { anchorRef, portalRef } = usePortalScope();
+  const isLink = href !== undefined || render !== undefined;
+
+  const classes = railItemClass({ current, disabled });
+
+  const content = (
+    <>
+      <RailIcon>{icon}</RailIcon>
+      <span className={collapsed ? "sr-only" : "min-w-0 flex-1 truncate"}>
+        {children}
+      </span>
+      {!collapsed && end && (
+        <span className="flex shrink-0 items-center">{end}</span>
+      )}
+    </>
+  );
+
+  const control = isLink ? (
+    <LinkElement
+      render={render}
+      // 禁用的链接去掉 href，保留 link 角色，让读屏仍能读出"不可用"
+      href={disabled ? undefined : href}
+      role={disabled ? "link" : undefined}
+      aria-disabled={disabled || undefined}
+      target={target}
+      rel={rel}
+      aria-current={current ? "page" : undefined}
+      onClick={disabled ? (event) => event.preventDefault() : onClick}
+      className={classes}
+    >
+      {content}
+    </LinkElement>
+  ) : (
+    <button
+      type="button"
+      disabled={disabled}
+      aria-current={current ? "page" : undefined}
+      onClick={onClick}
+      className={classes}
+    >
+      {content}
+    </button>
+  );
+
+  return (
+    <li {...props}>
+      {collapsed && !disabled ? (
+        // 收起时，悬停或键盘聚焦：一块同色的底从这一项向右展开，里面是栏目名。
+        // 它挂在 <body> 下，侧轨自己滚动也裁不到它；只给眼睛看，读屏读的是项里的隐藏文字
+        <BaseTooltip.Root>
+          <BaseTooltip.Trigger
+            ref={anchorRef}
+            render={control}
+            delay={0}
+            closeDelay={0}
+          />
+          <BaseTooltip.Portal ref={portalRef}>
+            <BaseTooltip.Positioner
+              side="right"
+              align="center"
+              sideOffset={0}
+              className="pointer-events-none z-(--z-overlay)"
+            >
+              <BaseTooltip.Popup
+                aria-hidden="true"
+                className={cn(
+                  "flex h-(--anchor-height) items-center bg-surface-muted pr-5 pl-1 text-sm font-medium whitespace-nowrap text-ink",
+                  // 从侧轨一侧拉开
+                  "[clip-path:inset(0)] transition-[clip-path] duration-(--duration-fast) ease-exit data-instant:transition-none",
+                  "data-ending-style:[clip-path:inset(0_100%_0_0)] data-starting-style:[clip-path:inset(0_100%_0_0)]",
+                )}
+              >
+                {children}
+              </BaseTooltip.Popup>
+            </BaseTooltip.Positioner>
+          </BaseTooltip.Portal>
+        </BaseTooltip.Root>
+      ) : (
+        control
+      )}
+    </li>
+  );
+}
+
+export type SideRailGroupProps = Omit<ComponentProps<"li">, "children"> & {
+  /** 这一组的小标题。收起时换成一条短线，名称仍然读得到 */
+  label: string;
+  /** `SideRailItem` */
+  children: ReactNode;
+};
+
+/** 把几个栏目归成一组。栏目多的时候用。它只是分组；能展开收起的是 `SideRailSub`。 */
+export function SideRailGroup({
+  label,
+  className,
+  children,
+  ...props
+}: SideRailGroupProps) {
+  const { collapsed } = useContext(SideRailContext);
+
+  return (
+    <li {...props} className={cn("not-first:mt-2", className)}>
+      {collapsed ? (
+        <div
+          aria-hidden="true"
+          className="mx-auto mb-2 h-px w-6 bg-line-strong [li:first-child>&]:hidden"
+        />
+      ) : (
+        <div
+          aria-hidden="true"
+          className="truncate px-5 pt-2 pb-1 font-tech text-xs text-ink-tertiary"
+        >
+          {`// ${label}`}
+        </div>
+      )}
+      <ul aria-label={label}>{children}</ul>
+    </li>
+  );
+}

package/src/components/side-rail/SideRailSub.tsx

@@ -0,0 +1,298 @@
+import { Collapsible as BaseCollapsible } from "@base-ui/react/collapsible";
+import { Menu as BaseMenu } from "@base-ui/react/menu";
+import {
+  Children,
+  createContext,
+  isValidElement,
+  useContext,
+  useEffect,
+  useRef,
+  type ComponentProps,
+  type MouseEvent,
+  type ReactNode,
+} from "react";
+import { useControllableState } from "../../hooks/useControllableState";
+import { usePortalScope } from "../../hooks/usePortalScope";
+import { TriangleRight } from "../../icons/TriangleRight";
+import { cn } from "../../lib/cn";
+import { defined } from "../../lib/defined";
+import { focusRingInset } from "../../lib/focus-ring";
+import {
+  menuGroupLabel,
+  menuItem,
+  menuItemCurrent,
+  menuItemHover,
+  menuPanel,
+} from "../dropdown-menu/menu-style";
+import { LinkElement, type LinkRender } from "../link-element/LinkElement";
+import { RailIcon, railItemClass, SideRailContext } from "./SideRail";
+
+/** 子项要知道自己是排在侧轨里，还是在收起时弹出的那块菜单里 */
+const SubContext = createContext<"list" | "menu">("list");
+
+type SubOwnProps = {
+  /** 图标。收起时只剩它 */
+  icon: ReactNode;
+  /** 这一组的名称：父项上的文字，也是子列表和菜单的名称 */
+  label: string;
+  /** 展开着吗。只在侧轨展开时有意义；收起的侧轨上是弹出的菜单 */
+  open?: boolean;
+  /**
+   * 一开始展开着吗。默认：当前项在里面就展开。
+   * 之后当前项换到了里面（从别处导航过来），也会自己展开
+   */
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** 直接放 `SideRailSubItem` */
+  children: ReactNode;
+};
+
+export type SideRailSubProps = SubOwnProps &
+  Omit<ComponentProps<"li">, keyof SubOwnProps>;
+
+/**
+ * 侧轨里带二级的栏目。父项本身不是一个去处：点它只是展开收起。
+ * 侧轨收起时没有地方就地展开，改成向右弹出一块菜单。
+ */
+export function SideRailSub({
+  icon,
+  label,
+  open: openProp,
+  defaultOpen,
+  onOpenChange,
+  children,
+  ...props
+}: SideRailSubProps) {
+  const { collapsed } = useContext(SideRailContext);
+  const { anchorRef, portalRef } = usePortalScope();
+
+  // 当前项在不在里面：从子元素上读，所以 SideRailSubItem 要直接放在这里
+  const containsCurrent = Children.toArray(children).some(
+    (child) =>
+      isValidElement<{ current?: unknown }>(child) &&
+      child.props.current === true,
+  );
+
+  const [open, setOpen] = useControllableState({
+    value: openProp,
+    defaultValue: defaultOpen ?? containsCurrent,
+    onChange: onOpenChange,
+  });
+
+  // 当前项换到了里面（从别处导航过来的）：自己展开，否则它藏着，看不出人在哪
+  const contained = useRef(containsCurrent);
+  useEffect(() => {
+    if (containsCurrent && !contained.current) setOpen(true);
+    contained.current = containsCurrent;
+  }, [containsCurrent, setOpen]);
+
+  if (collapsed) {
+    return (
+      <li {...props}>
+        {/* 悬停打开的菜单本来就不锁页面；点开的也不锁——它是导航，不是一组操作 */}
+        <BaseMenu.Root modal={false}>
+          <BaseMenu.Trigger
+            ref={anchorRef}
+            openOnHover
+            delay={0}
+            // 子项都藏在菜单里：当前项在里面时，父项替它显示成当前的样子
+            className={railItemClass({
+              current: containsCurrent,
+              disabled: false,
+            })}
+          >
+            <RailIcon>{icon}</RailIcon>
+            <span className="sr-only">{label}</span>
+          </BaseMenu.Trigger>
+          <BaseMenu.Portal ref={portalRef}>
+            <BaseMenu.Positioner
+              side="right"
+              align="start"
+              sideOffset={0}
+              className="z-(--z-overlay) outline-none"
+            >
+              <BaseMenu.Popup
+                className={cn(
+                  menuPanel,
+                  "max-h-(--available-height) overflow-y-auto overscroll-contain",
+                )}
+              >
+                <BaseMenu.Group>
+                  <BaseMenu.GroupLabel className={menuGroupLabel}>
+                    {label}
+                  </BaseMenu.GroupLabel>
+                  <SubContext value="menu">{children}</SubContext>
+                </BaseMenu.Group>
+              </BaseMenu.Popup>
+            </BaseMenu.Positioner>
+          </BaseMenu.Portal>
+        </BaseMenu.Root>
+      </li>
+    );
+  }
+
+  return (
+    <li {...props}>
+      <BaseCollapsible.Root open={open} onOpenChange={(next) => setOpen(next)}>
+        <BaseCollapsible.Trigger
+          className={(state) =>
+            cn(
+              "group/sub",
+              // 展开时短竖条在子项上；收着的时候父项替它显示
+              railItemClass({
+                current: containsCurrent && !state.open,
+                disabled: false,
+              }),
+              // 当前项在里面：展开着父项也不退回次要色
+              containsCurrent && "text-ink",
+            )
+          }
+        >
+          <RailIcon>{icon}</RailIcon>
+          <span className="min-w-0 flex-1 truncate">{label}</span>
+          <TriangleRight
+            size={8}
+            className="shrink-0 transition-transform duration-(--duration-fast) ease-standard group-data-panel-open/sub:rotate-90"
+          />
+        </BaseCollapsible.Trigger>
+        <BaseCollapsible.Panel
+          className={cn(
+            "h-(--collapsible-panel-height) overflow-hidden",
+            "transition-[height] duration-(--duration-base) ease-standard",
+            "data-ending-style:h-0 data-starting-style:h-0",
+          )}
+        >
+          {/* 引线对着父项图标的中线（左起 32px） */}
+          <ul
+            aria-label={label}
+            className="relative before:absolute before:inset-y-0 before:left-8 before:w-px before:bg-line before:content-['']"
+          >
+            <SubContext value="list">{children}</SubContext>
+          </ul>
+        </BaseCollapsible.Panel>
+      </BaseCollapsible.Root>
+    </li>
+  );
+}
+
+type SubItemOwnProps = {
+  /** 当前所在的页面：墨色、加粗，引线在这一段变成粗条；输出 `aria-current="page"` */
+  current?: boolean;
+  /** 行尾的补充：计数、角标 */
+  end?: ReactNode;
+  disabled?: boolean;
+  /** 传了就渲染成链接 */
+  href?: string;
+  target?: string;
+  rel?: string;
+  /** 用这个元素代替 `<a>`（路由库的链接组件）。传了就按链接处理 */
+  render?: LinkRender;
+  /** 没有 `href` 和 `render` 时渲染成按钮 */
+  onClick?: (event: MouseEvent<HTMLElement>) => void;
+  children: ReactNode;
+};
+
+export type SideRailSubItemProps = SubItemOwnProps &
+  Omit<ComponentProps<"li">, keyof SubItemOwnProps>;
+
+/** 二级里的一项。直接放在 `SideRailSub` 里。 */
+export function SideRailSubItem({
+  current = false,
+  end,
+  disabled = false,
+  href,
+  target,
+  rel,
+  render,
+  onClick,
+  children,
+  ...props
+}: SideRailSubItemProps) {
+  const placement = useContext(SubContext);
+  const isLink = href !== undefined || render !== undefined;
+
+  const content = (
+    <>
+      <span className="min-w-0 flex-1 truncate">{children}</span>
+      {end && <span className="flex shrink-0 items-center">{end}</span>}
+    </>
+  );
+
+  // 收起的侧轨：这一项是弹出菜单里的一个菜单项
+  if (placement === "menu") {
+    const classes = cn(
+      menuItem,
+      current ? menuItemCurrent.plain : menuItemHover,
+    );
+    return isLink ? (
+      <BaseMenu.LinkItem
+        render={render}
+        {...defined({ href: disabled ? undefined : href, target, rel })}
+        aria-current={current ? "page" : undefined}
+        aria-disabled={disabled || undefined}
+        data-disabled={disabled ? "" : undefined}
+        closeOnClick
+        onClick={disabled ? (event) => event.preventDefault() : onClick}
+        className={classes}
+      >
+        {content}
+      </BaseMenu.LinkItem>
+    ) : (
+      <BaseMenu.Item
+        disabled={disabled}
+        aria-current={current ? "page" : undefined}
+        onClick={onClick}
+        className={classes}
+      >
+        {content}
+      </BaseMenu.Item>
+    );
+  }
+
+  const classes = cn(
+    // 文字和父项的文字对齐：20px 的内边距 + 24px 的图标位 + 12px 的间隔
+    "relative flex h-10 w-full items-center gap-3 pr-4 pl-14 text-left text-sm",
+    "transition-colors duration-(--duration-fast) ease-standard",
+    focusRingInset,
+    disabled
+      ? "cursor-not-allowed text-ink-disabled"
+      : [
+          current ? "font-bold text-ink" : "text-ink-secondary",
+          "hover:bg-surface-muted hover:text-ink",
+        ],
+    // 引线在当前项这一段换成粗条
+    current &&
+      "before:absolute before:inset-y-2 before:left-[31px] before:w-[3px] before:bg-ink before:content-['']",
+  );
+
+  return (
+    <li {...props}>
+      {isLink ? (
+        <LinkElement
+          render={render}
+          // 禁用的链接去掉 href，保留 link 角色，让读屏仍能读出"不可用"
+          href={disabled ? undefined : href}
+          role={disabled ? "link" : undefined}
+          aria-disabled={disabled || undefined}
+          target={target}
+          rel={rel}
+          aria-current={current ? "page" : undefined}
+          onClick={disabled ? (event) => event.preventDefault() : onClick}
+          className={classes}
+        >
+          {content}
+        </LinkElement>
+      ) : (
+        <button
+          type="button"
+          disabled={disabled}
+          aria-current={current ? "page" : undefined}
+          onClick={onClick}
+          className={classes}
+        >
+          {content}
+        </button>
+      )}
+    </li>
+  );
+}

package/src/components/side-rail/index.ts

@@ -0,0 +1,14 @@
+export {
+  SideRail,
+  SideRailGroup,
+  SideRailItem,
+  type SideRailGroupProps,
+  type SideRailItemProps,
+  type SideRailProps,
+} from "./SideRail";
+export {
+  SideRailSub,
+  SideRailSubItem,
+  type SideRailSubItemProps,
+  type SideRailSubProps,
+} from "./SideRailSub";

package/src/components/skeleton/Skeleton.tsx

@@ -0,0 +1,70 @@
+import type { ComponentProps } from "react";
+import { cn } from "../../lib/cn";
+
+export type SkeletonVariant = "block" | "text" | "circle";
+
+export type SkeletonProps = Omit<ComponentProps<"span">, "children"> & {
+  /**
+   * - `block` 与内容等大的色块，尺寸用 `className` 给（`h-40 w-full`），默认；
+   * - `text` 几行文字，行高跟随所在位置的字号；
+   * - `circle` 圆形，头像、图标。
+   */
+  variant?: SkeletonVariant;
+  /** `text` 的行数，默认 3。多于一行时末行短一截 */
+  lines?: number;
+  /** 很轻的明度往返。默认不动 */
+  pulse?: boolean;
+};
+
+const fill = "block bg-surface-muted";
+
+/**
+ * 骨架：只画大块，不画细节。
+ * 自身对辅助技术隐藏；"正在加载"由外层区域的 `aria-busy="true"` 表达。
+ */
+export function Skeleton({
+  variant = "block",
+  lines = 3,
+  pulse = false,
+  className,
+  ...props
+}: SkeletonProps) {
+  const motion = pulse && "animate-pulse";
+
+  if (variant === "text") {
+    const count = Math.max(1, Math.floor(lines));
+    return (
+      <span
+        {...props}
+        aria-hidden="true"
+        data-variant={variant}
+        className={cn("flex flex-col gap-[0.6em]", motion, className)}
+      >
+        {Array.from({ length: count }, (_, index) => (
+          <span
+            key={index}
+            className={cn(
+              fill,
+              "h-[0.9em]",
+              count > 1 && index === count - 1 ? "w-3/5" : "w-full",
+            )}
+          />
+        ))}
+      </span>
+    );
+  }
+
+  return (
+    <span
+      {...props}
+      aria-hidden="true"
+      data-variant={variant}
+      className={cn(
+        fill,
+        variant === "circle" ? "size-10 rounded-full" : "h-16 w-full",
+        motion,
+        className,
+      )}
+    />
+  );
+}

package/src/components/skeleton/index.ts

@@ -0,0 +1 @@
+export { Skeleton, type SkeletonProps, type SkeletonVariant } from "./Skeleton";