@endfield-ui/react 0.0.0-stage → 0.1.0

package/src/components/accordion/Accordion.tsx

@@ -0,0 +1,168 @@
+import { Accordion as BaseAccordion } from "@base-ui/react/accordion";
+import {
+  createContext,
+  useContext,
+  useMemo,
+  type ComponentProps,
+  type ReactNode,
+} from "react";
+import { Minus } from "../../icons/Minus";
+import { cn } from "../../lib/cn";
+import { focusRingInset } from "../../lib/focus-ring";
+
+export type AccordionSize = "sm" | "md";
+export type AccordionLevel = 2 | 3 | 4 | 5 | 6;
+
+const AccordionContext = createContext<{
+  size: AccordionSize;
+  level: AccordionLevel;
+}>({ size: "md", level: 3 });
+
+export type AccordionProps = Omit<
+  ComponentProps<"div">,
+  "defaultValue" | "onChange" | "style"
+> & {
+  /** 可以同时展开几项。默认开了这个，那个就收起来 */
+  multiple?: boolean;
+  /** 展开着的那几项的 `value` */
+  value?: string[];
+  defaultValue?: string[];
+  onValueChange?: (value: string[]) => void;
+  /** 标题行高 40 / 48px，默认 `md` */
+  size?: AccordionSize;
+  /** 标题的层级，默认 3（`<h3>`）。按它在页面里的位置给 */
+  level?: AccordionLevel;
+  /**
+   * 收起的内容也留在页面里：浏览器的页内查找找得到，找到时自动展开。
+   * 常见问题这类"来找一句话"的内容值得开
+   */
+  searchable?: boolean;
+  disabled?: boolean;
+  /** `AccordionItem` */
+  children: ReactNode;
+};
+
+/**
+ * 折叠面板：一摞可以各自展开收起的小节。先问能不能不折叠——
+ * 藏起来的东西有人会找不到。
+ */
+export function Accordion({
+  multiple = false,
+  value,
+  defaultValue,
+  onValueChange,
+  size = "md",
+  level = 3,
+  searchable = false,
+  disabled,
+  className,
+  children,
+  ...props
+}: AccordionProps) {
+  const context = useMemo(() => ({ size, level }), [size, level]);
+
+  return (
+    <AccordionContext value={context}>
+      <BaseAccordion.Root
+        {...props}
+        multiple={multiple}
+        value={value}
+        defaultValue={defaultValue}
+        onValueChange={
+          onValueChange && ((next) => onValueChange(next as string[]))
+        }
+        hiddenUntilFound={searchable}
+        disabled={disabled}
+        data-size={size}
+        className={cn("flex flex-col border-t border-line text-ink", className)}
+      >
+        {children}
+      </BaseAccordion.Root>
+    </AccordionContext>
+  );
+}
+
+const triggerSize: Record<AccordionSize, string> = {
+  sm: "min-h-10 py-1.5 text-sm",
+  md: "min-h-12 py-2 text-base",
+};
+
+type ItemOwnProps = {
+  /** 这一项的标识：`Accordion` 的 `value` 里放的就是它 */
+  value: string;
+  /** 标题：写成"里面是什么" */
+  title: ReactNode;
+  /** 标题右侧、记号之前的补充：计数、一个标签。它在按钮里，不能放能点的东西 */
+  extra?: ReactNode;
+  disabled?: boolean;
+  /** 内容 */
+  children: ReactNode;
+};
+
+export type AccordionItemProps = ItemOwnProps &
+  Omit<ComponentProps<"div">, keyof ItemOwnProps | "style">;
+
+/** 折叠面板里的一节。 */
+export function AccordionItem({
+  value,
+  title,
+  extra,
+  disabled,
+  className,
+  children,
+  ...props
+}: AccordionItemProps) {
+  const { size, level } = useContext(AccordionContext);
+  const Heading = `h${level}` as const;
+
+  return (
+    <BaseAccordion.Item
+      {...props}
+      value={value}
+      disabled={disabled}
+      className={cn("border-b border-line", className)}
+    >
+      <BaseAccordion.Header render={<Heading />} className="flex">
+        <BaseAccordion.Trigger
+          className={cn(
+            "group/trigger flex w-full items-center gap-3 px-4 text-left font-medium",
+            "transition-colors duration-(--duration-fast) ease-standard",
+            "hover:bg-ink/5 data-panel-open:font-bold",
+            "data-disabled:cursor-not-allowed data-disabled:text-ink-disabled data-disabled:hover:bg-transparent",
+            focusRingInset,
+            triggerSize[size],
+          )}
+        >
+          <span className="min-w-0 flex-1 wrap-anywhere">{title}</span>
+          {extra && (
+            <span className="flex shrink-0 items-center gap-2 text-sm font-normal text-ink-secondary group-data-disabled/trigger:text-ink-disabled">
+              {extra}
+            </span>
+          )}
+          {/* 加号：两笔叠着，竖的那一笔在展开时转平，和横的重合成减号 */}
+          <span
+            aria-hidden="true"
+            className="relative flex size-4 shrink-0 items-center justify-center text-ink-secondary group-data-disabled/trigger:text-ink-disabled"
+          >
+            <Minus size={16} />
+            <Minus
+              size={16}
+              className="absolute rotate-90 transition-transform duration-(--duration-fast) ease-standard group-data-panel-open/trigger:rotate-0"
+            />
+          </span>
+        </BaseAccordion.Trigger>
+      </BaseAccordion.Header>
+      <BaseAccordion.Panel
+        className={cn(
+          "h-(--accordion-panel-height) overflow-hidden",
+          "transition-[height] duration-(--duration-base) ease-standard",
+          "data-ending-style:h-0 data-starting-style:h-0",
+        )}
+      >
+        <div className={cn("px-4 pb-4", size === "sm" && "text-sm")}>
+          {children}
+        </div>
+      </BaseAccordion.Panel>
+    </BaseAccordion.Item>
+  );
+}

