@endfield-ui/react 0.0.0-stage → 0.1.0

package/src/hooks/useTheme.ts

@@ -0,0 +1,102 @@
+import { useEffect, useSyncExternalStore } from "react";
+
+export type Theme = "light" | "dark";
+export type ThemePreference = Theme | "system";
+
+type Snapshot = { theme: ThemePreference; resolvedTheme: Theme };
+
+const STORAGE_KEY = "ef-theme";
+const DARK_QUERY = "(prefers-color-scheme: dark)";
+
+const serverSnapshot: Snapshot = { theme: "light", resolvedTheme: "light" };
+const listeners = new Set<() => void>();
+let snapshot: Snapshot | null = null;
+let stopWatchingSystem: (() => void) | null = null;
+
+function isPreference(value: unknown): value is ThemePreference {
+  return value === "light" || value === "dark" || value === "system";
+}
+
+function resolve(theme: ThemePreference): Theme {
+  if (theme !== "system") return theme;
+  return window.matchMedia?.(DARK_QUERY).matches ? "dark" : "light";
+}
+
+/** 取值顺序：上次保存的选择 → `<html data-theme>` 现有的值 → 亮色 */
+function readPreference(): ThemePreference {
+  try {
+    const stored = window.localStorage.getItem(STORAGE_KEY);
+    if (isPreference(stored)) return stored;
+  } catch {
+    // 存储不可用（隐私模式等）时退回到下面的来源
+  }
+  const attribute = document.documentElement.dataset.theme;
+  return attribute === "dark" ? "dark" : "light";
+}
+
+function getSnapshot(): Snapshot {
+  if (!snapshot) {
+    const theme = readPreference();
+    snapshot = { theme, resolvedTheme: resolve(theme) };
+  }
+  return snapshot;
+}
+
+function commit(theme: ThemePreference) {
+  snapshot = { theme, resolvedTheme: resolve(theme) };
+  document.documentElement.dataset.theme = snapshot.resolvedTheme;
+  for (const listener of listeners) listener();
+}
+
+function subscribe(listener: () => void) {
+  listeners.add(listener);
+
+  if (!stopWatchingSystem) {
+    const media = window.matchMedia?.(DARK_QUERY);
+    const onChange = () => {
+      if (getSnapshot().theme === "system") commit("system");
+    };
+    media?.addEventListener("change", onChange);
+    stopWatchingSystem = () => media?.removeEventListener("change", onChange);
+  }
+
+  return () => {
+    listeners.delete(listener);
+    if (listeners.size === 0) {
+      stopWatchingSystem?.();
+      stopWatchingSystem = null;
+    }
+  };
+}
+
+function setTheme(theme: ThemePreference) {
+  try {
+    window.localStorage.setItem(STORAGE_KEY, theme);
+  } catch {
+    // 存不下来也照常切换，只是刷新后不保留
+  }
+  commit(theme);
+}
+
+/**
+ * 读写 `<html data-theme>`。
+ *
+ * - `theme`：用户的选择，可以是 `"system"`；
+ * - `resolvedTheme`：实际生效的 `"light"` 或 `"dark"`；
+ * - `setTheme`：切换并记到 `localStorage`。
+ */
+export function useTheme(): Snapshot & {
+  setTheme: (theme: ThemePreference) => void;
+} {
+  const { theme, resolvedTheme } = useSyncExternalStore(
+    subscribe,
+    getSnapshot,
+    () => serverSnapshot,
+  );
+
+  useEffect(() => {
+    document.documentElement.dataset.theme = resolvedTheme;
+  }, [resolvedTheme]);
+
+  return { theme, resolvedTheme, setTheme };
+}

package/src/icons/ArrowCorner.tsx

@@ -0,0 +1,7 @@
+import { createIcon } from "./createIcon";
+
+/** 斜箭头 ↘：分节引导、"查看详情" */
+export const ArrowCorner = createIcon(
+  "ArrowCorner",
+  <path d="M5 5l14 14M19 7v12H7" />,
+);

package/src/icons/ArrowLeft.tsx

@@ -0,0 +1,6 @@
+import { createIcon } from "./createIcon";
+
+export const ArrowLeft = createIcon(
+  "ArrowLeft",
+  <path d="M20 12H5M11 5l-7 7 7 7" />,
+);

