@morlay/dsh-client-ui-primitives 0.0.6 → 0.0.8

package/src/client/schema-form/schema-form.module.css

@@ -0,0 +1,335 @@
+/* 行式编辑器的样式：等宽、行号、语法色、悬停行为——全部消费官方 `--dsw-*` token。
+   几何只有一套：行高 22px、行内间距 6px、动作键 20px、折叠列 14px、行号列 32px，行与行之间不各自决定。 */
+
+.editorRoot {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+  font-size: 14px;
+  line-height: 22px;
+  color: var(--dsw-alias-label-primary);
+}
+
+/* 一行：行号 + 折进 + 行内容。悬停给一层浅底。 */
+.lineRow {
+  display: flex;
+  /* 顶部对齐：行里出现输入框或多行值时，内容不跟着上下跳。 */
+  align-items: flex-start;
+  gap: 6px;
+  min-height: 22px;
+  padding-right: 8px;
+  white-space: nowrap;
+}
+
+.lineRow:hover {
+  background: var(--dsw-alias-bg-layer-2);
+}
+
+/* 选中一行（点行号）：整行留一层底色，便于对着行号找内容。 */
+.lineRow[data-selected='true'] {
+  background: var(--dsw-alias-bg-layer-3);
+}
+
+/* 本页改过还没保存：左边一道强调色，和「已经存进用户层」的浅灰区分开。 */
+.lineRow[data-dirty='true'] {
+  box-shadow: inset 2px 0 0 var(--dsw-alias-brand-primary);
+}
+
+.lineRow[data-overridden='true'] {
+  box-shadow: inset 2px 0 0 var(--dsw-elevation-stroke-color);
+}
+
+/* 改过的字段名用强调色（存没存看左边那道条）；出错时红优先。 */
+.lineRow[data-dirty='true'] [data-role='key'] {
+  color: var(--dsw-alias-brand-primary);
+}
+
+.lineRow[data-overridden='true'] [data-role='key'] {
+  color: var(--dsw-alias-brand-primary);
+}
+
+/* 有问题的行：半透明红底 + 左侧一道实红条，字段名与注释位那句都是红字。 */
+.lineRow[data-invalid='true'] {
+  background: color-mix(in srgb, var(--dsw-alias-state-error-secondary) 12%, transparent);
+  box-shadow: inset 2px 0 0 var(--dsw-alias-state-error-primary);
+}
+
+.lineRow[data-invalid='true'] [data-role='key'] {
+  color: var(--dsw-alias-state-error-primary);
+}
+
+/* 行内的行为按钮（撤回 / 恢复默认 / 复制 / 移除）：平时透明，悬停这一行才显形。 */
+.lineRow:hover [data-role='actions'] {
+  opacity: 1;
+}
+
+/* 一行的内容区：**缩进只作用在这里**——行号列固定在左边，缩进不推它。 */
+.lineBody {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  flex: 1;
+  min-width: 0;
+  min-height: 22px;
+}
+
+/* 行号列：右对齐、不可选、淡色。 */
+.lineNumber {
+  flex: none;
+  width: 32px;
+  line-height: 22px;
+  text-align: right;
+  color: var(--dsw-alias-label-caption);
+  user-select: none;
+  cursor: pointer;
+}
+
+/* 折叠 chevron（官方箭头图标，尺寸与别的行内图标同源）。 */
+.lineFold {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: 14px;
+  height: 22px;
+  padding: 0;
+  border: 0;
+  background: none;
+  color: var(--dsw-alias-label-caption);
+  cursor: pointer;
+}
+
+.lineFold:hover {
+  color: var(--dsw-alias-label-secondary);
+}
+
+/* 叶子行的折叠占位（保持列对齐）。 */
+.lineFoldSpacer {
+  flex: none;
+  width: 14px;
+}
+
+/* 键名（配置键原样；数组下标淡一些）。 */
+.lineKey {
+  flex: none;
+  color: var(--dsw-alias-label-primary);
+}
+
+.lineKey[data-index='true'] {
+  color: var(--dsw-alias-label-caption);
+}
+
+/* 结构符与标点（`{` `}` `[` `]` `:`）。 */
+.lineToken {
+  flex: none;
+  color: var(--dsw-alias-label-caption);
+}
+
+/* 值（token）：字符串 / 数字 / 布尔各有语法色。
+   **必须是块级盒**：`overflow` / `text-overflow` 对 inline 盒不生效，inline 的 token 无论多长都不会截断，
+   只会把行撑宽。 */
+.lineValue {
+  display: block;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  cursor: text;
+  color: var(--dsw-alias-state-business-primary);
+}
+
+.lineValue[data-tone='number'] {
+  color: var(--dsw-alias-state-warn-primary);
+}
+
+.lineValue[data-tone='boolean'] {
+  color: var(--dsw-alias-state-success-primary);
+}
+
+.lineValue[data-tone='empty'] {
+  color: var(--dsw-alias-label-caption);
+}
+
+/* 值在行里的位置（字段槽的宿主）：键名与结构符都是 `flex: none`，它是行里**唯一可收缩**的那一项。
+   不生长：短值保持自然宽度，长值才收缩到行尾并自己截断。 */
+.valueSlot {
+  display: block;
+  flex: 0 1 auto;
+  min-width: 0;
+  overflow: hidden;
+}
+
+/* 值上的下拉触发：**它自己就是值的呈现**（不再是「值 + 一个下拉」两遍），点开才出菜单。 */
+.valueTrigger {
+  display: inline-flex;
+  align-items: center;
+  gap: 2px;
+  min-width: 0;
+  padding: 0;
+  border: 0;
+  background: none;
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+  color: var(--dsw-alias-label-caption);
+}
+
+.valueTrigger:disabled {
+  cursor: default;
+}
+
+.valueTrigger:focus-visible {
+  outline: none;
+}
+
+/* 行内输入的外壳：官方 `Input` 压到与值同一行高，并**吃掉剩下的宽度**。
+   行内编辑与容器闭合行的添加输入共用它——两处的输入框因此长得一模一样。 */
+.compactInput {
+  display: inline-flex;
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.compactInput > span {
+  width: 100%;
+  height: 22px;
+  padding: 0 6px;
+  border-radius: 4px;
+}
+
+.compactInput input {
+  font-size: 14px;
+  line-height: 22px;
+}
+
+/* 多行值的行内输入：官方没有多行原子，所以这里用同一套观感的字段壳（同边框、同圆角、同焦点色），
+   高度跟着内容长、宽度同样撑满剩下的位置。 */
+.compactTextField {
+  display: inline-flex;
+  flex: 1 1 auto;
+  min-width: 0;
+  padding: 0 6px;
+  border-radius: 4px;
+  background: var(--dsw-alias-bg-layer-1);
+  /* 细线走 theme 的描边（0.5px 与颜色都由 token 给）。 */
+  border: 0;
+  box-shadow: 0 0 0 0.5px var(--dsw-elevation-stroke-color);
+}
+
+.compactTextField:focus-within {
+  --dsw-elevation-stroke-color: var(--dsw-alias-brand-primary);
+}
+
+.compactTextField > textarea {
+  flex: 1;
+  width: 100%;
+  min-height: 20px;
+  max-height: 240px;
+  padding: 0;
+  border: 0;
+  outline: none;
+  background: transparent;
+  resize: none;
+  field-sizing: content;
+  font-family: inherit;
+  font-size: 14px;
+  line-height: 22px;
+  color: var(--dsw-alias-label-primary);
+}
+
+/* 行内注释（schema 说明与业务文案）：比配置值小一档、tertiary 色，占满这一行剩下的宽度，长了就截断——
+   **真的被截断时**才由官方 `Tooltip` 给全文。 */
+.lineComment {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  color: var(--dsw-alias-label-tertiary);
+  font-family: inherit;
+  font-size: 12px;
+}
+
+/* 行内的校验消息（与注释放同一档字号）：可收缩、自己截断、**截断了**才由官方 `Tooltip` 给全文。
+   `flex: 0 1 auto`（不生长）：短消息别铺满整行，添加入口那一行里也不跟输入框抢剩下的宽度。 */
+.lineInvalid {
+  flex: 0 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  color: var(--dsw-alias-state-error-primary);
+  font-family: inherit;
+  font-size: 12px;
+}
+
+/* 行尾的动作组：方形图标键（默认透明，悬停时显形，显形规则写在行上）。 */
+.lineActions {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  flex: none;
+  opacity: 0;
+}
+
+.lineActions > button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 20px;
+  height: 20px;
+  padding: 0;
+  border: 0;
+  border-radius: 4px;
+  background: none;
+  color: var(--dsw-alias-label-secondary);
+  cursor: pointer;
+}
+
+.lineActions > button:hover {
+  background: var(--dsw-alias-bg-layer-3);
+  color: var(--dsw-alias-label-primary);
+}
+
+.lineActions > button:disabled {
+  cursor: not-allowed;
+  color: var(--dsw-alias-label-dimmed);
+}
+
+/* 编辑态的两个按钮常显，而且**要有底色与描边**：行底色上只有淡色图标是看不见的，
+   所以这里给实体按钮（theme 的描边 + 一层底），确认用成功档、取消用中性档。 */
+.hoverActions[data-editing='true'] {
+  opacity: 1;
+  gap: 6px;
+}
+
+.hoverActions[data-editing='true'] > button {
+  box-shadow: 0 0 0 0.5px var(--dsw-elevation-stroke-color);
+  background: var(--dsw-alias-bg-layer-1);
+  color: var(--dsw-alias-label-primary);
+}
+
+.hoverActions[data-editing='true'] > button:first-of-type {
+  color: var(--dsw-alias-state-success-primary);
+}
+
+/* 添加输入：**跟在容器的闭合括号同一行**（菜单锚在它上面），宽度吃掉剩下的位置。 */
+.addWrap {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  flex: 1 1 auto;
+  min-width: 0;
+  margin-left: 6px;
+}
+
+.addWrap[data-invalid='true'] input {
+  border-color: var(--dsw-alias-state-error-primary);
+}
+
+/* 一行说明（不可用 / 没有可生成项时用）。 */
+.hint {
+  margin: 0;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-tertiary);
+}

