@endfield-ui/react 0.0.0-stage → 0.2.0

package/src/components/combobox/Combobox.tsx

@@ -0,0 +1,450 @@
+import { Combobox as BaseCombobox } from "@base-ui/react/combobox";
+import { useMemo, useRef, type ReactNode, type Ref } from "react";
+import { usePortalScope } from "../../hooks/usePortalScope";
+import { Close } from "../../icons/Close";
+import { StatusDanger } from "../../icons/StatusDanger";
+import { TriangleRight } from "../../icons/TriangleRight";
+import { cn } from "../../lib/cn";
+import { Spinner } from "../spinner/Spinner";
+import { MenuCheck } from "../dropdown-menu/MenuCheck";
+import {
+  menuGroupLabel,
+  menuItem,
+  menuItemCurrent,
+  menuItemHover,
+  menuPanel,
+  type MenuVariant,
+} from "../dropdown-menu/menu-style";
+import { useFieldControl } from "../field/Field";
+import {
+  controlBox,
+  controlElement,
+  controlIconSize,
+  type ControlSize,
+  type ControlVariant,
+} from "../input/control-box";
+import {
+  multiValueBox,
+  valueChip,
+  valueChipRemove,
+  valueChipSize,
+  valueInputHeight,
+} from "../input/value-chip";
+
+export type ComboboxSize = ControlSize;
+export type ComboboxVariant = ControlVariant;
+
+export type ComboboxOption = {
+  value: string;
+  /** 显示的文字，也是检索的对象，所以必须是字符串 */
+  label: string;
+  /** 别名：检索时一并匹配，不显示。编号、缩写、旧称 */
+  keywords?: readonly string[];
+  disabled?: boolean;
+};
+
+export type ComboboxOptionGroup = {
+  /** 分组的小标题 */
+  label: string;
+  items: readonly ComboboxOption[];
+};
+
+type ComboboxCommonProps = {
+  /** 选项，或者 `{ label, items }` 的分组。分组和不分组的不要混着传 */
+  items: readonly ComboboxOption[] | readonly ComboboxOptionGroup[];
+  /** 没选时输入框里的提示 */
+  placeholder?: string;
+  /** 表单字段名：选中的值会随表单提交 */
+  name?: string;
+  /**
+   * 外框的画法，和输入框相同：
+   * - `sunken` 凹陷的底 + 一条底边线，默认；
+   * - `outline` 四边描边，放在凹陷底色的区域里时用。
+   */
+  variant?: ComboboxVariant;
+  /** 32 / 40 / 56px 高。多选时这是最小高度，已选项多了会长高 */
+  size?: ComboboxSize;
+  /**
+   * 面板的画法：
+   * - `plain` 跟随主题，默认；
+   * - `strong` 固定的深色面板，当前项整行黄底墨字。
+   */
+  panelVariant?: MenuVariant;
+  /** 一个都没匹配上时面板里的说明 */
+  emptyText?: ReactNode;
+  /**
+   * 正在取选项：面板里出一行"正在查找…"，这时不显示 `emptyText`。
+   * 已经拿到的选项照常显示
+   */
+  loading?: boolean;
+  /** `loading` 时那一行的文字 */
+  loadingText?: ReactNode;
+  /**
+   * 关掉之后不在本地筛选：`items` 给什么就显示什么。
+   * 选项由服务器按输入的文字返回时用，配合 `onInputValueChange` 和 `loading`
+   */
+  filter?: boolean;
+  /** 清除钮的可访问名称 */
+  clearLabel?: string;
+  /** 右侧三角按钮的可访问名称 */
+  toggleLabel?: string;
+  /** 错误态。放在 `Field` 里时跟随它的 `error` */
+  invalid?: boolean;
+  disabled?: boolean;
+  required?: boolean;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** 输入框里的文字变了：要自己去取选项（远程检索）时用 */
+  onInputValueChange?: (text: string) => void;
+  id?: string;
+  "aria-label"?: string;
+  "aria-describedby"?: string;
+  /** 给外框 */
+  className?: string;
+  /** 给里面的 `<input>` */
+  ref?: Ref<HTMLInputElement>;
+};
+
+export type ComboboxSingleProps = ComboboxCommonProps & {
+  multiple?: false;
+  value?: string | null;
+  defaultValue?: string | null;
+  /** 清除之后拿到的是 `null` */
+  onValueChange?: (value: string | null) => void;
+  removeLabel?: never;
+};
+
+export type ComboboxMultipleProps = ComboboxCommonProps & {
+  /**
+   * 可以选多项：值是数组，已选项在框里排成一个个小块。
+   * 没打字直接选时面板不关；打了字搜出来再选，文字清空、面板关上
+   */
+  multiple: true;
+  value?: string[];
+  defaultValue?: string[];
+  onValueChange?: (value: string[]) => void;
+  /** 小块上删除叉的可访问名称，拿到的是这一项的文字。默认"移除某某" */
+  removeLabel?: (label: string) => string;
+};
+
+export type ComboboxProps = ComboboxSingleProps | ComboboxMultipleProps;
+
+const isGrouped = (
+  items: ComboboxCommonProps["items"],
+): items is readonly ComboboxOptionGroup[] =>
+  items.length > 0 && "items" in items[0]!;
+
+/** 单行时是固定高度；多选会换行，所以只定最小高度（`multiValueBox`） */
+const boxSize: Record<ComboboxSize, string> = {
+  sm: "h-8 text-sm",
+  md: "h-10 text-base",
+  lg: "h-14 text-lg",
+};
+
+/*
+ * 焦点一直在输入框里，"移到了哪一项"只靠底色表示（没有焦点环可画）。
+ * 当前项本来就有底色，被移到时再深一档，否则看不出来。
+ */
+const currentHighlighted: Record<MenuVariant, string> = {
+  plain: "data-highlighted:bg-line",
+  strong: "data-highlighted:bg-action-pressed",
+};
+
+const iconButton =
+  "flex shrink-0 items-center justify-center self-stretch text-ink-secondary hover:text-ink disabled:cursor-not-allowed disabled:text-ink-disabled disabled:hover:text-ink-disabled";
+
+const byValue = (a: ComboboxOption | null, b: ComboboxOption | null) =>
+  a?.value === b?.value;
+
+/**
+ * 组合框：一个能打字的下拉。选项多到要找的时候用它；只有几项时用 `Select`。
+ * 值只能是选项里有的——它不是"带建议的输入框"。
+ * 每个组合框都要有标签：放进 `Field`，或者自己传 `aria-label`。
+ */
+export function Combobox(props: ComboboxProps) {
+  const {
+    items,
+    placeholder,
+    name,
+    variant = "sunken",
+    size = "md",
+    panelVariant = "plain",
+    emptyText = "没有匹配的选项",
+    loading = false,
+    loadingText = "正在查找…",
+    filter: filterLocally = true,
+    clearLabel = "清除",
+    toggleLabel = "展开选项",
+    invalid: invalidProp,
+    disabled: disabledProp,
+    required: requiredProp,
+    open,
+    defaultOpen,
+    onOpenChange,
+    onInputValueChange,
+    id: idProp,
+    "aria-label": ariaLabel,
+    "aria-describedby": describedByProp,
+    className,
+    ref,
+  } = props;
+  const { id, disabled, required, invalid, ...field } = useFieldControl({
+    id: idProp,
+    disabled: disabledProp,
+    required: requiredProp,
+    invalid: invalidProp,
+    "aria-describedby": describedByProp,
+  });
+  const boxRef = useRef<HTMLDivElement>(null);
+  const { anchorRef, portalRef } = usePortalScope();
+  const iconSize = controlIconSize[size];
+  const multiple = props.multiple === true;
+  const grouped = isGrouped(items);
+
+  const options = useMemo(
+    () => (isGrouped(items) ? items.flatMap((group) => group.items) : items),
+    [items],
+  );
+  // 远程检索时 items 每次只是一部分：选中的那一项可能不在这一批里。
+  // 把见过的选项都记下来，值才一直找得到它的文字
+  const seen = useRef(new Map<string, ComboboxOption>());
+  for (const option of options) seen.current.set(option.value, option);
+
+  // 对外的值是字符串，基元要的是选项本身
+  const find = (value: string | null | undefined) =>
+    value == null ? null : (seen.current.get(value) ?? null);
+  const findAll = (values: readonly string[]) =>
+    values.flatMap((value) => seen.current.get(value) ?? []);
+
+  // 匹配文字和别名；不分大小写、不分全半角
+  const { contains } = BaseCombobox.useFilter({ sensitivity: "base" });
+  const filter = (option: ComboboxOption, query: string) =>
+    contains(option.label, query) ||
+    (option.keywords?.some((keyword) => contains(keyword, query)) ?? false);
+
+  const renderOption = (option: ComboboxOption) => (
+    <BaseCombobox.Item
+      key={option.value}
+      value={option}
+      disabled={option.disabled}
+      className={(state) =>
+        cn(
+          menuItem,
+          multiple
+            ? // 多选时会有好几项被选中：用行首的小方格表达，不铺整行的底色
+              [menuItemHover, state.selected && "font-medium"]
+            : state.selected
+              ? [
+                  menuItemCurrent[panelVariant],
+                  currentHighlighted[panelVariant],
+                ]
+              : menuItemHover,
+        )
+      }
+      render={
+        multiple
+          ? ({ children, ...itemProps }, state) => (
+              <div {...itemProps}>
+                <MenuCheck checked={state.selected} disabled={state.disabled} />
+                {children}
+              </div>
+            )
+          : undefined
+      }
+    >
+      <span className="min-w-0 flex-1 truncate">{option.label}</span>
+    </BaseCombobox.Item>
+  );
+
+  const input = (hasValue: boolean) => (
+    <BaseCombobox.Input
+      ref={ref}
+      id={id}
+      // 多选时已经有小块了，就不再显示提示
+      placeholder={hasValue ? undefined : placeholder}
+      aria-label={ariaLabel}
+      aria-invalid={invalid || undefined}
+      aria-describedby={field["aria-describedby"]}
+      className={cn(
+        controlElement,
+        multiple
+          ? ["min-w-12 px-1", valueInputHeight[size]]
+          : "h-full pr-2 pl-3",
+      )}
+    />
+  );
+
+  const content = (
+    <>
+      <div
+        ref={(node) => {
+          boxRef.current = node;
+          anchorRef(node);
+        }}
+        data-variant={variant}
+        data-size={size}
+        data-invalid={invalid ? "" : undefined}
+        className={cn(
+          controlBox({ variant, invalid, disabled, readOnly: false }),
+          "items-center",
+          multiple ? multiValueBox[size] : boxSize[size],
+          className,
+        )}
+      >
+        {props.multiple ? (
+          <BaseCombobox.Chips className="flex min-w-0 flex-1 flex-wrap items-center gap-1 py-1 pl-2">
+            <BaseCombobox.Value>
+              {(selected: ComboboxOption[]) => (
+                <>
+                  {selected.map((option) => (
+                    <BaseCombobox.Chip
+                      key={option.value}
+                      aria-label={option.label}
+                      className={cn(
+                        // 直角的小块：它是已经定下来的值，不是会自己变的状态
+                        valueChip,
+                        "focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus",
+                        "data-disabled:text-ink-disabled",
+                        valueChipSize[size],
+                      )}
+                    >
+                      <span className="min-w-0 truncate">{option.label}</span>
+                      <BaseCombobox.ChipRemove
+                        aria-label={(
+                          props.removeLabel ?? ((label) => `移除${label}`)
+                        )(option.label)}
+                        className={valueChipRemove}
+                      >
+                        <Close size={12} />
+                      </BaseCombobox.ChipRemove>
+                    </BaseCombobox.Chip>
+                  ))}
+                  {input(selected.length > 0)}
+                </>
+              )}
+            </BaseCombobox.Value>
+          </BaseCombobox.Chips>
+        ) : (
+          input(false)
+        )}
+        {invalid && (
+          <StatusDanger size={iconSize} className="shrink-0 text-danger" />
+        )}
+        <BaseCombobox.Clear
+          aria-label={clearLabel}
+          className={cn(iconButton, "w-7")}
+        >
+          <Close size={iconSize - 2} />
+        </BaseCombobox.Clear>
+        <BaseCombobox.Trigger
+          aria-label={toggleLabel}
+          className={cn(iconButton, "w-8 pr-1")}
+        >
+          <span className="flex rotate-90 transition-transform duration-(--duration-fast) ease-standard in-data-popup-open:-rotate-90">
+            <TriangleRight size={iconSize - 4} />
+          </span>
+        </BaseCombobox.Trigger>
+      </div>
+
+      <BaseCombobox.Portal ref={portalRef}>
+        <BaseCombobox.Positioner
+          anchor={boxRef}
+          side="bottom"
+          align="start"
+          sideOffset={4}
+          className="z-(--z-overlay) outline-none"
+        >
+          <BaseCombobox.Popup
+            data-theme={panelVariant === "strong" ? "dark" : undefined}
+            data-variant={panelVariant}
+            className={cn(
+              menuPanel,
+              "max-w-(--available-width) min-w-(--anchor-width)",
+            )}
+          >
+            {/*
+             * 这两行是播报给读屏的状态区，元素本身要一直在：空着的时候不占地方
+             * （内边距只在有内容时才有），而不是 display: none
+             */}
+            <BaseCombobox.Status className="flex items-center gap-2 text-sm text-ink-secondary not-empty:px-3 not-empty:py-2">
+              {loading && (
+                <>
+                  <Spinner size="sm" label={null} />
+                  {loadingText}
+                </>
+              )}
+            </BaseCombobox.Status>
+            <BaseCombobox.Empty className="text-sm text-ink-secondary not-empty:px-3 not-empty:py-2">
+              {loading ? null : emptyText}
+            </BaseCombobox.Empty>
+            <BaseCombobox.List
+              aria-busy={loading || undefined}
+              className="max-h-[min(var(--available-height),20rem)] overflow-y-auto overscroll-contain empty:hidden"
+            >
+              {grouped
+                ? (group: ComboboxOptionGroup) => (
+                    <BaseCombobox.Group key={group.label} items={group.items}>
+                      <BaseCombobox.GroupLabel className={menuGroupLabel}>
+                        {group.label}
+                      </BaseCombobox.GroupLabel>
+                      <BaseCombobox.Collection>
+                        {renderOption}
+                      </BaseCombobox.Collection>
+                    </BaseCombobox.Group>
+                  )
+                : renderOption}
+            </BaseCombobox.List>
+          </BaseCombobox.Popup>
+        </BaseCombobox.Positioner>
+      </BaseCombobox.Portal>
+    </>
+  );
+
+  const common = {
+    items,
+    filter: filterLocally ? filter : null,
+    name,
+    disabled,
+    required,
+    open,
+    defaultOpen,
+    onOpenChange: onOpenChange && ((next: boolean) => onOpenChange(next)),
+    onInputValueChange:
+      onInputValueChange && ((text: string) => onInputValueChange(text)),
+    isItemEqualToValue: byValue,
+  };
+
+  if (props.multiple) {
+    const { value, defaultValue, onValueChange } = props;
+    return (
+      <BaseCombobox.Root<ComboboxOption, true>
+        {...common}
+        multiple
+        value={value && findAll(value)}
+        defaultValue={defaultValue && findAll(defaultValue)}
+        onValueChange={
+          onValueChange &&
+          ((next) => onValueChange(next.map((option) => option.value)))
+        }
+      >
+        {content}
+      </BaseCombobox.Root>
+    );
+  }
+
+  const { value, defaultValue, onValueChange } = props;
+  return (
+    <BaseCombobox.Root<ComboboxOption>
+      {...common}
+      // 受控时没选就是 null；undefined 留给"不受控"
+      value={value === undefined ? undefined : find(value)}
+      defaultValue={defaultValue === undefined ? undefined : find(defaultValue)}
+      onValueChange={
+        onValueChange && ((next) => onValueChange(next?.value ?? null))
+      }
+    >
+      {content}
+    </BaseCombobox.Root>
+  );
+}