package/src/components/accordion/index.ts

@@ -0,0 +1,8 @@
+export {
+  Accordion,
+  AccordionItem,
+  type AccordionItemProps,
+  type AccordionLevel,
+  type AccordionProps,
+  type AccordionSize,
+} from "./Accordion";

package/src/components/alert/Alert.tsx

@@ -0,0 +1,106 @@
+import type { ComponentProps, ComponentType, ReactNode } from "react";
+import { Close } from "../../icons/Close";
+import type { IconProps } from "../../icons/createIcon";
+import { StatusDanger } from "../../icons/StatusDanger";
+import { StatusInfo } from "../../icons/StatusInfo";
+import { StatusSuccess } from "../../icons/StatusSuccess";
+import { StatusWarning } from "../../icons/StatusWarning";
+import { cn } from "../../lib/cn";
+import { focusRing } from "../../lib/focus-ring";
+
+export type AlertTone = "info" | "success" | "warning" | "danger";
+
+export type AlertProps = Omit<ComponentProps<"div">, "title"> & {
+  /** 色调只点在左缘色条和图标上，底色保持中性。默认 `info` */
+  tone?: AlertTone;
+  /** 加粗的一行标题，可省 */
+  title?: ReactNode;
+  /** 右侧的一个操作，通常是 `text` 按钮 */
+  action?: ReactNode;
+  /** 传了就出现关闭图标。提示条自己不隐藏，由使用方决定 */
+  onClose?: () => void;
+  /** 关闭图标的可访问名称 */
+  closeLabel?: string;
+  /** 替换默认图标；传 `null` 去掉 */
+  icon?: ReactNode;
+};
+
+/* 四种色调用四种不同外形的图标：方框、圆、三角、菱形 */
+const toneIcon: Record<AlertTone, ComponentType<IconProps>> = {
+  info: StatusInfo,
+  success: StatusSuccess,
+  warning: StatusWarning,
+  danger: StatusDanger,
+};
+
+const toneBar: Record<AlertTone, string> = {
+  info: "border-l-info",
+  success: "border-l-success",
+  warning: "border-l-warning",
+  danger: "border-l-danger",
+};
+
+const toneText: Record<AlertTone, string> = {
+  info: "text-info",
+  success: "text-success",
+  warning: "text-warning",
+  danger: "text-danger",
+};
+
+/** 页面内的一条常驻消息。需要用户处理的重要信息用它，不用会消失的轻提示。 */
+export function Alert({
+  tone = "info",
+  title,
+  action,
+  onClose,
+  closeLabel = "关闭",
+  icon,
+  className,
+  children,
+  ...props
+}: AlertProps) {
+  const Icon = toneIcon[tone];
+  const graphic = icon === undefined ? <Icon size={20} /> : icon;
+
+  return (
+    <div
+      role={tone === "danger" || tone === "warning" ? "alert" : "status"}
+      {...props}
+      data-tone={tone}
+      className={cn(
+        "flex items-start gap-3 border border-l-4 border-line bg-surface-raised py-3 pr-3 pl-3 text-sm text-ink",
+        toneBar[tone],
+        className,
+      )}
+    >
+      {graphic !== null && (
+        <span aria-hidden="true" className={cn("shrink-0", toneText[tone])}>
+          {graphic}
+        </span>
+      )}
+      <div className="min-w-0 flex-1 wrap-anywhere">
+        {title && <p className="font-medium">{title}</p>}
+        {children && (
+          <div className={cn(title && "mt-0.5 text-ink-secondary")}>
+            {children}
+          </div>
+        )}
+      </div>
+      {action && <div className="shrink-0">{action}</div>}
+      {onClose && (
+        <button
+          type="button"
+          aria-label={closeLabel}
+          onClick={onClose}
+          className={cn(
+            "-my-1.5 -mr-1 inline-flex size-8 shrink-0 items-center justify-center text-ink-secondary hover:bg-ink/5 hover:text-ink active:bg-ink/10",
+            "transition-colors duration-(--duration-fast) ease-standard",
+            focusRing,
+          )}
+        >
+          <Close size={16} />
+        </button>
+      )}
+    </div>
+  );
+}