package/src/client/schema-form/testing/resize-observer-stub.ts

@@ -0,0 +1,63 @@
+// jsdom 里跑官方 `Tooltip`、以及靠 `scrollWidth` / `clientWidth` 判截断的行内文本的环境替身。
+//
+// 官方气泡的宽度/定位来自 `ResizeObserver` 回调（`visibility` 也只在那个回调里置为 visible），而 jsdom 没有这个
+// API：缺了它，hover 之后的 effect 会直接抛 `ReferenceError`。替身做两件事：注册时喂回一次 `borderBoxSize`
+// （让气泡进入可见态），并给用例一个 `notifyResize()`——真机上「盒子宽度变了」是浏览器通知的，jsdom 里没有那个
+// 事件，用例只能自己发一次。
+//
+// 它**不是**几何证据：真尺寸与定位只能在浏览器里量（本包 `.agents/standards/how-to-verify.md` 记了这条与探针的
+// 用法），所以用例的判据是「hover 出气泡、气泡里是全文」，不拿替身去断言气泡的实际尺寸。
+
+interface StubObserver {
+  readonly targets: Set<Element>;
+  readonly notify: ResizeObserverCallback;
+}
+
+const live = new Set<StubObserver>();
+
+export function stubResizeObserver(): void {
+  class ResizeObserverStub {
+    #notify: ResizeObserverCallback;
+    #targets = new Set<Element>();
+    #live: StubObserver;
+
+    constructor(notify: ResizeObserverCallback) {
+      this.#notify = notify;
+      this.#live = { targets: this.#targets, notify };
+      live.add(this.#live);
+    }
+
+    // 注册即回调一次（真实的 ResizeObserver 也会在首帧给一次初始尺寸）。
+    observe(target: Element): void {
+      this.#targets.add(target);
+      this.#notify([entry(target)], this as unknown as ResizeObserver);
+    }
+
+    unobserve(target: Element): void {
+      this.#targets.delete(target);
+    }
+
+    disconnect(): void {
+      this.#targets.clear();
+      live.delete(this.#live);
+    }
+  }
+  (globalThis as { ResizeObserver?: unknown }).ResizeObserver = ResizeObserverStub;
+}
+
+// 让还活着的替身观察者再收到一次尺寸通知：用例把元素的几何改掉之后调它，等价于浏览器通知「这个盒子变了」。
+export function notifyResize(): void {
+  for (const observer of live) {
+    const entries = [...observer.targets].map((target) => entry(target));
+    if (entries.length > 0) {
+      observer.notify(entries, undefined as unknown as ResizeObserver);
+    }
+  }
+}
+
+function entry(target: Element): ResizeObserverEntry {
+  return {
+    target,
+    borderBoxSize: [{ blockSize: 0, inlineSize: 0 }],
+  } as unknown as ResizeObserverEntry;
+}

package/src/client/schema-form/value.tsx

@@ -7,7 +7,9 @@ import { useState, type ReactNode } from "react";
 import { IconChevronDownOutlineRegular, Menu } from "@deepseek-ai/dsh-client-ui-primitives";
 import type { SelectOption } from "./hints.ts";
 import type { SchemaFieldOwnerProps } from "./slot-contract.ts";
-import { ICON_SIZE, LineValue, ValueTrigger } from "./styles.ts";
+import { ICON_SIZE } from "./geometry.ts";
+import css from "./schema-form.module.css";
+import { TruncatedTooltip } from "./TruncatedTooltip.tsx";
 
 // 编辑态文本：字符串就是原文（换行照旧），其余按 JSON 写。
 export function valueText(value: unknown): string {
@@ -42,21 +44,22 @@ export function tokenTone(value: unknown): "string" | "number" | "boolean" | "em
 export function InlineValue({ owner }: { owner: SchemaFieldOwnerProps }): ReactNode {
   if (owner.options !== undefined) return <OptionSelect owner={owner} options={owner.options} />;
   if (owner.node.meta.secret) {
-    // secret 不回显值：截断时不给全文，只给说明。
+    // secret 不回显值：这里显示的是「已配置」的 `••••••`，它不会截断，`owner.hint` 也不是「被截断文本的全文」
+    // ——按行内浮层的口径它不该弹气泡，所以回到非侵入的原行为：挂原生 `title`。
     return (
-      <LineValue data-tone="empty" title={owner.hint}>
+      <span className={css.lineValue} data-tone="empty" title={owner.hint}>
         {owner.secretConfigured ? "••••••" : ""}
-      </LineValue>
+      </span>
     );
   }
+  // 值长了会在行里截断（值槽可收缩）：确实截断时整份内容由官方 `Tooltip` 承载，放得下就不挂。
+  const text = tokenText(owner.value);
   return (
-    <LineValue
-      data-tone={owner.node.readOnly === null ? tokenTone(owner.value) : "empty"}
-      // 值长了会截断：整份内容挂在 title 上，hover 就能看全。
-      title={tokenText(owner.value)}
-    >
-      {tokenText(owner.value)}
-    </LineValue>
+    <TruncatedTooltip label={text}>
+      <span className={css.lineValue} data-tone={owner.node.readOnly === null ? tokenTone(owner.value) : "empty"}>
+        {text}
+      </span>
+    </TruncatedTooltip>
   );
 }
 
@@ -99,7 +102,7 @@ function OptionSelect({
         setOpen(false);
       }}
       anchor={
-        <ValueTrigger
+        <button className={css.valueTrigger}
           type="button"
           disabled={owner.disabled}
           aria-label={owner.label}
@@ -107,13 +110,13 @@ function OptionSelect({
             setOpen(true);
           }}
         >
-          <LineValue
+          <span className={css.lineValue}
             data-tone={current === undefined ? tokenTone(owner.value) : tokenTone(current.value)}
           >
             {label}
-          </LineValue>
+          </span>
           <IconChevronDownOutlineRegular size={ICON_SIZE} />
-        </ValueTrigger>
+        </button>
       }
     />
   );

package/src/client/settings-form/SettingsFieldRow.module.css

@@ -0,0 +1,93 @@
+/* 字段行（`SettingsFieldRow`）：官方 `SettingsValueField` 的留白口径（上下各 12px），分隔线由调用方按
+   「不是这一组的第一个字段」显式声明——两种排法与官方控件的留白因此完全一致。 */
+.row {
+  display: flex;
+  flex-direction: column;
+}
+
+.row[data-divider='true'] {
+  border-top: 0.5px solid var(--dsw-alias-border-l2);
+}
+
+/* 上下排（输入类）：标签 / 控件 / 说明同列。 */
+.body {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 0;
+}
+
+/* 右置排（切换类）：左列标签与说明，控件贴最右。 */
+.inline {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  padding: 12px 0;
+}
+
+.text {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  min-width: 0;
+}
+
+.label {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 13px;
+  font-weight: 500;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-primary);
+}
+
+/* 覆盖标记（「已覆盖」）：照官方 badge 的 neutral 那一档。 */
+.badge {
+  display: inline-flex;
+  align-items: center;
+  padding: 1px 8px;
+  border-radius: 999px;
+  corner-shape: round;
+  font-size: 11px;
+  line-height: 17px;
+  font-weight: 500;
+  color: var(--dsw-alias-label-secondary);
+  background: var(--dsw-alias-bg-module-platform);
+}
+
+/* 恢复默认的入口：文字按钮，没有边框与底色。 */
+.reset {
+  padding: 0;
+  border: none;
+  background: none;
+  font: inherit;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-secondary);
+  cursor: pointer;
+}
+
+.reset:hover:not(:disabled) {
+  color: var(--dsw-alias-label-primary);
+}
+
+.reset:disabled {
+  cursor: default;
+}
+
+.hint {
+  margin: 0;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.invalid {
+  margin: 0;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--dsw-alias-state-error-primary);
+}

