@endfield-ui/react 0.2.0 → 1.0.0

package/src/lib/README.md

@@ -7,8 +7,10 @@
 | `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 合成一个 |
+| `inline-style.ts` | `dropEmptyStyle()`：往元素上临时写过内联样式、又都撤掉之后，把空下来的 `style` 属性拿掉。浏览器是懒着同步这个属性的，直接删会落空、回头又冒出一个空的 |
 | `defined.ts` | `defined()`：去掉值是 `undefined` 的属性。把控件的属性合并到使用方给的元素上（`render`）之前用，免得把那个元素自己写的盖掉 |
 | `decor.ts` | `decor`：装饰层共用的类 |
+| `motion.ts` | 几处共用的动效类名。`enterFromSide`：浮层面板进场的方向位移——按基元给的 `data-side`，起点往触发元素那一侧偏 `--motion-shift`；`collapse` / `collapseEnter` / `collapseInner`：按高度收放；`fadeInFast`：小件的淡入；`indicator` / `indicatorBox`：画在容器 `::after` 上的选中指示，位置来自 `useIndicator`；`flipBox` / `flipLeaving`：补位（`useFlip`）的那一排，和里面走的那一项。见 [动效](../../../../docs/design/foundations/motion.md#补的几条约定) |
 | `date.ts` | 日期的纯函数：加减日和月、比较、把两天排成先后、夹到范围内、月历的六行七列。日期一律是 `YYYY-MM-DD` 的字符串，全部按 UTC 算，不碰本地时区。`Calendar`、`DatePicker`、`Schedule` 共用，不对外导出 |
 | `file.ts` | 文件的纯函数：按 `accept` 认类型（扩展名、MIME、`image/*` 通配）、把字节数写成 `1.2 MB`、取扩展名、判断是不是同一个文件。`FileUpload` 用，不对外导出 |
 

package/src/lib/cn.ts

@@ -24,6 +24,9 @@ const twMerge = extendTailwindMerge({
         "turn-in",
         "fade-in",
         "indeterminate",
+        "bracket-in",
+        "shift-in",
+        "wipe-in",
       ],
     },
   },

package/src/lib/inline-style.ts

@@ -0,0 +1,12 @@
+/**
+ * 往元素上临时写过内联样式、又都撤掉之后调：原来没有 `style` 属性的，
+ * 不留一个空的在上面。
+ *
+ * 先问一句"有没有这个属性"不是多余的：浏览器是懒着把内联样式同步成属性的，
+ * 不问就去删，删的那一下落空，回头它又冒出来一个空的 `style=""`。
+ */
+export function dropEmptyStyle(node: HTMLElement) {
+  if (node.style.length === 0 && node.hasAttribute("style")) {
+    node.removeAttribute("style");
+  }
+}

package/src/lib/motion.ts

