@adecore/editor-react 0.43.0 → 0.44.0

package/dist/templates.d.ts

@@ -0,0 +1,59 @@
+import { BUILT_IN_LIVE_TEMPLATES, BUILT_IN_POSTFIX_TEMPLATES } from './template-builtins.ts';
+export { BUILT_IN_LIVE_TEMPLATES, BUILT_IN_POSTFIX_TEMPLATES };
+export { type TemplatesFeature } from './live-templates.ts';
+export type TemplateLanguage = 'javascript' | 'typescript' | 'php' | 'css' | 'html' | 'xml' | 'other';
+export type TemplatePlace = 'code' | 'comment' | 'string';
+export interface LiveTemplate {
+    readonly id: string;
+    readonly key: string;
+    readonly body: string;
+    readonly description?: string;
+    readonly languages: readonly TemplateLanguage[];
+    readonly places?: readonly TemplatePlace[];
+    readonly group?: string;
+}
+export interface PostfixTemplate {
+    readonly id: string;
+    readonly key: string;
+    readonly body: string;
+    readonly description?: string;
+    readonly example?: string;
+    readonly languages: readonly ('javascript' | 'typescript' | 'php')[];
+    readonly expression?: 'any' | 'statement';
+}
+export interface TemplateSettings {
+    readonly liveInCompletion?: boolean;
+    readonly postfix?: boolean;
+    readonly postfixInCompletion?: boolean;
+}
+export interface LiveTemplateDraft {
+    readonly body: string;
+    readonly languages: readonly TemplateLanguage[];
+    readonly places: readonly TemplatePlace[];
+}
+export interface TemplateRegistryOptions {
+    readonly builtins?: boolean;
+}
+export interface TemplateUpdate {
+    readonly live?: readonly LiveTemplate[];
+    readonly postfix?: readonly PostfixTemplate[];
+    readonly disabled?: readonly string[];
+    readonly settings?: TemplateSettings;
+}
+export declare class TemplateRegistry {
+    private readonly builtins;
+    private readonly listeners;
+    private own;
+    private off;
+    private current;
+    private liveList;
+    private postfixList;
+    constructor(options?: TemplateRegistryOptions);
+    get live(): readonly LiveTemplate[];
+    get postfix(): readonly PostfixTemplate[];
+    get settings(): Required<TemplateSettings>;
+    set(update: TemplateUpdate): void;
+    onChange(listener: () => void): () => void;
+    private listed;
+}
+export declare function checkTemplate(template: LiveTemplate | PostfixTemplate, kind?: 'live' | 'postfix'): string | null;

package/dist/templates.js

