@endfield-ui/react 0.0.0-stage → 0.2.0

package/src/components/section-title/SectionTitle.tsx

@@ -0,0 +1,202 @@
+import type { ComponentProps, ElementType, ReactNode } from "react";
+import { useInView } from "../../hooks/useInView";
+import { ArrowCorner } from "../../icons/ArrowCorner";
+import { cn } from "../../lib/cn";
+
+export type SectionTitleVariant = "standard" | "plain" | "band" | "side";
+
+export type SectionTitleProps = Omit<ComponentProps<"header">, "title"> & {
+  /**
+   * - `standard` 灰色滑块 + 斜箭头 + 英文，下接中文。版块的第一级标题，默认；
+   * - `plain` 只留标题和左侧一条短竖条。文档、设置这类工具页面；
+   * - `band` 通栏信号黄色带。亮暗版块之间的过渡，一页最多一到两条；
+   * - `side` 竖排侧签。贴在横向展开的版块左缘，窄屏下回到横排。
+   */
+  variant?: SectionTitleVariant;
+  /** 真正的标题文字 */
+  children: ReactNode;
+  /** 英文结构层：`standard` 的栏目名、`side` 的大字。写真实的栏目名 */
+  latin?: ReactNode;
+  /** `band` 主题上方的小号副题 */
+  subtitle?: ReactNode;
+  /** `standard` 顶部的微文字行，如 `// 新闻　2026.10.08` */
+  meta?: ReactNode;
+  /** 标题层级，默认 2（`<h2>`） */
+  level?: 1 | 2 | 3 | 4 | 5 | 6;
+  /** `standard` 进入视口时播放一次入场，默认开启 */
+  animate?: boolean;
+  /** 英文只是标题的翻译时对读屏隐藏，避免重复朗读。默认隐藏 */
+  latinHidden?: boolean;
+  /** `side` 的底色：`accent` 信号黄，`muted` 浅灰 */
+  tone?: "accent" | "muted";
+  /** `band` 与 `side` 的线稿插图位，纯装饰 */
+  illustration?: ReactNode;
+};
+
+export function SectionTitle({
+  variant = "standard",
+  children,
+  latin,
+  subtitle,
+  meta,
+  level = 2,
+  animate = true,
+  latinHidden = true,
+  tone = "accent",
+  illustration,
+  className,
+  ref: forwardedRef,
+  ...props
+}: SectionTitleProps) {
+  const Heading: ElementType = `h${level}`;
+  const reveal = variant === "standard" && animate;
+  const [inViewRef, inView] = useInView<HTMLElement>({ disabled: !reveal });
+
+  const ref = (node: HTMLElement | null) => {
+    inViewRef.current = node;
+    if (typeof forwardedRef === "function") forwardedRef(node);
+    else if (forwardedRef) forwardedRef.current = node;
+  };
+
+  if (variant === "plain") {
+    return (
+      <header
+        {...props}
+        ref={ref}
+        className={cn("flex items-center gap-3", className)}
+      >
+        <span aria-hidden="true" className="h-6 w-1 shrink-0 bg-ink" />
+        <Heading className="min-w-0 text-2xl font-bold wrap-anywhere text-ink">
+          {children}
+        </Heading>
+      </header>
+    );
+  }
+
+  if (variant === "band") {
+    // 色带按自身宽度响应（容器查询），不看视口：它可能被放进窄栏里。
+    // 字号与留白随宽度分三档，插图在窄处去掉；wrap-anywhere 兜底，长单词也不会溢出
+    return (
+      <header
+        {...props}
+        ref={ref}
+        className={cn("@container bg-action text-on-action", className)}
+      >
+        <div className="flex min-h-16 items-center gap-4 px-4 py-4 @md:min-h-24 @md:gap-6 @md:px-10">
+          {illustration && (
+            <div aria-hidden="true" className="hidden shrink-0 @sm:block">
+              {illustration}
+            </div>
+          )}
+          <div className="min-w-0">
+            {subtitle && (
+              <p className="font-latin text-base leading-tight font-light wrap-anywhere uppercase @md:text-lg">
+                {subtitle}
+              </p>
+            )}
+            <Heading className="font-latin text-xl font-medium wrap-anywhere uppercase @xs:text-2xl @md:text-3xl">
+              {children}
+            </Heading>
+          </div>
+        </div>
+      </header>
+    );
+  }
+
+  if (variant === "side") {
+    return (
+      <header
+        {...props}
+        ref={ref}
+        className={cn(
+          "flex flex-wrap items-center gap-3 px-4 py-3",
+          "md:self-stretch md:px-3 md:py-6 md:[writing-mode:vertical-rl]",
+          tone === "accent"
+            ? "bg-action text-on-action"
+            : "bg-surface-muted text-ink",
+          className,
+        )}
+      >
+        {illustration && (
+          <div aria-hidden="true" className="shrink-0">
+            {illustration}
+          </div>
+        )}
+        <Heading className="text-sm font-medium">{children}</Heading>
+        {latin && (
+          <p
+            aria-hidden={latinHidden || undefined}
+            className="max-w-full font-latin text-2xl font-medium wrap-anywhere uppercase"
+          >
+            {latin}
+          </p>
+        )}
+      </header>
+    );
+  }
+
+  // 入场顺序：滑块 → 箭头 → 文字，每步错开 100ms
+  const pending = reveal && !inView;
+  const playing = reveal && inView;
+
+  return (
+    <header {...props} ref={ref} className={className}>
+      {meta && (
+        <p
+          className={cn(
+            "mb-2 font-tech text-xs text-ink-secondary",
+            pending && "opacity-0",
+            playing && "animate-fade-in [animation-delay:200ms]",
+          )}
+        >
+          {meta}
+        </p>
+      )}
+      {/* 放不下时英文折到滑块下面一行，而不是顶出容器 */}
+      <div className="flex flex-wrap items-center gap-x-2">
+        <span
+          aria-hidden="true"
+          className="relative block h-8 w-26 shrink-0 overflow-hidden"
+        >
+          {/* 滑块在亮暗两个主题下都是浅灰，所以箭头固定用墨色 */}
+          <span
+            className={cn(
+              "absolute inset-0 flex items-center justify-end bg-neutral-300 pr-1.5 text-neutral-900",
+              pending && "-translate-x-full",
+              playing && "animate-slide-in",
+            )}
+          >
+            <ArrowCorner
+              size={20}
+              className={cn(
+                pending && "-rotate-45",
+                playing && "animate-turn-in [animation-delay:100ms]",
+              )}
+            />
+          </span>
+        </span>
+        {latin && (
+          <p
+            aria-hidden={latinHidden || undefined}
+            className={cn(
+              "max-w-full font-latin text-xl leading-8 font-medium wrap-anywhere text-ink uppercase",
+              pending && "opacity-0",
+              playing && "animate-fade-in [animation-delay:200ms]",
+            )}
+          >
+            {latin}
+          </p>
+        )}
+      </div>
+      <Heading
+        className={cn(
+          "mt-1 text-2xl font-bold wrap-anywhere text-ink",
+          pending && "opacity-0",
+          playing && "animate-fade-in [animation-delay:200ms]",
+        )}
+      >
+        {children}
+      </Heading>
+    </header>
+  );
+}

