Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
style(comments): drop the personified register from the icon plugin
Elian Doranba4ebfb949df
diff --git a/packages/ckeditor5/src/plugins/inline_icon/inline_icon.spec.ts b/packages/ckeditor5/src/plugins/inline_icon/inline_icon.spec.tsindex dc7cf1a996..227e33de33 100644--- a/packages/ckeditor5/src/plugins/inline_icon/inline_icon.spec.ts+++ b/packages/ckeditor5/src/plugins/inline_icon/inline_icon.spec.ts@@ -97,9 +97,9 @@ describe("InlineIcon", () => {});describe("a reference link pasted from a rendered page", () => {- // The editing view draws a reference link with an icon inside it, so that is what lands on the- // clipboard. The icon is not the link's to carry — a reference holds no children — and it has- // to be dropped rather than split out to sit beside the link.+ // The editing view renders a reference link with an icon inside it, so that is what lands on+ // the clipboard. A reference takes no children, so the icon is dropped rather than split out+ // beside the link.it("loses the icon the renderer drew inside it, leaving the link alone", async () => {installGlobMock({getComponentByEl: () => ({ loadReferenceLinkTitle: () => Promise.resolve() }),@@ -151,7 +151,7 @@ describe("an icon's colour", () => {editor.execute("insertIcon", { iconClass: "bx bx-cog" });- // Inside the colour the text already wears, rather than beside it in a colour of its own.+ // Inside the colour the text already has, rather than beside it in a colour of its own.expect(editor.getData()).toBe(`<p><span style="color:rgb(255,0,0);">red`+ `<span class="tn-icon bx bx-cog"></span></span></p>`);});@@ -174,8 +174,8 @@ describe("an icon's size", () => {expect(editor.getData()).toBe(`<p>a<span class="text-big"><span class="tn-icon bx bx-cog"></span></span>b</p>`);- // A line sized as a whole stays one run. An icon the size cannot be put on splits it in- // two and is stranded between the halves at the size it started at.+ // A line sized as a whole stays one run. An icon that the size cannot apply to splits the+ // run in two and stays between the halves at its original size.editor.setData(`<p>a<span class="tn-icon bx bx-cog"></span>b</p>`);editor.model.change((writer) => {const root = editor.model.document.getRoot();@@ -223,7 +223,7 @@ describe("the balloon InlineIcon picks in", () => {expect(balloon.visibleView).not.toBeNull();expect(balloon.view.element?.contains(container)).toBe(true);// Everything a balloon shows sits inside the body collection's `ck-reset_all`, which would- // strip the application's own styling off the picker.+ // strip the application's own styling from the picker.expect(container.classList.contains("ck-reset_all-excluded")).toBe(true);});@@ -259,7 +259,7 @@ describe("the balloon InlineIcon picks in", () => {);pressChangeIcon(editor);- // The picker points at the icon rather than at a caret, since that is what is selected.+ // The picker points at the icon rather than at a caret, since the icon is what is selected.const { target } = editor.plugins.get(ContextualBalloon).getPositionOptions() ?? {};const at = typeof target === "function" ? target() : target;@@ -294,8 +294,8 @@ describe("the balloon InlineIcon picks in", () => {pressInsertIcon(editor);const container = showIconPicker.mock.calls[0][0].container;- // Esc reaches the editor only while the caret still has focus; once the picker has taken- // it, the balloon's own element is where the key lands.+ // Esc reaches the editor only while the caret has focus; once the picker has taken focus,+ // the key lands on the balloon's own element.container.dispatchEvent(escapeKeyDown());expect(release).toHaveBeenCalledOnce();expect(editor.plugins.get(ContextualBalloon).visibleView).toBeNull();@@ -333,8 +333,8 @@ describe("the balloon InlineIcon picks in", () => {});describe("where the balloon holding the picker ends up", () => {- // Real geometry needs the editor's own stylesheet, which the specs otherwise do without: it is- // what makes the balloon panel an absolutely positioned box the placing can move.+ // Real geometry needs the editor's own stylesheet, which the specs otherwise do without: it+ // makes the balloon panel an absolutely positioned box that repositioning can move.beforeAll(() => new Promise<void>((resolve, reject) => {const link = document.createElement("link");link.rel = "stylesheet";@@ -356,8 +356,8 @@ describe("where the balloon holding the picker ends up", () => {const balloon = editor.plugins.get(ContextualBalloon);const placedWhileEmpty = balloonRect(balloon).left;- // The observer delivers on a later frame, as it does for a host that paints through its- // own renderer rather than synchronously.+ // The observer fires on a later frame, as it does for a host that renders through its own+ // renderer rather than synchronously.await new Promise((resolve) => setTimeout(resolve, 100));const view = editor.editing.view;@@ -374,7 +374,7 @@ describe("where the balloon holding the picker ends up", () => {describe("InlineIcon under the shipped General HTML Support configuration", () => {// `textNoteHtmlSupportEnabled` ships off, which leaves GHS with an empty allow-list: a span- // carrying nothing but classes is dropped unless a plugin claims it.+ // with nothing but classes is dropped unless a plugin models it.it("keeps an icon that the plugin models, and loses one that nothing does", async () => {const withPlugin = await createTestEditor([ Paragraph, InlineIcon, GeneralHtmlSupport ], {htmlSupport: { allow: [] }@@ -411,10 +411,10 @@ function escapeKeyDown() {return new KeyboardEvent("keydown", { key: "Escape", keyCode: 27, bubbles: true });}-/** How wide the stand-in for the picker is, which the balloon has to be placed around. */+/** How wide the stand-in for the picker is, which the balloon is placed around. */const PAINTED_PICKER_WIDTH = 260;-/** A host that paints something the picker's size into the element the editor gives it. */+/** A host that renders something the picker's size into the element the editor passes it. */function installPaintingHost() {installGlobMock({getComponentByEl: () => ({@@ -438,7 +438,7 @@ function balloonRect(balloon: ContextualBalloon) {return element.getBoundingClientRect();}-/** Where the theme draws the arrow: centred for `arrow_n`/`arrow_s`, else 16px in from an edge. */+/** Where the theme puts the arrow: centred for `arrow_n`/`arrow_s`, else 16px in from an edge. */function arrowX(position: string | undefined, panel: DOMRect) {if (position?.endsWith("_nw") || position?.endsWith("_sw")) {return panel.left + 16;@@ -450,7 +450,7 @@ function arrowX(position: string | undefined, panel: DOMRect) {return panel.left + panel.width / 2;}-/** Puts the selection on the icon in the first paragraph, as clicking the widget would. */+/** Puts the selection on the icon in the first paragraph, as a click on the widget would. */function selectTheIcon(editor: ClassicEditor) {editor.model.change((writer) => {const paragraph = editor.model.document.getRoot()?.getChild(0);diff --git a/packages/ckeditor5/src/plugins/inline_icon/inline_icon_editing.ts b/packages/ckeditor5/src/plugins/inline_icon/inline_icon_editing.tsindex 0d8e9ff2f1..2e446760cc 100644--- a/packages/ckeditor5/src/plugins/inline_icon/inline_icon_editing.ts+++ b/packages/ckeditor5/src/plugins/inline_icon/inline_icon_editing.ts@@ -2,13 +2,13 @@ import {Command, type Editor, ModelElement, type ModelWriter, Plugin, toWidget, type ViewElement, Widget} from "ckeditor5";-/** The model element an icon is; it draws whatever {@link ICON_CLASS} names. */+/** The model element for an icon; the glyph comes from {@link ICON_CLASS}. */export const ICON = "inlineIcon";/** The icon pack's own class, such as `bx bx-star`. */const ICON_CLASS = "iconClass";-/** The class every icon in the app wears beside its pack's, and the one the upcast matches on. */+/** The class on every icon in the app, beside the pack's own, and what the upcast matches. */const MARKER_CLASS = "tn-icon";export const INSERT_ICON_COMMAND = "insertIcon";@@ -16,13 +16,13 @@ export const INSERT_ICON_COMMAND = "insertIcon";export const ICON_TRANSFORM_COMMAND = "iconTransform";/**- * The classes that turn or mirror a glyph, which the application already writes by hand — the right- * pane's icon is `bx bx-sidebar bx-flip-horizontal`. Boxicons names them, but the rules are not- * scoped to a pack, so they apply to any icon.+ * The classes that rotate or mirror a glyph. The application already writes them by hand — the+ * right pane's icon is `bx bx-sidebar bx-flip-horizontal` — and the rules in+ * `boxicons-compat.css` are not scoped to a pack, so they apply to any icon.*- * Each sets `transform`, so two never combine: whichever the stylesheet declares last wins. An icon- * therefore carries one of these or none, which is why {@link IconTransformCommand} holds a value- * rather than five independent flags.+ * Each rule sets `transform` at the same specificity, so two classes never combine: the one+ * declared last in the stylesheet applies. An icon therefore has one of these or none, which is+ * why {@link IconTransformCommand} stores a single value rather than five flags.*/export const ICON_TRANSFORMS = ["bx-rotate-90",@@ -35,11 +35,11 @@ export const ICON_TRANSFORMS = [export type IconTransform = typeof ICON_TRANSFORMS[number];/**- * The icon editing feature: an inline widget that stands for one icon of one installed icon pack,- * written as `<span class="tn-icon bx bx-star"></span>` — the form icons take everywhere else in- * the application, so the share theme and the in-app help draw it without knowing about the editor.+ * The icon editing feature: an inline widget for one icon of an installed icon pack, stored as+ * `<span class="tn-icon bx bx-star"></span>` — the markup icons use everywhere else in the+ * application, so the share theme and the in-app help render it with no editor-specific code.*- * Which icon to insert is the {@link InlineIconUI} plugin's business; this one only inserts it.+ * {@link InlineIconUI} provides the picker; this plugin only performs the insert.*/export default class InlineIconEditing extends Plugin {@@ -59,7 +59,7 @@ export default class InlineIconEditing extends Plugin {isInline: true,// Self-contained: the caret cannot be put inside it, and it is selected as a unit.isObject: true,- // Colouring needs no converter of ours; CKEditor's own carry these two.+ // CKEditor's own converters handle these two, so colouring needs none here.allowAttributes: [ ICON_CLASS, "fontColor", "fontBackgroundColor", "fontSize" ]});@@ -83,8 +83,8 @@ export default class InlineIconEditing extends Plugin {});editor.conversion.for("editingDowncast").elementToElement({- // Naming the attribute is what converts the element again when it changes, which is how- // a transform applied through the toolbar reaches the view.+ // Naming the attribute converts the element again when it changes, which is how a+ // transform set from the toolbar reaches the view.model: { name: ICON, attributes: [ ICON_CLASS ] },view: (modelElement, { writer }) => {const widget = toWidget(@@ -93,8 +93,8 @@ export default class InlineIconEditing extends Plugin {{ label: editor.t("Icon") });- // What InlineIconToolbar recognizes an icon by, since the widget's own element- // carries only the pack's classes.+ // How InlineIconToolbar identifies an icon: the widget element itself has only+ // the pack's classes.writer.setCustomProperty(ICON, true, widget);return widget;@@ -108,7 +108,7 @@ export default class InlineIconEditing extends Plugin {}/**- * Puts one icon where the selection is, replacing an icon that selection is already on. See+ * Inserts one icon at the selection, replacing an icon that selection is already on. See* {@link InlineIconEditing}.*/class InsertIconCommand extends Command {@@ -149,8 +149,8 @@ class InsertIconCommand extends Command {}/**- * Turns or mirrors the selected icon by rewriting the transform among its classes, of which- * {@link ICON_TRANSFORMS} explains there is at most one. `null` takes the icon back to upright.+ * Rotates or mirrors the selected icon by rewriting the transform among its classes, of which+ * there is at most one (see {@link ICON_TRANSFORMS}). `null` restores the icon to upright.*/class IconTransformCommand extends Command {@@ -184,14 +184,14 @@ class IconTransformCommand extends Command {}-/** The pack's classes, which is everything the element wears apart from {@link MARKER_CLASS}. */+/** The pack's classes: every class on the element apart from {@link MARKER_CLASS}. */function readIconClass(viewElement: ViewElement) {return Array.from(viewElement.getClassNames()).filter((className) => className !== MARKER_CLASS).join(" ");}-/** What the element wears in the view: the marker class, then the pack's own. */+/** The classes the element gets in the view: the marker class, then the pack's own. */function viewClasses(modelElement: ModelElement) {const iconClass = modelElement.getAttribute(ICON_CLASS);@@ -205,7 +205,7 @@ function selectedIcon(editor: Editor) {return selected?.is("element", ICON) ? selected : null;}-/** The transform an icon carries, or `null` where it is upright. */+/** The transform class on an icon, or `null` where it is upright. */function readTransform(icon: ModelElement): IconTransform | null {return readClasses(icon).find(isTransform) ?? null;}diff --git a/packages/ckeditor5/src/plugins/inline_icon/inline_icon_toolbar.spec.ts b/packages/ckeditor5/src/plugins/inline_icon/inline_icon_toolbar.spec.tsindex cb1601f98f..5c9cb44b2b 100644--- a/packages/ckeditor5/src/plugins/inline_icon/inline_icon_toolbar.spec.ts+++ b/packages/ckeditor5/src/plugins/inline_icon/inline_icon_toolbar.spec.ts@@ -9,7 +9,7 @@ import { createTestEditor } from "../../../test/editor-kit.js";import InlineIcon from "./inline_icon.js";import InlineIconToolbar from "./inline_icon_toolbar.js";-/** The shape of the repository's private register, which is where a definition can be read back. */+/** The shape of the repository's private register, where a definition can be read back. */interface ToolbarDefinitions {_toolbarDefinitions: Map<string, {itemsConfig: string[];@@ -24,7 +24,7 @@ describe("InlineIconToolbar", () => {editor = await createTestEditor([ Paragraph, InlineIcon ]);});- /** Puts one icon in the text and selects it, which is what the toolbar answers to. */+ /** Puts one icon in the text and selects it, which is what the toolbar responds to. */function selectIcon(iconClass: string) {setModelData(editor.model,@@ -32,7 +32,7 @@ describe("InlineIconToolbar", () => {);}- /** What the note holds for that icon, which is where a transform ends up. */+ /** What the note stores for that icon, which is where a transform ends up. */function storedIcon(iconClass: string) {return `<p>Press <span class="tn-icon ${iconClass}"></span></p>`;}@@ -54,7 +54,7 @@ describe("InlineIconToolbar", () => {return dropdown;}- /** The list's buttons, which carry the labels and the mark on the transform in force. */+ /** The list's buttons, with the labels and the mark on the transform in force. */function transformButtons(dropdown: DropdownView) {return Array.from(dropdown.listView?.items ?? []).filter((item): item is ListItemView => item instanceof ListItemView)@@ -105,8 +105,8 @@ describe("InlineIconToolbar", () => {editor.execute("iconTransform", { transform: "bx-flip-horizontal" });expect(editor.getData()).toBe(storedIcon("bx bx-sidebar bx-flip-horizontal"));- // One transform replaces another rather than joining it: the two would fight over- // `transform` in the stylesheet.+ // One transform replaces another rather than joining it: both set `transform` in the+ // stylesheet, so only the rule declared last would apply.editor.execute("iconTransform", { transform: "bx-rotate-90" });expect(editor.getData()).toBe(storedIcon("bx bx-sidebar bx-rotate-90"));diff --git a/packages/ckeditor5/src/plugins/inline_icon/inline_icon_toolbar.ts b/packages/ckeditor5/src/plugins/inline_icon/inline_icon_toolbar.tsindex dd6f5e2386..6403032e9f 100644--- a/packages/ckeditor5/src/plugins/inline_icon/inline_icon_toolbar.ts+++ b/packages/ckeditor5/src/plugins/inline_icon/inline_icon_toolbar.ts@@ -72,12 +72,12 @@ export default class InlineIconToolbar extends Plugin {}-/** A list item's model, which carries the transform its button stands for. */+/** A list item's model; `_iconTransform` is the transform its button applies. */interface TransformItemModel {_iconTransform: IconTransform | null;}-/** What the dropdown offers: upright, then each transform {@link ICON_TRANSFORMS} names. */+/** The dropdown's items: upright, then each transform in {@link ICON_TRANSFORMS}. */function transformItems(command: Command, t: LocaleTranslate) {const labels: Record<IconTransform, string> = {"bx-rotate-90": t("Rotate 90°"),@@ -100,8 +100,8 @@ function transformItems(command: Command, t: LocaleTranslate) {}/**- * One choice, marked while the selected icon carries it. They are radio items rather than- * checkboxes because the transforms exclude one another (see {@link ICON_TRANSFORMS}).+ * One choice, marked while the selected icon has that transform. They are radio items rather+ * than checkboxes because the transforms exclude one another (see {@link ICON_TRANSFORMS}).*/function transformItem(command: Command,diff --git a/packages/ckeditor5/src/plugins/inline_icon/inline_icon_ui.ts b/packages/ckeditor5/src/plugins/inline_icon/inline_icon_ui.tsindex 0a3a5206ed..f415bd7314 100644--- a/packages/ckeditor5/src/plugins/inline_icon/inline_icon_ui.ts+++ b/packages/ckeditor5/src/plugins/inline_icon/inline_icon_ui.ts@@ -13,12 +13,11 @@ import { INSERT_ICON_COMMAND } from "./inline_icon_editing.js";export const CHANGE_ICON = "changeIcon";/**- * The buttons an icon is inserted or swapped through, and the balloon the picking happens in.+ * The buttons that insert or replace an icon, and the balloon the picking happens in.*- * The editor owns the balloon — where it points, when it goes away — and the application paints its- * own picker into it through `showIconPicker`, which is the one place every installed icon pack is- * searchable. A host with no room for a balloon shows the picker its own way and answers with- * nothing to take down.+ * The editor positions the balloon and takes it down; the application renders its own picker into+ * it through `showIconPicker`, the one place every installed icon pack is searchable. A host with+ * no room for a balloon shows the picker its own way and returns nothing to release.*/export default class InlineIconUI extends Plugin {@@ -43,8 +42,8 @@ export default class InlineIconUI extends Plugin {this.addPickerButton(INSERT_ICON_COMMAND, t("Insert icon"));this.addPickerButton(CHANGE_ICON, t("Change icon"));- // Esc reaches the editor only while the caret still has focus; the picker takes focus with- // it, so the view carries a handler of its own (see {@link IconPickerView}).+ // Esc reaches the editor only while the caret has focus, and the picker takes focus away,+ // so {@link IconPickerView} registers a handler of its own.editor.keystrokes.set("Esc", (_data, cancel) => {if (this._pickerView) {this._hide();@@ -59,7 +58,7 @@ export default class InlineIconUI extends Plugin {super.destroy();}- /** Opens the picker, which the `/` palette asks for as well as the toolbar button. */+ /** Opens the picker; the `/` palette calls this as well as the toolbar buttons. */public showPicker() {const editor = this.editor;const editorEl = editor.editing.view.getDomRoot();@@ -77,7 +76,7 @@ export default class InlineIconUI extends Plugin {});// Wired per picker rather than once: the handler listens through the view, so destroying- // the view on the way out is what stops it listening.+ // the view on the way out stops it.clickOutsideHandler({emitter: view,activator: () => this._pickerView === view,@@ -112,16 +111,16 @@ export default class InlineIconUI extends Plugin {this._releasePicker = release;- // The host paints into the container only once the call above has returned, and a balloon- // placed while it is still empty puts its arrow half the picker's width away from the- // caret. Place it again whenever what it holds changes size, which a narrowed grid needs- // as much as the first paint does. The placing waits for the next frame: it can itself- // change the width the container is given, and Chrome reports that as an observer loop.+ // The host renders into the container only after the call above returns, and a balloon+ // placed around an empty container puts its arrow half the picker's width from the caret.+ // Reposition on every size change, not just the first render. The reposition waits for the+ // next frame because it can change the container's width, which Chrome reports as an+ // observer loop.this._pickerResize = new ResizeObserver(() => {cancelAnimationFrame(this._replacePicker);this._replacePicker = requestAnimationFrame(() => {- /* v8 ignore next -- disconnecting takes the pending frames with it */+ /* v8 ignore next -- disconnecting the observer cancels the pending frames */if (this._pickerView) {this._balloon.updatePosition();}@@ -170,7 +169,7 @@ export default class InlineIconUI extends Plugin {return;}- /* v8 ignore next -- a picker this plugin still holds is one the balloon has */+ /* v8 ignore next -- a picker this plugin still references is one the balloon still has */if (this._balloon.hasView(view)) {this._balloon.remove(view);}@@ -181,10 +180,10 @@ export default class InlineIconUI extends Plugin {}/**- * What the balloon holds: an element for the host to paint into, and nothing else.+ * The view inside the balloon: an element for the host to render into, and nothing else.*- * It carries `ck-reset_all-excluded` because everything a balloon shows sits inside the body- * collection's `ck-reset_all`, which would strip the application's own styling off the picker.+ * It has `ck-reset_all-excluded` because everything a balloon shows sits inside the body+ * collection's `ck-reset_all`, which would strip the application's own styling from the picker.*/class IconPickerView extends View {@@ -219,13 +218,13 @@ class IconPickerView extends View {}-/** Where the balloon points: the caret, read afresh on every placing, as the emoji picker does. */+/** Where the balloon points: the caret, read again on every placement, as the emoji picker does. */function getBalloonPosition(editor: Editor, shownAt: ViewRange) {const view = editor.editing.view;return {target: () => {- /* v8 ignore next -- a rendered document always holds a range for the caret */+ /* v8 ignore next -- a rendered document always has a range for the caret */const range = view.document.selection.getFirstRange() ?? shownAt;return view.domConverter.viewRangeToDom(range);