@endfield-ui/react 0.0.0-stage → 0.1.0

package/src/components/carousel/Carousel.tsx

@@ -0,0 +1,292 @@
+import {
+  Children,
+  createContext,
+  isValidElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  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";
+
+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 };
+
+/** 滚动停下之后多久算"停稳了"。没有 scrollend 事件的浏览器靠它 */
+const SETTLE_MS = 120;
+
+/**
+ * 媒体轮播：一次看一张的大幅媒体，前后翻。不自动播放。
+ * 轨道是原生的横向滚动加滚动吸附，触屏滑动是浏览器自带的。
+ */
+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 = useRef<HTMLDivElement>(null);
+  const settleTimer = useRef<ReturnType<typeof setTimeout>>(undefined);
+  // 给不跟着渲染重建的回调（尺寸变化）读最新的下标
+  const indexRef = useRef(index);
+  indexRef.current = index;
+
+  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 });
+    }
+  };
+
+  // 下标变了：滚过去。已经在那儿（用户自己滑过去的）就不动
+  useEffect(() => {
+    const track = trackRef.current;
+    if (!track || track.clientWidth === 0) return;
+    if (Math.round(track.scrollLeft / track.clientWidth) === index) return;
+    track.scrollTo?.({ left: index * track.clientWidth, behavior: "smooth" });
+  }, [index]);
+
+  // 宽度变了：轨道的滚动位置是像素，会错开，重新对到当前这一张（不要动画）
+  useEffect(() => {
+    const track = trackRef.current;
+    if (!track || typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(() => {
+      track.scrollTo?.({
+        left: indexRef.current * track.clientWidth,
+        behavior: "instant",
+      });
+    });
+    observer.observe(track);
+    return () => observer.disconnect();
+  }, []);
+
+  useEffect(() => () => clearTimeout(settleTimer.current), []);
+
+  // 用户自己滑：等滚动停稳，由停下的位置定下标。滚动途中不改——
+  // 翻页钮触发的滚动会路过中间那几张
+  const onScroll = useCallback(() => {
+    clearTimeout(settleTimer.current);
+    settleTimer.current = setTimeout(() => {
+      const track = trackRef.current;
+      if (!track || track.clientWidth === 0) return;
+      const stopped = Math.round(track.scrollLeft / track.clientWidth);
+      setIndex(Math.min(Math.max(stopped, 0), last));
+    }, SETTLE_MS);
+  }, [setIndex, last]);
+
+  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>
+  );
+}

package/src/components/carousel/index.ts

@@ -0,0 +1,7 @@
+export {
+  Carousel,
+  CarouselSlide,
+  type CarouselProps,
+  type CarouselRatio,
+  type CarouselSlideProps,
+} from "./Carousel";

package/src/components/checkbox/Checkbox.tsx

@@ -0,0 +1,94 @@
+import {
+  useEffect,
+  useRef,
+  type ChangeEvent,
+  type ComponentProps,
+  type ReactNode,
+} from "react";
+import { Check } from "../../icons/Check";
+import { Minus } from "../../icons/Minus";
+import { cn } from "../../lib/cn";
+import { focusRing } from "../../lib/focus-ring";
+import { mergeRefs } from "../../lib/merge-refs";
+import {
+  choiceBox,
+  choiceControl,
+  choiceFrame,
+  choiceLabel,
+  choiceMark,
+} from "./choice-style";
+
+export type CheckboxProps = Omit<ComponentProps<"input">, "type" | "size"> & {
+  /** 半选：一组子项只选了一部分。显示为短横，读屏读作"部分选中" */
+  indeterminate?: boolean;
+  /** 错误态：描边变红 */
+  invalid?: boolean;
+  onCheckedChange?: (checked: boolean) => void;
+  /** 右侧的文字标签。不传时必须自己给 `aria-label` */
+  children?: ReactNode;
+};
+
+/**
+ * 复选框。原生 `<input type="checkbox">`，受控用 `checked`、非受控用 `defaultChecked`。
+ * `className` 给整行，其余属性与 `ref` 给 `<input>`。
+ */
+export function Checkbox({
+  indeterminate = false,
+  invalid = false,
+  onCheckedChange,
+  onChange,
+  className,
+  children,
+  ref,
+  ...props
+}: CheckboxProps) {
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  // indeterminate 只能通过 DOM 属性设置，没有对应的 HTML 特性
+  useEffect(() => {
+    if (inputRef.current) inputRef.current.indeterminate = indeterminate;
+  }, [indeterminate]);
+
+  const handleChange = (event: ChangeEvent<HTMLInputElement>) => {
+    onChange?.(event);
+    onCheckedChange?.(event.target.checked);
+  };
+
+  return (
+    <label className={cn(choiceLabel, className)}>
+      <span className={choiceControl}>
+        <span className={choiceFrame}>
+          <input
+            {...props}
+            ref={mergeRefs(inputRef, ref)}
+            type="checkbox"
+            aria-invalid={invalid || undefined}
+            onChange={handleChange}
+            className={cn(
+              choiceBox,
+              // 半选只属于复选框：一组单选都没选时也会命中 :indeterminate，
+              // 所以这两个类不能放进与单选共用的 choiceBox
+              "indeterminate:border-surface-inverse indeterminate:bg-surface-inverse",
+              focusRing,
+            )}
+          />
+          <Check
+            size={14}
+            strokeWidth={3}
+            className={cn(
+              choiceMark,
+              // 菱形方案下"已选"就是实心菱形，不画对勾
+              "peer-checked:opacity-100 peer-indeterminate:opacity-0 choice-diamond:hidden",
+            )}
+          />
+          <Minus
+            size={14}
+            strokeWidth={3}
+            className={cn(choiceMark, "peer-indeterminate:opacity-100")}
+          />
+        </span>
+      </span>
+      {children !== undefined && <span className="min-w-0">{children}</span>}
+    </label>
+  );
+}

