@endfield-ui/react 0.0.0-stage → 0.2.0

package/src/components/calendar/Calendar.tsx

@@ -0,0 +1,443 @@
+import {
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentProps,
+  type KeyboardEvent,
+} from "react";
+import { useControllableState } from "../../hooks/useControllableState";
+import { ChevronLeft } from "../../icons/ChevronLeft";
+import { ChevronRight } from "../../icons/ChevronRight";
+import { cn } from "../../lib/cn";
+import {
+  addDays,
+  addMonths,
+  addMonthsToMonth,
+  clampDate,
+  dateParts,
+  monthGrid,
+  monthOf,
+  orderDates,
+  startOfWeek,
+  toDateObject,
+  today as localToday,
+} from "../../lib/date";
+import { focusRingInset } from "../../lib/focus-ring";
+import { IconButton } from "../icon-button/IconButton";
+
+/** 一段日期：`[起, 止]`，两头都包含。只有一天时两个一样 */
+export type DateRange = [start: string, end: string];
+
+type CalendarBaseProps = Omit<
+  ComponentProps<"div">,
+  "defaultValue" | "onChange"
+> & {
+  /** 现在显示的月份，`YYYY-MM`。不传时跟着选中的那一天（没选就是今天） */
+  month?: string;
+  defaultMonth?: string;
+  onMonthChange?: (month: string) => void;
+  /** 能选的最早一天 */
+  min?: string;
+  /** 能选的最晚一天 */
+  max?: string;
+  /** 返回真的日子不可选（比如周末、已经约满的日子） */
+  isDateDisabled?: (date: string) => boolean;
+  /** 一周从哪天开始：1 是星期一（默认），0 是星期日 */
+  weekStartsOn?: 0 | 1;
+  /** 月份标题、星期、读屏听到的日期名称按它走。默认 `zh-CN` */
+  locale?: string;
+  /** 哪一天算"今天"。默认取本地时间；服务端渲染或要一个固定的今天时自己传 */
+  today?: string;
+  previousLabel?: string;
+  nextLabel?: string;
+};
+
+export type CalendarSingleProps = CalendarBaseProps & {
+  range?: false;
+  /** 选中的那一天，`YYYY-MM-DD`；没选是 `null` */
+  value?: string | null;
+  defaultValue?: string | null;
+  onValueChange?: (value: string) => void;
+  startLabel?: never;
+  endLabel?: never;
+  pendingLabel?: never;
+};
+
+export type CalendarRangeProps = CalendarBaseProps & {
+  /** 选一段：点两下，第一下定起始日，第二下定结束日 */
+  range: true;
+  /** 选中的那一段，`[起, 止]`；没选是 `null` */
+  value?: DateRange | null;
+  defaultValue?: DateRange | null;
+  /** 只在一段选完时触发；后点的那天更早也会排成先后 */
+  onValueChange?: (value: DateRange) => void;
+  /** 读屏在两端那两天的名称后面听到的词，默认"起始日""结束日" */
+  startLabel?: string;
+  endLabel?: string;
+  /** 起始日定了之后的那句播报，默认"再选结束日" */
+  pendingLabel?: string;
+};
+
+export type CalendarProps = CalendarSingleProps | CalendarRangeProps;
+
+type Selection = string | DateRange | null;
+
+const UTC = { timeZone: "UTC" } as const;
+
+/** 值有没有变：一段日期每次都是新数组，要按内容比 */
+const keyOf = (value: Selection) =>
+  value === null ? "" : typeof value === "string" ? value : value.join("/");
+
+/** 键盘把焦点挪到哪一天。返回 `null` 是这个键不归月历管 */
+function moveFocus(
+  event: KeyboardEvent,
+  from: string,
+  weekStartsOn: 0 | 1,
+): string | null {
+  switch (event.key) {
+    case "ArrowLeft":
+      return addDays(from, -1);
+    case "ArrowRight":
+      return addDays(from, 1);
+    case "ArrowUp":
+      return addDays(from, -7);
+    case "ArrowDown":
+      return addDays(from, 7);
+    case "Home":
+      return startOfWeek(from, weekStartsOn);
+    case "End":
+      return addDays(startOfWeek(from, weekStartsOn), 6);
+    case "PageUp":
+      return addMonths(from, event.shiftKey ? -12 : -1);
+    case "PageDown":
+      return addMonths(from, event.shiftKey ? 12 : 1);
+    default:
+      return null;
+  }
+}
+
+/**
+ * 月历：选一天；加 `range` 是选一段。日期是 `YYYY-MM-DD` 的字符串。
+ * 要一个带面板的字段用 `DatePicker` / `DateRangePicker`。
+ */
+export function Calendar({
+  range = false,
+  value: valueProp,
+  defaultValue = null,
+  onValueChange,
+  month: monthProp,
+  defaultMonth,
+  onMonthChange,
+  min,
+  max,
+  isDateDisabled,
+  weekStartsOn = 1,
+  locale = "zh-CN",
+  today: todayProp,
+  previousLabel = "上个月",
+  nextLabel = "下个月",
+  startLabel = "起始日",
+  endLabel = "结束日",
+  pendingLabel = "再选结束日",
+  className,
+  ...props
+}: CalendarProps) {
+  const titleId = useId();
+  const gridRef = useRef<HTMLTableSectionElement>(null);
+  const [today] = useState(() => todayProp ?? localToday());
+  const currentDay = todayProp ?? today;
+
+  const [value, setValue] = useControllableState<Selection>({
+    value: valueProp,
+    defaultValue,
+    onChange: (next) => {
+      if (next !== null) {
+        (onValueChange as ((value: string | DateRange) => void) | undefined)?.(
+          next,
+        );
+      }
+    },
+  });
+  // 一段的两头；选一天时两头是同一天
+  const committed: DateRange | null =
+    value === null ? null : typeof value === "string" ? [value, value] : value;
+
+  // 选一段时：起始日定了、结束日还没定
+  const [anchor, setAnchor] = useState<string | null>(null);
+  // 指针停在哪一天（预览用）；键盘的位置在 focused 里
+  const [hovered, setHovered] = useState<string | null>(null);
+
+  // 键盘停在哪一天：整个网格只有它能被 Tab 停到
+  const [focused, setFocused] = useState(() =>
+    clampDate(committed?.[0] ?? currentDay, min, max),
+  );
+  const [month, setMonth] = useControllableState({
+    value: monthProp,
+    defaultValue: defaultMonth ?? monthOf(focused),
+    onChange: onMonthChange,
+  });
+  // 键盘移动之后要把焦点交给新的那一格；鼠标翻月不抢焦点
+  const pendingFocus = useRef(false);
+
+  // 从外面换了值（受控）：月历跟过去。自己选出来的不算——刚点的那天已经在眼前了
+  const valueKey = keyOf(value);
+  const lastKey = useRef(valueKey);
+  const start = committed?.[0] ?? null;
+  useEffect(() => {
+    if (valueKey === lastKey.current) return;
+    lastKey.current = valueKey;
+    setAnchor(null);
+    if (start === null) return;
+    setFocused(start);
+    setMonth(monthOf(start));
+  }, [valueKey, start, setMonth]);
+
+  useEffect(() => {
+    if (!pendingFocus.current) return;
+    pendingFocus.current = false;
+    gridRef.current
+      ?.querySelector<HTMLElement>(`[data-date="${focused}"]`)
+      ?.focus();
+  }, [focused, month]);
+
+  const weeks = useMemo(
+    () => monthGrid(month, weekStartsOn),
+    [month, weekStartsOn],
+  );
+
+  const formats = useMemo(
+    () => ({
+      title: new Intl.DateTimeFormat(locale, {
+        ...UTC,
+        year: "numeric",
+        month: "long",
+      }),
+      weekdayShort: new Intl.DateTimeFormat(locale, {
+        ...UTC,
+        weekday: "narrow",
+      }),
+      weekdayLong: new Intl.DateTimeFormat(locale, { ...UTC, weekday: "long" }),
+      day: new Intl.DateTimeFormat(locale, { ...UTC, dateStyle: "full" }),
+    }),
+    [locale],
+  );
+
+  const unavailable = (date: string) =>
+    (min !== undefined && date < min) ||
+    (max !== undefined && date > max) ||
+    (isDateDisabled?.(date) ?? false);
+
+  const focusDate = (date: string) => {
+    const next = clampDate(date, min, max);
+    pendingFocus.current = true;
+    setFocused(next);
+    if (monthOf(next) !== month) setMonth(monthOf(next));
+  };
+
+  const commit = (next: string | DateRange) => {
+    lastKey.current = keyOf(next);
+    setValue(next);
+  };
+
+  const select = (date: string) => {
+    if (unavailable(date)) return;
+    setFocused(date);
+    if (monthOf(date) !== month) setMonth(monthOf(date));
+    if (!range) {
+      commit(date);
+    } else if (anchor === null) {
+      setAnchor(date);
+    } else {
+      setAnchor(null);
+      commit(orderDates(anchor, date));
+    }
+  };
+
+  const turn = (months: number) => {
+    const next = addMonthsToMonth(month, months);
+    setMonth(next);
+    // 停靠点跟到新的月份里同一天（没有那一天就落在月末），否则 Tab 进不来
+    setFocused(clampDate(addMonths(focused, months), min, max));
+  };
+
+  const firstOfMonth = `${month}-01`;
+  const previousDisabled = min !== undefined && addDays(firstOfMonth, -1) < min;
+  const nextDisabled = max !== undefined && addMonths(firstOfMonth, 1) > max;
+
+  // 停靠点不在眼前这个月（鼠标翻了月）时，借给这个月的第一天
+  const tabStop = weeks.flat().includes(focused) ? focused : firstOfMonth;
+
+  // 现在画的是哪一段：起始日定了就只画它（原来那一段先让开），预览到指针或键盘所在的那天
+  const shown: DateRange | null =
+    anchor !== null ? [anchor, anchor] : committed;
+  const preview =
+    anchor !== null ? orderDates(anchor, hovered ?? focused) : null;
+
+  return (
+    <div
+      {...props}
+      data-month={month}
+      data-range={range ? "" : undefined}
+      data-pending={anchor !== null ? "" : undefined}
+      className={cn("inline-flex flex-col gap-1 text-ink", className)}
+    >
+      <div className="flex items-center justify-between gap-2">
+        <IconButton
+          size="sm"
+          aria-label={previousLabel}
+          disabled={previousDisabled}
+          onClick={() => turn(-1)}
+        >
+          <ChevronLeft />
+        </IconButton>
+        <div
+          id={titleId}
+          aria-live="polite"
+          className="text-sm font-bold tabular-nums"
+        >
+          {formats.title.format(toDateObject(firstOfMonth))}
+        </div>
+        <IconButton
+          size="sm"
+          aria-label={nextLabel}
+          disabled={nextDisabled}
+          onClick={() => turn(1)}
+        >
+          <ChevronRight />
+        </IconButton>
+      </div>
+
+      <table
+        role="grid"
+        aria-labelledby={titleId}
+        aria-multiselectable={range || undefined}
+        className="border-separate border-spacing-0"
+      >
+        <thead>
+          <tr>
+            {weeks[0]!.map((date) => (
+              <th
+                key={date}
+                scope="col"
+                abbr={formats.weekdayLong.format(toDateObject(date))}
+                className="h-8 w-10 text-xs font-normal text-ink-tertiary"
+              >
+                {formats.weekdayShort.format(toDateObject(date))}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody
+          ref={gridRef}
+          onPointerLeave={() => setHovered(null)}
+          onKeyDown={(event) => {
+            // 起始日定了之后按 Esc：取消这一次，回到原来的那一段
+            if (event.key === "Escape" && anchor !== null) {
+              setAnchor(null);
+              return;
+            }
+            const next = moveFocus(event, focused, weekStartsOn);
+            if (next === null) return;
+            event.preventDefault();
+            // 键盘动了，预览跟着键盘走
+            setHovered(null);
+            focusDate(next);
+          }}
+        >
+          {weeks.map((week) => (
+            <tr key={week[0]}>
+              {week.map((date) => {
+                const isStart = shown !== null && date === shown[0];
+                const isEnd = shown !== null && date === shown[1];
+                const endpoint = isStart || isEnd;
+                const between =
+                  shown !== null && date > shown[0] && date < shown[1];
+                const previewing =
+                  preview !== null &&
+                  !endpoint &&
+                  date >= preview[0] &&
+                  date <= preview[1];
+                const isToday = date === currentDay;
+                const outside = monthOf(date) !== month;
+                const disabled = unavailable(date);
+                const name = [
+                  formats.day.format(toDateObject(date)),
+                  range && isStart && startLabel,
+                  range && isEnd && endLabel,
+                ]
+                  .filter(Boolean)
+                  .join("，");
+                return (
+                  <td
+                    key={date}
+                    role="gridcell"
+                    aria-selected={endpoint || between}
+                    className="p-0"
+                  >
+                    <button
+                      type="button"
+                      data-date={date}
+                      data-today={isToday ? "" : undefined}
+                      data-outside={outside ? "" : undefined}
+                      data-range-start={range && isStart ? "" : undefined}
+                      data-range-end={range && isEnd ? "" : undefined}
+                      data-in-range={between ? "" : undefined}
+                      data-preview={previewing ? "" : undefined}
+                      tabIndex={date === tabStop ? 0 : -1}
+                      aria-label={name}
+                      aria-current={isToday ? "date" : undefined}
+                      // 不可选的日子仍然走得到：读屏要能读到它，只是选不了
+                      aria-disabled={disabled || undefined}
+                      onClick={() => select(date)}
+                      onFocus={() => setFocused(date)}
+                      onPointerEnter={
+                        range ? () => setHovered(date) : undefined
+                      }
+                      className={cn(
+                        "relative flex size-10 items-center justify-center font-tech text-sm tabular-nums",
+                        "transition-colors duration-(--duration-fast) ease-standard",
+                        focusRingInset,
+                        endpoint
+                          ? "bg-surface-inverse font-bold text-ink-inverse"
+                          : [
+                              // 一段的中间是连着的浅带；还没定结束日时是更浅的预览
+                              between ? "bg-ink/10" : previewing && "bg-ink/5",
+                              disabled
+                                ? "cursor-not-allowed text-ink-disabled line-through"
+                                : [
+                                    outside ? "text-ink-tertiary" : "text-ink",
+                                    between
+                                      ? "hover:bg-ink/15"
+                                      : "hover:bg-ink/5",
+                                  ],
+                            ],
+                        // 今天：数字下面一条短线，不只是换个字色
+                        isToday &&
+                          "after:absolute after:bottom-1.5 after:left-1/2 after:h-0.5 after:w-3 after:-translate-x-1/2 after:content-['']",
+                        isToday &&
+                          (endpoint
+                            ? "after:bg-accent-ink-inverse"
+                            : "after:bg-accent-ink"),
+                      )}
+                    >
+                      {dateParts(date).day}
+                    </button>
+                  </td>
+                );
+              })}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+      {range && (
+        // 起始日定了之后告诉读屏下一步做什么；看得见的人有那块实心的起始日和跟着走的浅带
+        <div aria-live="polite" className="sr-only">
+          {anchor !== null &&
+            `${formats.day.format(toDateObject(anchor))}，${startLabel}。${pendingLabel}`}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/calendar/index.ts

@@ -0,0 +1,7 @@
+export {
+  Calendar,
+  type CalendarProps,
+  type CalendarRangeProps,
+  type CalendarSingleProps,
+  type DateRange,
+} from "./Calendar";

package/src/components/carousel/Carousel.tsx

@@ -0,0 +1,252 @@
+import {
+  Children,
+  createContext,
+  isValidElement,
+  useContext,
+  type ComponentProps,
+  type KeyboardEvent,
+  type ReactNode,
+} from "react";
+import { useControllableState } from "../../hooks/useControllableState";
+import { ChevronLeft } from "../../icons/ChevronLeft";
+import { ChevronRight } from "../../icons/ChevronRight";
+import { cn } from "../../lib/cn";
+import { focusRing } from "../../lib/focus-ring";
+import { DashIndicator } from "../dash-indicator/DashIndicator";
+import { IconButton } from "../icon-button/IconButton";
+import { useSnapTrack } from "./snap-track";
+
+export type CarouselRatio = "16/9" | "4/3" | "1/1" | "3/4" | "21/9";
+
+const ratioClass: Record<CarouselRatio, string> = {
+  "16/9": "aspect-video",
+  "4/3": "aspect-4/3",
+  "1/1": "aspect-square",
+  "3/4": "aspect-3/4",
+  "21/9": "aspect-21/9",
+};
+
+const SlideContext = createContext<{
+  position: number;
+  count: number;
+  current: boolean;
+} | null>(null);
+
+export type CarouselProps = Omit<
+  ComponentProps<"section">,
+  "aria-label" | "onChange"
+> & {
+  /** 这组媒体是什么，比如"玩法介绍" */
+  "aria-label": string;
+  /** 现在是第几张，从 0 起 */
+  index?: number;
+  defaultIndex?: number;
+  onIndexChange?: (index: number) => void;
+  /** 到头之后绕回另一头。默认到头时翻页钮禁用 */
+  loop?: boolean;
+  /** 媒体的宽高比，默认 `16/9` */
+  ratio?: CarouselRatio;
+  /** 计数旁边再加一排进度短横 */
+  indicator?: boolean;
+  previousLabel?: string;
+  nextLabel?: string;
+  /** 直接放 `CarouselSlide` */
+  children: ReactNode;
+};
+
+type SlideLike = { title?: ReactNode; description?: ReactNode };
+
+/**
+ * 媒体轮播：一次看一张的大幅媒体，前后翻。不自动播放。
+ * 轨道是原生的横向滚动加滚动吸附，触屏滑动是浏览器自带的。
+ */
+export function Carousel({
+  index: indexProp,
+  defaultIndex = 0,
+  onIndexChange,
+  loop = false,
+  ratio = "16/9",
+  indicator = false,
+  previousLabel = "上一张",
+  nextLabel = "下一张",
+  className,
+  children,
+  ...props
+}: CarouselProps) {
+  // 标题和说明从子元素上读，所以子元素必须直接是 CarouselSlide
+  const slides = Children.toArray(children).filter((child) =>
+    isValidElement<SlideLike>(child),
+  );
+  const count = slides.length;
+  const last = Math.max(0, count - 1);
+
+  const [rawIndex, setIndex] = useControllableState({
+    value: indexProp,
+    defaultValue: defaultIndex,
+    onChange: onIndexChange,
+  });
+  const index = Math.min(Math.max(rawIndex, 0), last);
+  // 下标和滚动位置互相跟的那一段，和图片查看共用
+  const { trackRef, onScroll } = useSnapTrack({
+    index,
+    count,
+    onSettle: setIndex,
+  });
+
+  const go = (next: number) => {
+    if (count === 0) return;
+    const target = loop
+      ? (next + count) % count
+      : Math.min(Math.max(next, 0), last);
+    setIndex(target);
+    // 到头了，刚按的那个翻页钮马上要禁用：把焦点交给媒体，键盘还能接着用方向键翻回去
+    if (
+      !loop &&
+      (target === 0 || target === last) &&
+      document.activeElement instanceof HTMLButtonElement &&
+      trackRef.current?.parentElement?.contains(document.activeElement)
+    ) {
+      trackRef.current.focus({ preventScroll: true });
+    }
+  };
+
+  const onKeyDown = (event: KeyboardEvent<HTMLElement>) => {
+    const next = {
+      ArrowLeft: index - 1,
+      ArrowRight: index + 1,
+      Home: 0,
+      End: last,
+    }[event.key];
+    if (next === undefined) return;
+    event.preventDefault();
+    go(next);
+  };
+
+  const current = slides[index] as { props: SlideLike } | undefined;
+  const place = `第 ${index + 1} 张，共 ${count} 张`;
+
+  return (
+    <section
+      {...props}
+      role="group"
+      aria-roledescription="轮播"
+      data-ratio={ratio}
+      className={cn("flex flex-col gap-3 text-ink", className)}
+    >
+      <div className="relative isolate">
+        <div
+          ref={trackRef}
+          // 能聚焦：键盘要能在媒体上用方向键翻页
+          tabIndex={0}
+          onScroll={onScroll}
+          // 只管焦点就在轨道上的时候：幻灯片里的控件（视频的进度条）自己要用方向键
+          onKeyDown={(event) => {
+            if (event.target === event.currentTarget) onKeyDown(event);
+          }}
+          className={cn(
+            "flex snap-x snap-mandatory overflow-x-auto overscroll-x-contain bg-surface-muted [scrollbar-width:none]",
+            // 环画在外面：画在里面会被幻灯片盖住（它们是定位元素，画在轨道的轮廓之上）
+            focusRing,
+            ratioClass[ratio],
+          )}
+        >
+          {slides.map((slide, position) => (
+            <SlideContext
+              key={position}
+              value={{ position, count, current: position === index }}
+            >
+              {slide}
+            </SlideContext>
+          ))}
+        </div>
+        {/* 压在媒体左下角的一对圆钮。它们在轨道外面：轨道滚的时候不跟着走 */}
+        <div
+          onKeyDown={onKeyDown}
+          className="absolute bottom-3 left-3 z-1 flex gap-2"
+        >
+          <IconButton
+            variant="floating"
+            aria-label={previousLabel}
+            disabled={!loop && index <= 0}
+            onClick={() => go(index - 1)}
+          >
+            <ChevronLeft />
+          </IconButton>
+          <IconButton
+            variant="floating"
+            aria-label={nextLabel}
+            disabled={!loop && index >= last}
+            onClick={() => go(index + 1)}
+          >
+            <ChevronRight />
+          </IconButton>
+        </div>
+      </div>
+
+      <div className="flex flex-col gap-1">
+        {/* 看得见的计数和短横只给眼睛：同样的话下面的说明区会播报 */}
+        <div aria-hidden="true" className="flex items-center gap-3">
+          <span className="font-tech text-xs text-ink-secondary tabular-nums">
+            {`${index + 1} / ${count}`}
+          </span>
+          {indicator && <DashIndicator count={count} index={index} />}
+        </div>
+        <div aria-live="polite" className="flex flex-col gap-1">
+          <span className="sr-only">{place}</span>
+          {current?.props.title && (
+            <p className="text-lg font-bold wrap-anywhere">
+              {current.props.title}
+            </p>
+          )}
+          {current?.props.description && (
+            <p className="text-sm text-ink-secondary">
+              {current.props.description}
+            </p>
+          )}
+        </div>
+      </div>
+    </section>
+  );
+}
+
+export type CarouselSlideProps = Omit<ComponentProps<"div">, "title"> & {
+  /** 这一张的标题，显示在媒体下方 */
+  title?: ReactNode;
+  /** 标题下面的一段正文 */
+  description?: ReactNode;
+  /** 媒体：一张图或一段视频，铺满并裁切 */
+  children: ReactNode;
+};
+
+/** 轮播里的一张。直接放在 `Carousel` 里。 */
+export function CarouselSlide({
+  // 标题和说明由 Carousel 读走，画在媒体下面
+  title: _title,
+  description: _description,
+  className,
+  children,
+  ...props
+}: CarouselSlideProps) {
+  const slide = useContext(SlideContext);
+  if (!slide) {
+    throw new Error("CarouselSlide 要直接放在 Carousel 里面");
+  }
+
+  return (
+    <div
+      {...props}
+      role="group"
+      aria-roledescription="幻灯片"
+      aria-label={`第 ${slide.position + 1} 张，共 ${slide.count} 张`}
+      // 不在眼前的：里面的链接、视频控件 Tab 走不进去，读屏也读不到
+      inert={!slide.current}
+      data-current={slide.current ? "" : undefined}
+      className={cn(
+        "relative size-full shrink-0 snap-start overflow-clip *:size-full *:object-cover",
+        className,
+      )}
+    >
+      {children}
+    </div>
+  );
+}