@endfield-ui/react 0.0.0-stage → 0.2.0

package/src/lib/file.ts

@@ -0,0 +1,61 @@
+/** 文件的纯函数：按 `accept` 认类型、把字节数写成人读的大小。`FileUpload` 用，不对外导出 */
+
+/**
+ * 这个文件合不合 `accept`。写法和原生的 `<input accept>` 一样，逗号分开：
+ * `.pdf`（扩展名）、`image/*`（一类）、`text/plain`（一种）。不分大小写；没写就是都行。
+ */
+export function matchesAccept(
+  file: { name: string; type: string },
+  accept: string | undefined,
+): boolean {
+  const rules = (accept ?? "")
+    .split(",")
+    .map((rule) => rule.trim().toLowerCase())
+    .filter(Boolean);
+  if (rules.length === 0) return true;
+
+  const name = file.name.toLowerCase();
+  const type = file.type.toLowerCase();
+  return rules.some((rule) => {
+    if (rule.startsWith(".")) return name.endsWith(rule);
+    if (rule.endsWith("/*")) return type.startsWith(rule.slice(0, -1));
+    return type === rule;
+  });
+}
+
+const UNITS = ["B", "KB", "MB", "GB", "TB"];
+
+/**
+ * 字节数写成 `1.2 MB`：按 1024 进位；不到 100 的留一位小数（`.0` 不写），再大就取整。
+ * 字节不带小数。
+ */
+export function formatFileSize(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes < 0) return "";
+  let value = bytes;
+  let unit = 0;
+  const round = () =>
+    unit === 0 || value >= 100
+      ? Math.round(value)
+      : Math.round(value * 10) / 10;
+
+  while (unit < UNITS.length - 1 && round() >= 1024) {
+    value /= 1024;
+    unit += 1;
+  }
+  return `${round()} ${UNITS[unit]}`;
+}
+
+/** 扩展名，大写、不带点：`report.final.PDF` → `PDF`。没有、或者长得不像扩展名时是空的 */
+export function fileExtension(name: string): string {
+  const dot = name.lastIndexOf(".");
+  if (dot <= 0 || dot === name.length - 1) return "";
+  const extension = name.slice(dot + 1);
+  return /^[a-z0-9]{1,5}$/i.test(extension) ? extension.toUpperCase() : "";
+}
+
+/** 是不是同一个文件：名字、大小、修改时间都一样 */
+export function sameFile(a: File, b: File): boolean {
+  return (
+    a.name === b.name && a.size === b.size && a.lastModified === b.lastModified
+  );
+}

package/src/lib/focus-ring.ts

@@ -0,0 +1,11 @@
+/** 2px `focus` 色的环，与元素间隔 2px；仅键盘聚焦时出现。 */
+export const focusRing =
+  "focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus";
+
+/** 画在元素内侧的焦点环，用在会被滚动容器裁切的地方。 */
+export const focusRingInset =
+  "focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-focus";
+
+/** 外框自己不能聚焦、里面的控件能：控件聚焦时把环画在外框上（输入框）。 */
+export const focusRingWithin =
+  "has-focus-visible:outline-2 has-focus-visible:outline-offset-2 has-focus-visible:outline-focus";

package/src/lib/merge-refs.ts

@@ -0,0 +1,11 @@
+import type { Ref, RefCallback } from "react";
+
+/** 把几个 ref 合成一个：组件自己要用节点，同时还得把它交给使用方。 */
+export function mergeRefs<T>(...refs: (Ref<T> | undefined)[]): RefCallback<T> {
+  return (node) => {
+    for (const ref of refs) {
+      if (typeof ref === "function") ref(node);
+      else if (ref) ref.current = node;
+    }
+  };
+}

package/src/styles/README.md