package/src/client/settings-form/SettingsFieldRow.tsx

@@ -0,0 +1,103 @@
+// 字段行：设置面上"一个字段"的容器——标签、控件、说明、非法提示与"已覆盖"徽标都由它摆位置。
+// 两种排法按控件的宽度选：输入类（stack）是标签 / 控件 / 说明同列，切换类（inline）把控件贴最右。
+// 留白与分隔线的口径与官方 `SettingsValueField` 一致（上下各 12px、相邻 0.5px 细线）。
+
+import type { HTMLAttributes, ReactNode } from "react";
+import { classes } from "../controls/classes.ts";
+import css from "./SettingsFieldRow.module.css";
+
+export interface SettingsFieldRowProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, "children" | "color"> {
+  // 字段名。
+  label: string;
+  // 字段下面那句说明（"这一项到底管什么"）。
+  hint: string;
+  // 控件的摆法：`stack`（同列，输入类，缺省）或 `inline`（控件贴右，切换类）。
+  layout?: "stack" | "inline";
+  // 与上一个字段之间画一条细分隔线（这一组里不是第一个字段时为 true）。
+  divider?: boolean;
+  // 字段被用户层覆盖时的徽标文案；不给就不显示。
+  overriddenLabel?: string;
+  // 恢复默认的入口：给了它与 `resetLabel` 才显示（覆盖用户层那一项）。
+  resetLabel?: string;
+  onReset?: () => void;
+  // 非法提示；不给就只说合法的那些。
+  invalid?: string;
+  children: ReactNode;
+}
+
+export function SettingsFieldRow({
+  label,
+  hint,
+  layout = "stack",
+  divider = false,
+  overriddenLabel,
+  resetLabel,
+  onReset,
+  invalid,
+  children,
+  className,
+  ...rest
+}: SettingsFieldRowProps): ReactNode {
+  const labelNode = (
+    <span className={css.label}>
+      {label}
+      {overriddenLabel === undefined ? null : (
+        <>
+          <span className={css.badge}>{overriddenLabel}</span>
+          {resetLabel === undefined || onReset === undefined ? null : (
+            <button
+              type="button"
+              className={css.reset}
+              onClick={() => {
+                onReset();
+              }}
+            >
+              {resetLabel}
+            </button>
+          )}
+        </>
+      )}
+    </span>
+  );
+  const invalidNode =
+    invalid === undefined ? null : (
+      <p className={css.invalid} role="alert">
+        {invalid}
+      </p>
+    );
+  if (layout === "inline") {
+    return (
+      <div
+        className={classes(css.row, className)}
+        data-role="field-row"
+        data-divider={divider ? "true" : "false"}
+        {...rest}
+      >
+        <div className={css.inline}>
+          <div className={css.text}>
+            {labelNode}
+            <p className={css.hint}>{hint}</p>
+          </div>
+          {children}
+        </div>
+        {invalidNode}
+      </div>
+    );
+  }
+  return (
+    <div
+      className={classes(css.row, className)}
+      data-role="field-row"
+      data-divider={divider ? "true" : "false"}
+      {...rest}
+    >
+      <div className={css.body}>
+        {labelNode}
+        {children}
+        <p className={css.hint}>{hint}</p>
+      </div>
+      {invalidNode}
+    </div>
+  );
+}