@@ -0,0 +1,90 @@
+/**
+ * 浮层从触发它的那一侧来：进场的起点往触发处偏 `--motion-shift`，走完归位。
+ * 用在基元的浮层面板上——它们带着 `data-side`（面板在触发元素的哪一侧）。
+ *
+ * 位移只写在 `data-starting-style` 上：退场不走位移，只淡出。
+ * 用的地方自己给 `translate` 加过渡。`inline-start` / `inline-end` 按从左往右的排版算。
+ */
+export const enterFromSide = [
+  "data-starting-style:data-[side=bottom]:-translate-y-(--motion-shift)",
+  "data-starting-style:data-[side=top]:translate-y-(--motion-shift)",
+  "data-starting-style:data-[side=right]:-translate-x-(--motion-shift)",
+  "data-starting-style:data-[side=left]:translate-x-(--motion-shift)",
+  "data-starting-style:data-[side=inline-end]:-translate-x-(--motion-shift)",
+  "data-starting-style:data-[side=inline-start]:translate-x-(--motion-shift)",
+].join(" ");
+
+/**
+ * 按高度收放，不量高度：外面这一层是只有一行的网格，行高在 `0fr` 和 `1fr` 之间过渡；
+ * 里面再套一层 `collapseInner`，裁掉还放不下的那一截。表格的明细行、字段下面的错误文字
+ * 都这么收放——内容后来变高了也跟着走。
+ *
+ * 展开 300ms、收起 200ms。收起由 `data-leaving` 触发，配 `usePresence`：收完再卸载。
+ */
+export const collapse = [
+  "grid grid-rows-[1fr]",
+  "transition-[grid-template-rows] duration-(--duration-base) ease-standard",
+  "data-leaving:grid-rows-[0fr] data-leaving:duration-(--duration-fast)",
+].join(" ");
+
+/**
+ * 展开的起点，写在 `@starting-style` 里：元素一挂上就从 0 长出来，展开到一半又收起时
+ * 过渡从半路折回去。只给后来才出现的加（`usePresence` 的 `entered`）——一开始就展开着的，
+ * 不该在载入时播一遍。不支持它的旧浏览器只是没有展开的过程。
+ */
+export const collapseEnter = "starting:grid-rows-[0fr]";
+
+/** 只裁纵向：横向照旧，里面的东西该多宽还是多宽 */
+export const collapseInner = "min-h-0 min-w-0 overflow-y-clip";
+
+/** 小件的淡入，200ms：切过来的页签面板、新加的标签、新选的文件 */
+export const fadeInFast =
+  "animate-fade-in [animation-duration:var(--duration-fast)]";
+
+/**
+ * 选中指示：画在容器的 `::after` 上的一块东西，压在容器的底色之上、各项之下。
+ * 位置和尺寸来自 `useIndicator` 写在容器上的变量；换了一项时滑过去（200ms，
+ * 和各项换字色同一拍），没有当前项时原地淡出。
+ *
+ * 容器上没有 `data-indicator`（量不到）时不画——各项照旧自己画选中态，
+ * 所以给各项的选中底加一个 `in-data-indicator:` 的变体把它让出来。
+ * 这里只管定位和过渡：颜色、圆角由用的地方给，几何用 `indicatorBox` 或者自己写。
+ */
+export const indicator = [
+  "relative isolate",
+  "after:pointer-events-none after:absolute after:top-0 after:left-0 after:-z-1",
+  "after:hidden data-indicator:after:block",
+  "after:opacity-0 data-[indicator=on]:after:opacity-100",
+  "after:transition-[translate,width,height,opacity] after:duration-(--duration-fast) after:ease-standard",
+  // 没有当前项的时候只留淡入淡出：下一次亮起来是原地出现，不是从上一个位置滑来
+  "data-[indicator=off]:after:transition-[opacity]",
+  "data-indicator-instant:after:transition-none",
+].join(" ");
+
+/** 指示盖住当前项的整个盒子：分段选择的墨块、胶囊页签的底 */
+export const indicatorBox = [
+  "after:h-(--indicator-h) after:w-(--indicator-w)",
+  "after:translate-x-(--indicator-x) after:translate-y-(--indicator-y)",
+].join(" ");
+
+/**
+ * 补位（`useFlip`）：一排里有一项走了，其余的从旧位置滑到新位置。
+ *
+ * `flipBox` 给那一排——走的那一项以它为参照钉在原处，并且压在别的项下面。
+ * 少了一行它就矮了：高度由钩子量着收（200ms），这期间还在滑的项不露到它外面去；
+ * 各行靠上排，撑着的那一段空在底下。
+ * `flipLeaving` 给会走的每一项：带上 `data-leaving` 之后脱离排版（位置由钩子给）、
+ * 原地淡出、点不到。
+ *
+ * 过渡由用的地方自己写：各项的 `translate`（滑回原位）、走的那一项的 `opacity`，
+ * 都是 200ms——这几项多半本来就带着换色的过渡，得写进同一份清单里。
+ */
+export const flipBox = [
+  "relative isolate content-start overflow-y-clip",
+  "transition-[min-height] duration-(--duration-fast) ease-standard",
+].join(" ");
+
+export const flipLeaving = [
+  "data-leaving:pointer-events-none data-leaving:absolute data-leaving:-z-1",
+  "data-leaving:opacity-0",
+].join(" ");

package/src/styles/theme.css

@@ -1,9 +1,9 @@
 /*
- * endfield-ui 设计令牌（草案）
+ * endfield-ui 设计令牌
  *
  * 用法：
  *   @import "tailwindcss";
- *   @import "./theme.css";
+ *   @import "@endfield-ui/react/theme.css";
  *
  * 结构：
  *   1. 语义变量      随主题变化；亮色在 :root 与 [data-theme="light"]，
@@ -336,6 +336,13 @@
   --duration-slow: 400ms;
   --duration-slower: 600ms;
 
+  /*
+   * 进场的方向位移：浮层从触发它的那一侧来。只是提示方向，不是滑行。
+   * 大的那一档给大面积的和贴着视口边缘出来的（全屏菜单的栏目、轻提示）
+   */
+  --motion-shift: 4px;
+  --motion-shift-lg: 8px;
+
   /* —— 母题尺寸 —— */
   --cut-sm: 6px;
   --cut-md: 10px;
@@ -368,6 +375,9 @@
   --animate-fade-in: ef-fade-in 300ms ease-out both;
   --animate-indeterminate: ef-indeterminate 1.2s linear infinite alternate;
   --animate-pulse: ef-pulse 2s ease-in-out infinite;