package/src/components/combobox/index.ts

@@ -0,0 +1,10 @@
+export {
+  Combobox,
+  type ComboboxMultipleProps,
+  type ComboboxOption,
+  type ComboboxOptionGroup,
+  type ComboboxProps,
+  type ComboboxSingleProps,
+  type ComboboxSize,
+  type ComboboxVariant,
+} from "./Combobox";

package/src/components/completion-banner/CompletionBanner.tsx

@@ -0,0 +1,72 @@
+import type { ComponentProps, ElementType, ReactNode } from "react";
+import { cn } from "../../lib/cn";
+import { GhostText } from "../ghost-text/GhostText";
+
+export type CompletionBannerProps = Omit<ComponentProps<"div">, "title"> & {
+  /** 一句话说明完成了什么："第三阶段已完成" */
+  title: ReactNode;
+  /** 背后的巨型描边词，默认 `COMPLETED`。纯装饰；传 `null` 去掉 */
+  word?: ReactNode;
+  /** 标题下的一行说明 */
+  description?: ReactNode;
+  /** 右侧的一个行动：领取、查看下一阶段 */
+  action?: ReactNode;
+  /** 标题层级，默认 3（`<h3>`） */
+  level?: 2 | 3 | 4 | 5 | 6;
+};
+
+/**
+ * 完成横幅：一个阶段全部完成时，头部区域做一次明暗反转。
+ * 只在真正的里程碑上用；日常的"保存成功"用提示条就够了。
+ *
+ * 底是反转块：亮色主题下是深底黄字，暗色主题下是浅底深字。
+ * 整块是一个 `data-theme="inverse"` 的局部主题，`action` 里的按钮按这块底色取值。
+ */
+export function CompletionBanner({
+  title,
+  word = "COMPLETED",
+  description,
+  action,
+  level = 3,
+  className,
+  children,
+  ...props
+}: CompletionBannerProps) {
+  const Heading: ElementType = `h${level}`;
+
+  return (
+    <div
+      role="status"
+      data-theme="inverse"
+      {...props}
+      className={cn(
+        "@container relative isolate overflow-clip bg-surface text-ink",
+        className,
+      )}
+    >
+      {word !== null && (
+        <GhostText
+          variant="outline"
+          // 描边比默认的重一些，在这块底上才看得出来。
+          // 贴右下角、向左淡出，不从标题和说明后面穿过；容器窄到放不下时去掉
+          className="absolute -right-2 -bottom-3 -z-10 hidden text-5xl [--ghost-ink:color-mix(in_srgb,var(--ef-ink)_28%,transparent)] [mask-image:linear-gradient(to_left,black_45%,transparent)] @md:block"
+        >
+          {word}
+        </GhostText>
+      )}
+      <div className="flex flex-wrap items-center justify-between gap-x-6 gap-y-3 px-4 py-4 @md:px-6 @md:py-5">
+        {/* 强调色跟着这块底走：亮色页面上是黄字压墨底，暗色页面上是深黄字压近白底 */}
+        <div className="min-w-0 border-l-4 border-accent-ink pl-3">
+          <Heading className="text-lg font-bold wrap-anywhere text-accent-ink @md:text-xl">
+            {title}
+          </Heading>
+          {description && (
+            <p className="mt-1 text-sm text-ink/70">{description}</p>
+          )}
+          {children}
+        </div>
+        {action && <div className="shrink-0">{action}</div>}
+      </div>
+    </div>
+  );
+}

