@endfield-ui/react 0.0.0-stage → 0.2.0

package/src/components/date-picker/DatePicker.tsx

@@ -0,0 +1,182 @@
+import type { ReactNode, Ref } from "react";
+import { useControllableState } from "../../hooks/useControllableState";
+import { clampDate, today as localToday } from "../../lib/date";
+import { Calendar, type CalendarProps } from "../calendar/Calendar";
+import { useFieldControl } from "../field/Field";
+import type { ControlSize, ControlVariant } from "../input/control-box";
+import { DateField, dateFooterButton, dottedDate } from "./DateField";
+
+export type DatePickerSize = ControlSize;
+export type DatePickerVariant = ControlVariant;
+
+export type DatePickerProps = Pick<
+  CalendarProps,
+  "min" | "max" | "isDateDisabled" | "weekStartsOn" | "locale" | "today"
+> & {
+  /** 选中的那一天，`YYYY-MM-DD`；没选是 `null` */
+  value?: string | null;
+  defaultValue?: string | null;
+  /** 清除之后拿到的是 `null` */
+  onValueChange?: (value: string | null) => void;
+  /** 没选时显示的提示 */
+  placeholder?: ReactNode;
+  /** 表单字段名：选中的值（`YYYY-MM-DD`）会随表单提交 */
+  name?: string;
+  /**
+   * 外框的画法，和输入框相同：
+   * - `sunken` 凹陷的底 + 一条底边线，默认；
+   * - `outline` 四边描边，放在凹陷底色的区域里时用。
+   */
+  variant?: DatePickerVariant;
+  /** 32 / 40 / 56px 高 */
+  size?: DatePickerSize;
+  /** 日期怎么写。默认 `2026.10.09` */
+  format?: (date: string) => ReactNode;
+  /** 错误态。放在 `Field` 里时跟随它的 `error` */
+  invalid?: boolean;
+  disabled?: boolean;
+  /** 必填：面板里没有"清除" */
+  required?: boolean;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** 面板的可访问名称 */
+  panelLabel?: string;
+  todayLabel?: string;
+  clearLabel?: string;
+  id?: string;
+  "aria-label"?: string;
+  "aria-describedby"?: string;
+  /** 给外框 */
+  className?: string;
+  /** 给触发按钮 */
+  ref?: Ref<HTMLButtonElement>;
+};
+
+/**
+ * 日期选择：一个字段，点开是一块带月历的面板。值是 `YYYY-MM-DD` 的字符串。
+ * 触发器是按钮，不能打字——要打字用原生的 `<Input type="date">`。
+ * 每个日期选择都要有标签：放进 `Field`，或者自己传 `aria-label`。
+ *
+ * 选一段（起止日期）用 `DateRangePicker`。
+ */
+export function DatePicker({
+  value: valueProp,
+  defaultValue = null,
+  onValueChange,
+  placeholder = "选择日期",
+  name,
+  variant = "sunken",
+  size = "md",
+  format = dottedDate,
+  invalid: invalidProp,
+  disabled: disabledProp,
+  required: requiredProp,
+  open: openProp,
+  defaultOpen = false,
+  onOpenChange,
+  panelLabel = "选择日期",
+  todayLabel = "今天",
+  clearLabel = "清除",
+  min,
+  max,
+  isDateDisabled,
+  weekStartsOn,
+  locale,
+  today: todayProp,
+  id: idProp,
+  "aria-label": ariaLabel,
+  "aria-describedby": describedByProp,
+  className,
+  ref,
+}: DatePickerProps) {
+  const { id, disabled, required, invalid, ...field } = useFieldControl({
+    id: idProp,
+    disabled: disabledProp,
+    required: requiredProp,
+    invalid: invalidProp,
+    "aria-describedby": describedByProp,
+  });
+
+  const [value, setValue] = useControllableState<string | null>({
+    value: valueProp,
+    defaultValue,
+    onChange: onValueChange,
+  });
+  const [open, setOpen] = useControllableState({
+    value: openProp,
+    defaultValue: defaultOpen,
+    onChange: onOpenChange,
+  });
+
+  const pick = (next: string | null) => {
+    setValue(next);
+    setOpen(false);
+  };
+
+  const todayDate = todayProp ?? localToday();
+  const todayUnavailable =
+    clampDate(todayDate, min, max) !== todayDate ||
+    (isDateDisabled?.(todayDate) ?? false);
+
+  return (
+    <DateField
+      ref={ref}
+      id={id}
+      display={value === null ? null : format(value)}
+      placeholder={placeholder}
+      variant={variant}
+      size={size}
+      invalid={invalid}
+      disabled={disabled}
+      required={required}
+      open={open}
+      onOpenChange={setOpen}
+      panelLabel={panelLabel}
+      aria-label={ariaLabel}
+      aria-describedby={field["aria-describedby"]}
+      className={className}
+      fields={
+        name !== undefined && (
+          <input
+            type="hidden"
+            name={name}
+            value={value ?? ""}
+            disabled={disabled}
+          />
+        )
+      }
+    >
+      <Calendar
+        value={value}
+        onValueChange={pick}
+        min={min}
+        max={max}
+        isDateDisabled={isDateDisabled}
+        weekStartsOn={weekStartsOn}
+        locale={locale}
+        today={todayProp}
+      />
+      <div className="flex items-center justify-between border-t border-line pt-2">
+        <button
+          type="button"
+          disabled={todayUnavailable}
+          onClick={() => pick(todayDate)}
+          className={dateFooterButton}
+        >
+          {todayLabel}
+        </button>
+        {!required && (
+          <button
+            type="button"
+            disabled={value === null}
+            onClick={() => pick(null)}
+            className={dateFooterButton}
+          >
+            {clearLabel}
+          </button>
+        )}
+      </div>
+    </DateField>
+  );
+}

