@endfield-ui/react 0.0.0-stage → 0.2.0

package/src/components/slider/Slider.tsx

@@ -0,0 +1,219 @@
+import { Slider as BaseSlider } from "@base-ui/react/slider";
+import { useMemo, type ReactNode } from "react";
+import { cn } from "../../lib/cn";
+import { focusRingWithin } from "../../lib/focus-ring";
+import { useFieldContext, useFieldControl } from "../field/Field";
+
+export type SliderSize = "sm" | "md";
+
+export type SliderMark = {
+  value: number;
+  /** 刻度下面的标注；不传就只有一条短线 */
+  label?: ReactNode;
+};
+
+type SliderCommonProps = {
+  /** 下限，默认 0 */
+  min?: number;
+  /** 上限，默认 100 */
+  max?: number;
+  /** 一步走多少，默认 1 */
+  step?: number;
+  /** `PageUp` / `PageDown`、`Shift` + 方向键一次走多少，默认 10 */
+  largeStep?: number;
+  /** 整个控件占 32 / 40px 高，默认 `md` */
+  size?: SliderSize;
+  /** 在右侧显示当前值 */
+  showValue?: boolean;
+  /** 数值怎么写：`Intl.NumberFormat` 的选项（百分比、单位、小数位） */
+  format?: Intl.NumberFormatOptions;
+  /** 轨道下面的刻度。只是标注，不改变步长 */
+  marks?: readonly SliderMark[];
+  /** 表单字段名：值随表单提交 */
+  name?: string;
+  disabled?: boolean;
+  /** 不在 `Field` 里时必须给 */
+  "aria-label"?: string;
+  "aria-describedby"?: string;
+  className?: string;
+};
+
+export type SliderSingleProps = SliderCommonProps & {
+  value?: number;
+  defaultValue?: number;
+  /** 拖动的每一步都触发 */
+  onValueChange?: (value: number) => void;
+  /** 松手（或一次按键）之后触发：要发请求的事放这里 */
+  onValueCommitted?: (value: number) => void;
+  thumbLabels?: never;
+  minStepsBetweenValues?: never;
+};
+
+export type SliderRangeProps = SliderCommonProps & {
+  /** 传两个数就是范围滑块 */
+  value?: readonly [number, number];
+  defaultValue?: readonly [number, number];
+  onValueChange?: (value: [number, number]) => void;
+  onValueCommitted?: (value: [number, number]) => void;
+  /** 两个滑块各自的名称，默认"最小值""最大值" */
+  thumbLabels?: readonly [string, string];
+  /** 两个滑块之间至少隔几步，默认 0 */
+  minStepsBetweenValues?: number;
+};
+
+export type SliderProps = SliderSingleProps | SliderRangeProps;
+
+const controlSize: Record<SliderSize, string> = {
+  sm: "h-8",
+  md: "h-10",
+};
+
+/*
+ * 轨道两端各缩进半个滑块（6px）：滑块到头时它的外缘正好和别的字段对齐，不伸出去。
+ * 刻度按同样的算法落位，才对得上滑块的中心。
+ * （没有用基元的 thumbAlignment="edge"：它要先量一遍尺寸才显示滑块，服务端渲染时是空的）
+ */
+const THUMB_HALF = 6;
+const markLeft = (ratio: number) =>
+  `calc(${THUMB_HALF}px + (100% - ${THUMB_HALF * 2}px) * ${ratio})`;
+
+const thumb = [
+  "relative h-5 w-3 bg-surface-inverse shadow-[0_0_0_2px_var(--ef-surface)]",
+  // 触屏的点击区补到 40 × 40px
+  "before:absolute before:-inset-x-3.5 before:-inset-y-2.5 before:content-['']",
+  // 按住时正中亮一条强调色细线
+  "after:absolute after:inset-y-1 after:left-1/2 after:w-0.5 after:-translate-x-1/2 after:bg-accent-ink-inverse after:opacity-0 after:content-[''] data-dragging:after:opacity-100",
+  // 菱形方案：滑块是一个 14px 的菱形，按住时中间亮一个小方块
+  "choice-diamond:size-3.5 choice-diamond:rotate-45 choice-diamond:after:inset-1 choice-diamond:after:w-auto choice-diamond:after:translate-x-0",
+  "data-disabled:bg-ink-disabled",
+  focusRingWithin,
+].join(" ");
+
+/**
+ * 滑块：在一个范围里拖着选一个数。要的是确切的数时用 `Stepper`。
+ * 每个滑块都要有名称：放进 `Field`，或者自己传 `aria-label`。
+ */
+export function Slider(props: SliderProps) {
+  const {
+    min = 0,
+    max = 100,
+    step = 1,
+    largeStep = 10,
+    size = "md",
+    showValue = false,
+    format,
+    marks,
+    name,
+    disabled: disabledProp,
+    "aria-label": ariaLabel,
+    "aria-describedby": describedByProp,
+    className,
+  } = props;
+  const field = useFieldContext();
+  const { disabled, "aria-describedby": describedBy } = useFieldControl({
+    disabled: disabledProp,
+    "aria-describedby": describedByProp,
+  });
+  const labelledBy = ariaLabel ? undefined : field?.labelId;
+  const range = Array.isArray(props.value ?? props.defaultValue);
+  const thumbLabels = props.thumbLabels ?? (["最小值", "最大值"] as const);
+
+  // 数值区按最宽的那个值留宽：拖动时轨道不跟着伸缩
+  const valueWidth = useMemo(() => {
+    const formatter = new Intl.NumberFormat(undefined, format);
+    const widest = Math.max(
+      formatter.format(min).length,
+      formatter.format(max).length,
+    );
+    return `${range ? widest * 2 + 3 : widest}ch`;
+  }, [format, min, max, range]);
+
+  return (
+    <BaseSlider.Root
+      value={props.value}
+      defaultValue={props.defaultValue}
+      onValueChange={(next) =>
+        (props.onValueChange as ((value: unknown) => void) | undefined)?.(next)
+      }
+      onValueCommitted={(next) =>
+        (props.onValueCommitted as ((value: unknown) => void) | undefined)?.(
+          next,
+        )
+      }
+      min={min}
+      max={max}
+      step={step}
+      largeStep={largeStep}
+      minStepsBetweenValues={props.minStepsBetweenValues}
+      thumbCollisionBehavior="none"
+      format={format}
+      name={name}
+      disabled={disabled}
+      // 范围滑块是一个有名称的分组，里面两个滑块各有各的名称
+      {...(range && {
+        "aria-label": ariaLabel,
+        "aria-labelledby": labelledBy,
+      })}
+      data-size={size}
+      className={cn("flex w-full items-start gap-3 text-ink", className)}
+    >
+      <div className="min-w-0 flex-1">
+        <BaseSlider.Control
+          className={cn(
+            "flex touch-none items-center px-1.5 select-none data-disabled:cursor-not-allowed",
+            controlSize[size],
+          )}
+        >
+          <BaseSlider.Track className="h-1 w-full bg-line">
+            <BaseSlider.Indicator className="bg-ink data-disabled:bg-ink-disabled" />
+            {(range ? [0, 1] : [0]).map((index) => (
+              <BaseSlider.Thumb
+                key={index}
+                index={index}
+                {...(range
+                  ? { "aria-label": thumbLabels[index] }
+                  : { "aria-label": ariaLabel, "aria-labelledby": labelledBy })}
+                aria-describedby={describedBy}
+                className={thumb}
+              />
+            ))}
+          </BaseSlider.Track>
+        </BaseSlider.Control>
+
+        {marks && marks.length > 0 && (
+          <div aria-hidden="true" className="relative h-6 text-xs">
+            {marks.map((mark) => (
+              <span
+                key={mark.value}
+                style={{ left: markLeft((mark.value - min) / (max - min)) }}
+                className={cn(
+                  "absolute top-0 flex flex-col gap-0.5 whitespace-nowrap text-ink-secondary before:h-1.5 before:w-px before:bg-line-strong before:content-['']",
+                  // 两端的标注朝里排，不伸到控件外面去；短线仍然对着滑块的中心
+                  mark.value <= min
+                    ? "items-start"
+                    : mark.value >= max
+                      ? "-translate-x-full items-end"
+                      : "-translate-x-1/2 items-center",
+                )}
+              >
+                {mark.label}
+              </span>
+            ))}
+          </div>
+        )}
+      </div>
+
+      {showValue && (
+        <BaseSlider.Value
+          style={{ minWidth: valueWidth }}
+          className={cn(
+            "flex shrink-0 items-center justify-end font-tech text-sm font-bold tabular-nums data-disabled:text-ink-disabled",
+            controlSize[size],
+          )}
+        >
+          {(formatted) => formatted.join(" – ")}
+        </BaseSlider.Value>
+      )}
+    </BaseSlider.Root>
+  );
+}

