Skip to content

Build your personal knowledge base with Trilium Notes

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.ts
index 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.ts
index 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.ts
index 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&nbsp;<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.ts
index 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.ts
index 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);