package/src/components/date-picker/DateRangePicker.tsx

@@ -0,0 +1,203 @@
+import type { ReactNode, Ref } from "react";
+import { useControllableState } from "../../hooks/useControllableState";
+import {
+  Calendar,
+  type CalendarProps,
+  type DateRange,
+} from "../calendar/Calendar";
+import { useFieldControl } from "../field/Field";
+import type { ControlSize, ControlVariant } from "../input/control-box";
+import { DateField, dateFooterButton, dottedDate } from "./DateField";
+
+export type DateRangePickerProps = Pick<
+  CalendarProps,
+  "min" | "max" | "isDateDisabled" | "weekStartsOn" | "locale" | "today"
+> & {
+  /** 选中的那一段，`[起, 止]`，两头都包含；没选是 `null` */
+  value?: DateRange | null;
+  defaultValue?: DateRange | null;
+  /** 一段选完才触发；清除之后拿到的是 `null` */
+  onValueChange?: (value: DateRange | null) => void;
+  /** 没选时显示的提示 */
+  placeholder?: ReactNode;
+  /** 表单字段名：起始日和结束日各一个，值是 `YYYY-MM-DD` */
+  startName?: string;
+  endName?: string;
+  /**
+   * 外框的画法，和输入框相同：
+   * - `sunken` 凹陷的底 + 一条底边线，默认；
+   * - `outline` 四边描边，放在凹陷底色的区域里时用。
+   */
+  variant?: ControlVariant;
+  /** 32 / 40 / 56px 高 */
+  size?: ControlSize;
+  /** 每个日期怎么写。默认 `2026.10.09` */
+  format?: (date: string) => ReactNode;
+  /** 错误态。放在 `Field` 里时跟随它的 `error` */
+  invalid?: boolean;
+  disabled?: boolean;
+  /** 必填：面板里没有"清除" */
+  required?: boolean;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** 面板的可访问名称 */
+  panelLabel?: string;
+  /** 面板底下那句提示 */
+  hint?: ReactNode;
+  clearLabel?: string;
+  /** 读屏在两端那两天的名称后面听到的词 */
+  startLabel?: string;
+  endLabel?: string;
+  id?: string;
+  "aria-label"?: string;
+  "aria-describedby"?: string;
+  /** 给外框 */
+  className?: string;
+  /** 给触发按钮 */
+  ref?: Ref<HTMLButtonElement>;
+};
+
+/**
+ * 日期范围：一个字段，点开是一块带月历的面板，点两下选出起止两天。
+ * 值是 `[起, 止]`，两头都包含；结束日选完面板才关。
+ * 每个字段都要有标签：放进 `Field`，或者自己传 `aria-label`。
+ */
+export function DateRangePicker({
+  value: valueProp,
+  defaultValue = null,
+  onValueChange,
+  placeholder = "选择起止日期",
+  startName,
+  endName,
+  variant = "sunken",
+  size = "md",
+  format = dottedDate,
+  invalid: invalidProp,
+  disabled: disabledProp,
+  required: requiredProp,
+  open: openProp,
+  defaultOpen = false,
+  onOpenChange,
+  panelLabel = "选择起止日期",
+  hint = "先选起始日，再选结束日",
+  clearLabel = "清除",
+  startLabel,
+  endLabel,
+  min,
+  max,
+  isDateDisabled,
+  weekStartsOn,
+  locale,
+  today,
+  id: idProp,
+  "aria-label": ariaLabel,
+  "aria-describedby": describedByProp,
+  className,
+  ref,
+}: DateRangePickerProps) {
+  const { id, disabled, required, invalid, ...field } = useFieldControl({
+    id: idProp,
+    disabled: disabledProp,
+    required: requiredProp,
+    invalid: invalidProp,
+    "aria-describedby": describedByProp,
+  });
+
+  const [value, setValue] = useControllableState<DateRange | null>({
+    value: valueProp,
+    defaultValue,
+    onChange: onValueChange,
+  });
+  const [open, setOpen] = useControllableState({
+    value: openProp,
+    defaultValue: defaultOpen,
+    onChange: onOpenChange,
+  });
+
+  const pick = (next: DateRange | null) => {
+    setValue(next);
+    setOpen(false);
+  };
+
+  return (
+    <DateField
+      ref={ref}
+      id={id}
+      display={
+        value === null ? null : value[0] === value[1] ? (
+          // 起止是同一天：只写一个
+          format(value[0])
+        ) : (
+          <>
+            {format(value[0])}
+            <span aria-hidden="true" className="mx-1.5 text-ink-tertiary">
+              –
+            </span>
+            <span className="sr-only">至</span>
+            {format(value[1])}
+          </>
+        )
+      }
+      placeholder={placeholder}
+      variant={variant}
+      size={size}
+      invalid={invalid}
+      disabled={disabled}
+      required={required}
+      open={open}
+      onOpenChange={setOpen}
+      panelLabel={panelLabel}
+      aria-label={ariaLabel}
+      aria-describedby={field["aria-describedby"]}
+      className={className}
+      fields={
+        <>
+          {startName !== undefined && (
+            <input
+              type="hidden"
+              name={startName}
+              value={value?.[0] ?? ""}
+              disabled={disabled}
+            />
+          )}
+          {endName !== undefined && (
+            <input
+              type="hidden"
+              name={endName}
+              value={value?.[1] ?? ""}
+              disabled={disabled}
+            />
+          )}
+        </>
+      }
+    >
+      <Calendar
+        range
+        value={value}
+        onValueChange={pick}
+        min={min}
+        max={max}
+        isDateDisabled={isDateDisabled}
+        weekStartsOn={weekStartsOn}
+        locale={locale}
+        today={today}
+        startLabel={startLabel}
+        endLabel={endLabel}
+      />
+      <div className="flex items-center justify-between gap-3 border-t border-line pt-2">
+        <p className="px-2 text-xs text-ink-secondary">{hint}</p>
+        {!required && (
+          <button
+            type="button"
+            disabled={value === null}
+            onClick={() => pick(null)}
+            className={dateFooterButton}
+          >
+            {clearLabel}
+          </button>
+        )}
+      </div>
+    </DateField>
+  );
+}