package/src/components/slider/index.ts

@@ -0,0 +1,8 @@
+export {
+  Slider,
+  type SliderMark,
+  type SliderProps,
+  type SliderRangeProps,
+  type SliderSingleProps,
+  type SliderSize,
+} from "./Slider";

package/src/components/sparkline/Sparkline.tsx

@@ -0,0 +1,122 @@
+import type { ComponentProps } from "react";
+import { cn } from "../../lib/cn";
+
+export type SparklineVariant = "area" | "line";
+export type SparklineTone = "info" | "danger" | "accent" | "neutral";
+
+export type SparklineProps = Omit<ComponentProps<"svg">, "children"> & {
+  /** 一串数值，按先后顺序。少于两个点时什么都不画 */
+  data: readonly number[];
+  /** `area` 一块填充的面积，默认；`line` 一条折线 */
+  variant?: SparklineVariant;
+  /**
+   * - `info` 量值图表的蓝，默认；
+   * - `danger` 超支、异常的红；
+   * - `accent` 强调色；
+   * - `neutral` 次要的墨色。
+   */
+  tone?: SparklineTone;
+  /** 纵向范围的下端。默认从数据的最小值往下再留四分之一，让最低的那一点也有厚度 */
+  min?: number;
+  /** 纵向范围的上端。默认是数据的最大值 */
+  max?: number;
+  /** 传了它就是一张有名称的图；不传是纯装饰，对读屏隐藏 */
+  label?: string;
+};
+
+/* 画在一个 100 × 100 的格子里，再由 SVG 拉伸到实际的盒子 */
+const SIZE = 100;
+
+/** 保留两位小数：路径短一点，快照也稳定 */
+const round = (value: number) => Math.round(value * 100) / 100;
+
+/**
+ * 把一串数值换算成折线与面积的路径（100 × 100 的坐标系，y 向下）。
+ * 少于两个点时返回 `null`。
+ */
+export function sparklinePath(
+  data: readonly number[],
+  range: { min?: number; max?: number } = {},
+): { line: string; area: string } | null {
+  if (data.length < 2) return null;
+
+  const low = Math.min(...data);
+  const high = Math.max(...data);
+  const max = range.max ?? high;
+  const min = range.min ?? low - (high - low) * 0.25;
+  // 所有的值都一样（或范围给反了）时没有高低可言，画在正中
+  const span = max - min;
+
+  const points = data.map((value, index) => {
+    const x = (index / (data.length - 1)) * SIZE;
+    const ratio = span > 0 ? (value - min) / span : 0.5;
+    const y = SIZE - Math.min(Math.max(ratio, 0), 1) * SIZE;
+    return `${round(x)} ${round(y)}`;
+  });
+
+  const line = `M${points.join("L")}`;
+  return { line, area: `${line}L${SIZE} ${SIZE}L0 ${SIZE}Z` };
+}
+
+/* data 与 alert 是不随主题变的角色色：白底和深色行带上都认得出 */
+const areaClass: Record<SparklineTone, string> = {
+  info: "fill-data/75",
+  danger: "fill-alert/75",
+  accent: "fill-accent-ink/75",
+  neutral: "fill-ink-secondary/75",
+};
+
+const lineClass: Record<SparklineTone, string> = {
+  info: "stroke-data",
+  danger: "stroke-alert",
+  accent: "stroke-accent-ink",
+  neutral: "stroke-ink-secondary",
+};
+
+/**
+ * 行内的小型图表：没有坐标轴、网格和图例，只有一块面积或一条折线。
+ * 撑满给它的盒子（默认高 32px、通宽）。它旁边应该有数字——图只是帮着看趋势。
+ */
+export function Sparkline({
+  data,
+  variant = "area",
+  tone = "info",
+  min,
+  max,
+  label,
+  className,
+  ...props
+}: SparklineProps) {
+  const path = sparklinePath(data, { min, max });
+
+  return (
+    <svg
+      viewBox={`0 0 ${SIZE} ${SIZE}`}
+      preserveAspectRatio="none"
+      role={label ? "img" : undefined}
+      aria-label={label}
+      aria-hidden={label ? undefined : "true"}
+      focusable="false"
+      data-variant={variant}
+      data-tone={tone}
+      {...props}
+      // 折线贴着上下边缘时，线宽的一半会落在盒子外面
+      className={cn("block h-8 w-full overflow-visible", className)}
+    >
+      {path &&
+        (variant === "area" ? (
+          <path d={path.area} className={areaClass[tone]} />
+        ) : (
+          <path
+            d={path.line}
+            fill="none"
+            strokeWidth={1.5}
+            strokeLinejoin="miter"
+            // 图被横向拉伸了，线宽不跟着变
+            vectorEffect="non-scaling-stroke"
+            className={lineClass[tone]}
+          />
+        ))}
+    </svg>
+  );
+}