package/src/icons/ArrowRight.tsx

@@ -0,0 +1,6 @@
+import { createIcon } from "./createIcon";
+
+export const ArrowRight = createIcon(
+  "ArrowRight",
+  <path d="M4 12h15M13 5l7 7-7 7" />,
+);

package/src/icons/CalendarIcon.tsx

@@ -0,0 +1,10 @@
+import { createIcon } from "./createIcon";
+
+/**
+ * 日历：日期字段右侧的记号。
+ * 名字带 `Icon` 是因为 `Calendar` 已经是月历控件了
+ */
+export const CalendarIcon = createIcon(
+  "CalendarIcon",
+  <path d="M4 6h16v14H4zM4 11h16M8 3v5M16 3v5" />,
+);

package/src/icons/Check.tsx

@@ -0,0 +1,4 @@
+import { createIcon } from "./createIcon";
+
+/** 对勾：已选、已完成 */
+export const Check = createIcon("Check", <path d="M4 12l6 6L20 6" />);

package/src/icons/ChevronDown.tsx

@@ -0,0 +1,3 @@
+import { createIcon } from "./createIcon";
+
+export const ChevronDown = createIcon("ChevronDown", <path d="M4 9l8 8 8-8" />);

package/src/icons/ChevronLeft.tsx

@@ -0,0 +1,6 @@
+import { createIcon } from "./createIcon";
+
+export const ChevronLeft = createIcon(
+  "ChevronLeft",
+  <path d="M15 4l-8 8 8 8" />,
+);

package/src/icons/ChevronRight.tsx

@@ -0,0 +1,6 @@
+import { createIcon } from "./createIcon";
+
+export const ChevronRight = createIcon(
+  "ChevronRight",
+  <path d="M9 4l8 8-8 8" />,
+);

package/src/icons/Close.tsx

@@ -0,0 +1,3 @@
+import { createIcon } from "./createIcon";
+
+export const Close = createIcon("Close", <path d="M5 5l14 14M19 5L5 19" />);

package/src/icons/Crosshair.tsx

@@ -0,0 +1,7 @@
+import { createIcon } from "./createIcon";
+
+/** 四个取景角加中心的准星：图鉴里"未获得"的占位符 */
+export const Crosshair = createIcon(
+  "Crosshair",
+  <path d="M3 8V3h5M16 3h5v5M21 16v5h-5M8 21H3v-5M12 9v6M9 12h6" />,
+);

package/src/icons/Lock.tsx

@@ -0,0 +1,6 @@
+import { createIcon } from "./createIcon";
+
+export const Lock = createIcon(
+  "Lock",
+  <path d="M5 11h14v10H5zM8 11V7a4 4 0 0 1 8 0v4" />,
+);

package/src/icons/Menu.tsx

@@ -0,0 +1,4 @@
+import { createIcon } from "./createIcon";
+
+/** 三条横线：打开菜单 */
+export const Menu = createIcon("Menu", <path d="M3 6h18M3 12h18M3 18h18" />);

package/src/icons/Minus.tsx

@@ -0,0 +1,4 @@
+import { createIcon } from "./createIcon";
+
+/** 短横：半选、减少 */
+export const Minus = createIcon("Minus", <path d="M4 12h16" />);

package/src/icons/Plus.tsx

@@ -0,0 +1,3 @@
+import { createIcon } from "./createIcon";
+
+export const Plus = createIcon("Plus", <path d="M12 4v16M4 12h16" />);

package/src/icons/README.md