package/src/components/date-picker/index.ts

@@ -0,0 +1,7 @@
+export {
+  DatePicker,
+  type DatePickerProps,
+  type DatePickerSize,
+  type DatePickerVariant,
+} from "./DatePicker";
+export { DateRangePicker, type DateRangePickerProps } from "./DateRangePicker";

package/src/components/dialog/Dialog.tsx

@@ -0,0 +1,203 @@
+import { AlertDialog as BaseAlertDialog } from "@base-ui/react/alert-dialog";
+import { Dialog as BaseDialog } from "@base-ui/react/dialog";
+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 { Texture } from "../texture/Texture";
+import { firstFocusableIn } from "./initial-focus";
+import {
+  overlayBackdrop,
+  overlayClose,
+  overlayHeader,
+  overlaySurface,
+} from "./overlay-style";
+
+export type DialogSize = "sm" | "md" | "lg";
+
+type PopupProps = ComponentProps<typeof BaseDialog.Popup>;
+
+export type DialogProps = 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;
+  /** 最大宽度 480 / 640 / 1040px，窄屏上通宽。默认 `md` */
+  size?: DialogSize;
+  /**
+   * 需要用户明确回应的确认（破坏性操作）：角色是 `alertdialog`，点遮罩不关。
+   * `Esc` 和关闭图标仍然可用。
+   */
+  alert?: boolean;
+  /** 标题下方加一排小方点。纯装饰 */
+  ornament?: boolean;
+  /**
+   * 左下角的线稿，纯装饰。本库不带线稿：传自己的原创图形，
+   * 用 `currentColor` 画会跟着取低对比的墨色。高 48px
+   */
+  cornerArt?: ReactNode;
+  /** 关闭图标的可访问名称 */
+  closeLabel?: string;
+  /** 打开时焦点落在哪。默认是内容区里第一个可聚焦的元素：第一个字段，或者行动区的第一个按钮 */
+  initialFocus?: PopupProps["initialFocus"];
+  /** 关闭后焦点回到哪。默认是触发按钮 */
+  finalFocus?: PopupProps["finalFocus"];
+  /** 给弹窗本身 */
+  className?: string;
+  children?: ReactNode;
+};
+
+const ORNAMENT_DOTS = [0, 1, 2, 3, 4, 5];
+
+const sizeClass: Record<DialogSize, string> = {
+  sm: "max-w-[30rem]",
+  md: "max-w-[40rem]",
+  lg: "max-w-[65rem]",
+};
+
+/**
+ * 弹窗：深色斜纹标题带 + 点阵底的内容区。打开时焦点移入并被限制在内，
+ * 关闭后回到触发按钮；背景不可滚动、不可交互。不要弹窗套弹窗。
+ */
+export function Dialog({
+  trigger,
+  open,
+  defaultOpen,
+  onOpenChange,
+  title,
+  description,
+  footer,
+  size = "md",
+  alert = false,
+  ornament = false,
+  cornerArt,
+  closeLabel = "关闭",
+  initialFocus,
+  finalFocus,
+  className,
+  children,
+  ...props
+}: DialogProps) {
+  const { anchorRef, portalRef } = usePortalScope();
+  const contentRef = useRef<HTMLDivElement>(null);
+  // 两者除了 Root 与 Trigger 是同一批部件；确认弹窗的 Root 把角色和"点遮罩不关"定死了
+  const Base = (alert ? BaseAlertDialog : BaseDialog) as typeof BaseDialog;
+
+  return (
+    <Base.Root
+      open={open}
+      defaultOpen={defaultOpen}
+      onOpenChange={onOpenChange && ((next) => onOpenChange(next))}
+    >
+      {trigger && <Base.Trigger ref={anchorRef} render={trigger} />}
+      <Base.Portal ref={portalRef}>
+        <Base.Backdrop className={overlayBackdrop} />
+        <Base.Viewport className="fixed inset-0 z-(--z-overlay) flex items-center justify-center overflow-hidden p-4">
+          <Base.Popup
+            {...props}
+            initialFocus={initialFocus ?? firstFocusableIn(contentRef)}
+            finalFocus={finalFocus}
+            data-size={size}
+            className={cn(
+              overlaySurface,
+              "relative flex max-h-full min-h-0 w-full flex-col",
+              "transition-[scale,opacity] duration-(--duration-base) ease-exit",
+              "data-ending-style:scale-95 data-ending-style:opacity-0 data-starting-style:scale-95 data-starting-style:opacity-0",
+              sizeClass[size],
+              className,
+            )}
+          >
+            <div
+              data-theme="dark"
+              className={cn(overlayHeader, "min-h-16 justify-center px-12")}
+            >
+              <div className="flex flex-col items-center gap-1.5 py-3">
+                {/* 全站的标题大多是粗体，弹窗标题是例外：深底白字本身已经够醒目 */}
+                <Base.Title className="text-center text-xl font-normal wrap-anywhere">
+                  {title}
+                </Base.Title>
+                {ornament && (
+                  <span
+                    aria-hidden="true"
+                    data-ornament=""
+                    className="flex gap-1"
+                  >
+                    {ORNAMENT_DOTS.map((dot) => (
+                      <span key={dot} className="size-1 bg-ink/50" />
+                    ))}
+                  </span>
+                )}
+              </div>
+              <Base.Close aria-label={closeLabel} className={overlayClose}>
+                <Close size={24} />
+              </Base.Close>
+            </div>
+
+            <div
+              ref={contentRef}
+              className="relative flex min-h-0 flex-auto flex-col"
+            >
+              <Texture />
+              {/* 正文垫一层实色底，点阵只在四周露出一圈；内容过长时只有这一块滚动 */}
+              <div className="relative min-h-0 flex-auto overflow-y-auto overscroll-contain p-4">
+                <div className="bg-surface-raised p-5 wrap-anywhere">
+                  {description && (
+                    <Base.Description
+                      className={cn(
+                        "text-ink-secondary",
+                        children !== undefined && "mb-4",
+                      )}
+                    >
+                      {description}
+                    </Base.Description>
+                  )}
+                  {children}
+                </div>
+                {cornerArt && (
+                  // 排在正文那块实色底的下面、压在点阵上：不压正文，跟着内容一起滚
+                  <div
+                    aria-hidden="true"
+                    data-corner-art=""
+                    className="pointer-events-none mt-3 flex h-12 items-end text-ink-tertiary [&_svg]:h-full [&_svg]:w-auto"
+                  >
+                    {cornerArt}
+                  </div>
+                )}
+              </div>
+              {footer && (
+                <div className="relative flex shrink-0 flex-wrap justify-end gap-3 border-t border-line bg-surface-raised px-5 py-4">
+                  {footer}
+                </div>
+              )}
+            </div>
+          </Base.Popup>
+        </Base.Viewport>
+      </Base.Portal>
+    </Base.Root>
+  );
+}
+
+export type DialogCloseProps = {
+  /** 点了就关掉弹窗的按钮，比如"取消" */
+  children: ReactElement<Record<string, unknown>>;
+};
+
+/** 包住行动区里"点了就关"的按钮。弹窗和抽屉里都能用。 */
+export function DialogClose({ children }: DialogCloseProps) {
+  return <BaseDialog.Close render={children} />;
+}

