@endfield-ui/react 0.0.0-stage → 0.2.0

package/src/components/countdown/Countdown.tsx

@@ -0,0 +1,145 @@
+import {
+  useEffect,
+  useRef,
+  useState,
+  type ComponentProps,
+  type ReactNode,
+} from "react";
+import { cn } from "../../lib/cn";
+
+export type CountdownSize = "sm" | "md";
+export type CountdownState = "ample" | "urgent" | "expired";
+
+export type CountdownProps = Omit<ComponentProps<"span">, "children"> & {
+  /** 截止时间：`Date`、时间戳或能被 `new Date()` 解析的字符串 */
+  to: Date | number | string;
+  /** 剩余时间不多于这个毫秒数时进入紧迫态，默认 24 小时 */
+  urgentWithin?: number;
+  /** 到期后显示的文字 */
+  expiredLabel?: ReactNode;
+  /** 到期的那一刻调用一次；挂载时就已过期则不调用 */
+  onExpire?: () => void;
+  /** 超过一天时"天"的写法，如 `3天 04:12:09` */
+  dayUnit?: string;
+  /** 给读屏的静态截止时间。默认是"截止 + 本地格式的日期时间" */
+  deadlineLabel?: ReactNode;
+  size?: CountdownSize;
+};
+
+const DAY = 86_400_000;
+
+const sizeClass: Record<CountdownSize, string> = {
+  sm: "h-5 gap-1 px-2 text-xs",
+  md: "h-7 gap-1.5 px-3 text-sm",
+};
+
+/*
+ * 状态色用文字档的语义令牌作底、ink-inverse 作字：两个主题下都 ≥ 4.5:1。
+ * 角色色里的 alert 红作底时，墨字白字都不够。
+ */
+const stateClass: Record<CountdownState, string> = {
+  ample: "bg-success text-ink-inverse",
+  urgent: "bg-danger text-ink-inverse",
+  expired: "bg-surface-muted text-ink-secondary",
+};
+
+function pad(value: number) {
+  return String(value).padStart(2, "0");
+}
+
+function format(remaining: number, dayUnit: string) {
+  const seconds = Math.ceil(remaining / 1000);
+  const days = Math.floor(seconds / 86_400);
+  const clock = [
+    Math.floor((seconds % 86_400) / 3600),
+    Math.floor((seconds % 3600) / 60),
+    seconds % 60,
+  ]
+    .map(pad)
+    .join(":");
+  return days > 0 ? `${days}${dayUnit} ${clock}` : clock;
+}
+
+/**
+ * 倒计时：充裕时是绿色胶囊，紧迫时变红并多一个 `!`。
+ * 不会每秒播报——读屏拿到的是静态的截止时间，走到这里时才读当前剩余。
+ */
+export function Countdown({
+  to,
+  urgentWithin = DAY,
+  expiredLabel = "已结束",
+  onExpire,
+  dayUnit = "天",
+  deadlineLabel,
+  size = "md",
+  className,
+  ...props
+}: CountdownProps) {
+  const target = new Date(to).getTime();
+  const [now, setNow] = useState(() => Date.now());
+
+  useEffect(() => {
+    setNow(Date.now());
+    if (!(target > Date.now())) return;
+
+    const timer = setInterval(() => {
+      const current = Date.now();
+      setNow(current);
+      if (current >= target) clearInterval(timer);
+    }, 1000);
+    return () => clearInterval(timer);
+  }, [target]);
+
+  const remaining = Number.isNaN(target) ? 0 : Math.max(0, target - now);
+  const state: CountdownState =
+    remaining === 0
+      ? "expired"
+      : remaining <= urgentWithin
+        ? "urgent"
+        : "ample";
+
+  const onExpireRef = useRef(onExpire);
+  const previous = useRef(state);
+  useEffect(() => {
+    onExpireRef.current = onExpire;
+  });
+  useEffect(() => {
+    if (state === "expired" && previous.current !== "expired") {
+      onExpireRef.current?.();
+    }
+    previous.current = state;
+  }, [state]);
+
+  const valid = !Number.isNaN(target);
+
+  return (
+    <span
+      {...props}
+      data-state={state}
+      className={cn(
+        "inline-flex shrink-0 items-center rounded-full font-tech leading-none font-bold whitespace-nowrap tabular-nums",
+        sizeClass[size],
+        stateClass[state],
+        className,
+      )}
+    >
+      {state === "urgent" && <span aria-hidden="true">!</span>}
+      {/* 本地时间在服务端和浏览器里可能不同，这两处不做水合校验 */}
+      <span role="timer" aria-live="off" suppressHydrationWarning>
+        {state === "expired" ? expiredLabel : format(remaining, dayUnit)}
+      </span>
+      {valid && (
+        <span className="sr-only" suppressHydrationWarning>
+          {deadlineLabel ?? (
+            <>
+              截止{" "}
+              <time dateTime={new Date(target).toISOString()}>
+                {new Date(target).toLocaleString()}
+              </time>
+            </>
+          )}
+        </span>
+      )}
+    </span>
+  );
+}