package/src/client/settings-form/index.ts

@@ -1,19 +1,6 @@
-// 设置表单原语的 client 出口：模型 + 控件 + 表单框，命名与上游
-// `@deepseek-ai/dsh-client-ui-primitives` 同形（搬迁记录见本包 .agents/adrs/）。
+// 设置表单原语的 client 出口：**直接用上游那份**（同名同形的 `SettingsForm` / 两个字段控件 / 表单模型，样式
+// 本来就是上游的 `.module.css`），这里只留本包自造的那一个字段行——上游的 `SettingsValueField` 摆不下
+// 「标签 + 控件 + 说明 + 覆盖标记」这一整行。
 
-export { SettingsFormModel, settingsNumberField, settingsTextField } from "./form-model.ts";
-export type {
-  SettingsFieldSpec,
-  SettingsFieldState,
-  SettingsFieldWrite,
-  SettingsFormActions,
-  SettingsFormPathOp,
-  SettingsFormScope,
-  SettingsFormScopeSnapshot,
-  SettingsFormShell,
-  SettingsSecretSpec,
-} from "./form-model.ts";
-export { SettingsSecretField, SettingsValueField } from "./fields.tsx";
-export type { SettingsFieldProps } from "./fields.tsx";
-export { SettingsForm } from "./SettingsForm.tsx";
-export type { SettingsFormLabels, SettingsFormProps } from "./SettingsForm.tsx";
+export { SettingsFieldRow } from "./SettingsFieldRow.tsx";
+export type { SettingsFieldRowProps } from "./SettingsFieldRow.tsx";

package/src/css-modules.d.ts

@@ -0,0 +1,6 @@
+// 本包 client 半的组件样式是上游那套 CSS Modules（`*.module.css`，lightningcss 在构建期编译并内联）：
+// bundler 解析得动，TS 需要这份 ambient 声明把它定成「有一个 class 映射的模块」。
+declare module "*.module.css" {
+  const classes: Readonly<Record<string, string | undefined>>;
+  export default classes;
+}