package/src/components/dialog/index.ts

@@ -0,0 +1,7 @@
+export {
+  Dialog,
+  DialogClose,
+  type DialogCloseProps,
+  type DialogProps,
+  type DialogSize,
+} from "./Dialog";

package/src/components/dialog/initial-focus.ts

@@ -0,0 +1,19 @@
+import type { RefObject } from "react";
+
+const FOCUSABLE = [
+  "a[href]",
+  "button:not([disabled])",
+  'input:not([disabled]):not([type="hidden"])',
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  '[tabindex]:not([tabindex="-1"])',
+].join(",");
+
+/**
+ * 弹窗与抽屉打开时焦点落在哪：内容区里第一个能聚焦的元素——表单的第一个字段，
+ * 或者行动区的第一个按钮（约定是"取消"，破坏性确认因此不会一回车就执行）。
+ * 内容区里没有时返回 `true`，交还给默认行为（标题带里的关闭按钮）。
+ */
+export function firstFocusableIn(content: RefObject<HTMLElement | null>) {
+  return () => content.current?.querySelector<HTMLElement>(FOCUSABLE) ?? true;
+}

package/src/components/dialog/overlay-style.ts

@@ -0,0 +1,28 @@
+import { focusRingInset } from "../../lib/focus-ring";
+
+/*
+ * 弹窗与抽屉共用的外观：遮罩、深色标题带、关闭按钮。
+ * 标题带在亮、暗两个主题下都是深色，所以它自己是一个 `data-theme="dark"` 的
+ * 局部主题：里面的文字、关闭图标、焦点环都按深色底取值，不用逐个写死。
+ */
+
+/** 遮罩：纯黑半透明（亮 50% / 暗 70%），不模糊、不带色彩 */
+export const overlayBackdrop =
+  "fixed inset-0 z-(--z-overlay) bg-scrim transition-opacity duration-(--duration-fast) ease-standard data-ending-style:opacity-0 data-starting-style:opacity-0";
+
+/** 标题带的底：深色 + 斜纹。用的时候在元素上加 `data-theme="dark"` */
+export const overlayHeader =
+  "hatch relative flex shrink-0 items-center border-b border-line bg-surface-raised text-ink";
+
+/** 关闭按钮：24px 的叉、40px 的点击区，悬停转 90° */
+export const overlayClose = [
+  "absolute top-1/2 right-1 inline-flex size-10 -translate-y-1/2 items-center justify-center text-ink",
+  // 按下的浅灰是官网实测值的近似，只出现在深色带上
+  "active:text-neutral-300",
+  "[&_svg]:transition-transform [&_svg]:duration-(--duration-base) [&_svg]:ease-standard hover:[&_svg]:rotate-90",
+  focusRingInset,
+].join(" ");
+
+/** 浮层的面：直角、中性底、环境阴影。高对比模式下阴影不显示，补一圈边线 */
+export const overlaySurface =
+  "bg-surface-raised text-ink shadow-lg outline-none forced-colors:border";