@morlay/dsh-client-ui-primitives 0.0.4 → 0.0.5

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

@@ -21,7 +21,7 @@ const Input = styled("input")(styles.input);
 const Invalid = styled("p")(styles.invalid);
 const Hint = styled("p")(styles.hint);
 
-/** 上游 icons 里的 IconInfoOutlineRegular（fill-only 几何，整份图标表不搬）。 */
+// 上游 icons 里的 IconInfoOutlineRegular（fill-only 几何，整份图标表不搬）。
 function InfoGlyph({ size }: { size: number }) {
   return (
     <svg
@@ -42,50 +42,45 @@ function InfoGlyph({ size }: { size: number }) {
   );
 }
 
-/** What every settings field control needs regardless of its value type. */
+// What every settings field control needs regardless of its value type.
 export interface SettingsFieldProps {
-  /** Stable id associating the label with its control. */
+  // Stable id associating the label with its control.
   id: string;
-  /** Visible label. */
+  // Visible label.
   label: string;
-  /** One-line explanation rendered under the control. */
+  // One-line explanation rendered under the control.
   hint: string;
-  /** Draft text this control renders. */
+  // Draft text this control renders.
   text: string;
-  /** True when saving would leave a user-layer entry for this field. */
+  // True when saving would leave a user-layer entry for this field.
   overridden: boolean;
-  /** True when the draft is not a value this field accepts. */
+  // True when the draft is not a value this field accepts.
   invalid: boolean;
-  /** Copy for the overridden badge. */
+  // Copy for the overridden badge.
   overriddenLabel: string;
-  /** Copy for the reset control. */
+  // Copy for the reset control.
   resetLabel: string;
-  /** Copy shown in place of the hint while the draft is invalid. */
+  // Copy shown in place of the hint while the draft is invalid.
   invalidLabel: string;
-  /** Disables every control (read-only document, or an unavailable namespace). */
+  // Disables every control (read-only document, or an unavailable namespace).
   disabled: boolean;
-  /** Stage draft text. */
+  // Stage draft text.
   onEdit: (text: string) => void;
-  /** Stage a clear so the field re-inherits the composition layer. */
+  // Stage a clear so the field re-inherits the composition layer.
   onReset: () => void;
 }
 
-/**
- * A staged value field. `numeric` only hints the keypad: which drafts a field
- * accepts is decided by its spec, so the control never silently rewrites what
- * the user typed.
- * @param props - the field's copy, its staged text, and the edit actions.
- * @returns the labelled control.
- */
+// A staged value field. `numeric` only hints the keypad: which drafts a field accepts is decided by its spec, so the
+// control never silently rewrites what the user typed.
 export function SettingsValueField(
   props: Omit<SettingsFieldProps, "hint"> & {
-    /** Optional explanation shown below the input. */
+    // Optional explanation shown below the input.
     hint?: string;
-    /** Rules disclosed by the information button beside the label. */
+    // Rules disclosed by the information button beside the label.
     help?: { label: string; content: ReactNode };
-    /** Hints a numeric keypad without narrowing what the control accepts. */
+    // Hints a numeric keypad without narrowing what the control accepts.
     numeric?: boolean;
-    /** Placeholder shown while the draft is empty. */
+    // Placeholder shown while the draft is empty.
     placeholder?: string;
   },
 ) {
@@ -153,19 +148,14 @@ export function SettingsValueField(
   );
 }
 
-/**
- * A write-only credential control. The value never rides a response, so the
- * control reports only whether one is configured and starts blank; a blank
- * draft writes nothing, which keeps the stored key rather than clearing it.
- * 控件要求浏览器不要把已存的登录密码自动填进来（上游 11c0511271）。
- * @param props - the field's copy, its staged text, and the configured state.
- * @returns the labelled control.
- */
+// A write-only credential control. The value never rides a response, so the control reports only whether one is
+// configured and starts blank; a blank draft writes nothing, which keeps the stored key rather than clearing it.
+// 控件要求浏览器不要把已存的登录密码自动填进来（上游 11c0511271）。
 export function SettingsSecretField(
   props: Pick<SettingsFieldProps, "id" | "label" | "hint" | "text" | "disabled" | "onEdit"> & {
-    /** Whether the Host reports a configured credential for this reference. */
+    // Whether the Host reports a configured credential for this reference.
     configured: boolean;
-    /** Copy describing the configured state. */
+    // Copy describing the configured state.
     stateLabel: string;
   },
 ) {

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

@@ -1,165 +1,123 @@
-// 搬自 vendor/deepseek-harness/packages/client/ui-primitives/src/settings-form/form-model.ts
-// （上游 `@deepseek-ai/dsh-client-ui-primitives`，见本包 .agents/adrs 里的搬迁记录）；逻辑未改，
-// 只有 catch 的未用参数按 lint 口径写成可选绑定。改这里之前先看上游是否也改了同一处。
-
-/**
- * The staged form model behind a plugin's settings page.
- *
- * A card stages what the user types and writes it only when they save. Each
- * settings write is a durable, revision-fenced document mutation, so a control
- * that committed as it settled turned one edit into a write the user never
- * asked for and could not preview; staged text makes what is on screen exactly
- * what a save would store.
- *
- * A field shows its effective value — the user layer over the composition
- * layer over the schema default — and whether the user layer carries it. That
- * presence, not a value comparison, is what marks a field overridden: an
- * override equal to the composition default is still an override.
- */
+// 与 vendor/deepseek-harness/packages/client/ui-primitives/src/settings-form/form-model.ts 逐行对应；
+// 改这里之前先看上游是否也改了同一处（上游只读）。
+
+// The staged form model behind a plugin's settings page: a card stages what the user types and writes it only on
+// save, and a field is marked overridden by its user-layer presence rather than by a value comparison.
 
 import { createSnapshotStore, type SnapshotStore } from "@deepseek-ai/dsh-client-store";
 
-/** What the model reads of one Host entry's form. */
+// What the model reads of one Host entry's form.
 export interface SettingsFormScopeSnapshot<T> {
-  /** `ready` while the Host serves the entry to this client; the form renders nothing otherwise. */
+  // `ready` while the Host serves the entry to this client; the form renders nothing otherwise.
   status: "loading" | "ready" | "unavailable";
-  /** Last accepted schema-resolved section; undefined before the first acceptance. */
+  // Last accepted schema-resolved section; undefined before the first acceptance.
   value: T | undefined;
-  /** Composition layer the value resolves over: what a field reverts to once cleared. */
+  // Composition layer the value resolves over: what a field reverts to once cleared.
   base: unknown;
-  /** Raw user layer as stored; a field's PRESENCE here is what marks it overridden. */
+  // Raw user layer as stored; a field's PRESENCE here is what marks it overridden.
   user: unknown;
-  /** Whether the Host document accepts writes. */
+  // Whether the Host document accepts writes.
   writable: boolean;
-  /** Revision the snapshot was read at; a save fences its mutation with the revision its drafts started from. */
+  // Revision the snapshot was read at; a save fences its mutation with the revision its drafts started from.
   revision: number | undefined;
 }
 
-/** One path edit a save sends, as the shared configuration form's `mutate` accepts it. */
+// One path edit a save sends, as the shared configuration form's `mutate` accepts it.
 export type SettingsFormPathOp =
   | { op: "set"; path: readonly string[]; value: unknown }
   | { op: "unset"; path: readonly string[] };
 
-/** The entry form the model stages over: the reads and the atomic write of the form `ui-settings` shares per Host entry. */
+// The entry form the model stages over: the reads and the atomic write of the form `ui-settings` shares per Host entry.
 export interface SettingsFormScope<T> {
-  /** @returns the current sync snapshot. */
   getSnapshot(): SettingsFormScopeSnapshot<T>;
-  /**
-   * Observe snapshot replacements.
-   * @param listener - invoked after each snapshot change.
-   * @returns the disposer removing this listener.
-   */
+  // Observe snapshot replacements.
   subscribe(listener: () => void): () => void;
-  /**
-   * Apply ordered field edits in one revision-fenced write.
-   * @param ops - the edits, in staging order.
-   * @param expectedRevision - the revision the drafts were staged against, when known.
-   * @returns true for Host acceptance, false for refusal, after any recovery read.
-   */
+  // Apply ordered field edits in one revision-fenced write; resolves after any recovery read.
   mutate(ops: readonly SettingsFormPathOp[], expectedRevision?: number): Promise<boolean>;
 }
 
-/** The write one field's staged text performs when the card is saved. */
+// The write one field's staged text performs when the card is saved.
 export type SettingsFieldWrite = { kind: "set"; value: unknown } | { kind: "clear" };
 
-/** How one section field converts between its stored value and its draft text. */
+// How one section field converts between its stored value and its draft text.
 export interface SettingsFieldSpec {
-  /** Field name inside the namespace section. */
+  // Field name inside the namespace section.
   field: string;
-  /** Render a stored value as draft text; the empty string when the section carries none. */
+  // Render a stored value as draft text; the empty string when the section carries none.
   format: (value: unknown) => string;
-  /**
-   * The write this draft text stages, or undefined when the text is not a
-   * value this field accepts — which blocks the save rather than discarding it.
-   */
+  // The write this draft text stages, or undefined when the text is not a value this field accepts (blocks the save).
   parse: (text: string) => SettingsFieldWrite | undefined;
 }
 
-/**
- * A control whose value is written outside the settings section. A credential
- * literal never rides a response, so its draft has nothing to seed from: it is
- * blank until typed, and a blank draft writes nothing.
- */
+// A control whose value is written outside the settings section: a credential literal never rides a response, so its
+// draft is blank until typed and a blank draft writes nothing.
 export interface SettingsSecretSpec {
-  /** Field name addressing this control inside the card's form. */
+  // Field name addressing this control inside the card's form.
   field: string;
-  /** Write the staged text; resolves to whether the Host accepted it. */
+  // Write the staged text; resolves to whether the Host accepted it.
   write: (text: string) => Promise<boolean>;
 }
 
-/** One field as a card's control renders it. */
+// One field as a card's control renders it.
 export interface SettingsFieldState {
-  /** Draft text the control renders. */
+  // Draft text the control renders.
   text: string;
-  /**
-   * Whether saving would leave a user-layer entry for this field. A staged
-   * edit answers for itself, so the badge previews the save rather than
-   * reporting a state the pending edit already contradicts.
-   */
+  // Whether saving would leave a user-layer entry for this field; a staged edit answers for itself.
   overridden: boolean;
-  /** Whether the draft is not a value this field accepts, which blocks saving. */
+  // Whether the draft is not a value this field accepts, which blocks saving.
   invalid: boolean;
 }
 
-/** Form state every plugin card shares. */
+// Form state every plugin card shares.
 export interface SettingsFormShell {
-  /** False while the namespace is not served to this client; the card renders nothing. */
+  // False while the namespace is not served to this client; the card renders nothing.
   available: boolean;
-  /** Whether the Host document accepts writes. */
+  // Whether the Host document accepts writes.
   writable: boolean;
-  /** Whether the form holds edits that a save would write. */
+  // Whether the form holds edits that a save would write.
   dirty: boolean;
-  /** Whether any staged draft is invalid, which blocks the save. */
+  // Whether any staged draft is invalid, which blocks the save.
   invalid: boolean;
-  /** Whether a save is crossing the wire. */
+  // Whether a save is crossing the wire.
   saving: boolean;
-  /** Whether the last save did not land as staged; cleared by the next edit or save. */
+  // Whether the last save did not land as staged; cleared by the next edit or save.
   failed: boolean;
 }
 
-/** The write actions every plugin card's slot entry injects. */
+// The write actions every plugin card's slot entry injects.
 export interface SettingsFormActions {
-  /** Stage draft text for one field. */
+  // Stage draft text for one field.
   edit: (field: string, text: string) => void;
-  /** Stage a clear, so saving lets the field re-inherit the composition layer. */
+  // Stage a clear, so saving lets the field re-inherit the composition layer.
   resetField: (field: string) => void;
-  /** Write every staged edit, then re-seed from what the Host accepted. */
+  // Write every staged edit, then re-seed from what the Host accepted.
   save: () => void;
-  /** Drop every staged edit. */
+  // Drop every staged edit.
   discard: () => void;
 }
 
-/** One field's staged edit. */
+// One field's staged edit.
 interface StagedEdit {
-  /** Draft text the control renders. */
+  // Draft text the control renders.
   text: string;
-  /** True when this edit clears the field whatever text it shows. */
+  // True when this edit clears the field whatever text it shows.
   clear: boolean;
 }
 
-/** One staged edit resolved into the write a save performs. */
+// One staged edit resolved into the write a save performs.
 interface PlannedWrite {
-  /** Field this entry writes. */
+  // Field this entry writes.
   field: string;
-  /**
-   * Perform the write and report whether the Host holds the staged value
-   * afterwards; undefined when the draft is not a value the field accepts.
-   */
+  // Perform the write and report whether the Host holds the staged value afterwards.
   run?: () => Promise<boolean>;
   op?: SettingsFormPathOp;
 }
 
-/**
- * A whole-number field. An empty draft clears the field; any other draft that
- * is not a finite number blocks the save.
- * @param field - field name inside the namespace section.
- * @returns the field's conversion spec.
- */
+// A whole-number field: an empty draft clears the field, any other draft that is not a finite number blocks the save.
 export function settingsNumberField(field: string): SettingsFieldSpec {
   return {
     field,
-    // A section that carries no number for this field renders empty rather
-    // than as a value nobody chose.
+    // A section that carries no number for this field renders empty rather than as a value nobody chose.
     format: (value) => (typeof value === "number" ? String(value) : ""),
     parse: (text) => {
       const trimmed = text.trim();
@@ -170,12 +128,7 @@ export function settingsNumberField(field: string): SettingsFieldSpec {
   };
 }
 
-/**
- * A free-text field. An empty draft clears the field, so emptying the control
- * and saving is the same gesture as resetting it.
- * @param field - field name inside the namespace section.
- * @returns the field's conversion spec.
- */
+// A free-text field: an empty draft clears the field, so emptying the control and saving is the same as resetting it.
 export function settingsTextField(field: string): SettingsFieldSpec {
   return {
     field,
@@ -187,13 +140,8 @@ export function settingsTextField(field: string): SettingsFieldSpec {
   };
 }
 
-/**
- * Stages one card's edits over one settings namespace and writes them on save.
- *
- * The form publishes through a snapshot store because slot components read
- * through a snapshot selector, while both the scope and the local drafts
- * change underneath; every projection is rebuilt from the two together.
- */
+// Stages one card's edits over one settings namespace and writes them on save. The form publishes through a snapshot
+// store because slot components read through a snapshot selector while both the scope and the drafts change underneath.
 export class SettingsFormModel<T> {
   private readonly specs: Map<string, SettingsFieldSpec>;
   private readonly secretSpecs: Map<string, SettingsSecretSpec>;
@@ -204,11 +152,6 @@ export class SettingsFormModel<T> {
   private saving = false;
   private failed = false;
 
-  /**
-   * @param scope - the shared configuration form for this card's namespace.
-   * @param specs - the section fields this card edits.
-   * @param secrets - the card's write-only controls, written outside the section.
-   */
   constructor(
     private readonly scope: SettingsFormScope<T>,
     specs: SettingsFieldSpec[],
@@ -221,11 +164,7 @@ export class SettingsFormModel<T> {
     });
   }
 
-  /**
-   * Publish a projection of this form, rebuilt whenever the scope or a draft changes.
-   * @param project - build the card's state from the form's current reads.
-   * @returns the store the card's component reads through its bound selector.
-   */
+  // Publish a projection of this form, rebuilt whenever the scope or a draft changes.
   bind<S>(project: () => S): SnapshotStore<S> {
     const store = createSnapshotStore(project());
     this.listeners.add(() => {
@@ -234,10 +173,7 @@ export class SettingsFormModel<T> {
     return store;
   }
 
-  /**
-   * Read the card-level state: what the Host serves, and what a save would do.
-   * @returns the form state every card shares.
-   */
+  // Read the card-level state: what the Host serves, and what a save would do.
   shell(): SettingsFormShell {
     const snapshot = this.scope.getSnapshot();
     const plan = this.plan();
@@ -251,11 +187,7 @@ export class SettingsFormModel<T> {
     };
   }
 
-  /**
-   * Read one control's state.
-   * @param field - field name of a section field or of a write-only control.
-   * @returns the draft text, whether a save would leave an override, and whether it is invalid.
-   */
+  // Read one control's state: draft text, whether a save would leave an override, and whether it is invalid.
   field(field: string): SettingsFieldState {
     const staged = this.staged.get(field);
     if (this.secretSpecs.has(field)) {
@@ -277,10 +209,7 @@ export class SettingsFormModel<T> {
     };
   }
 
-  /**
-   * Build the edit, reset, save, and discard actions bound to this form.
-   * @returns the actions a card's slot entry injects.
-   */
+  // Build the edit, reset, save, and discard actions bound to this form.
   actions(): SettingsFormActions {
     return {
       edit: (field, text) => {
@@ -302,15 +231,8 @@ export class SettingsFormModel<T> {
     };
   }
 
-  /**
-   * Write every staged edit, then re-seed from what the Host accepted.
-   *
-   * The Host is the only authority on whether a value was accepted — its
-   * validators own the constraints no schema can express — so the outcome is
-   * read back from the section rather than predicted here. A save that did not
-   * land keeps its drafts, so the user can correct them instead of retyping.
-   * @returns settlement after every write and the read-back.
-   */
+  // Write every staged edit, then re-seed from what the Host accepted: the outcome is read back rather than predicted
+  // (the Host is the only authority), and a save that did not land keeps its drafts so the user can correct them.
   async save(): Promise<void> {
     const plan = this.plan();
     if (
@@ -344,18 +266,14 @@ export class SettingsFormModel<T> {
     }
   }
 
-  /** Release the form's accepted-value subscription. */
+  // Release the form's accepted-value subscription.
   dispose(): void {
     this.unsubscribe();
     this.listeners.clear();
   }
 
-  /**
-   * Every staged edit a save would write. An entry whose draft is not a value
-   * its field accepts carries no write: the form is still dirty, and the save
-   * refuses rather than dropping the edit.
-   * @returns the planned writes, in the order the fields were staged.
-   */
+  // Every staged edit a save would write; an entry whose draft its field rejects carries no write (the form stays
+  // dirty, and the save refuses rather than dropping the edit).
   private plan(): PlannedWrite[] {
     const plan: PlannedWrite[] = [];
     for (const [field, staged] of this.staged) {
@@ -388,8 +306,8 @@ export class SettingsFormModel<T> {
 
   private spec(field: string): SettingsFieldSpec {
     const spec = this.specs.get(field);
-    // Every call site names a field this card declared; a missing one is a
-    // wiring mistake that must not degrade into a silently inert control.
+    // Every call site names a field this card declared; a missing one is a wiring mistake that must not become a
+    // silently inert control.
     if (spec === undefined) throw new Error(`plugin card has no field ${field}`);
     return spec;
   }

package/src/client/styling/styled.tsx

@@ -24,10 +24,8 @@ export type StyledComponent<T extends ElementType> = ForwardRefExoticComponent<
   StyledProps<T> & RefAttributes<StyledRef<T>>
 > & { readonly [sxSymbol]: CSSProps };
 
-/**
- * `styled('div')({ padding: '4px' }, { '&:hover': { … } })` → 带 `data-css-*` 的组件。
- * 多个样式对象按顺序深合并（后者覆盖前者），便于把变体叠在基样式上。
- */
+// `styled('div')({ padding: '4px' }, { '&:hover': { … } })` → 带 `data-css-*` 的组件。
+// 多个样式对象按顺序深合并（后者覆盖前者），便于把变体叠在基样式上。
 export function styled<T extends ElementType>(
   Component: T,
   defaultProps: Partial<ComponentProps<T>> = {},
@@ -50,7 +48,7 @@ export function styled<T extends ElementType>(
   };
 }
 
-/** 取回 styled 组件携带的样式对象（需要在其之上继续组合时用）。 */
+// 取回 styled 组件携带的样式对象（需要在其之上继续组合时用）。
 export function styleOf(component: StyledComponent<ElementType>): CSSProps {
   return component[sxSymbol];
 }

package/src/client/theme.generated.ts

@@ -1,10 +1,9 @@
-/**
- * 官方主题的 `--dsw-*` token 全集（400 个），由 packages/client/ui-primitives/scripts/gen-design-tokens.mts 生成，勿手改。
- *
- * 叶子是该变量的**默认值**（官方 light 主题里首次出现的定义）：既是类型推导的来源，也可作 fallback。
- * `"$"` 键出现在「自身也是 token 的分支」上（命名体系里有 40 个短名同时是长名前缀的 token）。
- * 消费时只需树形状——`Token.vars()` 生成 `var(--dsw-…)`，不重新定义变量。
- * 漂移、往返与默认值完整性由 src/__tests__/design-tokens.spec.ts 守卫。 */
+// 官方主题的 `--dsw-*` token 全集（400 个），由 packages/client/ui-primitives/scripts/gen-design-tokens.mts 生成，勿手改。
+//
+// 叶子是该变量的**默认值**（官方 light 主题里首次出现的定义）：既是类型推导的来源，也可作 fallback。
+// `"$"` 键出现在「自身也是 token 的分支」上（命名体系里有 40 个短名同时是长名前缀的 token）。
+// 消费时只需树形状——`Token.vars()` 生成 `var(--dsw-…)`，不重新定义变量。
+// 漂移、往返与默认值完整性由 src/__tests__/design-tokens.spec.ts 守卫。
 export const designTokens = {
   alias: {
     bg: {

package/src/reference-markdown.tsx

@@ -106,7 +106,7 @@ function rangeOf(reference: Reference): string {
 // 本地引用的原文切片 → inline code；外部地址原样留下。引用不会嵌套（解析器保证），
 // 这里仍按 offset 顺序跳过被前一个切片覆盖的引用。
 // 边界：引用紧贴相邻 inline code 的反引号（`` `x`file:y ``）时两个 code span 会并成一个，
-// 这种写法退化成普通 code——与上一版包反引号的行为一致。
+// 这种写法退化成普通 code。
 function tokenizeReferences(text: string): {
   readonly source: string;
   readonly tokens: Map<string, Reference>;

package/src/reference.ts

@@ -522,7 +522,7 @@ function parseBareReference(raw: string): Reference | undefined {
   };
 }
 
-/** 引号 mention 的起手字符：`@"path with spaces"`。 */
+// 引号 mention 的起手字符：`@"path with spaces"`。
 const QUOTED_PATH = '"';
 
 function parseQuotedReference(body: string): Reference | undefined {