package/src/components/sparkline/index.ts

@@ -0,0 +1,6 @@
+export {
+  Sparkline,
+  type SparklineProps,
+  type SparklineTone,
+  type SparklineVariant,
+} from "./Sparkline";

package/src/components/spinner/Spinner.tsx

@@ -0,0 +1,64 @@
+import type { ComponentProps, ReactNode } from "react";
+import { cn } from "../../lib/cn";
+
+export type SpinnerSize = "sm" | "md";
+
+export type SpinnerProps = Omit<ComponentProps<"span">, "children"> & {
+  /** 12px 或 16px。要别的尺寸用 `className` 给 `size-*` */
+  size?: SpinnerSize;
+  /**
+   * 读屏听到的话，默认"加载中"。
+   * 旁边已经有文字说明正在加载时传 `null`：这时它只是装饰，对读屏隐藏。
+   */
+  label?: ReactNode;
+};
+
+const sizeClass: Record<SpinnerSize, string> = {
+  sm: "size-3",
+  md: "size-4",
+};
+
+// 系统开启"减少动态效果"时停成一个 45° 的菱形，和列表里的菱形记号是同一个样子
+const square =
+  "animate-spin bg-current motion-reduce:rotate-45 motion-reduce:animate-none";
+
+/**
+ * 行内加载指示：一个匀速旋转的小方块，颜色继承文字。
+ * 圆环形的用 `<ProgressRing size={16} />`；整块内容加载用 `Skeleton`。
+ */
+export function Spinner({
+  size = "md",
+  label = "加载中",
+  className,
+  ...props
+}: SpinnerProps) {
+  if (label === null) {
+    return (
+      <span
+        {...props}
+        aria-hidden="true"
+        className={cn(
+          "inline-block shrink-0 align-middle",
+          square,
+          sizeClass[size],
+          className,
+        )}
+      />
+    );
+  }
+
+  return (
+    <span
+      {...props}
+      role="status"
+      className={cn(
+        "inline-flex shrink-0 align-middle",
+        sizeClass[size],
+        className,
+      )}
+    >
+      <span aria-hidden="true" className={cn("block size-full", square)} />
+      <span className="sr-only">{label}</span>
+    </span>
+  );
+}

