@endfield-ui/react 0.0.0-stage → 0.2.0

package/src/components/drawer/Drawer.tsx

@@ -0,0 +1,213 @@
+import { Drawer as BaseDrawer } from "@base-ui/react/drawer";
+import {
+  useRef,
+  type ComponentProps,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import { usePortalScope } from "../../hooks/usePortalScope";
+import { Close } from "../../icons/Close";
+import { cn } from "../../lib/cn";
+import { firstFocusableIn } from "../dialog/initial-focus";
+import {
+  overlayBackdrop,
+  overlayClose,
+  overlayHeader,
+  overlaySurface,
+} from "../dialog/overlay-style";
+
+export type DrawerSide = "right" | "left" | "bottom";
+export type DrawerSize = "sm" | "md" | "lg";
+
+type PopupProps = ComponentProps<typeof BaseDrawer.Popup>;
+
+export type DrawerProps = Omit<
+  ComponentProps<"div">,
+  "title" | "children" | "className" | "style"
+> & {
+  /** 触发按钮。不传就用 `open` / `onOpenChange` 自己控制 */
+  trigger?: ReactElement<Record<string, unknown>>;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** 标题，在深色标题带里左对齐。它也是抽屉的可访问名称 */
+  title: ReactNode;
+  /** 标题下的一段说明，会关联给读屏 */
+  description?: ReactNode;
+  /** 底部的行动区，不随内容滚动 */
+  footer?: ReactNode;
+  /**
+   * 从哪一边滑入：
+   * - `right` 详情、设置，默认；
+   * - `left` 导航；
+   * - `bottom` 移动端的操作菜单，带拖动把手。
+   * 都可以朝来的方向划走。
+   */
+  side?: DrawerSide;
+  /** 侧边抽屉的宽度 320 / 400 / 480px，窄屏上通宽。默认 `md`。底部抽屉不用 */
+  size?: DrawerSize;
+  /** 靠页面内容的一侧加一条行动色的细条 */
+  accent?: boolean;
+  /** 关闭图标的可访问名称 */
+  closeLabel?: string;
+  /** 打开时焦点落在哪。默认是内容区里第一个可聚焦的元素 */
+  initialFocus?: PopupProps["initialFocus"];
+  /** 关闭后焦点回到哪。默认是触发按钮 */
+  finalFocus?: PopupProps["finalFocus"];
+  /** 给抽屉本身 */
+  className?: string;
+  children?: ReactNode;
+};
+
+const swipeDirection = {
+  right: "right",
+  left: "left",
+  bottom: "down",
+} as const;
+
+const viewportClass: Record<DrawerSide, string> = {
+  right: "justify-end",
+  left: "justify-start",
+  bottom: "items-end",
+};
+
+const sizeClass: Record<DrawerSize, string> = {
+  sm: "max-w-80",
+  md: "max-w-100",
+  lg: "max-w-120",
+};
+
+/*
+ * 位移跟着手指走（--drawer-swipe-movement-*），进出场时整块移到屏幕外。
+ * 拖动中不要过渡，否则抽屉会慢半拍。
+ */
+const motionClass: Record<DrawerSide, string> = {
+  right:
+    "translate-x-[var(--drawer-swipe-movement-x,0px)] data-ending-style:translate-x-full data-starting-style:translate-x-full",
+  left: "translate-x-[var(--drawer-swipe-movement-x,0px)] data-ending-style:-translate-x-full data-starting-style:-translate-x-full",
+  bottom:
+    "translate-y-[var(--drawer-swipe-movement-y,0px)] data-ending-style:translate-y-full data-starting-style:translate-y-full",
+};
+
+const accentClass: Record<DrawerSide, string> = {
+  right: "border-l-4 border-l-action",
+  left: "border-r-4 border-r-action",
+  bottom: "border-t-4 border-t-action",
+};
+
+/**
+ * 抽屉：从屏幕一侧滑入的面板。在不离开当前页面的前提下查看、编辑一个条目，
+ * 或者在窄屏上替代侧栏。焦点与背景的处理和弹窗相同。
+ */
+export function Drawer({
+  trigger,
+  open,
+  defaultOpen,
+  onOpenChange,
+  title,
+  description,
+  footer,
+  side = "right",
+  size = "md",
+  accent = false,
+  closeLabel = "关闭",
+  initialFocus,
+  finalFocus,
+  className,
+  children,
+  ...props
+}: DrawerProps) {
+  const { anchorRef, portalRef } = usePortalScope();
+  const contentRef = useRef<HTMLDivElement>(null);
+  const sheet = side === "bottom";
+
+  return (
+    <BaseDrawer.Root
+      open={open}
+      defaultOpen={defaultOpen}
+      onOpenChange={onOpenChange && ((next) => onOpenChange(next))}
+      swipeDirection={swipeDirection[side]}
+    >
+      {trigger && <BaseDrawer.Trigger ref={anchorRef} render={trigger} />}
+      <BaseDrawer.Portal ref={portalRef}>
+        <BaseDrawer.Backdrop
+          className={cn(
+            overlayBackdrop,
+            // 往外划的时候遮罩跟着变淡
+            "opacity-[calc(1-var(--drawer-swipe-progress,0))] data-swiping:duration-0",
+          )}
+        />
+        <BaseDrawer.Viewport
+          className={cn(
+            "fixed inset-0 z-(--z-overlay) flex overflow-hidden",
+            viewportClass[side],
+          )}
+        >
+          <BaseDrawer.Popup
+            {...props}
+            initialFocus={initialFocus ?? firstFocusableIn(contentRef)}
+            finalFocus={finalFocus}
+            data-side={side}
+            className={cn(
+              overlaySurface,
+              "flex min-h-0 w-full flex-col",
+              sheet ? "max-h-[85dvh]" : ["h-full", sizeClass[size]],
+              "transition-[translate] duration-(--duration-base) ease-exit data-swiping:duration-0 data-swiping:select-none",
+              motionClass[side],
+              accent && accentClass[side],
+              className,
+            )}
+          >
+            <div
+              data-theme="dark"
+              className={cn(
+                overlayHeader,
+                "min-h-12 pr-12 pl-4",
+                sheet && "pt-2",
+              )}
+            >
+              {sheet && (
+                // 拖动把手
+                <span
+                  aria-hidden="true"
+                  className="absolute top-1.5 left-1/2 h-1 w-8 -translate-x-1/2 bg-line-strong"
+                />
+              )}
+              <BaseDrawer.Title className="py-2.5 text-lg font-normal wrap-anywhere">
+                {title}
+              </BaseDrawer.Title>
+              <BaseDrawer.Close
+                aria-label={closeLabel}
+                className={overlayClose}
+              >
+                <Close size={24} />
+              </BaseDrawer.Close>
+            </div>
+
+            <div ref={contentRef} className="flex min-h-0 flex-auto flex-col">
+              <BaseDrawer.Content className="min-h-0 flex-auto overflow-y-auto overscroll-contain p-4 wrap-anywhere">
+                {description && (
+                  <BaseDrawer.Description
+                    className={cn(
+                      "text-ink-secondary",
+                      children !== undefined && "mb-4",
+                    )}
+                  >
+                    {description}
+                  </BaseDrawer.Description>
+                )}
+                {children}
+              </BaseDrawer.Content>
+
+              {footer && (
+                <div className="flex shrink-0 flex-wrap justify-end gap-3 border-t border-line px-4 py-3">
+                  {footer}
+                </div>
+              )}
+            </div>
+          </BaseDrawer.Popup>
+        </BaseDrawer.Viewport>
+      </BaseDrawer.Portal>
+    </BaseDrawer.Root>
+  );
+}

package/src/components/drawer/index.ts

@@ -0,0 +1,6 @@
+export {
+  Drawer,
+  type DrawerProps,
+  type DrawerSide,
+  type DrawerSize,
+} from "./Drawer";

package/src/components/dropdown-menu/DropdownMenu.tsx

@@ -0,0 +1,427 @@
+import { Menu as BaseMenu } from "@base-ui/react/menu";
+import {
+  useContext,
+  type ComponentProps,
+  type MouseEvent,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import { usePortalScope } from "../../hooks/usePortalScope";
+import { TriangleRight } from "../../icons/TriangleRight";
+import { cn } from "../../lib/cn";
+import { defined } from "../../lib/defined";
+import type { LinkRender } from "../link-element/LinkElement";
+import { MenuCheck } from "./MenuCheck";
+import {
+  MenuVariantContext,
+  menuGroupLabel,
+  menuItem,
+  menuItemCurrent,
+  menuItemHover,
+  menuPanel,
+  menuSeparator,
+  type MenuVariant,
+} from "./menu-style";
+
+export type DropdownMenuVariant = MenuVariant;
+export type DropdownMenuSide = "top" | "bottom" | "left" | "right";
+export type DropdownMenuAlign = "start" | "center" | "end";
+
+export type DropdownMenuProps = {
+  /** 触发按钮 */
+  trigger: ReactElement<Record<string, unknown>>;
+  /**
+   * - `plain` 跟随主题的面板，默认；
+   * - `strong` 固定的深色面板，当前项整行黄底墨字。
+   */
+  variant?: DropdownMenuVariant;
+  /** 面板出现在触发按钮的哪一侧，放不下时自动翻到对面。默认 `bottom` */
+  side?: DropdownMenuSide;
+  /** 和触发按钮的哪一边对齐。默认 `start` */
+  align?: DropdownMenuAlign;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** 给面板 */
+  className?: string;
+  /**
+   * `DropdownMenuItem`、`DropdownMenuCheckboxItem`、`DropdownMenuGroup`、
+   * `DropdownMenuSeparator`、`DropdownMenuRadioGroup`、`DropdownMenuSub`
+   */
+  children: ReactNode;
+};
+
+/**
+ * 点击触发的一组操作或选项。方向键移动、回车选择、`Esc` 关闭、按首字母跳转。
+ * 危险项放在最后并和其他项隔开。
+ */
+export function DropdownMenu({
+  trigger,
+  variant = "plain",
+  side = "bottom",
+  align = "start",
+  open,
+  defaultOpen,
+  onOpenChange,
+  className,
+  children,
+}: DropdownMenuProps) {
+  const { anchorRef, portalRef } = usePortalScope();
+
+  return (
+    <BaseMenu.Root
+      open={open}
+      defaultOpen={defaultOpen}
+      onOpenChange={onOpenChange && ((next) => onOpenChange(next))}
+    >
+      <BaseMenu.Trigger ref={anchorRef} render={trigger} />
+      <BaseMenu.Portal ref={portalRef}>
+        <BaseMenu.Positioner
+          side={side}
+          align={align}
+          sideOffset={4}
+          className="z-(--z-overlay) outline-none"
+        >
+          <BaseMenu.Popup
+            data-theme={variant === "strong" ? "dark" : undefined}
+            data-variant={variant}
+            className={cn(
+              menuPanel,
+              "max-h-(--available-height) overflow-y-auto overscroll-contain",
+              className,
+            )}
+          >
+            <MenuVariantContext value={variant}>{children}</MenuVariantContext>
+          </BaseMenu.Popup>
+        </BaseMenu.Positioner>
+      </BaseMenu.Portal>
+    </BaseMenu.Root>
+  );
+}
+
+export type DropdownMenuItemTone = "neutral" | "danger";
+
+type ItemOwnProps = {
+  /** `danger` 用于删除一类的操作：文字变红，放在最后并和其他项隔开 */
+  tone?: DropdownMenuItemTone;
+  /** 文字左侧的图标 */
+  iconStart?: ReactNode;
+  /** 行尾的补充：快捷键、计数 */
+  end?: ReactNode;
+  disabled?: boolean;
+  /** 点了之后是否关掉菜单。操作项默认关，链接项默认不关 */
+  closeOnClick?: boolean;
+  /** 传了就渲染成链接 */
+  href?: string;
+  target?: string;
+  rel?: string;
+  /** 用这个元素代替 `<a>`（路由库的链接组件）。传了就按链接处理 */
+  render?: LinkRender;
+  onClick?: (event: MouseEvent<HTMLElement>) => void;
+};
+
+export type DropdownMenuItemProps = ItemOwnProps &
+  Omit<ComponentProps<"div">, keyof ItemOwnProps | "id" | "style">;
+
+function itemContent(
+  iconStart: ReactNode,
+  children: ReactNode,
+  end: ReactNode,
+) {
+  return (
+    <>
+      {iconStart && (
+        <span
+          aria-hidden="true"
+          className="flex shrink-0 items-center [&_svg]:size-4"
+        >
+          {iconStart}
+        </span>
+      )}
+      <span className="min-w-0 flex-1 truncate">{children}</span>
+      {end && (
+        <span className="ml-4 flex shrink-0 items-center text-xs text-ink-secondary">
+          {end}
+        </span>
+      )}
+    </>
+  );
+}
+
+/** 菜单里的一个操作；传 `href` 就是一个链接。 */
+export function DropdownMenuItem({
+  tone = "neutral",
+  iconStart,
+  end,
+  disabled,
+  closeOnClick,
+  href,
+  target,
+  rel,
+  render,
+  onClick,
+  className,
+  children,
+  ...props
+}: DropdownMenuItemProps) {
+  const classes = cn(
+    menuItem,
+    menuItemHover,
+    tone === "danger" && "text-danger",
+    className,
+  );
+  const content = itemContent(iconStart, children, end);
+
+  if (href !== undefined || render !== undefined) {
+    return (
+      <BaseMenu.LinkItem
+        render={render}
+        {...defined({ href, target, rel })}
+        closeOnClick={closeOnClick}
+        onClick={onClick}
+        data-tone={tone}
+        className={classes}
+      >
+        {content}
+      </BaseMenu.LinkItem>
+    );
+  }
+
+  return (
+    <BaseMenu.Item
+      {...props}
+      disabled={disabled}
+      closeOnClick={closeOnClick}
+      onClick={onClick}
+      data-tone={tone}
+      className={classes}
+    >
+      {content}
+    </BaseMenu.Item>
+  );
+}
+
+export type DropdownMenuGroupProps = Omit<ComponentProps<"div">, "style"> & {
+  /** 分组的小标题 */
+  label?: ReactNode;
+};
+
+export function DropdownMenuGroup({
+  label,
+  children,
+  ...props
+}: DropdownMenuGroupProps) {
+  return (
+    <BaseMenu.Group {...props}>
+      {label && (
+        <BaseMenu.GroupLabel className={menuGroupLabel}>
+          {label}
+        </BaseMenu.GroupLabel>
+      )}
+      {children}
+    </BaseMenu.Group>
+  );
+}
+
+export type DropdownMenuSeparatorProps = Omit<ComponentProps<"div">, "style">;
+
+export function DropdownMenuSeparator({
+  className,
+  ...props
+}: DropdownMenuSeparatorProps) {
+  return (
+    <BaseMenu.Separator {...props} className={cn(menuSeparator, className)} />
+  );
+}
+
+export type DropdownMenuRadioGroupProps = {
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+  /** 这一组的小标题 */
+  label?: ReactNode;
+  disabled?: boolean;
+  children: ReactNode;
+};
+
+/** 一组里只有一个"当前项"的选项，比如语言、排序方式。 */
+export function DropdownMenuRadioGroup({
+  value,
+  defaultValue,
+  onValueChange,
+  label,
+  disabled,
+  children,
+}: DropdownMenuRadioGroupProps) {
+  const group = (
+    <BaseMenu.RadioGroup
+      value={value}
+      defaultValue={defaultValue}
+      onValueChange={onValueChange && ((next) => onValueChange(String(next)))}
+      disabled={disabled}
+    >
+      {children}
+    </BaseMenu.RadioGroup>
+  );
+
+  if (!label) return group;
+  return (
+    <BaseMenu.Group>
+      <BaseMenu.GroupLabel className={menuGroupLabel}>
+        {label}
+      </BaseMenu.GroupLabel>
+      {group}
+    </BaseMenu.Group>
+  );
+}
+
+export type DropdownMenuRadioItemProps = Omit<
+  ComponentProps<"div">,
+  "id" | "style" | "onClick"
+> & {
+  value: string;
+  disabled?: boolean;
+  /** 行尾的补充 */
+  end?: ReactNode;
+  /** 选了之后是否关掉菜单，默认关 */
+  closeOnClick?: boolean;
+};
+
+export function DropdownMenuRadioItem({
+  value,
+  disabled,
+  end,
+  closeOnClick = true,
+  className,
+  children,
+  ...props
+}: DropdownMenuRadioItemProps) {
+  const variant = useContext(MenuVariantContext);
+
+  return (
+    <BaseMenu.RadioItem
+      {...props}
+      value={value}
+      disabled={disabled}
+      closeOnClick={closeOnClick}
+      className={(state) =>
+        cn(
+          menuItem,
+          state.checked ? menuItemCurrent[variant] : menuItemHover,
+          className,
+        )
+      }
+    >
+      {itemContent(null, children, end)}
+    </BaseMenu.RadioItem>
+  );
+}
+
+export type DropdownMenuCheckboxItemProps = Omit<
+  ComponentProps<"div">,
+  "id" | "style" | "onClick"
+> & {
+  checked?: boolean;
+  defaultChecked?: boolean;
+  onCheckedChange?: (checked: boolean) => void;
+  disabled?: boolean;
+  /** 行尾的补充 */
+  end?: ReactNode;
+  /** 勾了之后是否关掉菜单。默认不关：可以连着改几项 */
+  closeOnClick?: boolean;
+};
+
+/** 能开能关的一项设置，比如"显示缩略图"。行首是一个小方格，没勾的时候也看得见。 */
+export function DropdownMenuCheckboxItem({
+  checked,
+  defaultChecked,
+  onCheckedChange,
+  disabled,
+  end,
+  closeOnClick = false,
+  className,
+  children,
+  ...props
+}: DropdownMenuCheckboxItemProps) {
+  return (
+    <BaseMenu.CheckboxItem
+      {...props}
+      checked={checked}
+      defaultChecked={defaultChecked}
+      onCheckedChange={onCheckedChange && ((next) => onCheckedChange(next))}
+      disabled={disabled}
+      closeOnClick={closeOnClick}
+      className={cn(menuItem, menuItemHover, className)}
+      render={(itemProps, state) => (
+        <div {...itemProps}>
+          <MenuCheck checked={state.checked} disabled={state.disabled} />
+          {itemContent(null, children, end)}
+        </div>
+      )}
+    />
+  );
+}
+
+export type DropdownMenuSubProps = {
+  /** 这一行的文字 */
+  label: ReactNode;
+  /** 文字左侧的图标 */
+  iconStart?: ReactNode;
+  disabled?: boolean;
+  /** 给子面板 */
+  className?: string;
+  /** 子面板里的选项 */
+  children: ReactNode;
+};
+
+/**
+ * 子菜单：菜单里的一行，停留或按 `→` 时在侧边展开另一块面板。
+ * 只做一层，不要在子菜单里再套子菜单。
+ */
+export function DropdownMenuSub({
+  label,
+  iconStart,
+  disabled,
+  className,
+  children,
+}: DropdownMenuSubProps) {
+  const variant = useContext(MenuVariantContext);
+  // 子面板也挂在 <body> 下：从这一行往上找，能找到主面板带着的主题
+  const { anchorRef, portalRef } = usePortalScope();
+
+  return (
+    <BaseMenu.SubmenuRoot disabled={disabled}>
+      <BaseMenu.SubmenuTrigger
+        ref={anchorRef}
+        className={cn(
+          menuItem,
+          menuItemHover,
+          // 子面板开着的时候这一行保持高亮：看得出面板是从哪一行出来的
+          "data-popup-open:bg-ink/5",
+        )}
+      >
+        {itemContent(iconStart, label, <TriangleRight size={10} />)}
+      </BaseMenu.SubmenuTrigger>
+      <BaseMenu.Portal ref={portalRef}>
+        <BaseMenu.Positioner
+          sideOffset={2}
+          // 面板有 1px 的边线和 4px 的上内边距：往上提这么多，第一项正好和这一行对齐
+          alignOffset={-5}
+          className="z-(--z-overlay) outline-none"
+        >
+          <BaseMenu.Popup
+            data-theme={variant === "strong" ? "dark" : undefined}
+            data-variant={variant}
+            className={cn(
+              menuPanel,
+              "max-h-(--available-height) overflow-y-auto overscroll-contain",
+              className,
+            )}
+          >
+            {children}
+          </BaseMenu.Popup>
+        </BaseMenu.Positioner>
+      </BaseMenu.Portal>
+    </BaseMenu.SubmenuRoot>
+  );
+}

package/src/components/dropdown-menu/MenuCheck.tsx

@@ -0,0 +1,44 @@
+import { Check } from "../../icons/Check";
+import { cn } from "../../lib/cn";
+
+export type MenuCheckProps = {
+  checked: boolean;
+  disabled?: boolean;
+};
+
+/**
+ * 菜单复选项、多选选项行首的小方格。画法同复选框（`checkbox/choice-style.ts`），
+ * 缩到 16px：未选是凹陷底 + 描边，已选是反转块 + 对勾；祖先上有
+ * `data-choice="diamond"` 时换成菱形，已选是实心的、不画对勾。
+ *
+ * 纯展示：勾没勾由所在的选项用 `aria-checked` / `aria-selected` 告诉读屏。
+ */
+export function MenuCheck({ checked, disabled = false }: MenuCheckProps) {
+  return (
+    // 外面这一层是定位盒：菱形比它小一圈，转 45° 后对角线正好还是 16px
+    <span
+      aria-hidden="true"
+      data-checked={checked ? "" : undefined}
+      className="flex size-4 shrink-0 items-center justify-center"
+    >
+      <span
+        className={cn(
+          "flex size-4 items-center justify-center border-2 transition-colors duration-(--duration-fast) ease-standard choice-diamond:size-3 choice-diamond:rotate-45",
+          disabled
+            ? [
+                "border-ink-disabled bg-surface-sunken text-ink-disabled",
+                // 菱形方案里"已选"只靠实心表达，禁用了也要保持实心
+                checked && "choice-diamond:bg-ink-disabled",
+              ]
+            : checked
+              ? "border-surface-inverse bg-surface-inverse text-accent-ink-inverse"
+              : "border-line-strong bg-surface-sunken",
+        )}
+      >
+        {checked && (
+          <Check size={10} strokeWidth={4} className="choice-diamond:hidden" />
+        )}
+      </span>
+    </span>
+  );
+}

package/src/components/dropdown-menu/index.ts

@@ -0,0 +1,22 @@
+export {
+  DropdownMenu,
+  DropdownMenuCheckboxItem,
+  DropdownMenuGroup,
+  DropdownMenuItem,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuSeparator,
+  DropdownMenuSub,
+  type DropdownMenuAlign,
+  type DropdownMenuCheckboxItemProps,
+  type DropdownMenuGroupProps,
+  type DropdownMenuItemProps,
+  type DropdownMenuItemTone,
+  type DropdownMenuProps,
+  type DropdownMenuRadioGroupProps,
+  type DropdownMenuRadioItemProps,
+  type DropdownMenuSeparatorProps,
+  type DropdownMenuSide,
+  type DropdownMenuSubProps,
+  type DropdownMenuVariant,
+} from "./DropdownMenu";