package/src/components/checkbox/choice-style.ts

@@ -0,0 +1,30 @@
+/*
+ * 复选、单选、开关共用的一行：真正的 <input> 画成控件本身，文字标签在右，
+ * 点击标签等同点击控件，整行不低于 40px。
+ */
+
+export const choiceLabel =
+  "group inline-flex min-h-10 items-start gap-2 py-2 text-base text-ink has-disabled:cursor-not-allowed has-disabled:text-ink-disabled";
+
+/** 控件的定位盒：高度等于一行文字，标签换行时控件仍然对齐第一行 */
+export const choiceControl = "flex h-[1lh] shrink-0 items-center";
+
+/*
+ * 复选框与单选框的方格 / 圆：
+ * 未选是凹陷底 + 2px 描边；已选是反转块，上面压 accent-ink-inverse 的记号——
+ * 亮色下是墨底黄记号，暗色下反转块是近白，记号换成深色档。
+ *
+ * 祖先上有 data-choice="diamond" 时换成菱形（方案 B）：方格缩到 14px 并转 45°，
+ * 对角线正好还是 20px；未选是空心菱形，已选是实心的，不再画对勾和圆点——
+ * 所以禁用的"已选"也要保持实心，否则和"未选"分不出来。
+ */
+export const choiceBox =
+  "peer size-5 shrink-0 appearance-none border-2 choice-diamond:size-3.5 choice-diamond:rotate-45 choice-diamond:checked:disabled:bg-ink-disabled border-line-strong bg-surface-sunken transition-colors duration-(--duration-fast) ease-standard group-hover:border-ink-secondary checked:border-surface-inverse checked:bg-surface-inverse aria-invalid:border-danger disabled:cursor-not-allowed disabled:border-ink-disabled disabled:bg-surface-sunken";
+
+/** 方格 / 圆的定位盒：菱形比它小一圈，所以居中 */
+export const choiceFrame =
+  "relative inline-flex size-5 items-center justify-center";
+
+/** 压在方格 / 圆正中的记号，默认透明，由 peer 的状态点亮 */
+export const choiceMark =
+  "pointer-events-none absolute inset-0 m-auto text-accent-ink-inverse opacity-0 peer-disabled:text-ink-disabled";

package/src/components/checkbox/index.ts

@@ -0,0 +1 @@
+export { Checkbox, type CheckboxProps } from "./Checkbox";

package/src/components/chip/FilterChip.tsx