package/src/components/completion-banner/index.ts

@@ -0,0 +1,4 @@
+export {
+  CompletionBanner,
+  type CompletionBannerProps,
+} from "./CompletionBanner";

package/src/components/context-menu/ContextMenu.tsx

@@ -0,0 +1,70 @@
+import { ContextMenu as BaseContextMenu } from "@base-ui/react/context-menu";
+import type { ReactElement, ReactNode } from "react";
+import { usePortalScope } from "../../hooks/usePortalScope";
+import { cn } from "../../lib/cn";
+import {
+  MenuVariantContext,
+  menuPanel,
+  type MenuVariant,
+} from "../dropdown-menu/menu-style";
+
+export type ContextMenuVariant = MenuVariant;
+
+export type ContextMenuProps = {
+  /**
+   * 菜单里的内容：`DropdownMenuItem`、`DropdownMenuCheckboxItem`、
+   * `DropdownMenuGroup`、`DropdownMenuSeparator`、`DropdownMenuSub`
+   */
+  menu: ReactNode;
+  /** 被右键的区域：一个能接收 `ref` 与事件的元素 */
+  children: ReactElement<Record<string, unknown>>;
+  /**
+   * - `plain` 跟随主题的面板，默认；
+   * - `strong` 固定的深色面板。
+   */
+  variant?: ContextMenuVariant;
+  onOpenChange?: (open: boolean) => void;
+  /** 不再拦右键：回到浏览器自己的菜单 */
+  disabled?: boolean;
+  /** 给面板 */
+  className?: string;
+};
+
+/**
+ * 右键菜单：在一块区域上点右键（或按菜单键、触屏长按）时出现在指针处的下拉菜单。
+ * 它只是捷径——里面的操作在页面上必须另有入口。
+ */
+export function ContextMenu({
+  menu,
+  children,
+  variant = "plain",
+  onOpenChange,
+  disabled,
+  className,
+}: ContextMenuProps) {
+  const { anchorRef, portalRef } = usePortalScope();
+
+  return (
+    <BaseContextMenu.Root
+      disabled={disabled}
+      onOpenChange={onOpenChange && ((next) => onOpenChange(next))}
+    >
+      <BaseContextMenu.Trigger ref={anchorRef} render={children} />
+      <BaseContextMenu.Portal ref={portalRef}>
+        <BaseContextMenu.Positioner className="z-(--z-overlay) outline-none">
+          <BaseContextMenu.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}>{menu}</MenuVariantContext>
+          </BaseContextMenu.Popup>
+        </BaseContextMenu.Positioner>
+      </BaseContextMenu.Portal>
+    </BaseContextMenu.Root>
+  );
+}

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

