@endfield-ui/react 0.0.0-stage → 0.2.0

package/src/components/carousel/index.ts

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

package/src/components/carousel/snap-track.ts

@@ -0,0 +1,74 @@
+import { useCallback, useEffect, useRef } from "react";
+
+/** 滚动停下之后多久算"停稳了"。没有 scrollend 事件的浏览器靠它 */
+const SETTLE_MS = 120;
+
+type SnapTrackOptions = {
+  /** 现在是第几张，从 0 起 */
+  index: number;
+  /** 一共几张 */
+  count: number;
+  /** 用户自己滑、停稳在了第几张 */
+  onSettle: (index: number) => void;
+};
+
+/**
+ * 一条横向滚动加滚动吸附的轨道，每一张和轨道一样宽。下标和滚动位置互相跟：
+ * 下标变了轨道滚过去；用户自己滑的时候反过来，等滚动停稳，由停下的位置定下标。
+ * 手势、惯性都是浏览器的。媒体轮播和图片查看共用，不对外导出。
+ *
+ * 把 `trackRef` 和 `onScroll` 交给那个滚动容器。
+ */
+export function useSnapTrack({ index, count, onSettle }: SnapTrackOptions) {
+  const trackRef = useRef<HTMLDivElement>(null);
+  const settleTimer = useRef<ReturnType<typeof setTimeout>>(undefined);
+  const last = Math.max(0, count - 1);
+  // 给不跟着渲染重建的回调（尺寸变化）读最新的下标
+  const indexRef = useRef(index);
+  indexRef.current = index;
+  const placed = useRef(false);
+
+  // 下标变了：滚过去。已经在那儿（用户自己滑过去的）就不动。
+  // 刚挂上的那一次直接到位：从第一张一路滑到第三张不是谁想看的
+  useEffect(() => {
+    const first = !placed.current;
+    placed.current = true;
+    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: first ? "instant" : "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);
+      onSettle(Math.min(Math.max(stopped, 0), last));
+    }, SETTLE_MS);
+  }, [onSettle, last]);
+
+  return { trackRef, onScroll };
+}

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";