package/src/components/alert/index.ts

@@ -0,0 +1 @@
+export { Alert, type AlertProps, type AlertTone } from "./Alert";

package/src/components/avatar/Avatar.tsx

@@ -0,0 +1,89 @@
+import { Avatar as BaseAvatar } from "@base-ui/react/avatar";
+import type { ComponentProps, ReactNode } from "react";
+import { cn } from "../../lib/cn";
+
+export type AvatarSize = "sm" | "md" | "lg" | "xl";
+
+export type AvatarProps = Omit<ComponentProps<"span">, "style"> & {
+  /** 名字。没有图时显示它的首字；也是头像默认的可访问名称 */
+  name?: string;
+  /** 图片地址。没给、没加载出来、加载失败时显示首字 */
+  src?: string;
+  /**
+   * 可访问名称，默认取 `name`。
+   * 旁边已经写了名字时传 `""`：头像变成纯装饰，对读屏隐藏
+   */
+  alt?: string;
+  /** 32 / 40 / 56 / 80px，默认 `md` */
+  size?: AvatarSize;
+  /** 选中：外面一圈行动色的环 */
+  selected?: boolean;
+  /** 没有图时显示的东西，代替首字（比如一个图标） */
+  children?: ReactNode;
+};
+
+const sizeClass: Record<AvatarSize, string> = {
+  sm: "size-8 text-xs",
+  md: "size-10 text-sm",
+  lg: "size-14 text-lg",
+  xl: "size-20 text-2xl",
+};
+
+/*
+ * 选中环：2px 的间隔 + 3px 的行动色 + 1px 的墨线。
+ * 墨线是给亮色页面的——黄色在白底上看不出来
+ */
+export const avatarSelectedRing =
+  "shadow-[0_0_0_2px_var(--ef-surface),0_0_0_5px_var(--ef-action),0_0_0_6px_var(--ef-ink)]";
+
+/** 中文名取第一个字；拉丁字母的名字取前两个词的首字母 */
+export function initialsOf(name: string): string {
+  const words = name.trim().split(/\s+/).filter(Boolean);
+  const first = [...(words[0] ?? "")][0];
+  if (!first) return "";
+  if (!/[a-z]/i.test(first)) return first;
+  const second = words.length > 1 ? ([...words[1]!][0] ?? "") : "";
+  return (first + second).toUpperCase();
+}
+
+/** 头像：代表一个人或一个角色的圆形图。自己不能点。 */
+export function Avatar({
+  name,
+  src,
+  alt = name ?? "",
+  size = "md",
+  selected = false,
+  className,
+  children,
+  ...props
+}: AvatarProps) {
+  const decorative = alt === "";
+
+  return (
+    <BaseAvatar.Root
+      {...props}
+      // 首字和图都只是这个名字的两种画法：整体是一张以名字命名的图
+      {...(decorative
+        ? { "aria-hidden": true }
+        : { role: "img", "aria-label": alt })}
+      data-size={size}
+      data-selected={selected ? "" : undefined}
+      className={cn(
+        "relative inline-flex shrink-0 items-center justify-center overflow-clip rounded-full bg-surface-muted font-medium text-ink-secondary select-none",
+        sizeClass[size],
+        selected && avatarSelectedRing,
+        className,
+      )}
+    >
+      {src && (
+        <BaseAvatar.Image src={src} alt="" className="size-full object-cover" />
+      )}
+      <BaseAvatar.Fallback
+        aria-hidden="true"
+        className="flex size-full items-center justify-center leading-none [&_svg]:size-1/2"
+      >
+        {children ?? (name ? initialsOf(name) : null)}
+      </BaseAvatar.Fallback>
+    </BaseAvatar.Root>
+  );
+}

package/src/components/avatar/AvatarSwitcher.tsx

