@linxin666/dsh-usage 0.4.10 → 0.4.12

package/src/client/settings-form.ts

@@ -0,0 +1,510 @@
+// Generated by scripts/sync-shared.mjs from shared/client/settings/settings-form.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Form model behind the plugin settings card. Every control applies itself:
+ * a pick (a segment, a select option, a reset) writes the moment it is made,
+ * and typed text writes once typing pauses or the reader leaves the field.
+ * Between the edit and the write the edit is held here as a draft, so what is
+ * on screen is exactly what the write will store; a write the Host refuses
+ * puts a pick back to the stored value and keeps typed text for correcting.
+ * Family-shared slice inlined into each plugin's client bundle.
+ */
+
+import type { ConfigForm, ConfigFormSnapshot } from '@deepseek-ai/dsh-client-ui-settings/client'
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-store'
+
+/** The write one field's draft text performs when it is applied. */
+export type FieldWrite =
+  | { kind: 'set'; value: unknown }
+  | { kind: 'clear' }
+
+/** How one field converts between its stored value and its draft text. */
+export interface FieldSpec {
+  /** Field name inside the namespace section. */
+  field: string
+  /**
+   * How the reader enters a value, which decides when it is written: a `pick`
+   * is a whole value at once and applies immediately; `type` is text arriving
+   * a keystroke at a time and applies once typing pauses or the field is left.
+   */
+  entry: 'pick' | 'type'
+  /**
+   * Whether the Host treats this field as a secret and redacts its value from
+   * the read-back (role('secret') in the section schema). Redacted secrets are
+   * never compared against the draft on save: the Host strips them from every
+   * wire view layer, so the settled snapshot carries nothing to read back. A
+   * staged secret set is judged by the mutation settling; the rest of its
+   * batch, when one exists, is still judged by read-back, and the atomic
+   * mutation lands every write or none.
+   */
+  secret?: boolean
+  /** Render a stored value as draft text; the empty string when the section carries none. */
+  format: (value: unknown) => string
+  /**
+   * The write this draft text performs, or undefined when the text is not a
+   * value this field accepts — which holds the draft unwritten rather than
+   * discarding it.
+   */
+  parse: (text: string) => FieldWrite | undefined
+}
+
+/** One field as the card renders it. */
+export interface FieldState {
+  /** Draft text the control renders. */
+  text: string
+  /** Whether the field leaves (or will leave) a user-layer entry. */
+  overridden: boolean
+  /** Whether the draft is not a value this field accepts, which holds it unwritten. */
+  invalid: boolean
+}
+
+/** Form state every plugin settings card shares. */
+export interface CardShell {
+  /** False while the namespace is still loading; the card renders nothing. */
+  available: boolean
+  /**
+   * Whether the namespace is actually served to this client. False when the
+   * Host deployment does not expose it (e.g. the owning plugin's settings
+   * domain is not mounted): the card renders an explanation
+   * instead of its form, so a missing namespace never looks like a missing
+   * plugin.
+   */
+  exposed: boolean
+  /** Whether the Host document accepts writes. */
+  writable: boolean
+  /** Whether the form holds drafts not yet written (typed text waiting for its pause). */
+  dirty: boolean
+  /** Whether any draft is invalid, which holds it unwritten. */
+  invalid: boolean
+  /** Whether a write is crossing the wire. */
+  saving: boolean
+  /** Whether the last write did not land; cleared by the next edit or write. */
+  failed: boolean
+  /**
+   * The rejection code/message the Host returned for the last failed save,
+   * surfaced next to the generic failure text. Undefined while no save has
+   * failed (or the failure carried no server reason).
+   */
+  failedReason?: string
+}
+
+/** The write actions the card's slot entry injects. */
+export interface CardActions {
+  /** Take draft text for one field; a pick writes at once, typed text after a pause. */
+  edit: (field: string, text: string) => void
+  /** Clear one field at once, so it re-inherits the composition layer. */
+  resetField: (field: string) => void
+  /** Write every pending draft now (a text field's Enter or blur), then re-seed from what the Host accepted. */
+  save: () => void
+  /** Drop every pending draft, putting each control back to the stored value (a text field's Escape). */
+  discard: () => void
+}
+
+/** How long typed text rests before it is written. */
+export const TYPE_PAUSE_MS = 600
+
+/** One field's staged edit. */
+interface StagedEdit {
+  /** Draft text the control renders. */
+  text: string
+  /** True when this edit clears the field whatever text it shows. */
+  clear: boolean
+}
+
+/** One staged edit resolved into the write a save performs. */
+interface PlannedWrite {
+  /** Field this entry writes. */
+  field: string
+  /** The durable write this entry performs, inside the save's one atomic mutation. */
+  op: BatchedWrite
+  /**
+   * Read the settled snapshot back and report whether the Host holds this
+   * write's effect. Undefined when the draft is not a value the field
+   * accepts: there is nothing to write, and the entry blocks the save.
+   */
+  judge: (() => boolean) | undefined
+}
+
+/** One durable write inside the save's atomic form mutation. */
+export interface BatchedWrite {
+  /** Field this entry writes. */
+  field: string
+  /** set stores a value; unset drops the leaf. */
+  op: 'set' | 'unset'
+  /** Value for op set (absent for unset). */
+  value?: unknown
+}
+
+/** Constraints a numeric field's accepted drafts must satisfy, mirroring the host schema. */
+export interface NumberConstraints {
+  /** The accepted value must be a whole number. */
+  integer?: boolean
+  /** The accepted value must be at least this. */
+  min?: number
+}
+
+/** A whole- or decimal-number field. An empty draft clears the field; any other draft that is not a finite number within the constraints stays unwritten. */
+export function numberField(field: string, constraints: NumberConstraints = {}): FieldSpec {
+  const { integer = false, min } = constraints
+  return {
+    field,
+    entry: 'type',
+    format: value => typeof value === 'number' ? String(value) : '',
+    parse: (text) => {
+      const trimmed = text.trim()
+      if (trimmed === '') return { kind: 'clear' }
+      const parsed = Number(trimmed)
+      if (!Number.isFinite(parsed)) return undefined
+      if (integer && !Number.isInteger(parsed)) return undefined
+      if (min !== undefined && parsed < min) return undefined
+      return { kind: 'set', value: parsed }
+    },
+  }
+}
+
+/**
+ * A free-text field. An empty draft clears the field. `entry` is `pick` when
+ * the text arrives whole from a picker (a preset or a reasoning level).
+ */
+export function textField(field: string, entry: FieldSpec['entry'] = 'type'): FieldSpec {
+  return {
+    field,
+    entry,
+    format: value => typeof value === 'string' ? value : '',
+    parse: (text) => {
+      const trimmed = text.trim()
+      return trimmed === '' ? { kind: 'clear' } : { kind: 'set', value: trimmed }
+    },
+  }
+}
+
+/**
+ * A free-text field the Host treats as a secret and redacts from the read-back
+ * (role('secret') in the section schema). The card still edits it like text,
+ * but a save never compares the redacted value back: the staged set is judged
+ * by the mutation settling (see {@link FieldSpec.secret}).
+ */
+export function secretField(field: string): FieldSpec {
+  return { ...textField(field), secret: true }
+}
+
+/** A boolean field, edited through true/false draft text. */
+export function booleanField(field: string): FieldSpec {
+  return {
+    field,
+    entry: 'pick',
+    format: value => typeof value === 'boolean' ? String(value) : '',
+    parse: (text) => {
+      const trimmed = text.trim()
+      if (trimmed === '') return { kind: 'clear' }
+      if (trimmed === 'true') return { kind: 'set', value: true }
+      if (trimmed === 'false') return { kind: 'set', value: false }
+      return undefined
+    },
+  }
+}
+
+/** An enumerated string field; only the listed choices are accepted. An empty draft clears the field. */
+export function choiceField(field: string, choices: readonly string[]): FieldSpec {
+  return {
+    field,
+    entry: 'pick',
+    format: value => typeof value === 'string' && choices.includes(value) ? value : '',
+    parse: (text) => {
+      if (text === '') return { kind: 'clear' }
+      return choices.includes(text) ? { kind: 'set', value: text } : undefined
+    },
+  }
+}
+
+/**
+ * Applies one card's edits to one settings namespace as the reader makes them.
+ *
+ * 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 write that did not
+ * land puts each pick back to the stored value, the way a switch that could not
+ * flip springs back, and keeps typed text so the reader can correct it instead
+ * of retyping.
+ */
+export class CardForm<T> {
+  private readonly specs: Map<string, FieldSpec>
+  private readonly staged = new Map<string, StagedEdit>()
+  private readonly listeners = new Set<() => void>()
+  /** The form subscription installed in the constructor; released by dispose(). */
+  private readonly disposeForm: () => void
+  private disposed = false
+  /** The pending write of typed text, waiting for typing to pause. */
+  private typePause: ReturnType<typeof setTimeout> | undefined
+  private saving = false
+  /** A save asked for while one was in flight; it runs once the first settles (#1754). */
+  private saveQueued = false
+  private failed = false
+  private failedReason: string | undefined
+
+  /** @param scope - the bound configuration form for this card's namespace. */
+  constructor(
+    private readonly scope: ConfigForm<T>,
+    specs: FieldSpec[],
+  ) {
+    this.specs = new Map(specs.map(spec => [spec.field, spec]))
+    this.disposeForm = scope.subscribe(() => { this.publish() })
+  }
+
+  /**
+   * Release the form subscription and every bound store listener. The card
+   * must call this on teardown; later calls are no-ops.
+   */
+  dispose(): void {
+    if (this.disposed) return
+    this.disposed = true
+    clearTimeout(this.typePause)
+    this.disposeForm()
+    this.listeners.clear()
+  }
+
+  /** Publish a projection of this form, rebuilt whenever the form or a draft changes. */
+  bind<S>(project: () => S): SnapshotStore<S> {
+    const store = createSnapshotStore(project())
+    this.listeners.add(() => { store.set(project()) })
+    return store
+  }
+
+  /** Read the card-level state: what the Host serves, and what is still waiting to be written. */
+  shell(): CardShell {
+    const snapshot = this.scope.getSnapshot()
+    const plan = this.plan()
+    return {
+      available: snapshot.status !== 'loading',
+      exposed: snapshot.status === 'ready',
+      writable: snapshot.writable,
+      dirty: plan.length > 0,
+      invalid: plan.some(item => item.judge === undefined),
+      saving: this.saving,
+      failed: this.failed,
+      ...this.failedReason === undefined ? {} : { failedReason: this.failedReason },
+    }
+  }
+
+  /** Read one field's state from the effective section and its staged draft. */
+  field(field: string): FieldState {
+    const spec = this.specOf(field)
+    const staged = this.staged.get(field)
+    if (staged === undefined) {
+      return { text: spec.format(this.sectionValue(field)), overridden: this.stored(field), invalid: false }
+    }
+    const write = staged.clear ? { kind: 'clear' as const } : spec.parse(staged.text)
+    return {
+      text: staged.text,
+      overridden: write?.kind === 'set',
+      invalid: write === undefined,
+    }
+  }
+
+  /** The actions the card's slot registration injects. */
+  actions(): CardActions {
+    return {
+      edit: (field, text) => { this.stage(field, { text, clear: false }) },
+      resetField: (field) => {
+        this.stage(field, { text: this.specOf(field).format(this.baseValue(field)), clear: true })
+      },
+      save: () => { this.applyNow() },
+      discard: () => {
+        clearTimeout(this.typePause)
+        if (this.staged.size === 0 && !this.failed) return
+        this.staged.clear()
+        this.failed = false
+        this.failedReason = undefined
+        this.publish()
+      },
+    }
+  }
+
+  /**
+   * Run one write, and re-run it once if another was asked for while this one
+   * was still in flight.
+   *
+   * A write is a Host round trip that also drives the profile reconcile, and
+   * the Host runs it inside one exclusive transaction. Answering an edit that
+   * arrives mid-flight by returning immediately dropped it with no explanation
+   * (#1754). Serializing instead means an edit made while another write is
+   * still settling is written against the settled state.
+   * @returns settlement after the mutation and the read-back.
+   */
+  async requestSave(): Promise<void> {
+    if (this.saving) {
+      this.saveQueued = true
+      return
+    }
+    await this.save()
+    if (!this.saveQueued) return
+    this.saveQueued = false
+    await this.requestSave()
+  }
+
+  /**
+   * Write every valid draft in one atomic form mutation, then re-seed from
+   * what the Host accepted. A draft the field does not accept stays on screen,
+   * unwritten, without holding the others back.
+   *
+   * The batch rides one mutate, so cross-field validate hooks (baseURL+model)
+   * judge it as a unit: the Host either applies every write or refuses the
+   * batch. The form contract answers a refusal or a skipped write with `false`
+   * (it recovers with a fresh Host view instead of throwing), so the outcome is
+   * judged twice: the answer itself, and then the settled snapshot read back
+   * one planned write at a time. One missed write fails the whole batch. A
+   * transport that rejects instead (the dsh-web bridge controller on a dead
+   * connection) reports through the same failure path with its rejection
+   * message. A batch that did not land puts its picks and clears back to the
+   * stored value and keeps its typed text, so the reader can correct it.
+   * @returns settlement after the mutation and the read-back.
+   */
+  async save(): Promise<void> {
+    const plan = this.plan()
+    const valid = plan.filter((item): item is PlannedWrite & { judge: () => boolean } => item.judge !== undefined)
+    if (valid.length === 0 || this.saving) return
+    // Snapshot the staged entries this write carries, so an edit staged while
+    // it is in flight (which replaces the same key) survives: only settle the
+    // key when the entry is still the one this write started from.
+    const pending = new Map<string, StagedEdit | undefined>()
+    for (const item of valid) pending.set(item.field, this.staged.get(item.field))
+    this.saving = true
+    this.failed = false
+    this.failedReason = undefined
+    this.publish()
+    // One atomic namespace mutation: the form contract takes ordered path
+    // operations, so the whole staged batch is validated, persisted, and
+    // recovered together — either every write lands or none does.
+    const ops: Array<{ op: 'set'; path: string[]; value: string | number | boolean } | { op: 'unset'; path: string[] }> = valid.map(item => item.op.op === 'set'
+      ? { op: 'set', path: [item.field], value: (item.op as { value: string | number | boolean }).value }
+      : { op: 'unset', path: [item.field] })
+    let failedReason: string | undefined
+    let accepted = false
+    try {
+      accepted = await this.scope.mutate(ops)
+    } catch (error) {
+      failedReason = error instanceof Error ? error.message : String(error)
+    }
+    // `false` is the contract's refusal/skip answer, and the form still
+    // resolves after a refusal (it recovers with a fresh view), so the answer
+    // alone is not enough: judge every planned write against the settled
+    // snapshot as well. The mutation is atomic, so one missed write fails the
+    // whole save and keeps the drafts.
+    const landed = accepted && failedReason === undefined && valid.every(item => item.judge())
+    for (const [field, before] of pending) {
+      if (this.staged.get(field) !== before) continue
+      if (landed || before === undefined || before.clear || this.specOf(field).entry === 'pick') this.staged.delete(field)
+    }
+    this.saving = false
+    this.failed = !landed
+    // A refused or unlanded batch carries no server reason: the card surfaces
+    // its generic failure copy; a rejecting transport (the bridge) adds its
+    // message.
+    this.failedReason = failedReason
+    this.publish()
+  }
+
+  /**
+   * Every staged edit a write would carry. An entry whose draft is not a value
+   * its field accepts carries no write: the form is still dirty, and the draft
+   * stays on screen rather than being dropped. A staged edit that matches the
+   * effective section is not a write at all.
+   * @returns the planned writes, in the order the fields were staged.
+   */
+  private plan(): PlannedWrite[] {
+    const plan: PlannedWrite[] = []
+    for (const [field, staged] of this.staged) {
+      const spec = this.specOf(field)
+      if (staged.clear) {
+        if (this.stored(field)) plan.push({ field, op: { field, op: 'unset' }, judge: () => this.landedUnset(field) })
+        continue
+      }
+      if (staged.text === spec.format(this.sectionValue(field))) continue
+      const write = spec.parse(staged.text)
+      if (write === undefined) plan.push({ field, op: { field, op: 'unset' }, judge: undefined })
+      else if (write.kind === 'clear') plan.push({ field, op: { field, op: 'unset' }, judge: () => this.landedUnset(field) })
+      else plan.push({ field, op: { field, op: 'set', value: write.value }, judge: () => this.landedSet(field, write.value) })
+    }
+    return plan
+  }
+
+  /**
+   * Read-back judgment for a planned set: the user layer must hold the
+   * intended value once the mutation has settled.
+   */
+  private landedSet(field: string, value: unknown): boolean {
+    // A redacted secret never appears in any wire view layer: the Host strips
+    // role('secret') fields and reports them through a sidecar the form
+    // snapshot does not expose, so there is nothing to compare the draft
+    // against. Settling is the only signal the form has; the rest of the
+    // batch, when one exists, still carries the atomic verdict by read-back.
+    if (this.specOf(field).secret) return true
+    return this.userLayer()?.[field] === value
+  }
+
+  /**
+   * Read-back judgment for a planned unset: the field must be gone from the
+   * user layer once the mutation has settled.
+   */
+  private landedUnset(field: string): boolean {
+    return !this.stored(field)
+  }
+
+  /**
+   * Take one edit and schedule its write: a pick or a clear is written now,
+   * typed text once typing has rested for TYPE_PAUSE_MS.
+   */
+  private stage(field: string, edit: StagedEdit): void {
+    this.staged.set(field, edit)
+    this.failed = false
+    this.failedReason = undefined
+    this.publish()
+    if (edit.clear || this.specOf(field).entry === 'pick') {
+      this.applyNow()
+      return
+    }
+    clearTimeout(this.typePause)
+    this.typePause = setTimeout(() => { this.applyNow() }, TYPE_PAUSE_MS)
+  }
+
+  /** Write every pending draft now, taking the place of a waiting pause. */
+  private applyNow(): void {
+    clearTimeout(this.typePause)
+    this.typePause = undefined
+    if (this.disposed) return
+    void this.requestSave()
+  }
+
+  private specOf(field: string): FieldSpec {
+    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.
+    if (spec === undefined) throw new Error(`settings card has no field ${field}`)
+    return spec
+  }
+
+  private snapshotOf(): ConfigFormSnapshot<T> {
+    return this.scope.getSnapshot()
+  }
+
+  private sectionValue(field: string): unknown {
+    return (this.snapshotOf().value as Record<string, unknown> | undefined)?.[field]
+  }
+
+  private baseValue(field: string): unknown {
+    return (this.snapshotOf().base as Record<string, unknown> | undefined)?.[field]
+  }
+
+  private userLayer(): Record<string, unknown> | undefined {
+    return this.snapshotOf().user as Record<string, unknown> | undefined
+  }
+
+  private stored(field: string): boolean {
+    const user = this.userLayer()
+    return user !== undefined && Object.hasOwn(user, field)
+  }
+
+  private publish(): void {
+    for (const listener of this.listeners) listener()
+  }
+}