package/src/components/countdown/index.ts

@@ -0,0 +1,6 @@
+export {
+  Countdown,
+  type CountdownProps,
+  type CountdownSize,
+  type CountdownState,
+} from "./Countdown";

package/src/components/dash-indicator/DashIndicator.tsx

@@ -0,0 +1,44 @@
+import type { ComponentProps } from "react";
+import { cn } from "../../lib/cn";
+
+export type DashIndicatorProps = Omit<ComponentProps<"span">, "children"> & {
+  /** 一共几项 */
+  count: number;
+  /** 当前是第几项，从 0 起 */
+  index: number;
+};
+
+/**
+ * 进度短横：一排短横线表示"共几项、在第几项"。只做指示，不可点击；
+ * 要能翻动，旁边配一个 `Navigator` 或一对翻页钮。
+ */
+export function DashIndicator({
+  count,
+  index,
+  className,
+  ...props
+}: DashIndicatorProps) {
+  const total = Math.max(0, Math.floor(count));
+  const current = Math.min(Math.max(Math.floor(index), 0), total - 1);
+
+  return (
+    <span
+      role="img"
+      aria-label={`第 ${current + 1} 项，共 ${total} 项`}
+      {...props}
+      className={cn("inline-flex items-center gap-1", className)}
+    >
+      {Array.from({ length: total }, (_, position) => (
+        <span
+          key={position}
+          data-current={position === current ? "" : undefined}
+          className={cn(
+            "h-0.5 transition-[width,background-color] duration-(--duration-base) ease-standard",
+            // 当前一根除了换色还加长一倍，不只靠颜色
+            position === current ? "w-8 bg-accent-ink" : "w-4 bg-line-strong",
+          )}
+        />
+      ))}
+    </span>
+  );
+}

package/src/components/dash-indicator/index.ts

@@ -0,0 +1 @@
+export { DashIndicator, type DashIndicatorProps } from "./DashIndicator";

package/src/components/data-row/DataRow.tsx

