H4: string and path settings controls, live completion and tooltip settings

- Settings dialog: every string setting gets a text field with in-place
  hints (quotes or spaces around a path, control characters, length);
  keys ending in path/executable also get "Browse…" through the dialog
  plugin's native picker (new desktop IPC pick_file). git.executable
  from M4.1 gets the control without UI changes.
- settings.open {section?, query?} for agents and live checks.
- New keys editor.completion.autoPopup, editor.completion.delayMs and
  editor.hover.delayMs; the assist module reads them live through
  CodeMirror compartments.
- Tests: engine settings test, control/engine key lists, Vitest for the
  controls and the live wiring. Docs: architecture, ui-parity, parity
  Settings row, gaps.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
danny 2026-10-25 13:10:19 +01:00
parent b0f8550aeb
commit 197d5b7d27
19 changed files with 1149 additions and 41 deletions

View file

@ -10,7 +10,7 @@ import { renderMarkdown } from "./markdown";
import { engineAssistTransport, queryAt } from "./request";
import { toHover, type AssistBuffer, type AssistTransport } from "./types";
/** Milliseconds the pointer rests before the hover is asked for. */
/** Default milliseconds the pointer rests before the hover is asked for (`editor.hover.delayMs`). */
export const HOVER_DELAY = 350;
/**
@ -60,10 +60,15 @@ export async function hoverAt(
*
* @param buffer - the buffer the editor state shows.
* @param transport - how to reach the engine.
* @param delay - milliseconds the pointer rests before the hover is asked for.
*/
export function lspHover(buffer: AssistBuffer, transport: AssistTransport = engineAssistTransport): Extension {
export function lspHover(
buffer: AssistBuffer,
transport: AssistTransport = engineAssistTransport,
delay: number = HOVER_DELAY,
): Extension {
return hoverTooltip((view, pos) => hoverAt(view, pos, buffer, transport), {
hoverTime: HOVER_DELAY,
hoverTime: delay,
hideOnChange: true,
});
}

View file

@ -5,8 +5,10 @@
* queries, see `request.ts`).
*
* {@link assistExtensions} is the hook the editor uses: PHP files of a
* buffer get the extensions, everything else none. Colours come from
* `--lt-*` tokens only; strings from the catalog.
* buffer get the extensions, everything else none. Completion and hover
* follow the assist settings live (`settings.ts`: auto popup, completion
* delay, hover delay). Colours come from `--lt-*` tokens only; strings
* from the catalog.
*/
import { autocompletion } from "@codemirror/autocomplete";
import type { Extension } from "@codemirror/state";
@ -17,6 +19,7 @@ import { itemOf, lspCompletionSource } from "./completion";
import { lspHover } from "./hover";
import { kindIcon } from "./icons";
import { engineAssistTransport } from "./request";
import { liveAssistSettings, storeAssistSettings, type AssistSettings, type AssistSettingsSource } from "./settings";
import { lspSignatureHelp } from "./signature";
import type { AssistBuffer, AssistTransport } from "./types";
@ -122,30 +125,48 @@ const assistTheme: Extension = EditorView.theme({
},
});
/**
* The completion extension for given settings: typing opens the list only
* with auto popup on, after the completion delay.
*
* @param buffer - the buffer the editor state shows.
* @param transport - how to reach the engine.
* @param settings - the assist settings.
*/
function completionExtension(buffer: AssistBuffer, transport: AssistTransport, settings: AssistSettings): Extension {
return autocompletion({
override: [lspCompletionSource(buffer, transport)],
activateOnTyping: settings.autoPopup,
activateOnTypingDelay: settings.completionDelay,
icons: false,
addToOptions: [{ render: (completion) => kindIcon(completion.type ?? "text"), position: 20 }],
optionClass: (completion) => (itemOf.get(completion)?.deprecated === true ? "lt-assist-deprecated" : ""),
});
}
/**
* The assist extensions of an editor state.
*
* @param path - project-relative path of the file.
* @param buffer - the buffer it shows; none for states without one.
* @param transport - how to reach the engine.
* @param settings - where the assist settings come from; the settings store by default.
* @returns the extensions; empty unless a PHP file of a buffer.
*/
export function assistExtensions(
path: string,
buffer: AssistBuffer | undefined,
transport: AssistTransport = engineAssistTransport,
settings: AssistSettingsSource = storeAssistSettings,
): Extension {
if (!buffer || languageOf(path) !== "php") {
return [];
}
return [
autocompletion({
override: [lspCompletionSource(buffer, transport)],
icons: false,
addToOptions: [{ render: (completion) => kindIcon(completion.type ?? "text"), position: 20 }],
optionClass: (completion) => (itemOf.get(completion)?.deprecated === true ? "lt-assist-deprecated" : ""),
}),
lspHover(buffer, transport),
liveAssistSettings(settings, [
(values) => completionExtension(buffer, transport, values),
(values) => lspHover(buffer, transport, values.hoverDelay),
]),
lspSignatureHelp(buffer, transport),
assistTracker(buffer, transport),
assistTheme,

View file

@ -0,0 +1,195 @@
/**
* The settings of code assistance (H4), read live from the settings store:
*
* - `editor.completion.autoPopup` (bool, default true): whether typing
* opens the completion list; the completion shortcut always does.
* - `editor.completion.delayMs` (0–2000, default 0): how long typing has
* to pause before completion is asked for.
* - `editor.hover.delayMs` (100–3000, default 350): how long the pointer
* rests before the hover documentation is asked for.
*
* {@link liveAssistSettings} keeps an editor state's completion and hover
* extensions in step with these values: a change from the dialog, the
* control channel or an agent reconfigures every open editor at once.
*/
import type { Extension } from "@codemirror/state";
import { Compartment, StateEffect, StateField } from "@codemirror/state";
import { ViewPlugin, type EditorView } from "@codemirror/view";
import { getActivePinia } from "pinia";
import { watch } from "vue";
import { useSettingsStore } from "../../../stores/settings";
/** The assist settings with values the editor can use. */
export interface AssistSettings {
/** Whether typing opens the completion list. */
autoPopup: boolean;
/** Milliseconds typing pauses before completion is asked for. */
completionDelay: number;
/** Milliseconds the pointer rests before the hover is asked for. */
hoverDelay: number;
}
/** Setting keys of the assist settings. */
export const ASSIST_SETTING_KEYS = {
autoPopup: "editor.completion.autoPopup",
completionDelay: "editor.completion.delayMs",
hoverDelay: "editor.hover.delayMs",
} as const;
/** The engine's defaults, used while a value is missing or unusable. */
export const ASSIST_DEFAULTS: Readonly<AssistSettings> = {
autoPopup: true,
completionDelay: 0,
hoverDelay: 350,
};
/** Where the assist settings come from, and how changes are followed. */
export interface AssistSettingsSource {
/** The current values. */
current(): AssistSettings;
/**
* Calls `listener` after the values change.
*
* @returns a function that stops following.
*/
subscribe(listener: () => void): () => void;
}
/**
* A whole number from untrusted data, clamped to a range.
*
* @param value - the data.
* @param min - smallest value.
* @param max - largest value.
* @param fallback - used when the data is no finite number.
*/
function clampInt(value: unknown, min: number, max: number, fallback: number): number {
if (typeof value !== "number" || !Number.isFinite(value)) {
return fallback;
}
return Math.min(max, Math.max(min, Math.round(value)));
}
/**
* Reads the assist settings from setting values (unchecked), with the
* defaults for missing or malformed values and numbers clamped to the
* engine's ranges.
*
* @param values - setting values by key.
*/
export function toAssistSettings(values: Readonly<Record<string, unknown>>): AssistSettings {
const autoPopup = values[ASSIST_SETTING_KEYS.autoPopup];
return {
autoPopup: typeof autoPopup === "boolean" ? autoPopup : ASSIST_DEFAULTS.autoPopup,
completionDelay: clampInt(values[ASSIST_SETTING_KEYS.completionDelay], 0, 2000, ASSIST_DEFAULTS.completionDelay),
hoverDelay: clampInt(values[ASSIST_SETTING_KEYS.hoverDelay], 100, 3000, ASSIST_DEFAULTS.hoverDelay),
};
}
/**
* Whether two sets of assist settings are equal.
*
* @param a - one set.
* @param b - the other.
*/
export function sameAssistSettings(a: AssistSettings, b: AssistSettings): boolean {
return a.autoPopup === b.autoPopup && a.completionDelay === b.completionDelay && a.hoverDelay === b.hoverDelay;
}
/**
* The settings store of the active Pinia as a source. Without an active
* Pinia (an editor used outside the app) it gives the defaults and never
* changes.
*/
export const storeAssistSettings: AssistSettingsSource = {
current() {
const pinia = getActivePinia();
return pinia ? toAssistSettings(useSettingsStore(pinia).values) : { ...ASSIST_DEFAULTS };
},
subscribe(listener) {
const pinia = getActivePinia();
if (!pinia) {
return () => undefined;
}
const store = useSettingsStore(pinia);
return watch(
() => toAssistSettings(store.values),
(next, previous) => {
if (!sameAssistSettings(next, previous)) {
listener();
}
},
);
},
};
/** Records which settings an editor state's assist extensions were built with. */
const applied = StateEffect.define<AssistSettings>();
/** The settings the state's assist extensions use. */
const appliedField = StateField.define<AssistSettings>({
create: () => ({ ...ASSIST_DEFAULTS }),
update: (value, tr) => {
for (const effect of tr.effects) {
if (effect.is(applied)) {
return effect.value;
}
}
return value;
},
});
/** Builds an extension for the given settings. */
export type SettingsBuilder = (settings: AssistSettings) => Extension;
/**
* Extensions that depend on the assist settings and follow them live.
* Each builder sits in its own compartment; when the source reports a
* change (or a view gets a state built with older values), the
* compartments are reconfigured with the new values. The reconfiguration
* is dispatched outside any editor update.
*
* @param source - where the settings come from.
* @param builders - one builder per settings-dependent extension.
* @returns the extensions, built with the current values.
*/
export function liveAssistSettings(source: AssistSettingsSource, builders: readonly SettingsBuilder[]): Extension {
const initial = source.current();
const slots = builders.map((build) => ({ build, compartment: new Compartment() }));
const sync = (view: EditorView): void => {
const next = source.current();
if (sameAssistSettings(next, view.state.field(appliedField))) {
return;
}
view.dispatch({
effects: [
...slots.map((slot) => slot.compartment.reconfigure(slot.build(next))),
applied.of(next),
],
});
};
const follower = ViewPlugin.define((view) => {
let live = true;
const stop = source.subscribe(() => {
if (live) {
sync(view);
}
});
queueMicrotask(() => {
if (live) {
sync(view);
}
});
return {
destroy() {
live = false;
stop();
},
};
});
return [
appliedField.init(() => initial),
...slots.map((slot) => slot.compartment.of(slot.build(initial))),
follower,
];
}

View file

@ -3,27 +3,33 @@
* The settings dialog (`settings.open`, `Mod+,`), built from the engine's
* `settings.list`: sections on the left, the settings of the chosen
* section on the right, each with its control by type (enum → select,
* int → number field with min/max, bool → switch), label and description
* from the catalog, and "Reset to default" when it differs from the
* default.
* int → number field with min/max, bool → switch, string → text field,
* plus "Browse…" for a path, see `stringSetting.ts`), label and
* description from the catalog, and "Reset to default" when it differs
* from the default.
*
* - **Search:** the field filters by label, description, key and section
* name; while it has text, every match shows, grouped by section.
* - **Changes** apply at once through `settings.set` (a number when the
* field is committed: Enter, the spinner or leaving it). A refused value
* shows its error under the control and keeps the typed text.
* - **Changes** apply at once through `settings.set` (a number or a text
* when the field is committed: Enter, the spinner or leaving it; a path
* when the file picker returns one). A refused value shows its error
* under the control and keeps the typed text.
* - **Live:** values follow `settingsChanged` through the settings store,
* so a change over the control channel shows while the dialog is open.
* - **Keyboard:** Escape closes, Tab and Shift+Tab stay inside the dialog,
* and the focus returns to where it was.
* - **One modal:** opening the dialog closes the palette or the close
* question (see `commands/modals.ts`).
* - **Agents:** `settings.open {section?, query?}` opens on a section or
* with a search, so the dialog can be shown over the control channel
* without clicks.
*/
import { X } from "@lucide/vue";
import { computed, nextTick, onBeforeUnmount, onMounted, reactive, ref } from "vue";
import { useModalsStore } from "../../commands/modals";
import { useCommandsStore } from "../../commands/store";
import { t } from "../../i18n";
import { pickFile, type JsonValue } from "../../ipc";
import {
descriptionOf,
groupSections,
@ -34,6 +40,7 @@ import {
type SettingDef,
type SettingSection,
} from "../../stores/settings";
import { checkString, isPathSetting, placeholderOf } from "./stringSetting";
const commands = useCommandsStore();
const settings = useSettingsStore();
@ -45,7 +52,7 @@ const open = ref(false);
const query = ref("");
/** Id of the chosen section. */
const current = ref<string | null>(null);
/** Text typed into number fields, by key; shown while their value is refused. */
/** Text typed into number and text fields, by key; shown while their value is refused. */
const drafts = reactive<Record<string, string>>({});
/** The dialog element. */
const dialog = ref<HTMLElement | null>(null);
@ -105,6 +112,21 @@ function numberText(def: SettingDef): string {
return typeof value === "number" ? String(value) : "";
}
/**
* The text of a text field: the refused draft while there is an error,
* else the value.
*
* @param def - the setting.
*/
function stringText(def: SettingDef): string {
const draft = drafts[def.key];
if (draft !== undefined && settings.errors[def.key] !== undefined) {
return draft;
}
const value = settings.values[def.key];
return typeof value === "string" ? value : "";
}
/**
* The value of a select.
*
@ -172,6 +194,56 @@ async function onNumber(def: SettingDef, event: Event): Promise<void> {
}
}
/**
* Sends a text to `settings.set` after the checks of
* {@link checkString}; a refused text stays in the field with its error.
*
* @param def - the setting.
* @param text - the new value.
*/
async function applyString(def: SettingDef, text: string): Promise<void> {
drafts[def.key] = text;
const error = checkString(def, text);
if (error !== null) {
settings.setError(def.key, error);
return;
}
if (await settings.set(def.key, text)) {
Reflect.deleteProperty(drafts, def.key);
}
}
/**
* Applies a committed text field.
*
* @param def - the setting.
* @param event - the change event.
*/
async function onString(def: SettingDef, event: Event): Promise<void> {
const target = event.target;
if (target instanceof HTMLInputElement) {
await applyString(def, target.value);
}
}
/**
* "Browse…" of a path setting: shows the native file picker and applies
* the chosen file. Cancelling changes nothing; a picker that cannot open
* shows its error under the control.
*
* @param def - the setting.
*/
async function onBrowse(def: SettingDef): Promise<void> {
const picked = await pickFile(t("settings.dialog.browseTitle", { name: labelOf(def) }));
if (!picked.ok) {
settings.setError(def.key, t("settings.error.browseFailed", { message: picked.error.message }));
return;
}
if (picked.value !== null) {
await applyString(def, picked.value);
}
}
/**
* Flips a switch.
*
@ -202,8 +274,13 @@ function choose(id: string): void {
query.value = "";
}
/** Opens the dialog (or focuses its search field) and reloads the settings. */
async function show(): Promise<void> {
/**
* Opens the dialog (or focuses its search field) and reloads the settings.
*
* @param params - optional `{section?, query?}` from `settings.open`:
* the section id to show, the search text; anything else is ignored.
*/
async function show(params?: JsonValue): Promise<void> {
modals.opened("settings", close);
if (!open.value) {
const active = document.activeElement;
@ -211,6 +288,14 @@ async function show(): Promise<void> {
query.value = "";
open.value = true;
}
if (typeof params === "object" && params !== null && !Array.isArray(params)) {
if (typeof params.section === "string") {
choose(params.section);
}
if (typeof params.query === "string") {
query.value = params.query.slice(0, 200);
}
}
await nextTick();
search.value?.focus();
await settings.load();
@ -295,7 +380,7 @@ function onFocusIn(event: FocusEvent): void {
}
onMounted(() => {
withdraw = commands.provide("settings.open", { run: show });
withdraw = commands.provide("settings.open", { run: (params) => show(params) });
document.addEventListener("focusin", onFocusIn);
});
@ -419,6 +504,7 @@ defineExpose({ show, close });
v-for="def in section.settings"
:key="def.key"
class="settings__row"
:class="{ 'settings__row--wide': def.type === 'string' }"
:data-key="def.key"
data-test="settings-row"
>
@ -478,6 +564,32 @@ defineExpose({ show, close });
data-test="settings-control"
@change="onNumber(def, $event)"
>
<template v-else-if="def.type === 'string'">
<input
:id="controlId(def)"
class="settings__input settings__input--text"
type="text"
:value="stringText(def)"
:placeholder="placeholderOf(def) || undefined"
spellcheck="false"
autocomplete="off"
:aria-describedby="`${controlId(def)}-description`"
:aria-invalid="settings.errors[def.key] ? 'true' : undefined"
:aria-errormessage="settings.errors[def.key] ? `${controlId(def)}-error` : undefined"
data-test="settings-control"
@change="onString(def, $event)"
>
<button
v-if="isPathSetting(def)"
type="button"
class="settings__browse"
:aria-label="t('settings.dialog.browseLabel', { name: labelOf(def) })"
data-test="settings-browse"
@click="onBrowse(def)"
>
{{ t("settings.dialog.browse") }}
</button>
</template>
<button
v-else
:id="controlId(def)"
@ -634,6 +746,16 @@ defineExpose({ show, close });
min-width: 0;
}
.settings__row--wide {
flex-direction: column;
align-items: stretch;
gap: 6px;
}
.settings__row--wide .settings__control {
flex-shrink: 1;
}
.settings__label {
display: block;
}
@ -674,6 +796,11 @@ defineExpose({ show, close });
width: 6em;
}
.settings__input--text {
flex: 1;
min-width: 0;
}
.settings__input[aria-invalid="true"] {
border-color: var(--lt-error);
}
@ -719,6 +846,17 @@ defineExpose({ show, close });
cursor: pointer;
}
.settings__browse {
padding: 3px 8px;
font: inherit;
font-size: var(--lt-font-size-small);
color: var(--lt-fg);
background: none;
border: 1px solid var(--lt-border);
border-radius: 4px;
cursor: pointer;
}
.settings__reset:disabled {
color: var(--lt-fg-muted);
cursor: default;
@ -729,6 +867,7 @@ defineExpose({ show, close });
.settings__search:focus-visible,
.settings__input:focus-visible,
.settings__switch:focus-visible,
.settings__browse:focus-visible,
.settings__reset:focus-visible {
outline: 2px solid var(--lt-accent);
outline-offset: 1px;

View file

@ -0,0 +1,91 @@
/**
* Rules of the settings dialog's text control for string settings (H4):
* which string settings are paths (they get a "Browse…" button), what the
* field shows while empty, and the checks made before asking the engine.
*
* The rules work on any string setting `settings.list` reports, so a new
* one (such as `git.executable`) gets the control without changes here.
* The engine still validates every value; these checks only catch mistakes
* early and say how to fix them.
*/
import { t } from "../../i18n";
import type { SettingDef } from "../../stores/settings";
/** Longest value in UTF-8 bytes; the engine's limit for string settings. */
export const MAX_STRING_BYTES = 4096;
/** Endings of a key's last segment that mark a path setting. */
const PATH_ENDINGS = ["path", "executable"];
/**
* Whether a text has control characters (U+0000–U+001F, U+007F), which no
* single-line setting needs.
*
* @param text - the text.
*/
function hasControlChars(text: string): boolean {
for (let i = 0; i < text.length; i += 1) {
const code = text.charCodeAt(i);
if (code < 0x20 || code === 0x7f) {
return true;
}
}
return false;
}
/**
* Whether a setting holds a file path: a string setting whose key ends in
* `path` or `executable` (`phpactor.path`, `php.executable`,
* `git.executable`, `x.pharPath`).
*
* @param def - the setting.
*/
export function isPathSetting(def: SettingDef): boolean {
if (def.type !== "string") {
return false;
}
const last = (def.key.split(".").at(-1) ?? "").toLowerCase();
return PATH_ENDINGS.some((ending) => last.endsWith(ending));
}
/**
* What an empty text field shows: "Detected automatically" for a path
* setting whose default is empty (the engine then looks for the tool
* itself), nothing otherwise.
*
* @param def - the setting.
*/
export function placeholderOf(def: SettingDef): string {
return isPathSetting(def) && def.default === "" ? t("settings.hint.pathAuto") : "";
}
/**
* Checks a typed value before it goes to `settings.set`.
*
* - Longer than {@link MAX_STRING_BYTES} UTF-8 bytes, or with control
* characters: refused for every string setting.
* - Paths: refused when wrapped in quotes (as copied from a shell or the
* file manager) or with spaces at either end.
*
* @param def - the setting.
* @param text - the typed value.
* @returns the error text from the catalog, or null when the value may be sent.
*/
export function checkString(def: SettingDef, text: string): string | null {
if (new TextEncoder().encode(text).length > MAX_STRING_BYTES) {
return t("settings.error.stringTooLong", { max: MAX_STRING_BYTES });
}
if (hasControlChars(text)) {
return t("settings.error.stringControl");
}
if (!isPathSetting(def)) {
return null;
}
if (/^\s*(["']).*\1\s*$/.test(text) && text.trim().length >= 2) {
return t("settings.error.pathQuoted");
}
if (text !== text.trim()) {
return t("settings.error.pathSpaces");
}
return null;
}