package/src/components/section-title/index.ts

@@ -0,0 +1,5 @@
+export {
+  SectionTitle,
+  type SectionTitleProps,
+  type SectionTitleVariant,
+} from "./SectionTitle";

package/src/components/segmented-control/SegmentedControl.tsx

@@ -0,0 +1,220 @@
+import {
+  createContext,
+  useContext,
+  useId,
+  useMemo,
+  type ComponentProps,
+  type ReactNode,
+} from "react";
+import { useControllableState } from "../../hooks/useControllableState";
+import { cn } from "../../lib/cn";
+import { useFieldContext } from "../field/Field";
+import {
+  controlSize,
+  type ControlSize,
+  type ControlVariant,
+} from "../input/control-box";
+
+export type SegmentedControlSize = ControlSize;
+export type SegmentedControlVariant = ControlVariant;
+
+type SegmentedContextValue = {
+  name: string;
+  value: string | undefined;
+  select: (value: string) => void;
+  size: SegmentedControlSize;
+  disabled: boolean;
+  required: boolean;
+  invalid: boolean;
+};
+
+const SegmentedContext = createContext<SegmentedContextValue | null>(null);
+
+export type SegmentedControlProps = Omit<
+  ComponentProps<"div">,
+  "onChange" | "defaultValue"
+> & {
+  /** 受控的当前值 */
+  value?: string;
+  /** 非受控时的初始值 */
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+  /** 表单字段名：选中的值会随表单提交。缺省自动生成 */
+  name?: string;
+  /** 32 / 40 / 56px 高，和输入框同三档 */
+  size?: SegmentedControlSize;
+  /**
+   * 轨道的画法，和输入框相同：
+   * - `sunken` 凹陷的底 + 一条底边线，默认；
+   * - `outline` 四边描边，放在凹陷底色的区域里时用。
+   */
+  variant?: SegmentedControlVariant;
+  disabled?: boolean;
+  required?: boolean;
+  /** 错误态。放在 `Field` 里时跟随它的 `error` */
+  invalid?: boolean;
+};
+
+const track: Record<SegmentedControlVariant, string> = {
+  sunken: "border-b-2 bg-surface-sunken",
+  outline: "border bg-surface",
+};
+
+/**
+ * 分段选择：两到五个值里选一个，选项并排摆在一条轨道里。
+ * 语义是单选组——方向键换值，带 `name` 时随表单提交。里面只放 `Segment`。
+ * 标签用 `Field` 包住它，或者自己传 `aria-label`。
+ *
+ * 切换的是下面显示哪一块内容时用 `Tabs`，不是它。
+ */
+export function SegmentedControl({
+  value,
+  defaultValue,
+  onValueChange,
+  name,
+  size = "md",
+  variant = "sunken",
+  disabled: disabledProp,
+  required: requiredProp,
+  invalid: invalidProp,
+  className,
+  ...props
+}: SegmentedControlProps) {
+  const field = useFieldContext();
+  const autoName = useId();
+  const [current, setCurrent] = useControllableState<string | undefined>({
+    value,
+    defaultValue,
+    onChange: (next) => {
+      if (next !== undefined) onValueChange?.(next);
+    },
+  });
+
+  const disabled = disabledProp ?? field?.disabled ?? false;
+  const required = requiredProp ?? field?.required ?? false;
+  const invalid = invalidProp ?? field?.invalid ?? false;
+  const groupName = name ?? autoName;
+
+  const context = useMemo<SegmentedContextValue>(
+    () => ({
+      name: groupName,
+      value: current,
+      select: setCurrent,
+      size,
+      disabled,
+      required,
+      invalid,
+    }),
+    [groupName, current, setCurrent, size, disabled, required, invalid],
+  );
+
+  return (
+    <SegmentedContext value={context}>
+      <div
+        role="radiogroup"
+        // 字段是 <fieldset> 时名称由 <legend> 给；否则指向字段的标签
+        aria-labelledby={field && !field.group ? field.labelId : undefined}
+        aria-describedby={field?.describedBy}
+        aria-invalid={invalid || undefined}
+        aria-required={required || undefined}
+        aria-disabled={disabled || undefined}
+        {...props}
+        data-variant={variant}
+        data-size={size}
+        className={cn(
+          // 各段等宽，按最宽的那一段定；比容器宽时一起收窄，文字截断
+          "inline-grid max-w-full auto-cols-fr grid-flow-col p-0.5 text-ink",
+          "transition-colors duration-(--duration-fast) ease-standard",
+          track[variant],
+          controlSize[size],
+          // 和输入框一样靠边线说状态
+          disabled
+            ? "border-line"
+            : invalid
+              ? "border-danger"
+              : "border-line-strong focus-within:border-ink",
+          className,
+        )}
+      />
+    </SegmentedContext>
+  );
+}
+
+const segmentPadding: Record<SegmentedControlSize, string> = {
+  sm: "gap-1.5 px-3 [&_svg]:size-3.5",
+  md: "gap-2 px-4 [&_svg]:size-4",
+  lg: "gap-2.5 px-6 [&_svg]:size-5",
+};
+
+type SegmentOwnProps = {
+  value: string;
+  /** 文字左边的图标。只有图标时要给 `aria-label` */
+  icon?: ReactNode;
+  disabled?: boolean;
+  /** 这一段的可访问名称；不传就是里面的文字 */
+  "aria-label"?: string;
+  children?: ReactNode;
+};
+
+export type SegmentProps = SegmentOwnProps &
+  Omit<ComponentProps<"label">, keyof SegmentOwnProps>;
+
+/** 分段选择里的一段。`className` 给这一段的外壳。 */
+export function Segment({
+  value,
+  icon,
+  disabled: disabledProp,
+  "aria-label": ariaLabel,
+  className,
+  children,
+  ...props
+}: SegmentProps) {
+  const context = useContext(SegmentedContext);
+  if (!context) {
+    throw new Error("<Segment> 必须放在 <SegmentedControl> 里");
+  }
+  const checked = context.value === value;
+  const disabled = disabledProp ?? context.disabled;
+
+  return (
+    <label
+      {...props}
+      data-selected={checked ? "" : undefined}
+      data-disabled={disabled ? "" : undefined}
+      className={cn(
+        "relative flex min-w-0 items-center justify-center font-medium whitespace-nowrap select-none",
+        "transition-colors duration-(--duration-fast) ease-standard",
+        // 焦点环画在这一段上，并提到相邻段之上
+        "has-focus-visible:z-1 has-focus-visible:outline-2 has-focus-visible:outline-offset-2 has-focus-visible:outline-focus",
+        segmentPadding[context.size],
+        disabled ? "cursor-not-allowed" : "cursor-pointer",
+        // 选中不加粗：加粗会让这一段变宽，整条跟着跳。靠的是填充反转
+        checked
+          ? disabled
+            ? "bg-disabled text-on-disabled"
+            : "bg-surface-inverse text-ink-inverse"
+          : disabled
+            ? "text-ink-disabled"
+            : "text-ink-secondary hover:bg-ink/5 hover:text-ink",
+        className,
+      )}
+    >
+      <input
+        type="radio"
+        name={context.name}
+        value={value}
+        checked={checked}
+        disabled={disabled}
+        required={context.required}
+        aria-label={ariaLabel}
+        aria-invalid={context.invalid || undefined}
+        onChange={() => context.select(value)}
+        className="absolute inset-0 size-full cursor-[inherit] appearance-none outline-none"
+      />
+      {icon}
+      {children !== undefined && (
+        <span className="pointer-events-none min-w-0 truncate">{children}</span>
+      )}
+    </label>
+  );
+}

package/src/components/segmented-control/index.ts

@@ -0,0 +1,8 @@
+export {
+  Segment,
+  SegmentedControl,
+  type SegmentedControlProps,
+  type SegmentedControlSize,
+  type SegmentedControlVariant,
+  type SegmentProps,
+} from "./SegmentedControl";