@endfield-ui/react 0.0.0-stage → 0.2.0

package/src/components/schedule/Schedule.tsx

@@ -0,0 +1,457 @@
+import {
+  createContext,
+  useContext,
+  useMemo,
+  type ComponentProps,
+  type CSSProperties,
+  type MouseEvent,
+  type ReactNode,
+} from "react";
+import { useOverflowing } from "../../hooks/useOverflowing";
+import { cn } from "../../lib/cn";
+import { dateParts, daysBetween, eachDay, toDateObject } from "../../lib/date";
+import { decor } from "../../lib/decor";
+import { focusRingInset } from "../../lib/focus-ring";
+import { LinkElement, type LinkRender } from "../link-element/LinkElement";
+import { Tag } from "../tag/Tag";
+
+type ScheduleContextValue = {
+  start: string;
+  /** 一共几天 */
+  days: number;
+  /** 读屏听到的起止日期 */
+  describe: (start: string, end: string) => string;
+};
+
+const ScheduleContext = createContext<ScheduleContextValue | null>(null);
+
+function useSchedule(part: string) {
+  const context = useContext(ScheduleContext);
+  if (!context) throw new Error(`${part} 要放在 Schedule 里面`);
+  return context;
+}
+
+export type ScheduleProps = Omit<ComponentProps<"div">, "aria-label"> & {
+  /** 这张排期的名称。横向能滚动时，滚动的那一块用它 */
+  label: string;
+  /** 第一天，`YYYY-MM-DD` */
+  start: string;
+  /** 最后一天（包含） */
+  end: string;
+  /**
+   * 哪几天是日期锚：压在轴条上的日期块，往下带一条引线。
+   * 默认是第一天和范围内每个月的 1 号
+   */
+  anchors?: readonly string[];
+  /** 今天：画一条竖线。不传就不画 */
+  today?: string;
+  /** 一天至少多宽，像素。默认 32。容器够宽时各列平分多出来的宽度 */
+  dayWidth?: number;
+  /** 读屏听到的日期按它写。默认 `zh-CN` */
+  locale?: string;
+  /**
+   * 读屏听到的起止日期怎么说。默认"10月3日至10月12日"，只有一天时是"10月5日"。
+   * 换了 `locale` 一般也要换它
+   */
+  describeRange?: (start: string, end: string) => string;
+  /** `ScheduleTrack` */
+  children?: ReactNode;
+};
+
+const pad = (value: number) => String(value).padStart(2, "0");
+
+/* 轴、引线、各条轨共用同一份列：一天一列 */
+const dayColumns =
+  "grid grid-cols-[repeat(var(--schedule-days),minmax(var(--schedule-day),1fr))]";
+
+/* 类目竖轨的宽度。轴和引线要从它右边起 */
+const RAIL = "w-12";
+const AFTER_RAIL = "left-12";
+
+/**
+ * 排期：横向的时间轨图。条目从起始日的位置开始，长度就是持续时间。
+ * 最小单位是天。放不下时在自己的容器里横向滚动。
+ */
+export function Schedule({
+  label,
+  start,
+  end,
+  anchors: anchorsProp,
+  today,
+  dayWidth = 32,
+  locale = "zh-CN",
+  describeRange,
+  className,
+  style,
+  children,
+  ...props
+}: ScheduleProps) {
+  const [scrollerRef, overflowing] = useOverflowing();
+  const dates = useMemo(() => eachDay(start, end), [start, end]);
+  const days = dates.length;
+
+  const anchors = useMemo(
+    () =>
+      new Set(
+        anchorsProp ??
+          dates.filter(
+            (date, position) => position === 0 || dateParts(date).day === 1,
+          ),
+      ),
+    [anchorsProp, dates],
+  );
+
+  const context = useMemo(() => {
+    const day = new Intl.DateTimeFormat(locale, {
+      timeZone: "UTC",
+      month: "long",
+      day: "numeric",
+    });
+    const say = (date: string) => day.format(toDateObject(date));
+    return {
+      start,
+      days,
+      describe:
+        describeRange ??
+        ((from: string, to: string) =>
+          from === to ? say(from) : `${say(from)}至${say(to)}`),
+    };
+  }, [start, days, locale, describeRange]);
+
+  const column = (date: string) => daysBetween(start, date) + 1;
+  const todayColumn =
+    today !== undefined && today >= start && today <= end
+      ? column(today)
+      : null;
+
+  return (
+    <ScheduleContext value={context}>
+      <div
+        ref={scrollerRef}
+        {...props}
+        data-overflowing={overflowing.x ? "" : undefined}
+        // 只有真的能横向滚动时才是一个能聚焦的区域（同表格）
+        {...(overflowing.x && {
+          role: "region",
+          "aria-label": label,
+          tabIndex: 0,
+        })}
+        style={
+          {
+            "--schedule-days": days,
+            "--schedule-day": `${dayWidth}px`,
+            ...style,
+          } as CSSProperties
+        }
+        className={cn(
+          "isolate overflow-x-auto text-ink [--schedule-surface:var(--ef-surface)]",
+          focusRingInset,
+          className,
+        )}
+      >
+        {/*
+         * 宽度写死成"竖轨 + 天数 × 每天的宽度"，比容器窄时撑满容器。
+         * 不能让它跟着内容走：名称长的条目会把自己那几列撑宽，位置就不准了
+         */}
+        <div
+          role={overflowing.x ? undefined : "group"}
+          aria-label={overflowing.x ? undefined : label}
+          className="relative w-[calc(3rem+var(--schedule-days)*var(--schedule-day))] min-w-full"
+        >
+          {/* 空档：没有条目的时段露出这层淡斜纹 */}
+          <div
+            aria-hidden="true"
+            className={cn(
+              decor,
+              "absolute inset-y-0 right-0 bg-surface-sunken hatch",
+              AFTER_RAIL,
+            )}
+          />
+
+          {/* 引线：从每个日期锚往下，画在条目后面 */}
+          <div
+            aria-hidden="true"
+            className={cn(
+              decor,
+              "absolute inset-y-0 right-0",
+              AFTER_RAIL,
+              dayColumns,
+            )}
+          >
+            {[...anchors].map((date) => (
+              <span
+                key={date}
+                style={{ gridColumn: column(date) }}
+                className="row-start-1 border-l border-dashed border-line-strong"
+              />
+            ))}
+          </div>
+
+          {/* 时间轴 */}
+          <div aria-hidden="true" className="relative flex">
+            {/* 左上角：盖住滚过去的日号 */}
+            <div
+              className={cn(
+                "sticky left-0 z-3 shrink-0 bg-(--schedule-surface)",
+                RAIL,
+              )}
+            />
+            <div
+              className={cn(
+                "h-8 flex-1 items-center bg-surface-muted",
+                dayColumns,
+              )}
+            >
+              {dates.map((date, position) => {
+                if (anchors.has(date)) {
+                  const { month, day } = dateParts(date);
+                  return (
+                    <Tag
+                      key={date}
+                      variant="inverse"
+                      size="sm"
+                      numeric
+                      marked
+                      data-anchor={date}
+                      // 日期块比一天的格子宽：从这一格的左缘起，压到后面的格子上
+                      className="z-1 justify-self-start"
+                    >
+                      {`${pad(month)}.${pad(day)}`}
+                    </Tag>
+                  );
+                }
+                // 被前一个日期块压住的那一格不写日号
+                const covered =
+                  position > 0 && anchors.has(dates[position - 1]!);
+                return (
+                  <span
+                    key={date}
+                    className="text-center font-tech text-micro text-ink-tertiary tabular-nums"
+                  >
+                    {covered ? null : dateParts(date).day}
+                  </span>
+                );
+              })}
+            </div>
+          </div>
+
+          <div className="relative flex flex-col gap-1 pt-1">{children}</div>
+
+          {/* 今天：一条竖线，画在条目上面 */}
+          {todayColumn !== null && (
+            <div
+              aria-hidden="true"
+              className={cn(
+                decor,
+                "absolute inset-y-0 right-0 z-2",
+                AFTER_RAIL,
+                dayColumns,
+              )}
+            >
+              <span
+                data-today=""
+                style={{ gridColumn: todayColumn }}
+                className="row-start-1 border-l-2 border-accent-ink"
+              />
+            </div>
+          )}
+        </div>
+      </div>
+    </ScheduleContext>
+  );
+}
+
+export type ScheduleTrackProps = Omit<
+  ComponentProps<"section">,
+  "aria-label"
+> & {
+  /** 类目的名称：竖轨上的字，也是这条轨的可访问名称 */
+  label: string;
+  /** 竖轨上的图标 */
+  icon?: ReactNode;
+  /** 直接放 `ScheduleItem` */
+  children?: ReactNode;
+};
+
+/**
+ * 一条轨：一个类目的条目排在一行里，时间重叠的自动错到下一行。
+ * 竖轨的颜色用 `className="[--track-color:…] [--track-ink:…]"` 换。
+ */
+export function ScheduleTrack({
+  label,
+  icon,
+  className,
+  children,
+  ...props
+}: ScheduleTrackProps) {
+  useSchedule("ScheduleTrack");
+
+  return (
+    <section
+      {...props}
+      aria-label={label}
+      className={cn(
+        "flex [--track-color:var(--ef-surface-inverse)] [--track-ink:var(--ef-ink-inverse)]",
+        className,
+      )}
+    >
+      {/* 竖轨冻结在左边：底不透明，滚过去的条目才不会透出来 */}
+      <div
+        aria-hidden="true"
+        className={cn(
+          "sticky left-0 z-3 flex shrink-0 flex-col items-center gap-2 bg-(--track-color) py-2 text-(--track-ink)",
+          // 和右边的条目之间留一条表面色的缝
+          "border-r-4 border-(--schedule-surface)",
+          RAIL,
+        )}
+      >
+        {icon && (
+          <span className="flex size-4 shrink-0 items-center justify-center [&_svg]:size-4">
+            {icon}
+          </span>
+        )}
+        <span className="text-xs leading-none font-medium tracking-label [writing-mode:vertical-rl]">
+          {label}
+        </span>
+      </div>
+      <ul
+        className={cn(
+          "min-h-12 flex-1 grid-flow-row-dense auto-rows-[3rem] gap-y-1",
+          dayColumns,
+        )}
+      >
+        {children}
+      </ul>
+    </section>
+  );
+}
+
+export type ScheduleItemVariant = "banner" | "system";
+
+type ItemOwnProps = {
+  /** 第一天，`YYYY-MM-DD` */
+  start: string;
+  /** 最后一天（包含） */
+  end: string;
+  /** 名称 */
+  title: ReactNode;
+  /** 类型小标签：右上角的白底描边小块。只有 `banner` 有 */
+  type?: ReactNode;
+  /**
+   * - `banner` 活动：浅底，可以垫一张图，左上是墨色的名称块，默认；
+   * - `system` 系统类：炭灰底 + 行动色侧签 + 一条虚线，不带图。
+   */
+  variant?: ScheduleItemVariant;
+  /** 垫在条目下面的图，铺满并裁切。只有 `banner` 有 */
+  media?: ReactNode;
+  /** 传了名称就是一个链接，点击范围铺满整个条目 */
+  href?: string;
+  target?: string;
+  rel?: string;
+  /** 用这个元素代替 `<a>`（路由库的链接组件）。传了就按链接处理 */
+  render?: LinkRender;
+  onClick?: (event: MouseEvent<HTMLElement>) => void;
+};
+
+export type ScheduleItemProps = ItemOwnProps &
+  Omit<ComponentProps<"li">, keyof ItemOwnProps | "children">;
+
+/** 排期里的一个条目。直接放在 `ScheduleTrack` 里。 */
+export function ScheduleItem({
+  start,
+  end,
+  title,
+  type,
+  variant = "banner",
+  media,
+  href,
+  target,
+  rel,
+  render,
+  onClick,
+  className,
+  style,
+  ...props
+}: ScheduleItemProps) {
+  const schedule = useSchedule("ScheduleItem");
+  const first = daysBetween(schedule.start, start);
+  const last = daysBetween(schedule.start, end);
+  // 整个都在范围外：不画
+  if (last < 0 || first >= schedule.days || last < first) return null;
+
+  // 超出范围的两头裁到范围内
+  const from = Math.max(first, 0) + 1;
+  const to = Math.min(last, schedule.days - 1) + 2;
+  const isLink = href !== undefined || render !== undefined;
+  const banner = variant === "banner";
+
+  const name = isLink ? (
+    <LinkElement
+      render={render}
+      href={href}
+      target={target}
+      rel={rel}
+      onClick={onClick}
+      // 点击范围铺满整个条目；焦点环画在条目上
+      className="outline-none after:absolute after:inset-0 after:content-['']"
+    >
+      {title}
+    </LinkElement>
+  ) : (
+    title
+  );
+
+  return (
+    <li
+      {...props}
+      data-variant={variant}
+      data-clipped-start={first < 0 ? "" : undefined}
+      data-clipped-end={last >= schedule.days ? "" : undefined}
+      style={{ gridColumn: `${from} / ${to}`, ...style }}
+      className={cn(
+        // 条目自己是一个容器：窄到放不下类型标签时把它收掉
+        "@container relative isolate flex min-w-0 overflow-clip text-sm",
+        "has-focus-visible:outline-2 has-focus-visible:-outline-offset-2 has-focus-visible:outline-focus",
+        banner
+          ? "items-start justify-between gap-2 bg-surface-muted p-2"
+          : // 系统类条目在两个主题下都是炭灰底：control 系列本来就不随主题变
+            "items-center gap-2 bg-control pr-2 text-on-control",
+        className,
+      )}
+    >
+      {banner ? (
+        <>
+          {media && (
+            <div
+              aria-hidden="true"
+              className="absolute inset-0 -z-10 *:size-full *:object-cover"
+            >
+              {media}
+            </div>
+          )}
+          <span className="flex h-6 max-w-full min-w-0 items-center bg-surface-inverse px-2 font-medium text-ink-inverse">
+            <span className="truncate">{name}</span>
+          </span>
+          {type && (
+            <Tag variant="outline" size="sm" className="@max-[10rem]:hidden">
+              {type}
+            </Tag>
+          )}
+        </>
+      ) : (
+        <>
+          <span
+            aria-hidden="true"
+            className="w-1.5 shrink-0 self-stretch bg-action"
+          />
+          <span className="min-w-0 truncate font-medium">{name}</span>
+          <span
+            aria-hidden="true"
+            className="min-w-4 flex-1 border-t border-dashed border-action"
+          />
+        </>
+      )}
+      <span className="sr-only">{`，${schedule.describe(start, end)}`}</span>
+    </li>
+  );
+}