@@ -0,0 +1,31 @@
+# icons
+
+原创图标组件。目前只有控件自己用到的二十个：
+
+| 图标 | 用在哪 |
+| --- | --- |
+| `ArrowCorner`（斜箭头 ↘）、`ArrowLeft`、`ArrowRight` | 分节标题、文字按钮 |
+| `ChevronLeft`、`ChevronRight`、`ChevronDown` | 返回按钮、翻页、滚动提示 |
+| `TriangleRight`（实心三角 ▶） | 页签的箭头块 |
+| `Close`、`Plus`、`Minus`、`Check` | 关闭、增减、已选与半选 |
+| `StatusInfo`、`StatusSuccess`、`StatusWarning`、`StatusDanger` | 提示条的四种色调、输入框的错误图标 |
+| `Lock`、`Crosshair`（四个取景角加准星） | 物品格的"锁定"与"未获得" |
+| `Menu`（三条横线） | 顶栏的菜单钮 |
+| `CalendarIcon` | 日期选择右侧的记号（`Calendar` 这个名字给了月历控件） |
+| `Upload`（托盘加一支朝上的箭头） | 文件上传的投放区 |
+
+四个状态图标的外形各不相同——方框、圆、三角、菱形——状态因此不只靠颜色区分。
+
+## 规则
+
+- **只收录原创图标。** 不收录、不描摹官方图标与 Logo，包括游戏内图标、官网导航图标和阵营徽记。
+- 绘制规范见 [图标规范](../../../../docs/design/foundations/iconography.md)：24 网格、2px 描边、平头端点、尖角拐角、几何母题（菱形、三角、斜杠）。
+- 每个图标一个文件，用 [`createIcon`](createIcon.tsx) 生成：接受 `size` 与 `className`，颜色用 `currentColor`，默认 `aria-hidden`。
+
+```tsx
+import { createIcon } from "./createIcon";
+
+export const Plus = createIcon("Plus", <path d="M12 4v16M4 12h16" />);
+```
+
+- 通用图标（关闭、箭头、搜索等）优先画一套自己的；需要大量通用图标时，可以在文档站里搭配成熟的开源图标库，但不要打包进本库。

package/src/icons/StatusDanger.tsx

@@ -0,0 +1,7 @@
+import { createIcon } from "./createIcon";
+
+/** 菱形：危险、错误 */
+export const StatusDanger = createIcon(
+  "StatusDanger",
+  <path d="M12 2.5l9.5 9.5-9.5 9.5L2.5 12zM12 7v6M12 15v2" />,
+);

package/src/icons/StatusInfo.tsx

@@ -0,0 +1,7 @@
+import { createIcon } from "./createIcon";
+
+/** 方框：说明。四种状态图标各用一种外形，不只靠颜色区分 */
+export const StatusInfo = createIcon(
+  "StatusInfo",
+  <path d="M4 4h16v16H4zM12 11v6M12 7v2" />,
+);

package/src/icons/StatusSuccess.tsx

@@ -0,0 +1,10 @@
+import { createIcon } from "./createIcon";
+
+/** 圆 + 对勾：成功 */
+export const StatusSuccess = createIcon(
+  "StatusSuccess",
+  <>
+    <circle cx="12" cy="12" r="9" />
+    <path d="M7.5 12.5l3 3 6-7" />
+  </>,
+);

package/src/icons/StatusWarning.tsx

@@ -0,0 +1,7 @@
+import { createIcon } from "./createIcon";
+
+/** 三角：警告 */
+export const StatusWarning = createIcon(
+  "StatusWarning",
+  <path d="M12 4l9 16H3zM12 10v5M12 16.5v2" />,
+);

package/src/icons/TriangleRight.tsx

@@ -0,0 +1,7 @@
+import { createIcon } from "./createIcon";
+
+/** 实心三角 ▶：前往、展开 */
+export const TriangleRight = createIcon(
+  "TriangleRight",
+  <path d="M7 4l12 8-12 8z" fill="currentColor" stroke="none" />,
+);

package/src/icons/Upload.tsx

@@ -0,0 +1,7 @@
+import { createIcon } from "./createIcon";
+
+/** 上传：一个托盘，上面一支朝上的箭头 */
+export const Upload = createIcon(
+  "Upload",
+  <path d="M12 16V4M7 9l5-5 5 5M4 15v5h16v-5" />,
+);

package/src/icons/createIcon.tsx

@@ -0,0 +1,34 @@
+import type { ComponentProps, ReactNode } from "react";
+
+export type IconProps = Omit<ComponentProps<"svg">, "children"> & {
+  /** 显示尺寸，默认 24。线宽随尺寸等比缩放 */
+  size?: number | string;
+};
+
+/**
+ * 按图标规范生成组件：24 网格、2px 描边、平头端点、尖角拐角、颜色继承。
+ * 默认对辅助技术隐藏；单独承担含义时由使用方传 `aria-label` 并去掉 `aria-hidden`。
+ */
+export function createIcon(displayName: string, content: ReactNode) {
+  function Icon({ size = 24, ...props }: IconProps) {
+    return (
+      <svg
+        width={size}
+        height={size}
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth={2}
+        strokeLinecap="butt"
+        strokeLinejoin="miter"
+        aria-hidden="true"
+        focusable="false"
+        {...props}
+      >
+        {content}
+      </svg>
+    );
+  }
+  Icon.displayName = displayName;
+  return Icon;
+}