+  --animate-bracket-in: ef-bracket-in 200ms ease-out both;
+  --animate-shift-in: ef-shift-in 300ms ease-out both;
+  --animate-wipe-in: ef-wipe-in 300ms ease-out both;
 
   /* 三次短促闪烁后点亮（官网实测的关键帧节奏） */
   @keyframes ef-flicker {
@@ -507,6 +517,54 @@
       opacity: 0.6;
     }
   }
+
+  /*
+   * 角括号落位：八段短线各自从角的顶点伸到满长。写成 after:animate-bracket-in，
+   * 和 corner-brackets 一起用——八层的顺序（横、竖交替）跟着 utilities.css 里那八层背景走。
+   * 只写起点：终点就是括号自己的尺寸。只动背景的尺寸，括号不会比平时多占一点地方
+   */
+  @keyframes ef-bracket-in {
+    from {
+      background-size:
+        0 var(--_w),
+        var(--_w) 0,
+        0 var(--_w),
+        var(--_w) 0,
+        0 var(--_w),
+        var(--_w) 0,
+        0 var(--_w),
+        var(--_w) 0;
+    }
+  }
+
+  /*
+   * 位移入场：从偏着的地方淡入归位。往哪边偏、偏多少由用的地方给
+   * （--shift-x / --shift-y，量用 --motion-shift 那两档），不给就只是淡入。
+   * 只写起点：终点就是元素自己的样子
+   */
+  @keyframes ef-shift-in {
+    from {
+      opacity: 0;
+      translate: var(--shift-x, 0) var(--shift-y, 0);
+    }
+  }
+
+  /*
+   * 擦入：从左往右露出来。两头都要写——"没有裁切"和 inset() 之间插不了值。
+   * 有东西画到盒子外面一点的（小型面积图的折线有半个线宽在外面），用 --wipe-bleed
+   * 把另外几边往外让，不然走完之后那一圈是被裁掉的
+   */
+  @keyframes ef-wipe-in {
+    from {
+      clip-path: inset(
+        calc(0px - var(--wipe-bleed, 0px)) 100%
+          calc(0px - var(--wipe-bleed, 0px)) calc(0px - var(--wipe-bleed, 0px))
+      );
+    }
+    to {
+      clip-path: inset(calc(0px - var(--wipe-bleed, 0px)));
+    }
+  }
 }
 
 /* ------------------------------------------------------------------ */
@@ -552,6 +610,24 @@
   --color-info: var(--ef-info);
 }
 
+/* ------------------------------------------------------------------ */
+/* 主题切换                                                             */
+/* ------------------------------------------------------------------ */
+
+/*
+ * useTheme 切亮暗时整页交叉淡化一次（浏览器支持视图过渡时）。切的那一下它在 <html> 上标
+ * data-theme-switching，这里把根的那几层换成"颜色、透明度"那一档的时长。
+ * 只在这个标记下生效：使用方自己的视图过渡不受影响。三层要一起给——只改新旧两层的话，
+ * 组那一层还是浏览器默认的 250ms，整个过渡要到那时候才算完。
+ * "减少动态效果"不在这里管：开了的时候 useTheme 根本不走视图过渡
+ */
+:root[data-theme-switching]::view-transition-group(root),
+:root[data-theme-switching]::view-transition-old(root),
+:root[data-theme-switching]::view-transition-new(root) {
+  animation-duration: var(--duration-fast);
+  animation-timing-function: var(--ease-standard);
+}
+
 /* ------------------------------------------------------------------ */
 /* 减少动态效果                                                         */
 /* ------------------------------------------------------------------ */
@@ -563,6 +639,9 @@
     animation-duration: 0.01ms !important;
     animation-iteration-count: 1 !important;
     transition-duration: 0.01ms !important;
+    /* 延迟也归零：不然错开的入场会变成一项一项蹦出来 */
+    animation-delay: 0s !important;
+    transition-delay: 0s !important;
     scroll-behavior: auto !important;
   }
 }

package/src/styles/utilities.css

@@ -121,7 +121,8 @@
 /* ------------------------------------------------------------------ */
 /* 角括号：四角各一个 L 形短线，用 ::after 的背景画，不占用 outline。    */
 /* 宿主要自己定位（relative 或 absolute）；括号画在宿主之外，            */
-/* 所以宿主和它的裁切祖先之间要留出 --bracket-offset 的空隙             */
+/* 所以宿主和它的裁切祖先之间要留出 --bracket-offset 的空隙。            */
+/* 要它出现时"落位"，再加 after:animate-bracket-in（关键帧在 theme.css）  */
 /* ------------------------------------------------------------------ */
 
 @utility corner-brackets {