package/src/client/usage-settings-card.ts

@@ -0,0 +1,72 @@
+/**
+ * The usage page's settings card: the plugin switch and the three display
+ * rows, written through the family card form so a pick lands at once and a
+ * typed value after a pause, exactly as the other Web Extensions pages do.
+ * @module @linxin666/dsh-usage/client/usage-settings-card
+ */
+
+import type { ConfigForm } from '@deepseek-ai/dsh-client-ui-settings/client'
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store'
+import { CardForm, booleanField, choiceField, numberField, type CardActions, type CardShell, type FieldState } from './settings-form.ts'
+
+/** The settings fields this page edits (the namespace's own schema). */
+export interface UsageSettings {
+  enabled?: boolean
+  pollIntervalSec?: number
+  /** Currency the spend figures are displayed in; the ledger stays CNY. */
+  spendCurrency?: 'CNY' | 'USD'
+  /** CNY per USD, consulted only while the display currency is USD. */
+  cnyPerUsd?: number
+}
+
+/** The display currencies the spend figures offer. */
+export const SPEND_CURRENCIES = ['CNY', 'USD'] as const
+
+/** Bounds of the poll interval, mirroring the host schema; the slider walks them in steps of 10 s. */
+export const POLL_INTERVAL_RANGE = { min: 30, max: 3600, step: 10 }
+
+/** What the settings card renders. */
+export interface UsageSettingsCardState extends CardShell {
+  enabled: FieldState
+  pollIntervalSec: FieldState
+  spendCurrency: FieldState
+  cnyPerUsd: FieldState
+}
+
+/** The card's snapshot and its form actions, as the section receives them. */
+export interface UsageSettingsCardFace extends CardActions {
+  store: SnapshotStore<UsageSettingsCardState>
+}
+
+/** Bridges the usage namespace onto the family card form for the plugin's lifetime. */
+export class UsageSettingsCardController {
+  private readonly form: CardForm<UsageSettings>
+  private readonly store: SnapshotStore<UsageSettingsCardState>
+
+  /** @param scope - the bound configuration form of the usage namespace. */
+  constructor(scope: ConfigForm<UsageSettings>) {
+    this.form = new CardForm(scope, [
+      booleanField('enabled'),
+      numberField('pollIntervalSec', { integer: true, min: POLL_INTERVAL_RANGE.min }),
+      choiceField('spendCurrency', SPEND_CURRENCIES),
+      numberField('cnyPerUsd', { min: 0.01 }),
+    ])
+    this.store = this.form.bind(() => ({
+      ...this.form.shell(),
+      enabled: this.form.field('enabled'),
+      pollIntervalSec: this.form.field('pollIntervalSec'),
+      spendCurrency: this.form.field('spendCurrency'),
+      cnyPerUsd: this.form.field('cnyPerUsd'),
+    }))
+  }
+
+  /** The face the section's slot entry injects. */
+  inject(): UsageSettingsCardFace {
+    return { store: this.store, ...this.form.actions() }
+  }
+
+  /** Release the form subscription; the plugin disposer calls this on teardown. */
+  dispose(): void {
+    this.form.dispose()
+  }
+}