package/src/components/schedule/index.ts

@@ -0,0 +1,9 @@
+export {
+  Schedule,
+  ScheduleItem,
+  ScheduleTrack,
+  type ScheduleItemProps,
+  type ScheduleItemVariant,
+  type ScheduleProps,
+  type ScheduleTrackProps,
+} from "./Schedule";

package/src/components/scroll-area/ScrollArea.tsx

@@ -0,0 +1,137 @@
+import { ScrollArea as BaseScrollArea } from "@base-ui/react/scroll-area";
+import type { ComponentProps, CSSProperties, Ref } from "react";
+import { cn } from "../../lib/cn";
+import { focusRingInset } from "../../lib/focus-ring";
+
+export type ScrollAreaOrientation = "vertical" | "horizontal" | "both";
+
+export type ScrollAreaProps = Omit<
+  ComponentProps<"div">,
+  "aria-label" | "className" | "style" | "ref"
+> & {
+  /** 这一块是什么。能滚的时候它是一个能聚焦的区域，读屏听到的就是这个名称 */
+  "aria-label": string;
+  /** 哪个方向能滚，默认 `vertical`。只管一个方向时，另一个方向滚不了 */
+  orientation?: ScrollAreaOrientation;
+  /** 真正在滚的那个元素：给页内目录、回到顶部的 `target` */
+  viewportRef?: Ref<HTMLDivElement>;
+  /** 给外框：高度或者高度上限写在这里 */
+  className?: string;
+  style?: CSSProperties;
+  /** 给外框 */
+  ref?: Ref<HTMLDivElement>;
+};
+
+/*
+ * 滚动条：12px 宽的一条是能抓、能点的范围；正中一条 1px 的轨，
+ * 滑块是压在轨上的一段 3px 的粗条——和页内目录、侧轨二级的引线是同一个画法
+ */
+const barClass: Record<"vertical" | "horizontal", string> = {
+  vertical:
+    "w-3 before:absolute before:inset-y-0 before:left-1/2 before:w-px before:-translate-x-1/2 before:bg-line",
+  horizontal:
+    "h-3 before:absolute before:inset-x-0 before:top-1/2 before:h-px before:-translate-y-1/2 before:bg-line",
+};
+
+const thumbClass: Record<"vertical" | "horizontal", string> = {
+  vertical:
+    "w-full before:inset-y-0 before:left-1/2 before:w-[3px] before:-translate-x-1/2",
+  horizontal:
+    "h-full before:inset-x-0 before:top-1/2 before:h-[3px] before:-translate-y-1/2",
+};
+
+function Scrollbar({
+  orientation,
+}: {
+  orientation: "vertical" | "horizontal";
+}) {
+  return (
+    <BaseScrollArea.Scrollbar
+      orientation={orientation}
+      className={cn("group/bar flex", barClass[orientation])}
+    >
+      <BaseScrollArea.Thumb
+        className={cn(
+          "relative before:absolute before:bg-ink-secondary before:content-['']",
+          "before:transition-colors before:duration-(--duration-fast) before:ease-standard",
+          "group-hover/bar:before:bg-ink active:before:bg-ink",
+          // 高对比模式下背景色会被系统拿掉：换成系统的文字色，滑块才看得见
+          "forced-colors:before:bg-[CanvasText]",
+          thumbClass[orientation],
+        )}
+      />
+    </BaseScrollArea.Scrollbar>
+  );
+}
+
+/**
+ * 滚动区：一块自己能滚的区域，滚动条是画出来的。高度（或高度上限）由 `className` 给。
+ * 只有真的溢出时才有滚动条，也才是一个能聚焦的区域。
+ *
+ * 整页的滚动留给浏览器，不要把页面主体包进来。
+ * `className` 与 `ref` 给外框，其余属性（`onScroll` 等）给真正在滚的可视区。
+ */
+export function ScrollArea({
+  "aria-label": label,
+  orientation = "vertical",
+  viewportRef,
+  className,
+  style,
+  ref,
+  children,
+  ...props
+}: ScrollAreaProps) {
+  const vertical = orientation !== "horizontal";
+  const horizontal = orientation !== "vertical";
+
+  return (
+    <BaseScrollArea.Root
+      ref={ref}
+      style={style}
+      data-scroll-area=""
+      data-orientation={orientation}
+      // 给了高度上限时内容短就跟着矮：外框是一个竖排的弹性容器，可视区在里面收缩
+      className={cn("flex min-h-0 min-w-0 flex-col text-ink", className)}
+    >
+      <BaseScrollArea.Viewport
+        {...props}
+        ref={viewportRef}
+        // 不管的那个方向不让滚（基元默认两个方向都是 scroll）
+        style={
+          orientation === "vertical"
+            ? { overflowX: "hidden" }
+            : orientation === "horizontal"
+              ? { overflowY: "hidden" }
+              : undefined
+        }
+        className={cn(
+          "min-h-0 flex-auto",
+          focusRingInset,
+          // 溢出的那一侧让出滚动条的位置，内容不会被压住。让的是可视区自己的外边距：
+          // 写成内边距的话，它在滚动容器里是"滚到头才有的留白"，途中内容照样被压住
+          vertical && "data-has-overflow-y:mr-3",
+          horizontal && "data-has-overflow-x:mb-3",
+        )}
+        render={(viewportProps, state) => {
+          const scrollable =
+            (vertical && state.hasOverflowY) ||
+            (horizontal && state.hasOverflowX);
+          return (
+            <div
+              {...viewportProps}
+              // 只有真的能滚时才是一个有名称、能聚焦的区域：键盘要能滚它，
+              // 但不溢出的时候不该白占一个 Tab 停靠点
+              {...(scrollable && { role: "region", "aria-label": label })}
+              tabIndex={scrollable ? 0 : -1}
+            />
+          );
+        }}
+      >
+        <BaseScrollArea.Content>{children}</BaseScrollArea.Content>
+      </BaseScrollArea.Viewport>
+      {vertical && <Scrollbar orientation="vertical" />}
+      {horizontal && <Scrollbar orientation="horizontal" />}
+      {orientation === "both" && <BaseScrollArea.Corner />}
+    </BaseScrollArea.Root>
+  );
+}

