@qilin-agent/client-ui-primitives 3.1.3 → 3.1.4

package/lib/settings-form/SettingsForm.module.css

@@ -0,0 +1,53 @@
+/* Settings form: the controls a page shows under a plugin's title, and the save that writes them. */
+
+.form {
+  display: flex;
+  flex-direction: column;
+}
+
+.readOnly,
+.unavailable {
+  margin: 0 0 12px;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--qilin-alias-label-tertiary);
+}
+
+.footer {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding-top: 16px;
+}
+
+.failed {
+  flex: 1;
+  min-width: 0;
+  margin: 0;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--qilin-alias-label-error);
+}
+
+.save {
+  appearance: none;
+  border: 1px solid transparent;
+  border-radius: var(--qilin-radius-md);
+  padding: 5px 14px;
+  font: inherit;
+  font-size: 13px;
+  line-height: 1.5;
+  cursor: pointer;
+  background: var(--qilin-alias-label-primary);
+  color: var(--qilin-alias-bg-layer-3);
+}
+
+.save:disabled {
+  opacity: 0.4;
+  cursor: default;
+}
+
+.save:focus-visible {
+  outline: var(--qilin-focus-ring-width) solid var(--qilin-focus-ring-color, var(--qilin-alias-state-business-primary));
+  outline-offset: 1px;
+}

package/lib/settings-form/fields.module.css

@@ -0,0 +1,145 @@
+/* Settings form fields: label, control, override badge, and hint. */
+
+.field {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 0;
+}
+
+.field + .field {
+  border-top: 0.5px solid var(--qilin-alias-border-l2);
+}
+
+.head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.label {
+  flex: 1;
+  min-width: 0;
+  font-size: 13px;
+  font-weight: 500;
+  line-height: 1.5;
+  color: var(--qilin-alias-label-primary);
+}
+
+.labelGroup {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  flex: 1;
+  min-width: 0;
+}
+
+.labelGroup > .label {
+  flex: 0 1 auto;
+}
+
+.helpButton {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: 24px;
+  height: 24px;
+  padding: 0;
+  border: 0;
+  border-radius: var(--qilin-radius-sm);
+  background: none;
+  color: var(--qilin-alias-label-tertiary);
+  cursor: pointer;
+}
+
+.helpButton:hover,
+.helpButton[aria-expanded='true'] {
+  background: var(--qilin-alias-bg-layer-4);
+  color: var(--qilin-alias-label-secondary);
+}
+
+.helpButton:focus-visible {
+  outline: var(--qilin-focus-ring-width) solid var(--qilin-focus-ring-color, var(--qilin-alias-state-business-primary));
+  outline-offset: 1px;
+}
+
+.help {
+  padding: 10px 0 0;
+  font-size: 12px;
+  line-height: 1.6;
+  color: var(--qilin-alias-label-secondary);
+}
+
+.help > p {
+  margin: 0;
+}
+
+.help > p + p {
+  margin-top: 8px;
+}
+
+.badges {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.reset {
+  border: none;
+  background: none;
+  padding: 0;
+  font: inherit;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--qilin-alias-label-secondary);
+  cursor: pointer;
+}
+
+.reset:hover:not(:disabled) {
+  color: var(--qilin-alias-label-primary);
+}
+
+.reset:disabled {
+  cursor: default;
+}
+
+.input {
+  height: 34px;
+  padding: 0 12px;
+  border: 0.5px solid var(--qilin-alias-border-l4);
+  border-radius: var(--qilin-radius-md);
+  background: var(--qilin-alias-bg-layer-3);
+  font: inherit;
+  font-size: 13px;
+  line-height: 1.5;
+  color: var(--qilin-alias-label-primary);
+}
+
+.input:focus-visible {
+  outline: none;
+  border-color: var(--qilin-alias-state-business-primary);
+}
+
+.input:disabled {
+  color: var(--qilin-alias-label-tertiary);
+  cursor: default;
+}
+
+.input[aria-invalid='true'] {
+  border-color: var(--qilin-alias-state-error-primary);
+}
+
+.invalid {
+  margin: 0;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--qilin-alias-state-error-primary);
+}
+
+.hint {
+  margin: 0;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--qilin-alias-label-tertiary);
+}

package/lib/types/CommandText.d.ts

@@ -0,0 +1,16 @@
+/** Display text and owner-localized identification for a command scrollport. */
+export interface CommandTextProps {
+    /** Original command or formatted command arguments, without truncation. */
+    text: string;
+    /** Accessible name while the text can scroll horizontally. */
+    label: string;
+    /** Owner typography and positioning. */
+    className?: string | undefined;
+}
+/**
+ * Render command text without adding Tab stops for content that fits.
+ * @param props - Text, localized scrollport name, and owner styling.
+ * @returns A horizontal text scrollport, named and keyboard-focusable only when overflowing.
+ */
+export declare function CommandText({ text, label, className }: CommandTextProps): import("react").JSX.Element;
+//# sourceMappingURL=CommandText.d.ts.map

package/lib/types/TerminalBlock.d.ts