package/src/components/spinner/index.ts

@@ -0,0 +1 @@
+export { Spinner, type SpinnerProps, type SpinnerSize } from "./Spinner";

package/src/components/stat/Stat.tsx

@@ -0,0 +1,79 @@
+import type { ComponentProps, ReactNode } from "react";
+import { cn } from "../../lib/cn";
+import { Tag } from "../tag/Tag";
+
+export type StatSize = "md" | "lg";
+export type StatTrend = "up" | "down";
+
+export type StatProps = Omit<ComponentProps<"div">, "children"> & {
+  /** 微标，说明这是什么数。前面的 `//` 由组件加，不用自己写 */
+  label: ReactNode;
+  /** 主角：一个需要被一眼看到的数字 */
+  value: ReactNode;
+  /** 单位，小一号、与数字基线对齐 */
+  unit?: ReactNode;
+  /** 增量，连同正负号一起传，如 `+6%`、`−2%` */
+  delta?: ReactNode;
+  /** `up` 渲染为增益签，默认；`down` 渲染为危险色文字 */
+  trend?: StatTrend;
+  /** 并排几个时，让最重要的那个用 `lg` */
+  size?: StatSize;
+};
+
+const valueSize: Record<StatSize, string> = {
+  md: "text-4xl",
+  lg: "text-5xl",
+};
+
+/** 统计块：不装进卡片，只用左缘一条墨色竖线。 */
+export function Stat({
+  label,
+  value,
+  unit,
+  delta,
+  trend = "up",
+  size = "md",
+  className,
+  ...props
+}: StatProps) {
+  const hasDelta = delta !== undefined && delta !== null;
+
+  return (
+    <div
+      {...props}
+      data-size={size}
+      className={cn("min-w-0 border-l-4 border-ink pl-4 text-ink", className)}
+    >
+      <p className="font-tech text-xs tracking-label text-ink-secondary">
+        <span aria-hidden="true">{"// "}</span>
+        {label}
+      </p>
+      <p className="mt-2 flex flex-wrap items-baseline gap-x-2 gap-y-1">
+        <span
+          className={cn(
+            "min-w-0 font-tech leading-none font-medium wrap-anywhere tabular-nums",
+            valueSize[size],
+          )}
+        >
+          {value}
+        </span>
+        {unit !== undefined && unit !== null && (
+          <span className="text-sm text-ink-secondary">{unit}</span>
+        )}
+        {hasDelta &&
+          (trend === "down" ? (
+            <span
+              data-trend="down"
+              className="font-tech text-sm font-bold text-danger tabular-nums"
+            >
+              {delta}
+            </span>
+          ) : (
+            <Tag variant="gain" size="sm" numeric data-trend="up">
+              {delta}
+            </Tag>
+          ))}
+      </p>
+    </div>
+  );
+}

package/src/components/stat/index.ts

@@ -0,0 +1 @@
+export { Stat, type StatProps, type StatSize, type StatTrend } from "./Stat";