package/src/icons/index.ts

@@ -0,0 +1,21 @@
+export { createIcon, type IconProps } from "./createIcon";
+export { ArrowCorner } from "./ArrowCorner";
+export { ArrowLeft } from "./ArrowLeft";
+export { ArrowRight } from "./ArrowRight";
+export { CalendarIcon } from "./CalendarIcon";
+export { Check } from "./Check";
+export { ChevronDown } from "./ChevronDown";
+export { ChevronLeft } from "./ChevronLeft";
+export { ChevronRight } from "./ChevronRight";
+export { Close } from "./Close";
+export { Crosshair } from "./Crosshair";
+export { Lock } from "./Lock";
+export { Menu } from "./Menu";
+export { Minus } from "./Minus";
+export { Plus } from "./Plus";
+export { StatusDanger } from "./StatusDanger";
+export { StatusInfo } from "./StatusInfo";
+export { StatusSuccess } from "./StatusSuccess";
+export { StatusWarning } from "./StatusWarning";
+export { TriangleRight } from "./TriangleRight";
+export { Upload } from "./Upload";

package/src/index.ts

@@ -0,0 +1,82 @@
+export * from "./components/accordion";
+export * from "./components/alert";
+export * from "./components/avatar";
+export * from "./components/back-to-top";
+export * from "./components/badge";
+export * from "./components/bracket-title";
+export * from "./components/breadcrumb";
+export * from "./components/button";
+export * from "./components/calendar";
+export * from "./components/carousel";
+export * from "./components/checkbox";
+export * from "./components/chip";
+export * from "./components/combobox";
+export * from "./components/completion-banner";
+export * from "./components/context-menu";
+export * from "./components/corner-brackets";
+export * from "./components/countdown";
+export * from "./components/data-row";
+export * from "./components/date-picker";
+export * from "./components/dash-indicator";
+export * from "./components/dialog";
+export * from "./components/drawer";
+export * from "./components/dropdown-menu";
+export * from "./components/empty-state";
+export * from "./components/field";
+export * from "./components/file-upload";
+export * from "./components/flyout-bar";
+export * from "./components/ghost-text";
+export * from "./components/hatch";
+export * from "./components/hazard-stripe";
+export * from "./components/icon-button";
+export * from "./components/input";
+export * from "./components/item-slot";
+export * from "./components/kbd";
+export * from "./components/list";
+export * from "./components/loader";
+export * from "./components/marquee";
+export * from "./components/media-card";
+export * from "./components/nav-action";
+export * from "./components/nav-menu";
+export * from "./components/navigator";
+export * from "./components/pagination";
+export * from "./components/panel";
+export * from "./components/play-button";
+export * from "./components/popover";
+export * from "./components/progress";
+export * from "./components/radio";
+export * from "./components/rec-indicator";
+export * from "./components/registration-strip";
+export * from "./components/schedule";
+export * from "./components/scroll-hint";
+export * from "./components/section-title";
+export * from "./components/segmented-control";
+export * from "./components/select";
+export * from "./components/side-rail";
+export * from "./components/skeleton";
+export * from "./components/slider";
+export * from "./components/sparkline";
+export * from "./components/spinner";
+export * from "./components/stat";
+export * from "./components/stepper";
+export * from "./components/steps";
+export * from "./components/switch";
+export * from "./components/table";
+export * from "./components/tabs";
+export * from "./components/tag";
+export * from "./components/tag-input";
+export * from "./components/term";
+export * from "./components/textarea";
+export * from "./components/texture";
+export * from "./components/tick-ring";
+export * from "./components/timeline";
+export * from "./components/toast";
+export * from "./components/toc";
+export * from "./components/toolbar";
+export * from "./components/tooltip";
+export * from "./components/top-bar";
+export * from "./components/viewfinder";
+
+export * from "./hooks";
+export * from "./icons";
+export { cn } from "./lib/cn";

package/src/lib/README.md

