@morlay/dsh-client-ui-primitives 0.0.2-alpha.6 → 0.0.2-alpha.8

package/dist/client.d.cts

@@ -1,7 +1,8 @@
 import { a as formatReferenceMention, c as parseReferenceToken, i as formatReference, n as ReferenceSpan, o as isLocalReference, r as findReferences, s as parseReference, t as Reference } from "./reference-BX54bj6_.cjs";
 import { Context } from "@deepseek-ai/cordis";
-import { ComponentProps, ComponentPropsWithRef, ElementType, ForwardRefExoticComponent, Ref, RefAttributes } from "react";
+import { ComponentProps, ComponentPropsWithRef, ElementType, ForwardRefExoticComponent, ReactNode, Ref, RefAttributes } from "react";
 import { MarkdownFileMentions, MarkdownLabels, MarkdownLabels as MarkdownLabels$1, MarkdownPathImages } from "@deepseek-ai/dsh-client-ui-primitives";
+import { SnapshotStore } from "@deepseek-ai/dsh-client-store";
 //#region ../../../node_modules/.pnpm/csstype@3.2.3/node_modules/csstype/index.d.ts
 interface StandardLonghandProperties<TLength = (string & {}) | 0, TTime = string & {}> {
   /**
@@ -9414,7 +9415,7 @@ declare function styleOf(component: StyledComponent<ElementType>): CSSProps;
 //#endregion
 //#region src/client/theme.generated.d.ts
 /**
- * 官方主题的 `--dsw-*` token 全集（361 个），由 packages/client/ui-primitives/scripts/gen-design-tokens.mts 生成，勿手改。
+ * 官方主题的 `--dsw-*` token 全集（373 个），由 packages/client/ui-primitives/scripts/gen-design-tokens.mts 生成，勿手改。
  *
  * 叶子是该变量的**默认值**（官方 light 主题里首次出现的定义）：既是类型推导的来源，也可作 fallback。
  * `"$"` 键出现在「自身也是 token 的分支」上（命名体系里有 40 个短名同时是长名前缀的 token）。
@@ -9512,6 +9513,26 @@ declare const designTokens: {
         };
       };
     };
+    readonly code: {
+      readonly diff: {
+        readonly added: "var(--dsw-static-green-500-a08)";
+        readonly deleted: "var(--dsw-static-red-600-a08)";
+      };
+    };
+    readonly file: {
+      readonly diff: {
+        readonly added: {
+          readonly bg: "rgb(230, 244, 231)";
+          readonly gutter: "rgb(237, 247, 237)";
+          readonly marker: "rgb(1, 162, 65)";
+        };
+        readonly deleted: {
+          readonly bg: "rgb(252, 230, 226)";
+          readonly gutter: "rgb(253, 236, 233)";
+          readonly marker: "rgb(186, 39, 35)";
+        };
+      };
+    };
     readonly interactive: {
       readonly bg: {
         readonly active: "rgba(38, 49, 72, 0.1)";
@@ -10093,7 +10114,11 @@ declare const designTokens: {
     readonly green: {
       readonly "100": "rgb(230, 250, 237)";
       readonly "400": "rgb(78, 209, 126)";
-      readonly "500": "rgb(34, 197, 94)";
+      readonly "500": {
+        readonly $: "rgb(34, 197, 94)";
+        readonly a08: "rgb(34 197 94 / 8%)";
+        readonly a12: "rgb(34 197 94 / 12%)";
+      };
       readonly "900": "rgb(35, 60, 44)";
     };
     readonly neutral: {
@@ -10138,9 +10163,15 @@ declare const designTokens: {
     readonly red: {
       readonly "50": "rgb(254, 242, 242)";
       readonly "100": "rgb(254, 226, 226)";
-      readonly "400": "rgb(242, 90, 90)";
+      readonly "400": {
+        readonly $: "rgb(242, 90, 90)";
+        readonly a12: "rgb(242 90 90 / 12%)";
+      };
       readonly "500": "rgb(239, 68, 68)";
-      readonly "600": "rgb(236, 19, 19)";
+      readonly "600": {
+        readonly $: "rgb(236, 19, 19)";
+        readonly a08: "rgb(236 19 19 / 8%)";
+      };
       readonly "900": "rgb(87, 12, 12)";
     };
   };
@@ -10239,6 +10270,26 @@ declare const dsw: TokenVars<{
         };
       };
     };
+    readonly code: {
+      readonly diff: {
+        readonly added: "var(--dsw-static-green-500-a08)";
+        readonly deleted: "var(--dsw-static-red-600-a08)";
+      };
+    };
+    readonly file: {
+      readonly diff: {
+        readonly added: {
+          readonly bg: "rgb(230, 244, 231)";
+          readonly gutter: "rgb(237, 247, 237)";
+          readonly marker: "rgb(1, 162, 65)";
+        };
+        readonly deleted: {
+          readonly bg: "rgb(252, 230, 226)";
+          readonly gutter: "rgb(253, 236, 233)";
+          readonly marker: "rgb(186, 39, 35)";
+        };
+      };
+    };
     readonly interactive: {
       readonly bg: {
         readonly active: "rgba(38, 49, 72, 0.1)";
@@ -10820,7 +10871,11 @@ declare const dsw: TokenVars<{
     readonly green: {
       readonly "100": "rgb(230, 250, 237)";
       readonly "400": "rgb(78, 209, 126)";
-      readonly "500": "rgb(34, 197, 94)";
+      readonly "500": {
+        readonly $: "rgb(34, 197, 94)";
+        readonly a08: "rgb(34 197 94 / 8%)";
+        readonly a12: "rgb(34 197 94 / 12%)";
+      };
       readonly "900": "rgb(35, 60, 44)";
     };
     readonly neutral: {
@@ -10865,9 +10920,15 @@ declare const dsw: TokenVars<{
     readonly red: {
       readonly "50": "rgb(254, 242, 242)";
       readonly "100": "rgb(254, 226, 226)";
-      readonly "400": "rgb(242, 90, 90)";
+      readonly "400": {
+        readonly $: "rgb(242, 90, 90)";
+        readonly a12: "rgb(242 90 90 / 12%)";
+      };
       readonly "500": "rgb(239, 68, 68)";
-      readonly "600": "rgb(236, 19, 19)";
+      readonly "600": {
+        readonly $: "rgb(236, 19, 19)";
+        readonly a08: "rgb(236 19 19 / 8%)";
+      };
       readonly "900": "rgb(87, 12, 12)";
     };
   };
@@ -10877,6 +10938,302 @@ declare const dsw: TokenVars<{
 type MarkdownCopySeat = (key: "copy" | "copied" | "markdown.footnotes") => string;
 declare function markdownLabels(t: MarkdownCopySeat): MarkdownLabels;
 //#endregion
+//#region src/client/settings-form/form-model.d.ts
+/** What the model reads of one Host entry's form. */
+interface SettingsFormScopeSnapshot<T> {
+  /** `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. */
+  value: T | undefined;
+  /** 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. */
+  user: unknown;
+  /** 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: number | undefined;
+}
+/** One path edit a save sends, as the shared configuration form's `mutate` accepts it. */
+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. */
+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.
+   */
+  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.
+   */
+  mutate(ops: readonly SettingsFormPathOp[], expectedRevision?: number): Promise<boolean>;
+}
+/** The write one field's staged text performs when the card is saved. */
+type SettingsFieldWrite = {
+  kind: "set";
+  value: unknown;
+} | {
+  kind: "clear";
+};
+/** How one section field converts between its stored value and its draft text. */
+interface SettingsFieldSpec {
+  /** Field name inside the namespace section. */
+  field: string;
+  /** 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.
+   */
+  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.
+ */
+interface SettingsSecretSpec {
+  /** Field name addressing this control inside the card's form. */
+  field: string;
+  /** 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. */
+interface SettingsFieldState {
+  /** 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.
+   */
+  overridden: boolean;
+  /** Whether the draft is not a value this field accepts, which blocks saving. */
+  invalid: boolean;
+}
+/** Form state every plugin card shares. */
+interface SettingsFormShell {
+  /** False while the namespace is not served to this client; the card renders nothing. */
+  available: boolean;
+  /** Whether the Host document accepts writes. */
+  writable: boolean;
+  /** Whether the form holds edits that a save would write. */
+  dirty: boolean;
+  /** Whether any staged draft is invalid, which blocks the save. */
+  invalid: boolean;
+  /** 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. */
+  failed: boolean;
+}
+/** The write actions every plugin card's slot entry injects. */
+interface SettingsFormActions {
+  /** 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. */
+  resetField: (field: string) => void;
+  /** Write every staged edit, then re-seed from what the Host accepted. */
+  save: () => void;
+  /** Drop every staged edit. */
+  discard: () => void;
+}
+/**
+ * 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.
+ */
+declare 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.
+ */
+declare 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.
+ */
+declare class SettingsFormModel<T> {
+  private readonly scope;
+  private readonly specs;
+  private readonly secretSpecs;
+  private readonly staged;
+  private readonly listeners;
+  private baseline;
+  private readonly unsubscribe;
+  private saving;
+  private failed;
+  /**
+   * @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(scope: SettingsFormScope<T>, specs: SettingsFieldSpec[], secrets?: SettingsSecretSpec[]);
+  /**
+   * 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.
+   */
+  bind<S>(project: () => S): SnapshotStore<S>;
+  /**
+   * Read the card-level state: what the Host serves, and what a save would do.
+   * @returns the form state every card shares.
+   */
+  shell(): SettingsFormShell;
+  /**
+   * 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.
+   */
+  field(field: string): SettingsFieldState;
+  /**
+   * Build the edit, reset, save, and discard actions bound to this form.
+   * @returns the actions a card's slot entry injects.
+   */
+  actions(): SettingsFormActions;
+  /**
+   * 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.
+   */
+  save(): Promise<void>;
+  /** Release the form's accepted-value subscription. */
+  dispose(): void;
+  /**
+   * 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.
+   */
+  private plan;
+  private stage;
+  private spec;
+  private snapshotOf;
+  private sectionValue;
+  private baseValue;
+  private userLayer;
+  private stored;
+  private publish;
+}
+//#endregion
+//#region src/client/settings-form/fields.d.ts
+/** What every settings field control needs regardless of its value type. */
+interface SettingsFieldProps {
+  /** Stable id associating the label with its control. */
+  id: string;
+  /** Visible label. */
+  label: string;
+  /** One-line explanation rendered under the control. */
+  hint: string;
+  /** Draft text this control renders. */
+  text: string;
+  /** 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. */
+  invalid: boolean;
+  /** Copy for the overridden badge. */
+  overriddenLabel: string;
+  /** Copy for the reset control. */
+  resetLabel: string;
+  /** Copy shown in place of the hint while the draft is invalid. */
+  invalidLabel: string;
+  /** Disables every control (read-only document, or an unavailable namespace). */
+  disabled: boolean;
+  /** Stage draft text. */
+  onEdit: (text: string) => void;
+  /** 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.
+ */
+declare function SettingsValueField(props: Omit<SettingsFieldProps, "hint"> & {
+  /** Optional explanation shown below the input. */
+  hint?: string;
+  /** Rules disclosed by the information button beside the label. */
+  help?: {
+    label: string;
+    content: ReactNode;
+  };
+  /** Hints a numeric keypad without narrowing what the control accepts. */
+  numeric?: boolean;
+  /** Placeholder shown while the draft is empty. */
+  placeholder?: string;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * 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.
+ * @param props - the field's copy, its staged text, and the configured state.
+ * @returns the labelled control.
+ */
+declare function SettingsSecretField(props: Pick<SettingsFieldProps, "id" | "label" | "hint" | "text" | "disabled" | "onEdit"> & {
+  /** Whether the Host reports a configured credential for this reference. */
+  configured: boolean;
+  /** Copy describing the configured state. */
+  stateLabel: string;
+}): import("react/jsx-runtime").JSX.Element;
+//#endregion
+//#region src/client/settings-form/SettingsForm.d.ts
+/** The copy the form frame renders, from the owning plugin's dictionary. */
+interface SettingsFormLabels {
+  /** Shown in place of the controls while the namespace is not served. */
+  unavailable: string;
+  /** Shown over the controls while the document is read-only. */
+  readOnly: string;
+  /** Shown beside the save after a save the Host did not accept. */
+  saveFailed: string;
+  /** The save control. */
+  save: string;
+  /** The save control while a save is crossing the wire. */
+  saving: string;
+}
+/** Form chrome shared by every settings page. */
+interface SettingsFormProps {
+  /** The frame's copy. */
+  labels: SettingsFormLabels;
+  /** The form state: availability, writability, and what a save would do. */
+  state: SettingsFormShell;
+  /** Write every staged edit. */
+  onSave: () => void;
+  /** Drop every staged edit; the form calls it when it leaves the page. */
+  onDiscard: () => void;
+  /** The plugin's controls. */
+  children: ReactNode;
+}
+/**
+ * Render one plugin's settings form.
+ * @param props - the form's copy and state, its controls, and the save and discard actions.
+ * @returns the form, or the unavailable line while the namespace is not served.
+ */
+declare function SettingsForm(props: SettingsFormProps): import("react/jsx-runtime").JSX.Element;
+//#endregion
 //#region src/reference-markdown.d.ts
 interface ReferenceActions {
   readonly openFile: (path: string) => void;
@@ -10896,4 +11253,4 @@ declare const ReferenceMarkdown: import("react").MemoExoticComponent<({ text, la
 declare const inject: readonly string[];
 declare function apply(_ctx: Context): void;
 //#endregion
-export { type CSSObject, type CSSProps, type CSSSelector, type CSSValue, type CSSVar, type CSSVarRef, MarkdownCopySeat, type Reference, type ReferenceActions, ReferenceMarkdown, type ReferenceMarkdownProps, type ReferenceSpan, type StyledComponent, Styling, Token, type TokenVars, type Tokens, apply, designTokens, dsw, findReferences, formatReference, formatReferenceMention, inject, isLocalReference, markdownLabels, parseReference, parseReferenceToken, referenceMentions, styleOf, styled, styling };
+export { type CSSObject, type CSSProps, type CSSSelector, type CSSValue, type CSSVar, type CSSVarRef, MarkdownCopySeat, type Reference, type ReferenceActions, ReferenceMarkdown, type ReferenceMarkdownProps, type ReferenceSpan, type SettingsFieldProps, type SettingsFieldSpec, type SettingsFieldState, type SettingsFieldWrite, SettingsForm, type SettingsFormActions, type SettingsFormLabels, SettingsFormModel, type SettingsFormPathOp, type SettingsFormProps, type SettingsFormScope, type SettingsFormScopeSnapshot, type SettingsFormShell, SettingsSecretField, type SettingsSecretSpec, SettingsValueField, type StyledComponent, Styling, Token, type TokenVars, type Tokens, apply, designTokens, dsw, findReferences, formatReference, formatReferenceMention, inject, isLocalReference, markdownLabels, parseReference, parseReferenceToken, referenceMentions, settingsNumberField, settingsTextField, styleOf, styled, styling };