package/src/components/scroll-area/index.ts

@@ -0,0 +1,5 @@
+export {
+  ScrollArea,
+  type ScrollAreaOrientation,
+  type ScrollAreaProps,
+} from "./ScrollArea";

package/src/components/scroll-hint/ScrollHint.tsx

@@ -0,0 +1,78 @@
+import {
+  useCallback,
+  type ComponentProps,
+  type ReactNode,
+  type RefObject,
+} from "react";
+import {
+  useScrollPosition,
+  type ScrollMetrics,
+} from "../../hooks/useScrollPosition";
+import { ChevronDown } from "../../icons/ChevronDown";
+import { cn } from "../../lib/cn";
+
+export type ScrollHintVariant = "line" | "chevron";
+
+export type ScrollHintProps = Omit<ComponentProps<"div">, "children"> & {
+  /** 上方的小字，默认 `SCROLL` */
+  label?: ReactNode;
+  /**
+   * - `line` 一条细竖线 + 一个下坠的光点，默认；
+   * - `chevron` 一个下坠的折线箭头，窄屏用。
+   */
+  variant?: ScrollHintVariant;
+  /** 看哪个滚动容器。不传就是整个页面 */
+  target?: RefObject<HTMLElement | null>;
+  /** 滚过多少像素算"已经开始滚动"，默认 8 */
+  threshold?: number;
+};
+
+/**
+ * 滚动提示：只在确实还能往下滚、并且还没开始滚的时候出现，滚动开始后淡出。
+ * 纯装饰，对读屏隐藏；位置由使用方定（首屏底部居中或右下）。
+ */
+export function ScrollHint({
+  label = "SCROLL",
+  variant = "line",
+  target,
+  threshold = 8,
+  className,
+  ...props
+}: ScrollHintProps) {
+  // 确实还能往下滚，并且还没开始滚。指定了容器但它还没挂上时不显示
+  const stillAtTop = useCallback(
+    ({ scrolled, room }: ScrollMetrics) =>
+      room > threshold && scrolled <= threshold,
+    [threshold],
+  );
+  const visible = useScrollPosition(target, stillAtTop, false);
+
+  return (
+    <div
+      aria-hidden="true"
+      {...props}
+      data-visible={visible ? "" : undefined}
+      className={cn(
+        "pointer-events-none inline-flex flex-col items-center gap-2 text-ink-secondary",
+        "transition-opacity duration-(--duration-base) ease-standard",
+        visible ? "opacity-100" : "opacity-0",
+        className,
+      )}
+    >
+      <span className="font-tech text-micro tracking-label uppercase">
+        {label}
+      </span>
+      {variant === "line" ? (
+        <span className="relative h-10 w-px bg-line-strong">
+          {/* 光点骑在线上：6px 的点对 1px 的线，向左偏 2.5px */}
+          <span className="absolute top-0 -left-[2.5px] size-1.5 animate-scroll-hint rounded-full bg-accent-ink" />
+        </span>
+      ) : (
+        <ChevronDown
+          size={16}
+          className="animate-scroll-hint text-accent-ink"
+        />
+      )}
+    </div>
+  );
+}

package/src/components/scroll-hint/index.ts

@@ -0,0 +1,5 @@
+export {
+  ScrollHint,
+  type ScrollHintProps,
+  type ScrollHintVariant,
+} from "./ScrollHint";