@@ -0,0 +1,70 @@
+# styles
+
+| 文件 | 内容 |
+| --- | --- |
+| [theme.css](theme.css) | 设计令牌：语义变量（亮 / 暗）+ Tailwind v4 `@theme` 映射 |
+| [utilities.css](utilities.css) | `@utility`：母题工具类（斜纹、切角、斜楔、角括号、镂空字、警示条纹、竖条变箭头），以及菱形表单符号的开关 |
+| [index.css](index.css) | 入口：`tailwindcss` → `theme.css` → `utilities.css` → 基础样式 → `@source` |
+
+对外的三个入口（见包的 `exports`）：
+
+| 引入路径 | 对应 | 给谁用 |
+| --- | --- | --- |
+| `@endfield-ui/react/tailwind.css` | `index.css` | 用 Tailwind v4 的项目，代替 `@import "tailwindcss"` |
+| `@endfield-ui/react/styles.css` | `dist/styles.css` | 不用 Tailwind 的项目，预编译产物 |
+| `@endfield-ui/react/theme.css` | `theme.css` | 只要令牌、不要组件 |
+
+## theme.css 的结构
+
+1. **语义变量**：亮色定义在 `:root` 与 `[data-theme="light"]`（对齐官网的纸白基底），`[data-theme="dark"]` 覆盖为暗色（对齐游戏 HUD 与官网深色版块）。两种取值都可以加在局部容器上。
+   - `[data-theme="inverse"]` 是"和所在主题相反"，给反转块（标题带、表头带）用：底和字取所在主题的 `surface-inverse` / `ink-inverse`，其余取相反主题的值。亮、暗两块里的 `--ef-x-*` 就是给它准备的那份"相反主题的取值"，**改亮、暗任何一个值时要把另一块里对应的 `--ef-x-*` 一起改**——[theme.test.ts](theme.test.ts) 会核对。
+2. **`@theme`**：不随主题变化的原始令牌——色板、字体、字阶、圆角、阴影、缓动、动画、切角尺寸（`--cut-sm` / `md` / `lg`），以及层叠值（`--z-float` 100、`--z-nav` 200、`--z-overlay` 300、`--z-toast` 400、`--z-loader` 1000，用法是 `z-(--z-overlay)`）。
+3. **`@theme inline`**：把第 1 步的语义变量映射成 Tailwind 颜色，生成 `bg-surface`、`text-ink`、`border-line` 这类工具类。
+
+## 只用令牌
+
+```css
+@import "tailwindcss";
+@import "@endfield-ui/react/theme.css";
+```
+
+```html
+<html data-theme="dark">
+  <button class="bg-action text-on-action font-sans text-lg">前往游戏</button>
+</html>
+```
+
+## 修改令牌
+
+令牌值的依据写在 [docs/design/foundations](../../../../docs/design/foundations/color.md)。改动任何一个值时，同步改对应文档里的表格；文档里每个值都标了来源等级（实测 / 观察 / 社区 / 推断），替换"社区"和"推断"级别的值时请在文档里写明新的依据。
+
+新增或改名自定义的字阶、阴影、缓动、动画、字距令牌时，还要同步 [lib/cn.ts](../lib/cn.ts) 里登记给 `tailwind-merge` 的清单，否则 `cn()` 会把它们归错类。
+
+## 母题工具类
+
+| 工具类 | 作用 | 可调的变量 |
+| --- | --- | --- |
+| `hatch`，加 `hatch-mid` / `hatch-fine` | 45° 斜纹的粗、中、细三档 | `--hatch-color`、`--hatch-width` |
+| `hazard` | 黄黑警示条纹 | `--hazard-size` |
+| `cut-tr`、`cut-br`、`cut-diagonal`，加 `cut-sm` / `cut-md` / `cut-lg` | 切角与切口大小 | `--cut` |
+| `wedge`、`wedge-l`、`wedge-r` | 两侧 / 单侧斜切 | `--wedge` |
+| `corner-brackets` | 四角的 L 形短线，画在 `::after` 上 | `--bracket-color`、`--bracket-arm`、`--bracket-width`、`--bracket-offset` |
+| `ghost-hatch`、`ghost-outline` | 镂空字的斜纹与描边两种画法 | `--ghost-ink` |
+| `dot-grid` | 点阵底纹 | `--dot-color`、`--dot-size`、`--dot-gap` |
+| `blueprint-grid` | 工程网格底纹 | `--grid-color`、`--grid-gap` |
+| `contour` | 等高线底纹，贴在右下角、朝左上淡出 | `--contour-color`、`--contour-size`、`--contour-position`、`--contour-image` |
+| `marker-bar`、`marker-arrow` | 按钮里竖条变箭头的两个形状 | `--marker-bar` |
+
+- 跟着主题走的颜色（斜纹、角括号、镂空字、三种底纹）默认取 `--ef-ink`；警示条纹和斜纹的"中"档有意不随主题变。
+- `cut-*` 与 `wedge*` 用的是 `clip-path`，会把焦点环一起裁掉。可聚焦的元素把它们写在伪元素上：`before:cut-tr before:bg-action`。
+- `corner-brackets` 不替宿主设 `position`，宿主自己要是 `relative` 或 `absolute`。
+- `contour` 是遮罩（`mask-image`），会把元素自己的内容一起遮掉：只能写在空的装饰层上。`dot-grid` 和 `blueprint-grid` 是背景，没有这个限制，但同样建议画在独立的装饰层上。
+- 镂空字不叫 `text-hatch`：`text-*` 是字号和文字颜色的名字空间，`cn()` 合并类名时会把它当成颜色。
+
+这些类只画形状。什么东西可以切角、哪里能放斜纹，见 [docs/design/elements](../../../../docs/design/elements/corner-and-wedge.md) 各篇的"什么时候用"。预编译的 `styles.css` 里只有组件自己用到的那几个；不用 Tailwind 的项目用对应的装饰组件。
+
+文件末尾还有一个自定义变体 `choice-diamond:`，在祖先带 `data-choice="diamond"` 时生效，复选与单选靠它整体换成菱形符号。
+
+## 注意
+
+`index.css` 里的 `@source "../"` 扫的是整个 `src`，不能缩成只扫 `components`：焦点环这类共用的类名写在 `lib` 里，扫不到就不会生成。

package/src/styles/index.css

@@ -0,0 +1,25 @@
+/*
+ * endfield-ui 样式入口
+ *
+ * 已经在用 Tailwind CSS v4 的项目，用它代替 `@import "tailwindcss"`：
+ *   @import "@endfield-ui/react/tailwind.css";
+ *
+ * 不用 Tailwind 的项目，引入预编译好的 `@endfield-ui/react/styles.css`。
+ */
+
+@import "tailwindcss";
+@import "./theme.css";
+@import "./utilities.css";
+
+/*
+ * 让 Tailwind 扫到本包用到的类名。要扫整个 src，不能只扫 components：
+ * 焦点环这类共用的类名写在 lib 里。
+ */
+@source "../";
+
+@layer base {
+  body {
+    background-color: var(--ef-surface);
+    color: var(--ef-ink);
+  }
+}