@@ -0,0 +1,103 @@
+import { BUILT_IN_LIVE_TEMPLATES, BUILT_IN_POSTFIX_TEMPLATES } from './template-builtins.js';
+import { checkSnippet } from './snippet.js';
+export { BUILT_IN_LIVE_TEMPLATES, BUILT_IN_POSTFIX_TEMPLATES };
+export {} from './live-templates.js';
+const MAX_KEY_LENGTH = 40;
+const MAX_BODY_LENGTH = 20_000;
+const POSTFIX_LANGUAGES = ['javascript', 'typescript', 'php'];
+const LANGUAGES = ['javascript', 'typescript', 'php', 'css', 'html', 'xml', 'other'];
+const PLACES = ['code', 'comment', 'string'];
+/*
+ * The templates the editors of a project know: the built-in ones and the ones a host sets. A host that keeps
+ * templates feeds them through `set`, and the editors read the registry on every use.
+ */
+export class TemplateRegistry {
+  builtins;
+  listeners = new Set();
+  own = {
+    live: [],
+    postfix: []
+  };
+  off = new Set();
+  current = {
+    liveInCompletion: true,
+    postfix: true,
+    postfixInCompletion: true
+  };
+  liveList;
+  postfixList;
+  constructor(options = {}) {
+    this.builtins = options.builtins !== false;
+    this.liveList = this.listed(BUILT_IN_LIVE_TEMPLATES, []);
+    this.postfixList = this.listed(BUILT_IN_POSTFIX_TEMPLATES, []);
+  }
+  /* The built-in templates that are not disabled, then the host's. */
+  get live() {
+    return this.liveList;
+  }
+  get postfix() {
+    return this.postfixList;
+  }
+  get settings() {
+    return this.current;
+  }
+  /* Replaces what the update names. A template that fails `checkTemplate` is dropped; this never throws. */
+  set(update) {
+    this.own = {
+      live: update.live === undefined ? this.own.live : update.live.filter(template => checkTemplate(template, 'live') === null),
+      postfix: update.postfix === undefined ? this.own.postfix : update.postfix.filter(template => checkTemplate(template, 'postfix') === null)
+    };
+    this.off = update.disabled === undefined ? this.off : new Set(update.disabled);
+    if (update.settings !== undefined) {
+      this.current = {
+        liveInCompletion: update.settings.liveInCompletion !== false,
+        postfix: update.settings.postfix !== false,
+        postfixInCompletion: update.settings.postfixInCompletion !== false
+      };
+    }
+    this.liveList = this.listed(BUILT_IN_LIVE_TEMPLATES, this.own.live);
+    this.postfixList = this.listed(BUILT_IN_POSTFIX_TEMPLATES, this.own.postfix);
+    for (const listener of [...this.listeners]) {
+      listener();
+    }
+  }
+  /* Calls `listener` after every `set`. Returns the function that stops it. */
+  onChange(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  listed(builtins, own) {
+    return [...(this.builtins ? builtins.filter(template => !this.off.has(template.id)) : []), ...own];
+  }
+}
+/*
+ * Why a template cannot be used, in English for a host to show, or null. `kind` says which rules apply; without it a
+ * template with an `expression` or an `example` counts as a postfix one.
+ */
+export function checkTemplate(template, kind) {
+  const postfix = kind === undefined ? 'expression' in template || 'example' in template : kind === 'postfix';
+  if (template.id === '') {
+    return 'The template has no id.';
+  }
+  if (template.key === '' || template.key.length > MAX_KEY_LENGTH) {
+    return `The key is one to ${MAX_KEY_LENGTH} characters.`;
+  }
+  if (postfix ? !/^[\p{L}\p{N}_$]+$/u.test(template.key) : /\s/.test(template.key)) {
+    return postfix ? 'The key holds letters, digits, underscores and dollar signs only.' : 'The key holds no whitespace.';
+  }
+  if (template.body.trim() === '') {
+    return 'The text is empty.';
+  }
+  if (template.body.length > MAX_BODY_LENGTH) {
+    return `The text is longer than ${MAX_BODY_LENGTH} characters.`;
+  }
+  if (template.languages.length === 0 || template.languages.some(language => !(postfix ? POSTFIX_LANGUAGES : LANGUAGES).includes(language))) {
+    return 'The languages are empty or not known.';
+  }
+  if (!postfix && template.places?.some(place => !PLACES.includes(place)) === true) {
+    return 'The places are not known.';
+  }
+  return checkSnippet(template.body);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/editor-react",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "type": "module",
   "description": "Language-enabled editors, feature coordination and React popups over injected language services.",
   "license": "FSL-1.1-MIT",
@@ -62,9 +62,9 @@
     "test": "bun test --conditions=source"
   },
   "dependencies": {
-    "@adecore/editor": "0.43.0",
-    "@adecore/lsp": "0.43.0",
-    "@adecore/merge": "0.43.0",
+    "@adecore/editor": "0.44.0",
+    "@adecore/lsp": "0.44.0",
+    "@adecore/merge": "0.44.0",
     "emmet": "^2.4.11",
     "lucide-react": "^1.61.0",
     "react-markdown": "^10.1.0",
@@ -73,14 +73,14 @@
     "zustand": "^5.0.16"
   },
   "peerDependencies": {
-    "@adecore/ui": "^0.43.0",
+    "@adecore/ui": "^0.44.0",
     "i18next": "^26.4.2",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
     "react-i18next": "^17.0.15"
   },
   "devDependencies": {
-    "@adecore/ui": "0.43.0",
+    "@adecore/ui": "0.44.0",
     "@types/bun": "^1.4.4",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",

package/src/PickPopup.tsx

@@ -105,6 +105,7 @@ export function PickPopup({ language, view, rect }: { language: EditorLanguage;
     }
 
     const activeId = optionIds.get(view.active);
+    const mnemonics = view.groups.some((group) => group.rows.some((row) => row.mnemonic !== undefined));
 
     useInputPopup(language, listId, activeId);
 
@@ -135,11 +136,17 @@ export function PickPopup({ language, view, rect }: { language: EditorLanguage;
                                 role="option"
                                 tabIndex={-1}
                                 aria-selected={row.id === view.active || view.chosen.includes(row.id)}
+                                aria-keyshortcuts={row.mnemonic}
                                 data-active={row.id === view.active}
                                 data-chosen={view.chosen.includes(row.id)}
                                 className="flex h-7 w-full items-center gap-2 rounded-md px-2 text-left text-xs cursor-row data-[chosen=true]:bg-accent/15"
                                 onClick={(event) => language.pick.choose(row.id, { toggle: event.metaKey || event.ctrlKey, range: event.shiftKey })}
                             >
+                                {mnemonics && (
+                                    <span aria-hidden="true" className="w-3 shrink-0 text-center font-mono text-text-faint">
+                                        {row.mnemonic}
+                                    </span>
+                                )}
                                 <span className={row.path ? 'shrink-0' : 'min-w-0 truncate'}>
                                     <MatchedLabel label={row.label} query={view.query} />
                                 </span>

package/src/completion.ts

@@ -91,6 +91,30 @@ function mapCompletionEdits(
     return valid ? mapped : null;
 }
 
+/** A row a source of the editor offers beside the language server's. */
+export interface LocalCompletionItem {
+    /** The label, kind, detail, documentation, filter text and sort text of the row; its edit range is the typed prefix on the caret's line, ending at the caret. */
+    readonly item: CompletionItem;
+
+    /** Runs instead of the insertion: the source inserts the row itself. */
+    accept(): void;
+}
+
+/** What a source is asked for when the list is requested. */
+export interface CompletionRequest {
+    readonly position: EditorPosition;
+
+    /** Whether the person asked for the list with the keyboard. */
+    readonly explicit: boolean;
+    readonly triggerCharacter?: string;
+}
+
+/** Rows that come from the editor itself, such as templates, merged into the list of the language server. */
+export interface CompletionSource {
+    /** Synchronous and cheap; asked on every request of the list. */
+    items(request: CompletionRequest): readonly LocalCompletionItem[];
+}
+
 /*
  * The suggestions that open while a word is typed. A single typed identifier character or a trigger
  * character of the server asks for the list; every character after that only filters the list that
@@ -129,6 +153,13 @@ export class CompletionFeature {
     private acceptSequence = 0;
     private disposed = false;
     private readonly resolved = new Map<CompletionItem, CompletionItem>();
+    private readonly sources = new Set<CompletionSource>();
+
+    /* The rows of the list that a source inserts itself. */
+    private locals = new Map<CompletionItem, LocalCompletionItem>();
+
+    /* Whether the list holds the rows `showItems` gave it and no request refreshes it. */
+    private shown = false;
 
     constructor(language: EditorLanguage, timers: Timers = realTimers) {
         this.language = language;
@@ -169,6 +200,30 @@ export class CompletionFeature {
         this.beginRequest({ triggerKind: 1 }, 0);
     }
 
+    /** Adds rows to every list, also in a document without a language server. Returns the function that takes the source away again. */
+    addSource(source: CompletionSource): () => void {
+        this.sources.add(source);
+
+        return () => {
+            this.sources.delete(source);
+        };
+    }
+
+    /** Opens the list with only these rows, the typed prefix starting at `start`, as Insert Live Template does. */
+    showItems(items: readonly LocalCompletionItem[], start: EditorPosition): void {
+        this.language.pick.close();
+        this.close();
+        this.shown = true;
+        this.locals = new Map(items.map((local) => [local.item, local]));
+        this.pool = items.map((local) => local.item);
+        this.incomplete = false;
+        this.start = start;
+        this.active = 0;
+        this.touched = false;
+        this.server = '';
+        this.refilter();
+    }
+
     move(delta: number): void {
         if (this.ranked.length === 0) {
             return;
@@ -199,6 +254,16 @@ export class CompletionFeature {
             return;
         }
 
+        const local = this.locals.get(entry.item);
+
+        if (local !== undefined) {
+            recentChoicesOf(this.language.languageId).record(entry.item);
+            this.close();
+            local.accept();
+
+            return;
+        }
+
         const { editor, project, uri, snippets } = this.language;
         const acceptSequence = ++this.acceptSequence;
         this.accepting?.abort();
@@ -584,6 +649,8 @@ export class CompletionFeature {
         this.activeKey = null;
         this.start = null;
         this.resolved.clear();
+        this.locals = new Map();
+        this.shown = false;
 
         if (this.language.popups.getState().completion !== null) {
             this.language.popups.setState({ completion: null });
@@ -659,6 +726,17 @@ export class CompletionFeature {
     private edited(change: EditorTextChange): void {
         this.textRevision++;
 
+        // The rows were given, so typing only filters them.
+        if (this.shown && this.isOpen) {
+            if (change.source === 'input' && change.changes.length === 1 && Array.from(change.changes[0]!.text).every(isIdentifierCharacter)) {
+                this.refilter();
+            } else {
+                this.close();
+            }
+
+            return;
+        }
+
         if (change.source !== 'input' || change.changes.length !== 1) {
             this.close();
 
@@ -711,7 +789,7 @@ export class CompletionFeature {
     private beginRequest(context: CompletionContext, delay: number): void {
         const { uri } = this.language;
 
-        if (!this.language.service.supports(METHOD, uri)) {
+        if (!this.language.service.supports(METHOD, uri) && this.sources.size === 0) {
             return;
         }
 
@@ -726,26 +804,41 @@ export class CompletionFeature {
         this.controller?.abort();
         const controller = new AbortController();
         this.controller = controller;
-        let normalized: ReturnType<typeof itemsOf>;
+        let normalized: ReturnType<typeof itemsOf> = { items: [], incomplete: false };
+        let failed = false;
 
-        try {
-            const result = await this.language.service.completion(uri, position, context, { signal: controller.signal });
+        if (this.language.service.supports(METHOD, uri)) {
+            try {
+                const result = await this.language.service.completion(uri, position, context, { signal: controller.signal });
 
-            if (request !== this.request || this.controller !== controller || controller.signal.aborted) {
-                return;
-            }
+                if (request !== this.request || this.controller !== controller || controller.signal.aborted) {
+                    return;
+                }
 
-            normalized = itemsOf(result);
-        } catch {
-            if (request === this.request && this.controller === controller && !controller.signal.aborted) {
-                this.close();
+                normalized = itemsOf(result);
+            } catch {
+                if (request !== this.request || this.controller !== controller || controller.signal.aborted) {
+                    return;
+                }
+
+                failed = true;
             }
+        }
+
+        const locals = [...this.sources].flatMap((source) =>
+            source.items({ position, explicit: this.explicit && !refresh, triggerCharacter: context.triggerCharacter })
+        );
+
+        // A failed request still leaves the rows of the sources.
+        if (failed && locals.length === 0) {
+            this.close();
 
             return;
         }
 
         const { items, incomplete } = normalized;
-        this.pool = items;
+        this.pool = [...items, ...locals.map((local) => local.item)];
+        this.locals = new Map(locals.map((local) => [local.item, local]));
         this.incomplete = incomplete;
         this.resolved.clear();
         this.server = project.host.serverNames?.(uri)[0] ?? '';
@@ -844,7 +937,12 @@ export class CompletionFeature {
         this.resolving?.abort();
         const entry = this.ranked[this.active];
 
-        if (entry === undefined || this.resolved.has(entry.item) || this.language.service.providerOptions('completionItem/resolve', uri) === undefined) {
+        if (
+            entry === undefined ||
+            this.locals.has(entry.item) ||
+            this.resolved.has(entry.item) ||
+            this.language.service.providerOptions('completionItem/resolve', uri) === undefined
+        ) {
             return;
         }
 

package/src/editor-language.ts

@@ -34,7 +34,9 @@ import { SelectionRangesFeature } from './selection-ranges.ts';
 import { SemanticTokensFeature, type SemanticTokensOptions } from './semantic-tokens.ts';
 import { SignatureFeature } from './signature.ts';
 import { SnippetFeature } from './snippet-session.ts';
+import { SurroundFeature } from './surround.ts';
 import { SymbolsFeature } from './symbols.ts';
+import { TemplatesFeature } from './live-templates.ts';
 import type { Place } from './navigation-history.ts';
 import type { LanguageDocumentHandle, ProjectLanguage } from './project-language.ts';
 
@@ -75,6 +77,8 @@ export class EditorLanguage {
     readonly signature: SignatureFeature;
     readonly snippets: SnippetFeature;
     readonly markup: MarkupFeature;
+    readonly templates: TemplatesFeature;
+    readonly surround: SurroundFeature;
     readonly highlights: HighlightsFeature;
     readonly pick: PickFeature;
     readonly codeActions: CodeActionsFeature;
@@ -117,6 +121,8 @@ export class EditorLanguage {
         this.completion = new CompletionFeature(this, timers);
         this.snippets = new SnippetFeature(this, timers);
         this.markup = new MarkupFeature(this);
+        this.templates = new TemplatesFeature(this);
+        this.surround = new SurroundFeature(this);
         this.signature = new SignatureFeature(this, timers);
         this.highlights = new HighlightsFeature(this, timers);
         this.symbols = new SymbolsFeature(this, timers);

package/src/host-types.ts

@@ -6,6 +6,7 @@ import type { ClipboardHistory } from './clipboard-history.ts';
 import type { ProjectFiles } from './workspace-edit.ts';
 import type { Place } from './navigation-history.ts';
 import type { ProblemSource } from './project-problems.ts';
+import type { LiveTemplateDraft, TemplateRegistry } from './templates.ts';
 import type { ServerMessage } from '@adecore/lsp';
 
 export interface DiskText {
@@ -68,6 +69,12 @@ export interface LanguageHost {
     readonly keymap?: Keymap;
     /* What Paste from History lists. A new `ClipboardHistory` that lives as long as the project without one; pass one to choose its size or to keep its entries. */
     readonly clipboard?: ClipboardHistory;
+    /* What templates the editors of the project know. A registry of the built-in ones that lives as long as the project without one. */
+    readonly templates?: TemplateRegistry;
+    /* Save as Live Template: the host opens its own form with this draft. Without it the command does nothing. */
+    saveAsLiveTemplate?(draft: LiveTemplateDraft): void;
+    /* The last row of the template lists, "Configure live templates…"; the row is left out without it. */
+    openTemplateSettings?(): void;
     /* How many places Last Edit Location and Next Edit Location remember; 150 without one. */
     readonly editHistoryLimit?: number;
     /* The height in pixels of the list-and-preview area of the peek and the call hierarchy, so a person's drag outlives the panel; 180 without one. */

package/src/index.ts

@@ -66,6 +66,7 @@ export type {
     WrapView
 } from './popups.ts';
 export { type MarkupFeature } from './markup.ts';
+export { type SurroundFeature } from './surround.ts';
 export type { MarkupSettings } from './markup.ts';
 export { RowHost, LineActionHost } from './row-host.ts';
 export type { HostedRow, HostedAction } from './row-host.ts';
@@ -75,6 +76,21 @@ export type { Place } from './navigation-history.ts';
 export { EditLocations, type EditPlace } from './edit-locations.ts';
 export { ClipboardHistory, type ClipboardEntry, type ClipboardHistoryOptions } from './clipboard-history.ts';
 export { type PasteHistoryFeature } from './paste-history.ts';
+export {
+    TemplateRegistry,
+    checkTemplate,
+    BUILT_IN_LIVE_TEMPLATES,
+    BUILT_IN_POSTFIX_TEMPLATES,
+    type TemplatesFeature,
+    type LiveTemplate,
+    type PostfixTemplate,
+    type LiveTemplateDraft,
+    type TemplateLanguage,
+    type TemplatePlace,
+    type TemplateSettings,
+    type TemplateRegistryOptions,
+    type TemplateUpdate
+} from './templates.ts';
 export { openingPlace, viewStates, followViewStates, viewStateKey, forgetMovesFrom } from './view-state.ts';
 export type { ViewState, RevealLineRequest } from './view-state.ts';
 export { lspLanguageIdOf, shikiLanguageOf, shikiLanguageOfPath } from './language-ids.ts';

package/src/key-priority.ts

@@ -10,6 +10,8 @@ export const KEY_PRIORITY = {
     hover: 1400,
     completion: 1300,
     snippets: 1200,
+    // Between snippets and markup, so the spacing of a hundred bends here: Tab has to reach the templates after a running snippet and before Emmet.
+    templates: 1150,
     markup: 1100,
     signature: 1000,
     highlights: 900,