@@ -0,0 +1,261 @@
+import {
+  Children,
+  createContext,
+  isValidElement,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  type ComponentProps,
+  type ReactNode,
+} from "react";
+import { useControllableState } from "../../hooks/useControllableState";
+import { ChevronDown } from "../../icons/ChevronDown";
+import { ChevronLeft } from "../../icons/ChevronLeft";
+import { ChevronRight } from "../../icons/ChevronRight";
+import { cn } from "../../lib/cn";
+import { IconButton } from "../icon-button/IconButton";
+import { Avatar, type AvatarSize } from "./Avatar";
+
+export type AvatarSwitcherOrientation = "vertical" | "horizontal";
+
+type SwitcherContextValue = {
+  name: string;
+  value: string | null;
+  size: AvatarSize;
+  select: (value: string) => void;
+};
+
+const SwitcherContext = createContext<SwitcherContextValue | null>(null);
+
+export type AvatarSwitcherProps = Omit<
+  ComponentProps<"div">,
+  "aria-label" | "defaultValue" | "onChange"
+> & {
+  /** 选的是什么，比如"人员" */
+  "aria-label": string;
+  /** 选中的那一个的 `value` */
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+  /** 竖排（默认）或横排 */
+  orientation?: AvatarSwitcherOrientation;
+  /** 头像的大小，默认 `lg`（56px） */
+  size?: AvatarSize;
+  /** 翻页钮到头之后绕回另一头。默认到头时禁用 */
+  loop?: boolean;
+  /** 表单字段名：选中的值会随表单提交 */
+  name?: string;
+  previousLabel?: string;
+  nextLabel?: string;
+  /** 直接放 `AvatarSwitcherItem` */
+  children: ReactNode;
+};
+
+type ItemLike = { value?: unknown; disabled?: unknown };
+
+/**
+ * 头像切换：一列圆形头像里选一个，两端各一个圆形翻页钮。
+ * 语义是单选组——方向键换人。头像放不下时给它一个高度（横排时是宽度）上限，
+ * 头像在两个翻页钮之间滚动。
+ */
+export function AvatarSwitcher({
+  value: valueProp,
+  defaultValue,
+  onValueChange,
+  orientation = "vertical",
+  size = "lg",
+  loop = false,
+  name: nameProp,
+  previousLabel = "上一个",
+  nextLabel = "下一个",
+  className,
+  children,
+  ...props
+}: AvatarSwitcherProps) {
+  const generatedName = useId();
+  const name = nameProp ?? generatedName;
+  const vertical = orientation === "vertical";
+  const scrollerRef = useRef<HTMLDivElement>(null);
+
+  const [value, setValue] = useControllableState<string | null>({
+    value: valueProp,
+    defaultValue: defaultValue ?? null,
+    onChange: (next) => {
+      if (next !== null) onValueChange?.(next);
+    },
+  });
+
+  // 翻页钮要知道前后是谁：从子元素上读，所以子元素必须直接是 AvatarSwitcherItem
+  const values = Children.toArray(children).flatMap((child) => {
+    if (!isValidElement<ItemLike>(child)) return [];
+    const { value: itemValue, disabled } = child.props;
+    return typeof itemValue === "string" && !disabled ? [itemValue] : [];
+  });
+  const index = value === null ? -1 : values.indexOf(value);
+  const last = values.length - 1;
+  const step = (delta: 1 | -1) => {
+    if (values.length === 0) return;
+    const next =
+      index === -1
+        ? delta === 1
+          ? 0
+          : last
+        : loop
+          ? (index + delta + values.length) % values.length
+          : Math.min(last, Math.max(0, index + delta));
+    setValue(values[next]!);
+  };
+
+  // 选中的那个滚进来。只动自己的滚动容器，不带着页面一起滚
+  useEffect(() => {
+    const scroller = scrollerRef.current;
+    const item = scroller?.querySelector<HTMLElement>("[data-current]");
+    if (!scroller || !item) return;
+    const start = vertical ? item.offsetTop : item.offsetLeft;
+    const length = vertical ? item.offsetHeight : item.offsetWidth;
+    const view = vertical ? scroller.clientHeight : scroller.clientWidth;
+    const scrolled = vertical ? scroller.scrollTop : scroller.scrollLeft;
+    // 留出选中环和焦点环的位置
+    const margin = 12;
+    let target = scrolled;
+    if (start - margin < scrolled) target = start - margin;
+    else if (start + length + margin > scrolled + view) {
+      target = start + length + margin - view;
+    }
+    if (target !== scrolled) {
+      scroller.scrollTo?.(vertical ? { top: target } : { left: target });
+    }
+  }, [value, vertical]);
+
+  const context = useMemo(
+    () => ({ name, value, size, select: setValue }),
+    [name, value, size, setValue],
+  );
+
+  const Previous = vertical ? ChevronDown : ChevronLeft;
+  const Next = vertical ? ChevronDown : ChevronRight;
+
+  return (
+    <SwitcherContext value={context}>
+      <div
+        {...props}
+        role="radiogroup"
+        aria-orientation={orientation}
+        data-orientation={orientation}
+        className={cn(
+          // 比容器宽的时候缩到容器的宽度：头像在两个翻页钮之间滚动，不撑破页面
+          "inline-flex max-w-full items-center gap-1",
+          vertical ? "flex-col" : "flex-row",
+          className,
+        )}
+      >
+        {/* 翻页钮不占 Tab 顺序：键盘在单选组里用方向键就够了 */}
+        <IconButton
+          variant="floating"
+          size="sm"
+          tabIndex={-1}
+          aria-label={previousLabel}
+          disabled={!loop && index <= 0}
+          onClick={() => step(-1)}
+        >
+          <Previous className={vertical ? "rotate-180" : undefined} />
+        </IconButton>
+        <div
+          ref={scrollerRef}
+          className={cn(
+            // 内边距给选中环和焦点环留位置，否则会被滚动容器裁掉
+            "relative flex min-h-0 min-w-0 flex-1 gap-4 p-3 [scrollbar-width:none]",
+            vertical
+              ? "flex-col overflow-x-hidden overflow-y-auto"
+              : "flex-row overflow-x-auto overflow-y-hidden",
+          )}
+        >
+          {children}
+        </div>
+        <IconButton
+          variant="floating"
+          size="sm"
+          tabIndex={-1}
+          aria-label={nextLabel}
+          disabled={!loop && index >= last}
+          onClick={() => step(1)}
+        >
+          <Next />
+        </IconButton>
+      </div>
+    </SwitcherContext>
+  );
+}
+
+type ItemOwnProps = {
+  value: string;
+  /** 名字：这一项的可访问名称，没有图时显示它的首字 */
+  label: string;
+  /** 头像的图片地址 */
+  src?: string;
+  disabled?: boolean;
+  /** 没有图时显示的东西，代替首字 */
+  children?: ReactNode;
+};
+
+export type AvatarSwitcherItemProps = ItemOwnProps &
+  Omit<ComponentProps<"label">, keyof ItemOwnProps>;
+
+/** 头像切换里的一个头像。 */
+export function AvatarSwitcherItem({
+  value,
+  label,
+  src,
+  disabled = false,
+  className,
+  children,
+  ...props
+}: AvatarSwitcherItemProps) {
+  const context = useContext(SwitcherContext);
+  if (!context) {
+    throw new Error("AvatarSwitcherItem 要放在 AvatarSwitcher 里面");
+  }
+  const checked = context.value === value;
+
+  return (
+    <label
+      {...props}
+      data-current={checked ? "" : undefined}
+      className={cn(
+        "relative flex shrink-0 rounded-full",
+        disabled ? "cursor-not-allowed" : "cursor-pointer",
+        className,
+      )}
+    >
+      <input
+        type="radio"
+        name={context.name}
+        value={value}
+        checked={checked}
+        disabled={disabled}
+        aria-label={label}
+        onChange={() => context.select(value)}
+        className="peer absolute inset-0 size-full cursor-[inherit] appearance-none rounded-full outline-none"
+      />
+      <Avatar
+        name={label}
+        src={src}
+        alt=""
+        size={context.size}
+        selected={checked}
+        className={cn(
+          "pointer-events-none transition-opacity duration-(--duration-fast) ease-standard",
+          // 选中不只靠那一圈黄：其余的退后一档
+          !checked && "opacity-60 peer-hover:opacity-100",
+          disabled && "opacity-30 peer-hover:opacity-30",
+          // 焦点环画在选中环（6px）的外面，隔 1px
+          "peer-focus-visible:outline-2 peer-focus-visible:outline-offset-[7px] peer-focus-visible:outline-focus",
+        )}
+      >
+        {children}
+      </Avatar>
+    </label>
+  );
+}

package/src/components/avatar/index.ts

@@ -0,0 +1,8 @@
+export { Avatar, type AvatarProps, type AvatarSize } from "./Avatar";
+export {
+  AvatarSwitcher,
+  AvatarSwitcherItem,
+  type AvatarSwitcherItemProps,
+  type AvatarSwitcherOrientation,
+  type AvatarSwitcherProps,
+} from "./AvatarSwitcher";