@@ -17,6 +17,8 @@ export interface TerminalBlockLabels {
     failed: string;
     /** Run-state text for a clean settle. */
     done: string;
+    /** Accessible name of one command line's scrollport, numbered from 1. */
+    commandLine: (index: number) => string;
     /** Copy-button idle label. */
     copy: string;
     /** Copy-button label during the post-copy confirmation window. */

package/lib/types/darwin-desktop.d.ts

@@ -6,4 +6,13 @@
  * @returns true only inside the macOS Electron shell.
  */
 export declare function isDarwinDesktop(): boolean;
+/**
+ * Subscribe to `data-platform` flips on `<html>` for decisions made outside
+ * render (apply-world projections that cannot re-read the DOM per frame).
+ * The listener fires on attribute changes after this call, not for the
+ * current value — pair it with a fresh `isDarwinDesktop()` read.
+ * @param listener - Called on every `data-platform` attribute change.
+ * @returns Disposer that stops watching.
+ */
+export declare function watchDarwinDesktop(listener: () => void): () => void;
 //# sourceMappingURL=darwin-desktop.d.ts.map

package/lib/types/index.d.ts

@@ -1,6 +1,14 @@
 /**
  * Cordis-free React primitives styled only through `--qilin-*` tokens.
  */
+export { SettingsForm } from './settings-form/SettingsForm.tsx';
+export type { SettingsFormLabels, SettingsFormProps } from './settings-form/SettingsForm.tsx';
+export { SettingsSecretField, SettingsValueField } from './settings-form/fields.tsx';
+export type { SettingsFieldProps } from './settings-form/fields.tsx';
+export { SettingsFormModel, settingsNumberField, settingsTextField } from './settings-form/form-model.ts';
+export type { SettingsFieldSpec, SettingsFieldState, SettingsFieldWrite, SettingsFormActions, SettingsFormPathOp, SettingsFormScope, SettingsFormScopeSnapshot, SettingsFormShell, SettingsSecretSpec, } from './settings-form/form-model.ts';
+export { CommandText } from './CommandText.tsx';
+export type { CommandTextProps } from './CommandText.tsx';
 export { StateDot } from './StateDot.tsx';
 export type { StateDotState } from './StateDot.tsx';
 export { DisclosureRow } from './DisclosureRow.tsx';
@@ -53,7 +61,7 @@ export { useCopyFeedback } from './use-copy-feedback.ts';
 export type { CopyFeedback } from './use-copy-feedback.ts';
 export { relativeTime } from './relative-time.ts';
 export { rankByName } from './rank-by-name.ts';
-export { isDarwinDesktop } from './darwin-desktop.ts';
+export { isDarwinDesktop, watchDarwinDesktop } from './darwin-desktop.ts';
 export type { RelativeTime, RelativeTimeUnit } from './relative-time.ts';
 export { JsonTree } from './JsonTree.tsx';
 export type { JsonTreeProps, JsonTreeLabels } from './JsonTree.tsx';

package/lib/types/settings-form/SettingsForm.d.ts

@@ -0,0 +1,46 @@
+/**
+ * One plugin's settings form as its page on the Plugins page shows it: the
+ * read-only notice when the deployment stores settings read-only, the
+ * plugin's controls, and the save that writes every staged edit. The page
+ * draws the plugin's title and one-liner itself.
+ *
+ * Only a save writes. Leaving the page drops every staged edit, so the form
+ * discards on unmount and offers no discard control. A form whose namespace
+ * the Host stopped serving says so in place of its controls rather than
+ * showing fields nothing would accept.
+ */
+import { type ReactNode } from 'react';
+import type { SettingsFormShell } from './form-model.ts';
+/** The copy the form frame renders, from the owning plugin's dictionary. */
+export 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. */
+export 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.
+ */
+export declare function SettingsForm(props: SettingsFormProps): import("react").JSX.Element;
+//# sourceMappingURL=SettingsForm.d.ts.map

package/lib/types/settings-form/fields.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The controls of a settings form. Each renders one field's label, its staged
+ * text, whether saving would leave an override, and — when one stands — the
+ * reset that stages a clear back to the composition layer. Nothing here
+ * writes: a control reports what the user typed, and the form's save is the
+ * single point where a draft becomes a document mutation.
+ */
+import { type ReactNode } from 'react';
+/** What every settings field control needs regardless of its value type. */
+export 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.
+ */
+export 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.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.
+ * The control asks browsers not to autofill saved login passwords.
+ * @param props - the field's copy, its staged text, and the configured state.
+ * @returns the labelled control.
+ */
+export 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.Element;
+//# sourceMappingURL=fields.d.ts.map

package/lib/types/settings-form/form-model.d.ts

@@ -0,0 +1,214 @@
+/**
+ * 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.
+ */
+import { type SnapshotStore } from '@qilin-agent/client-store';
+/** 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. */
+    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. */
+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. */
+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.
+     */
+    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. */
+export type SettingsFieldWrite = {
+    kind: 'set';
+    value: unknown;
+} | {
+    kind: 'clear';
+};
+/** How one section field converts between its stored value and its draft text. */
+export 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.
+ */
+export 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. */
+export 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. */
+export 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. */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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;
+}
+//# sourceMappingURL=form-model.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qilin-agent/client-ui-primitives",
   "description": "Pure React atoms for the qilin web UI: controls, icons, markdown, and JSON inspectors (zero cordis)",
-  "version": "3.1.3",
+  "version": "3.1.4",
   "publishConfig": {
     "access": "public"
   },
@@ -51,8 +51,9 @@
     "react-dom": "^18.2.0",
     "shiki": "^4.3.1",
     "simple-icons": "16.31.0",
-    "@qilin-agent/util-workspace-path": "3.1.3",
-    "@qilin-agent/kylin": "~4.0.3"
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/client-store": "3.1.4",
+    "@qilin-agent/util-workspace-path": "3.1.4"
   },
   "files": [
     "lib/index.js",