@@ -0,0 +1,17 @@
+# lib
+
+纯函数与常量。这里不放 React 组件和 hooks。
+
+| 文件 | 内容 |
+| --- | --- |
+| `cn.ts` | `cn()`：合并类名（`clsx` + `tailwind-merge`）。里面登记了 [theme.css](../styles/theme.css) 的自定义令牌名，否则 `text-micro` 会被当成颜色、与 `text-ink` 互相覆盖 |
+| `focus-ring.ts` | `focusRing`、`focusRingInset`、`focusRingWithin`：全库统一的焦点环类名 |
+| `merge-refs.ts` | `mergeRefs()`：组件自己要用节点、同时还得把它交给使用方时，把几个 ref 合成一个 |
+| `defined.ts` | `defined()`：去掉值是 `undefined` 的属性。把控件的属性合并到使用方给的元素上（`render`）之前用，免得把那个元素自己写的盖掉 |
+| `decor.ts` | `decor`：装饰层共用的类 |
+| `date.ts` | 日期的纯函数：加减日和月、比较、把两天排成先后、夹到范围内、月历的六行七列。日期一律是 `YYYY-MM-DD` 的字符串，全部按 UTC 算，不碰本地时区。`Calendar`、`DatePicker`、`Schedule` 共用，不对外导出 |
+| `file.ts` | 文件的纯函数：按 `accept` 认类型（扩展名、MIME、`image/*` 通配）、把字节数写成 `1.2 MB`、取扩展名、判断是不是同一个文件。`FileUpload` 用，不对外导出 |
+
+没有单独的"变体工具"：各组件直接写 `Record<Variant, string>` 再用 `cn()` 合并，够用且类型清楚。
+
+以后可能放进来的：与 DOM 无关的格式化函数，例如把数字格式化成等宽的 `01 / 04`。

package/src/lib/cn.ts

@@ -0,0 +1,34 @@
+import { clsx, type ClassValue } from "clsx";
+import { extendTailwindMerge } from "tailwind-merge";
+
+/*
+ * theme.css 里的自定义令牌名需要登记，否则 tailwind-merge 会把 `text-micro`
+ * 当成颜色，与 `text-ink` 互相覆盖。改动 theme.css 的令牌名时同步改这里。
+ */
+const twMerge = extendTailwindMerge({
+  extend: {
+    theme: {
+      text: ["micro", "ghost"],
+      tracking: ["ghost", "label"],
+      shadow: ["rail"],
+      ease: ["standard", "emphasis", "exit"],
+      animate: [
+        "flicker",
+        "fill",
+        "scroll-hint",
+        "breathe",
+        "marquee",
+        "spin-slow",
+        "blink",
+        "slide-in",
+        "turn-in",
+        "fade-in",
+        "indeterminate",
+      ],
+    },
+  },
+});
+
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs));
+}

package/src/lib/date.ts