@@ -0,0 +1,282 @@
+import {
+  createContext,
+  useContext,
+  type ComponentProps,
+  type CSSProperties,
+  type ReactNode,
+} from "react";
+import { cn } from "../../lib/cn";
+import { focusRing } from "../../lib/focus-ring";
+import { bandCanvas, bandGap, bandRow } from "../list/band-style";
+import { Sparkline } from "../sparkline/Sparkline";
+
+export type DataRowColumns = {
+  /** 名称那一列的列名 */
+  name: ReactNode;
+  /** 走势列的列名。不给就没有这一列 */
+  trend?: ReactNode;
+  /** 当前值那一列的列名 */
+  value: ReactNode;
+  /** 参考值列的列名。不给就没有这一列 */
+  reference?: ReactNode;
+};
+
+export type DataRowListProps = Omit<ComponentProps<"div">, "children"> & {
+  /** 这张表的名称，读屏会读出来 */
+  label?: string;
+  /** 各列的列名；有没有走势列、参考值列也由它决定 */
+  columns: DataRowColumns;
+  /** `DataRow` */
+  children: ReactNode;
+};
+
+type Layout = { trend: boolean; reference: boolean };
+
+const LayoutContext = createContext<Layout>({ trend: false, reference: false });
+
+/*
+ * 列的模板。容器变窄时先收起走势列（@lg 以下），再收起参考值列（@sm 以下）；
+ * 对应的单元格用 hidden 收起，模板跟着少一列。
+ */
+const NARROW = "grid-cols-[minmax(0,1fr)_auto]";
+const columnsClass = (layout: Layout) =>
+  cn(
+    NARROW,
+    layout.reference && "@sm:grid-cols-[minmax(0,1fr)_auto_auto]",
+    layout.trend &&
+      (layout.reference
+        ? "@lg:grid-cols-[minmax(0,1.2fr)_minmax(0,1fr)_auto_auto]"
+        : "@lg:grid-cols-[minmax(0,1.2fr)_minmax(0,1fr)_auto]"),
+  );
+
+const trendCell = "hidden @lg:block";
+const referenceCell = "hidden @sm:block";
+
+/* 每一行（连同列头）都是一个子网格：对齐到表格的那一组列 */
+const rowGrid = "col-span-full grid grid-cols-subgrid items-center gap-x-4";
+
+/*
+ * 列名之间的短竖线画在单元格左边的缝里。截断写在里面那一层上：
+ * 写在单元格自己身上的话，overflow 会把竖线一起裁掉。
+ */
+const headerCell =
+  "relative min-w-0 not-first:before:absolute not-first:before:top-1/2 not-first:before:-left-2 not-first:before:h-3 not-first:before:w-px not-first:before:-translate-y-1/2 not-first:before:bg-line-strong not-first:before:content-['']";
+
+function HeaderCell({
+  className,
+  children,
+}: {
+  className?: string;
+  children: ReactNode;
+}) {
+  return (
+    <span role="columnheader" className={cn(headerCell, className)}>
+      <span className="block truncate">{children}</span>
+    </span>
+  );
+}
+
+/**
+ * 数据行带：浅色画布上一条条深色的行，上面一条胶囊形的列头。
+ * 语义是一张表格；里面只放 `DataRow`。
+ */
+export function DataRowList({
+  label,
+  columns,
+  className,
+  children,
+  ...props
+}: DataRowListProps) {
+  const layout: Layout = {
+    trend: columns.trend !== undefined,
+    reference: columns.reference !== undefined,
+  };
+
+  return (
+    <div
+      {...props}
+      className={cn("@container text-ink", bandCanvas, className)}
+    >
+      <div
+        role="table"
+        aria-label={label}
+        className={cn("grid", bandGap, columnsClass(layout))}
+      >
+        <div
+          role="row"
+          className={cn(
+            rowGrid,
+            // 透明的边线：数据行有一圈 1px 的线，列头也占上这 1px，两边的文字才对得齐
+            "min-h-6 rounded-full border border-transparent bg-surface-muted pr-3 pl-4 text-xs",
+          )}
+        >
+          <HeaderCell>{columns.name}</HeaderCell>
+          {layout.trend && (
+            <HeaderCell className={trendCell}>{columns.trend}</HeaderCell>
+          )}
+          <HeaderCell className="text-right">{columns.value}</HeaderCell>
+          {layout.reference && (
+            <HeaderCell className={cn(referenceCell, "text-right")}>
+              {columns.reference}
+            </HeaderCell>
+          )}
+        </div>
+        <LayoutContext value={layout}>{children}</LayoutContext>
+      </div>
+    </div>
+  );
+}
+
+export type DataRowTone = "neutral" | "info" | "accent" | "danger";
+
+export type DataRowProps = Omit<ComponentProps<"div">, "children"> & {
+  /** 这一行的名称 */
+  name: ReactNode;
+  /**
+   * 左缘的类目色条：一个 CSS 颜色值，通常传令牌变量（`var(--color-special)`）。
+   * 不要用黄色——黄色是"选中"和"收藏"
+   */
+  categoryColor?: string;
+  /** 收藏。只传它是一个静态的标记；同时传 `onFavoriteChange` 才是一个能点的切换按钮 */
+  favorite?: boolean;
+  onFavoriteChange?: (favorite: boolean) => void;
+  /** 收藏按钮的可访问名称，默认"收藏" */
+  favoriteLabel?: string;
+  /** 走势：一串数值，画成行内的小型面积图。表头没有走势列时不显示 */
+  series?: readonly number[];
+  /** 当前值。正负号连同数值一起传：颜色之外还要有符号 */
+  value: ReactNode;
+  /**
+   * 当前值的含义：
+   * - `info` 产出、正向（蓝）；
+   * - `accent` 消耗、关注（黄）；
+   * - `danger` 超支、异常（红），走势图也跟着变红；
+   * - `neutral` 不表态，默认。
+   */
+  tone?: DataRowTone;
+  /** 参考值（理论值、上限）。表头没有参考值列时不显示 */
+  reference?: ReactNode;
+};
+
+/* 行是局部暗色主题：这几档文字色按深色底取值，对比度都在 4.5:1 以上 */
+const toneClass: Record<DataRowTone, string> = {
+  neutral: "text-ink",
+  info: "text-info",
+  accent: "text-accent-ink",
+  danger: "text-danger",
+};
+
+const favoriteDot = "block size-4 rounded-full";
+const favoriteOn = "bg-action";
+/* 未收藏是一个空心的圆环：形状也不同，不只靠颜色 */
+const favoriteOff = "border-2 border-ink-tertiary";
+
+/** 数据行带里的一行。放在 `DataRowList` 里。 */
+export function DataRow({
+  name,
+  categoryColor,
+  favorite,
+  onFavoriteChange,
+  favoriteLabel = "收藏",
+  series,
+  value,
+  tone = "neutral",
+  reference,
+  className,
+  style,
+  ...props
+}: DataRowProps) {
+  const layout = useContext(LayoutContext);
+  const hasFavorite = favorite !== undefined || onFavoriteChange !== undefined;
+  const dotClass = cn(favoriteDot, favorite ? favoriteOn : favoriteOff);
+
+  return (
+    <div
+      role="row"
+      // 固定的深色：行里的文字、焦点环都按深色底取值
+      data-theme="dark"
+      data-tone={tone}
+      data-favorite={favorite ? "" : undefined}
+      {...props}
+      style={
+        categoryColor
+          ? ({
+              "--data-row-category": categoryColor,
+              ...style,
+            } as CSSProperties)
+          : style
+      }
+      className={cn(rowGrid, bandRow, "relative min-h-11 pr-3 pl-4", className)}
+    >
+      {categoryColor && (
+        <span
+          aria-hidden="true"
+          data-category=""
+          className="absolute inset-y-0 left-0 w-1 bg-(--data-row-category)"
+        />
+      )}
+
+      <div role="rowheader" className="flex min-w-0 items-center gap-2.5">
+        {hasFavorite &&
+          (onFavoriteChange ? (
+            <button
+              type="button"
+              aria-label={favoriteLabel}
+              aria-pressed={favorite ?? false}
+              onClick={() => onFavoriteChange(!favorite)}
+              // 圆只有 16px，点击区用伪元素向外补到 36px
+              className={cn(
+                "relative shrink-0 rounded-full after:absolute after:-inset-2.5 after:content-['']",
+                focusRing,
+              )}
+            >
+              <span className={dotClass} />
+            </button>
+          ) : (
+            <span aria-hidden="true" className={cn(dotClass, "shrink-0")} />
+          ))}
+        <span className="min-w-0 truncate">
+          {name}
+          {favorite && !onFavoriteChange && (
+            <span className="sr-only">（已收藏）</span>
+          )}
+        </span>
+      </div>
+
+      {layout.trend && (
+        <div role="cell" className={cn(trendCell, "h-8")}>
+          {series && (
+            <Sparkline
+              data={series}
+              // 量值图表归蓝；只有这一行异常时换成红
+              tone={tone === "danger" ? "danger" : "info"}
+              className="h-full"
+            />
+          )}
+        </div>
+      )}
+
+      <div
+        role="cell"
+        className={cn(
+          "text-right font-tech font-bold whitespace-nowrap tabular-nums",
+          toneClass[tone],
+        )}
+      >
+        {value}
+      </div>
+
+      {layout.reference && (
+        <div
+          role="cell"
+          className={cn(
+            referenceCell,
+            "text-right font-tech whitespace-nowrap text-ink-secondary tabular-nums",
+          )}
+        >
+          {reference}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/data-row/index.ts

@@ -0,0 +1,8 @@
+export {
+  DataRow,
+  DataRowList,
+  type DataRowColumns,
+  type DataRowListProps,
+  type DataRowProps,
+  type DataRowTone,
+} from "./DataRow";

package/src/components/date-picker/DateField.tsx

@@ -0,0 +1,159 @@
+import { Popover as BasePopover } from "@base-ui/react/popover";
+import { useRef, type ReactNode, type Ref } from "react";
+import { usePortalScope } from "../../hooks/usePortalScope";
+import { CalendarIcon } from "../../icons/CalendarIcon";
+import { StatusDanger } from "../../icons/StatusDanger";
+import { cn } from "../../lib/cn";
+import { focusRing } from "../../lib/focus-ring";
+import { menuPanel } from "../dropdown-menu/menu-style";
+import {
+  controlBox,
+  controlIconSize,
+  controlSize,
+  type ControlSize,
+  type ControlVariant,
+} from "../input/control-box";
+
+/*
+ * 日期选择和日期范围共用的那层壳：输入框的外框 + 一个按钮 + 一块气泡面板。
+ * 不对外导出。面板里放什么（月历、底下那一行）由两个控件各自给。
+ */
+
+/** 和日期块、微标行同一种写法：`2026.10.09` */
+export const dottedDate = (date: string) => date.replaceAll("-", ".");
+
+/** 面板底下那一行里的文字钮 */
+export const dateFooterButton = cn(
+  "px-2 py-1 text-sm font-medium text-ink underline underline-offset-4 hover:text-ink-secondary",
+  "disabled:cursor-not-allowed disabled:text-ink-disabled disabled:no-underline",
+  focusRing,
+);
+
+export type DateFieldProps = {
+  /** 外框里显示的值；没选时传 `null`，显示 `placeholder` */
+  display: ReactNode | null;
+  placeholder: ReactNode;
+  /** 随表单提交用的隐藏字段 */
+  fields?: ReactNode;
+  variant: ControlVariant;
+  size: ControlSize;
+  invalid: boolean;
+  disabled: boolean;
+  required: boolean;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** 面板的可访问名称 */
+  panelLabel: string;
+  id?: string;
+  "aria-label"?: string;
+  "aria-describedby"?: string;
+  /** 给外框 */
+  className?: string;
+  /** 给触发按钮 */
+  ref?: Ref<HTMLButtonElement>;
+  /** 面板里的东西 */
+  children: ReactNode;
+};
+
+export function DateField({
+  display,
+  placeholder,
+  fields,
+  variant,
+  size,
+  invalid,
+  disabled,
+  required,
+  open,
+  onOpenChange,
+  panelLabel,
+  id,
+  "aria-label": ariaLabel,
+  "aria-describedby": describedBy,
+  className,
+  ref,
+  children,
+}: DateFieldProps) {
+  const { anchorRef, portalRef } = usePortalScope();
+  const boxRef = useRef<HTMLDivElement>(null);
+  const popupRef = useRef<HTMLDivElement>(null);
+  const iconSize = controlIconSize[size];
+
+  return (
+    <BasePopover.Root open={open} onOpenChange={(next) => onOpenChange(next)}>
+      <div
+        ref={(node) => {
+          boxRef.current = node;
+          anchorRef(node);
+        }}
+        data-variant={variant}
+        data-size={size}
+        data-invalid={invalid ? "" : undefined}
+        className={cn(
+          controlBox({ variant, invalid, disabled, readOnly: false }),
+          // 面板开着的时候边线保持聚焦的墨色
+          !disabled && !invalid && "has-data-popup-open:border-ink",
+          controlSize[size],
+          className,
+        )}
+      >
+        <BasePopover.Trigger
+          ref={ref}
+          id={id}
+          disabled={disabled}
+          aria-label={ariaLabel}
+          aria-invalid={invalid || undefined}
+          aria-required={required || undefined}
+          aria-describedby={describedBy}
+          className="flex h-full min-w-0 flex-1 cursor-default items-center gap-2 px-3 text-left outline-none disabled:cursor-not-allowed"
+        >
+          {display === null ? (
+            <span className="min-w-0 flex-1 truncate text-ink-tertiary">
+              {placeholder}
+            </span>
+          ) : (
+            <span className="min-w-0 flex-1 truncate font-tech tabular-nums">
+              {display}
+            </span>
+          )}
+          {invalid && (
+            <StatusDanger size={iconSize} className="shrink-0 text-danger" />
+          )}
+          <CalendarIcon
+            size={iconSize}
+            className={cn(
+              "shrink-0",
+              disabled ? "text-ink-disabled" : "text-ink-secondary",
+            )}
+          />
+        </BasePopover.Trigger>
+        {fields}
+      </div>
+
+      <BasePopover.Portal ref={portalRef}>
+        <BasePopover.Positioner
+          // 面板对着外框落位，不是对着里面的按钮：否则差出一条边线的宽度
+          anchor={boxRef}
+          side="bottom"
+          align="start"
+          sideOffset={4}
+          className="z-(--z-overlay) outline-none"
+        >
+          <BasePopover.Popup
+            ref={popupRef}
+            aria-label={panelLabel}
+            // 打开时焦点落在月历里能被 Tab 停到的那一天：选中的，没选时是今天
+            initialFocus={() =>
+              popupRef.current?.querySelector<HTMLElement>(
+                '[data-date][tabindex="0"]',
+              ) ?? true
+            }
+            className={cn(menuPanel, "flex flex-col gap-2 p-2")}
+          >
+            {children}
+          </BasePopover.Popup>
+        </BasePopover.Positioner>
+      </BasePopover.Portal>
+    </BasePopover.Root>
+  );
+}