@@ -0,0 +1,68 @@
+import type { ComponentProps, MouseEvent } from "react";
+import { useControllableState } from "../../hooks/useControllableState";
+import { cn } from "../../lib/cn";
+import { focusRing } from "../../lib/focus-ring";
+import {
+  capsuleBase,
+  capsuleSize,
+  capsuleState,
+  type CapsuleSize,
+} from "./capsule-style";
+
+export type FilterChipProps = Omit<ComponentProps<"button">, "aria-pressed"> & {
+  /** 受控的选中状态 */
+  selected?: boolean;
+  /** 非受控时的初始状态 */
+  defaultSelected?: boolean;
+  onSelectedChange?: (selected: boolean) => void;
+  size?: CapsuleSize;
+};
+
+/**
+ * 筛选胶囊：一个可以独立开关的条件，几个并排就是多选筛选。
+ * 几项里只能选一项时用 `Tabs` 的 `capsule` 变体或单选。
+ */
+export function FilterChip({
+  selected,
+  defaultSelected = false,
+  onSelectedChange,
+  size = "md",
+  disabled = false,
+  type = "button",
+  className,
+  onClick,
+  ...props
+}: FilterChipProps) {
+  const [on, setOn] = useControllableState({
+    value: selected,
+    defaultValue: defaultSelected,
+    onChange: onSelectedChange,
+  });
+
+  return (
+    <button
+      {...props}
+      type={type}
+      disabled={disabled}
+      aria-pressed={on}
+      data-selected={on ? "" : undefined}
+      onClick={(event: MouseEvent<HTMLButtonElement>) => {
+        onClick?.(event);
+        if (!event.defaultPrevented) setOn(!on);
+      }}
+      className={cn(
+        capsuleBase,
+        focusRing,
+        capsuleSize[size],
+        disabled
+          ? on
+            ? capsuleState.selectedDisabled
+            : capsuleState.disabled
+          : on
+            ? capsuleState.selected
+            : capsuleState.rest,
+        className,
+      )}
+    />
+  );
+}

package/src/components/chip/ResourceChip.tsx

@@ -0,0 +1,63 @@
+import type { ComponentProps, ReactNode } from "react";
+import { cn } from "../../lib/cn";
+
+export type ResourceChipSize = "sm" | "md";
+
+export type ResourceChipProps = Omit<ComponentProps<"span">, "children"> & {
+  /** 资源的图标，放进左端的圆形底托。本库不带资源图标，由使用方提供 */
+  icon?: ReactNode;
+  /** 数量，等宽数字 */
+  children: ReactNode;
+  /** 给读屏的完整说明，如"燃料 1,280"。提供后数字本身对辅助技术隐藏 */
+  label?: string;
+  size?: ResourceChipSize;
+};
+
+const sizeClass: Record<ResourceChipSize, string> = {
+  sm: "h-6 gap-1 pr-2.5 text-xs",
+  md: "h-7 gap-1.5 pr-3 text-sm",
+};
+
+const iconPadding: Record<ResourceChipSize, string> = {
+  sm: "pl-0.5",
+  md: "pl-1",
+};
+
+const plainPadding: Record<ResourceChipSize, string> = {
+  sm: "pl-2.5",
+  md: "pl-3",
+};
+
+/** 资源胶囊：货币、材料的当前数量——会变的状态，所以是胶囊。 */
+export function ResourceChip({
+  icon,
+  label,
+  size = "md",
+  className,
+  children,
+  ...props
+}: ResourceChipProps) {
+  return (
+    <span
+      {...props}
+      className={cn(
+        // 有意不随主题翻转：control 系列在两个主题下取值相同
+        "inline-flex shrink-0 items-center rounded-full bg-control font-tech leading-none font-bold whitespace-nowrap text-on-control tabular-nums",
+        sizeClass[size],
+        icon ? iconPadding[size] : plainPadding[size],
+        className,
+      )}
+    >
+      {icon && (
+        <span
+          aria-hidden="true"
+          className="inline-flex size-5 shrink-0 items-center justify-center rounded-full bg-on-control/15 [&_svg]:size-3"
+        >
+          {icon}
+        </span>
+      )}
+      <span aria-hidden={label ? "true" : undefined}>{children}</span>
+      {label && <span className="sr-only">{label}</span>}
+    </span>
+  );
+}

package/src/components/chip/capsule-style.ts

@@ -0,0 +1,22 @@
+/*
+ * 可选中的胶囊：细边，选中时反转为墨底。
+ * 筛选胶囊与页签的 `capsule` 变体是同一个外观，类名放在一处免得两边走样。
+ */
+
+export type CapsuleSize = "sm" | "md";
+
+export const capsuleBase =
+  "inline-flex shrink-0 items-center rounded-full border leading-none font-medium whitespace-nowrap transition-colors duration-(--duration-fast) ease-standard";
+
+export const capsuleSize: Record<CapsuleSize, string> = {
+  sm: "h-7 px-3 text-xs",
+  md: "h-8 px-4 text-sm",
+};
+
+export const capsuleState = {
+  selected: "border-transparent bg-surface-inverse text-ink-inverse",
+  rest: "border-line-strong text-ink hover:bg-ink/5",
+  disabled: "cursor-not-allowed border-line text-ink-disabled",
+  selectedDisabled:
+    "cursor-not-allowed border-transparent bg-disabled text-on-disabled",
+} as const;

package/src/components/chip/index.ts

@@ -0,0 +1,6 @@
+export { FilterChip, type FilterChipProps } from "./FilterChip";
+export {
+  ResourceChip,
+  type ResourceChipProps,
+  type ResourceChipSize,
+} from "./ResourceChip";