@@ -0,0 +1,5 @@
+export {
+  ContextMenu,
+  type ContextMenuProps,
+  type ContextMenuVariant,
+} from "./ContextMenu";

package/src/components/corner-brackets/CornerBrackets.tsx

@@ -0,0 +1,43 @@
+import type { ComponentProps } from "react";
+import { cn } from "../../lib/cn";
+
+export type CornerBracketsSize = "sm" | "md";
+
+export type CornerBracketsProps = ComponentProps<"div"> & {
+  /** 要不要画括号，默认画。用作选中态时把选中状态传进来 */
+  visible?: boolean;
+  /** 臂长 12px 或 16px */
+  size?: CornerBracketsSize;
+};
+
+const sizeClass: Record<CornerBracketsSize, string> = {
+  sm: "[--bracket-arm:12px]",
+  md: "[--bracket-arm:16px]",
+};
+
+/**
+ * 角括号：四角各一个 L 形短线，把里面的东西框出来。
+ * 用于矩阵里的单选（物品格、名册卡、图鉴）；列表行用左缘色条，页签用底色，都不用它。
+ *
+ * 括号画在盒子之外 4px：它所在的容器不能贴着盒子裁切。
+ * 括号只是给眼睛看的，选中态另外要有 `aria-selected` / `aria-pressed`。
+ */
+export function CornerBrackets({
+  visible = true,
+  size = "sm",
+  className,
+  ...props
+}: CornerBracketsProps) {
+  return (
+    <div
+      {...props}
+      data-visible={visible ? "" : undefined}
+      className={cn(
+        "relative",
+        visible && "corner-brackets",
+        sizeClass[size],
+        className,
+      )}
+    />
+  );
+}

package/src/components/corner-brackets/index.ts

@@ -0,0 +1,5 @@
+export {
+  CornerBrackets,
+  type CornerBracketsProps,
+  type CornerBracketsSize,
+} from "./CornerBrackets";