@@ -0,0 +1,125 @@
+/*
+ * 日期的纯函数。日期一律是 `YYYY-MM-DD` 的字符串：没有时间，也没有时区
+ * （和原生 `<input type="date">` 的值是同一种写法）。月份是 `YYYY-MM`。
+ *
+ * 全部按 UTC 算：本地时区和夏令时会让"加一天"偶尔变成加 23 或 25 小时，
+ * 落到前一天或后一天上。只有"今天是几号"要问本地时间。
+ */
+
+const DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const MONTH = /^(\d{4})-(\d{2})$/;
+const DAY_MS = 86_400_000;
+
+const pad = (value: number, length = 2) => String(value).padStart(length, "0");
+
+const toUTC = (date: string) => {
+  const match = DATE.exec(date);
+  if (!match) return Number.NaN;
+  return Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3]));
+};
+
+const fromUTC = (time: number) => {
+  const date = new Date(time);
+  return `${pad(date.getUTCFullYear(), 4)}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())}`;
+};
+
+/** 是不是一个真的日期：格式对，而且这一天存在（`2026-02-30` 不算） */
+export function isDate(value: unknown): value is string {
+  return typeof value === "string" && fromUTC(toUTC(value)) === value;
+}
+
+/** 今天，按本地时间 */
+export function today(): string {
+  const now = new Date();
+  return `${pad(now.getFullYear(), 4)}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+}
+
+/** 拆成年、月（1 – 12）、日 */
+export function dateParts(date: string) {
+  const [year, month, day] = date.split("-").map(Number);
+  return { year: year!, month: month!, day: day! };
+}
+
+export function addDays(date: string, days: number): string {
+  return fromUTC(toUTC(date) + days * DAY_MS);
+}
+
+/** 这个月有几天 */
+export function daysInMonth(year: number, month: number): number {
+  return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+
+/** 加减月份。那个月没有这一天就落在月末：1 月 31 日加一个月是 2 月 28 日 */
+export function addMonths(date: string, months: number): string {
+  const { year, month, day } = dateParts(date);
+  const index = year * 12 + (month - 1) + months;
+  const nextYear = Math.floor(index / 12);
+  const nextMonth = (index % 12) + 1;
+  return `${pad(nextYear, 4)}-${pad(nextMonth)}-${pad(Math.min(day, daysInMonth(nextYear, nextMonth)))}`;
+}
+
+/** 从 `from` 到 `to` 隔了几天；`to` 在前时是负数 */
+export function daysBetween(from: string, to: string): number {
+  return Math.round((toUTC(to) - toUTC(from)) / DAY_MS);
+}
+
+/** 星期几：0 是星期日，6 是星期六 */
+export function dayOfWeek(date: string): number {
+  return new Date(toUTC(date)).getUTCDay();
+}
+
+/** 夹到 `min` 和 `max` 之间。同一种写法的日期可以直接按字符串比大小 */
+export function clampDate(date: string, min?: string, max?: string): string {
+  if (min && date < min) return min;
+  if (max && date > max) return max;
+  return date;
+}
+
+/** 把两天排成先后：`[早的, 晚的]`。同一天就是两个一样的 */
+export function orderDates(a: string, b: string): [string, string] {
+  return a <= b ? [a, b] : [b, a];
+}
+
+/** 这个日期所在的月份，`YYYY-MM` */
+export function monthOf(date: string): string {
+  return date.slice(0, 7);
+}
+
+export function isMonth(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  const match = MONTH.exec(value);
+  return !!match && Number(match[2]) >= 1 && Number(match[2]) <= 12;
+}
+
+export function addMonthsToMonth(month: string, months: number): string {
+  return monthOf(addMonths(`${month}-01`, months));
+}
+
+/** 这一周的第一天。`weekStartsOn`：0 是从星期日起，1 是从星期一起 */
+export function startOfWeek(date: string, weekStartsOn: 0 | 1 = 1): string {
+  return addDays(date, -((dayOfWeek(date) - weekStartsOn + 7) % 7));
+}
+
+/**
+ * 一个月的月历：固定六行七列，前后用相邻月份的日子补齐。
+ * 固定六行是为了翻月时高度不跳
+ */
+export function monthGrid(month: string, weekStartsOn: 0 | 1 = 1): string[][] {
+  const first = startOfWeek(`${month}-01`, weekStartsOn);
+  return Array.from({ length: 6 }, (_, week) =>
+    Array.from({ length: 7 }, (_, day) => addDays(first, week * 7 + day)),
+  );
+}
+
+/** 从 `start` 到 `end`（都包含）的每一天 */
+export function eachDay(start: string, end: string): string[] {
+  const count = daysBetween(start, end) + 1;
+  return Array.from({ length: Math.max(0, count) }, (_, offset) =>
+    addDays(start, offset),
+  );
+}
+
+/** 交给 `Intl.DateTimeFormat` 用的 `Date`。格式化时要带 `timeZone: "UTC"` */
+export function toDateObject(date: string): Date {
+  return new Date(toUTC(date));
+}

package/src/lib/decor.ts

@@ -0,0 +1,6 @@
+/**
+ * 装饰层共用的类：不挡操作、不可选中；高对比模式与打印时整个去掉。
+ * 用它的元素同时要加 `aria-hidden="true"`。
+ */
+export const decor =
+  "pointer-events-none select-none forced-colors:hidden print:hidden";

package/src/lib/defined.ts

@@ -0,0 +1,9 @@
+/**
+ * 去掉值是 `undefined` 的属性。把控件的属性合并到使用方给的元素上之前用：
+ * 控件没有的东西（比如 `href`），不能把那个元素自己写的盖掉。
+ */
+export function defined<T extends object>(props: T): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(props).filter(([, value]) => value !== undefined),
+  ) as Partial<T>;
+}