@olddevs/ui 4.6.0 → 4.6.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +8 -0
- package/docs/api/editor-extension.en.md +15 -15
- package/docs/api/migration-notes.en.md +8 -8
- package/docs/api/utilities.en.md +6 -6
- package/docs/components/actions/split-button.en.md +9 -9
- package/docs/components/content/data-display.en.md +1 -1
- package/docs/components/content/layout-primitives.en.md +3 -3
- package/docs/components/content/rich-text-toc.en.md +1 -1
- package/docs/components/content/rich-text-view.en.md +12 -12
- package/docs/components/content/virtual-grid.en.md +2 -2
- package/docs/components/date-time/date-picker.en.md +1 -1
- package/docs/components/inputs/rich-text-editor.en.md +159 -159
- package/docs/components/navigation/mega-menu.en.md +10 -10
- package/docs/components/overlays/menu.en.md +2 -2
- package/docs/components/overlays/shortcuts-help.en.md +1 -1
- package/docs/components/table/data-table.en.md +3 -3
- package/docs/components/table/filter-bar.en.md +1 -1
- package/docs/components/table/toolbar.en.md +1 -1
- package/docs/glossary.en.md +184 -152
- package/docs/glossary.md +182 -151
- package/docs/icons.en.md +9 -9
- package/docs/palette.en.md +3 -3
- package/docs/theming.en.md +6 -6
- package/package.json +1 -1
package/docs/glossary.en.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
sourceHash:
|
|
2
|
+
sourceHash: 6a5aa1851689
|
|
3
3
|
---
|
|
4
4
|
|
|
5
5
|
# Glossary of `@olddevs/ui`
|
|
@@ -9,6 +9,34 @@ library) introduces a second meaning, and the two drift apart silently. If a wor
|
|
|
9
9
|
meanings, both get compound names ("palette primitive", "overlay layer"), and the bare word stays
|
|
10
10
|
with one of them.
|
|
11
11
|
|
|
12
|
+
A concept that came from the industry is called by the word of its origin: the Tiptap engine,
|
|
13
|
+
WAI-ARIA, React Aria, Radix, Material 3, Storybook, Node.js. The English term is taken from there,
|
|
14
|
+
and the Russian one is translated from the English, not the other way around: translating back from
|
|
15
|
+
Russian returns a different word, and the reader cannot find the concept by searching. The kit
|
|
16
|
+
coins its own name only for a concept that the industry has no name for.
|
|
17
|
+
|
|
18
|
+
Every table has two columns for this rule. "Source" is where the English word comes from: the
|
|
19
|
+
origin, "common" (an ordinary industry word with no single owner) or "own" (the kit's name). "Also
|
|
20
|
+
searched as" lists the words other systems use for the same concept: they help a search find the
|
|
21
|
+
row, and they are not used in prose.
|
|
22
|
+
|
|
23
|
+
A public name (a prop, a function, a type) comes from the English term. Renaming follows semver
|
|
24
|
+
(the "Versions" section of the kit's `AGENTS.md`): the new name arrives as an alias in a minor
|
|
25
|
+
version, and the old one is marked `@deprecated` and removed in the next major version.
|
|
26
|
+
|
|
27
|
+
Origins: [Tiptap](https://tiptap.dev/docs), [ProseMirror](https://prosemirror.net/docs/guide/),
|
|
28
|
+
[WAI-ARIA APG](https://www.w3.org/WAI/ARIA/apg/), [React Aria](https://react-spectrum.adobe.com/react-aria/),
|
|
29
|
+
[Radix](https://www.radix-ui.com), [M3](https://m3.material.io),
|
|
30
|
+
[DTCG](https://www.designtokens.org) (the W3C token format), [Storybook](https://storybook.js.org),
|
|
31
|
+
[Chromatic](https://www.chromatic.com/docs/), [Node.js](https://nodejs.org/api/packages.html),
|
|
32
|
+
[MDN](https://developer.mozilla.org), [BlockNote](https://www.blocknotejs.org),
|
|
33
|
+
[Carbon](https://carbondesignsystem.com), [MUI](https://mui.com), [Polaris](https://polaris.shopify.com),
|
|
34
|
+
[Apple HIG](https://developer.apple.com/design/human-interface-guidelines/),
|
|
35
|
+
[CKEditor](https://ckeditor.com/docs/ckeditor5/latest/features/source-editing.html),
|
|
36
|
+
[Astro](https://docs.astro.build/en/concepts/islands/),
|
|
37
|
+
[text-mask](https://github.com/text-mask/text-mask/blob/master/componentDocumentation.md#guide),
|
|
38
|
+
[Ben Kamens](https://bjk5.com/post/44698559168/breaking-down-amazons-mega-dropdown) (menu aim).
|
|
39
|
+
|
|
12
40
|
General terms are written in prose as ordinary words, lowercase: "consumer", "role", "showcase".
|
|
13
41
|
Editor terms are capitalized ("Block", "Toolbar"): they are easy to confuse with an everyday word,
|
|
14
42
|
and the capital letter shows that the word means exactly what the table says.
|
|
@@ -22,60 +50,60 @@ Prop names are a separate vocabulary:
|
|
|
22
50
|
|
|
23
51
|
## Kit and consumer
|
|
24
52
|
|
|
25
|
-
| Term | Meaning | Not to be confused with |
|
|
26
|
-
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
27
|
-
| **kit** | The `@olddevs/ui` design system: tokens, themes, accessible components and their documentation | The package: that is how the kit is delivered. A library: the kit is not called that, the word is taken by third-party dependencies (react-aria, Radix, Tiptap) |
|
|
28
|
-
| **package** | The `@olddevs/ui` npm artifact with entry points and `styles.css`; published to npm | The kit: one kit has one package, but the kit is also its decisions, the showcase and the design mockup |
|
|
29
|
-
| **entry point** | An import path that the package declares in `exports`: `@olddevs/ui`, `/icons`, `/color`, `/editor`, `/editor/schema`, `/editor/highlight`, `/locales/ru`, `/locales/en`. Anything that is not an entry point is not public API | A path in `src/`: it can change in any version |
|
|
30
|
-
| **public contract** | The exports of the entry points, their types, the documented behavior and `styles.css` | The sources: they prove behavior, but cannot be imported |
|
|
31
|
-
| **consumer** | An application that installs the package and builds its screens from the kit | A user: they work with a screen, not with the API |
|
|
32
|
-
| **screen** | A page or form of the consumer's application. Domain texts, requests, status vocabularies and the screen layout belong to it, not to the kit | A kit component |
|
|
33
|
-
| **requesting screen** | A consumer screen that needs the component now. A component without one is not taken on, except where ADR-0048 allows it | The consumer: that is the whole application, while the requesting screen is one of its screens |
|
|
34
|
-
| **primitive** | A kit component that other components and consumer screens are built from: `Toolbar` is the primitive of the Editor's Toolbar. Not replaced by hand-written markup | A palette primitive: a color token of layer 1 |
|
|
35
|
-
| **component family** | Components with one purpose and shared exports (`MobileTabBar` and `MobileTabBarItem`), described on one Reference page | A color
|
|
36
|
-
| **category** | A section of the Reference and a source folder: `actions`, `app-shell`, `content`, `date-time`, `inputs`, `navigation`, `overlays`, `table`. A component lives in the same category in `docs/components/` and in `src/components/` | A component family: a category groups several families |
|
|
37
|
-
| **core** | Components that require the full set of checks: behavioral tests, class coverage, axe, snapshots (ADR-0014) | The periphery |
|
|
38
|
-
| **periphery** | Wrappers over the ready-made behavior of `react-aria-components`: a reduced set of checks is enough for them | The core |
|
|
39
|
-
| **message catalog** | The kit's interface strings that `UiProvider` passes to components: the ready-made catalogs are the `locales/ru` and `locales/en` entry points; without the provider, an English fallback in code applies. A component prop overrides a string individually ([i18n.md](i18n.md)) | The component catalog. Screen texts: the kit does not translate them |
|
|
40
|
-
| **component catalog** | An index of all public components by category — [components/index.md](components/index.md) | The message catalog |
|
|
53
|
+
| Term | Meaning | Not to be confused with | Source | Also searched as |
|
|
54
|
+
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ---------------------------------------- |
|
|
55
|
+
| **kit** | The `@olddevs/ui` design system: tokens, themes, accessible components and their documentation | The package: that is how the kit is delivered. A library: the kit is not called that, the word is taken by third-party dependencies (react-aria, Radix, Tiptap) | common | UI kit, design system, component library |
|
|
56
|
+
| **package** | The `@olddevs/ui` npm artifact with entry points and `styles.css`; published to npm | The kit: one kit has one package, but the kit is also its decisions, the showcase and the design mockup | npm | — |
|
|
57
|
+
| **entry point** | An import path that the package declares in `exports`: `@olddevs/ui`, `/icons`, `/color`, `/editor`, `/editor/schema`, `/editor/highlight`, `/locales/ru`, `/locales/en`. Anything that is not an entry point is not public API | A path in `src/`: it can change in any version | Node.js | subpath export |
|
|
58
|
+
| **public contract** | The exports of the entry points, their types, the documented behavior and `styles.css` | The sources: they prove behavior, but cannot be imported | semver | public API |
|
|
59
|
+
| **consumer** | An application that installs the package and builds its screens from the kit | A user: they work with a screen, not with the API | common | library user |
|
|
60
|
+
| **screen** | A page or form of the consumer's application. Domain texts, requests, status vocabularies and the screen layout belong to it, not to the kit | A kit component | own | page, view |
|
|
61
|
+
| **requesting screen** | A consumer screen that needs the component now. A component without one is not taken on, except where ADR-0048 allows it | The consumer: that is the whole application, while the requesting screen is one of its screens | own | — |
|
|
62
|
+
| **primitive** | A kit component that other components and consumer screens are built from: `Toolbar` is the primitive of the Editor's Toolbar. Not replaced by hand-written markup | A palette primitive: a color token of layer 1 | Radix | building block |
|
|
63
|
+
| **component family** | Components with one purpose and shared exports (`MobileTabBar` and `MobileTabBarItem`), described on one Reference page | A color scale: a row of palette primitives of one hue | own | compound component |
|
|
64
|
+
| **category** | A section of the Reference and a source folder: `actions`, `app-shell`, `content`, `date-time`, `inputs`, `navigation`, `overlays`, `table`. A component lives in the same category in `docs/components/` and in `src/components/` | A component family: a category groups several families | own | — |
|
|
65
|
+
| **core** | Components that require the full set of checks: behavioral tests, class coverage, axe, snapshots (ADR-0014) | The periphery | own | — |
|
|
66
|
+
| **periphery** | Wrappers over the ready-made behavior of `react-aria-components`: a reduced set of checks is enough for them | The core | own | — |
|
|
67
|
+
| **message catalog** | The kit's interface strings that `UiProvider` passes to components: the ready-made catalogs are the `locales/ru` and `locales/en` entry points; without the provider, an English fallback in code applies. A component prop overrides a string individually ([i18n.md](i18n.md)) | The component catalog. Screen texts: the kit does not translate them | common | locale messages, translations |
|
|
68
|
+
| **component catalog** | An index of all public components by category — [components/index.md](components/index.md) | The message catalog | own | component index |
|
|
41
69
|
|
|
42
70
|
## Documentation and checks
|
|
43
71
|
|
|
44
|
-
| Term | Meaning | Not to be confused with |
|
|
45
|
-
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
46
|
-
| **the Reference** | Markdown in the package's `docs/`: component, API and convention pages — the source of truth about the public contract. Ships in the package and is shown on the site as is | The wiki: it retells the Reference for people and is wrong when they disagree. ADRs: they explain why a decision was made |
|
|
47
|
-
| **showcase** | The kit's Storybook: stories, snapshots and accessibility checks; published to GitHub Pages | The documentation site: the showcase is a workshop, not text for a reader. The flyout of a mega menu |
|
|
48
|
-
| **snapshot** | A reference image of a showcase story in `tests-visual/`; taken and compared only locally (ADR-0013) | A screenshot for documentation: it checks nothing |
|
|
49
|
-
| **gate** | One automatic check that fails the run: the contrast gate (`npm run contrast`), the i18n gate, `format:check` | The release checklist: a gate is one check from its list |
|
|
50
|
-
| **release checklist** | The full list of checks before a merge and a release — the "Checks" section of `AGENTS.md`. Run locally: CI does not check pushes | A GitHub Actions workflow: it publishes the showcase and the package, but checks nothing |
|
|
51
|
-
| **mirror** | The Figma file `Olddevs UI DS`: mirrors the kit but is not the source of truth; when they differ, Figma is changed (ADR-0015) | A mockup that code is written from: the only exception is a component that does not exist in code yet |
|
|
52
|
-
| **wave** | A set of changes that was planned and released together; ADRs and comments refer to the wave number | A package version: the wave number is unrelated to the release number |
|
|
72
|
+
| Term | Meaning | Not to be confused with | Source | Also searched as |
|
|
73
|
+
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------- | ---------------------------- |
|
|
74
|
+
| **the Reference** | Markdown in the package's `docs/`: component, API and convention pages — the source of truth about the public contract. Ships in the package and is shown on the site as is | The wiki: it retells the Reference for people and is wrong when they disagree. ADRs: they explain why a decision was made | common | API reference |
|
|
75
|
+
| **showcase** | The kit's Storybook: stories, snapshots and accessibility checks; published to GitHub Pages | The documentation site: the showcase is a workshop, not text for a reader. The flyout of a mega menu | Storybook | Storybook, workshop |
|
|
76
|
+
| **snapshot** | A reference image of a showcase story in `tests-visual/`; taken and compared only locally (ADR-0013) | A screenshot for documentation: it checks nothing | Chromatic | visual regression test |
|
|
77
|
+
| **gate** | One automatic check that fails the run: the contrast gate (`npm run contrast`), the i18n gate, `format:check` | The release checklist: a gate is one check from its list | common | quality gate, required check |
|
|
78
|
+
| **release checklist** | The full list of checks before a merge and a release — the "Checks" section of `AGENTS.md`. Run locally: CI does not check pushes | A GitHub Actions workflow: it publishes the showcase and the package, but checks nothing | own | — |
|
|
79
|
+
| **mirror** | The Figma file `Olddevs UI DS`: mirrors the kit but is not the source of truth; when they differ, Figma is changed (ADR-0015) | A mockup that code is written from: the only exception is a component that does not exist in code yet | own | Figma library |
|
|
80
|
+
| **wave** | A set of changes that was planned and released together; ADRs and comments refer to the wave number | A package version: the wave number is unrelated to the release number | own | milestone |
|
|
53
81
|
|
|
54
82
|
## Tokens and themes
|
|
55
83
|
|
|
56
|
-
| Term | Meaning | Not to be confused with |
|
|
57
|
-
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
|
58
|
-
| **token layer** | One of the four steps of the color chain: palette primitives → roles → component tokens → brand. A lower layer knows nothing about a higher one ([theming.md](theming.md#четыре-слоя)) | An overlay layer: a z-index step |
|
|
59
|
-
| **palette primitive** | A layer 1 token `--od-<family>-<step>`: a color as a value, with no role and no theme. The consumer does not override it | A primitive: a kit component |
|
|
60
|
-
| **color
|
|
61
|
-
| **role** | A layer 2 token: what is painted with what — `--surface-*`, `--text-*`, `--accent*`, tones. A theme changes only roles | A Tailwind class: it is built on a role, not the other way round |
|
|
62
|
-
| **component token** | A layer 3 token — how one component family differs from the shared role (`--overlay-scrim`, `--topbar-bg`). The list is closed | A role |
|
|
63
|
-
| **theme** | A set of role values on `<html data-theme>`: `dark` (default), `light`, `dim` | An accent: it is an independent axis. The Editor's Paper |
|
|
64
|
-
| **accent** | The color of action and highlight on `<html data-accent>`: `blue` (default), `violet` | The `accent` tone: it takes the accent's value, but it is a component axis |
|
|
65
|
-
| **brand** | Layer 4: a brand block `[data-brand]` on top of roles and component tokens — the consumer's own palette as a single CSS block | A theme: a brand works in any theme |
|
|
66
|
-
| **surface** | A background role: `--surface-app`, `--surface-panel`, `--surface-elevated` and the related roles; in components, the aliases `--bg-0…4` | The Editor's `surface` prop: it chooses the Paper |
|
|
67
|
-
| **inverse surface** | A group of roles for a pill placed directly on a Document that differs from it by polarity, not by a single step: light in `dark` and `dim`, dark in `light` (`--surface-inverse`, `--text-on-inverse`) | The `--surface-contrast` surface: it is a step of the same theme |
|
|
68
|
-
| **tone** | A semantic color from the `Tone` vocabulary: `neutral`, `accent`, `success`, `warning`, `danger`. A tone has two roles: `--<tone>` is the fill under text, `--<tone>-strong` is text and border on a background | A variant (`variant`): it controls how prominent the tone is |
|
|
69
|
-
| **density** | The default vertical rhythm of tables through `UiProvider`: `comfortable` or `compact`; a table prop overrides it | A size (`size`): it is the axis of one component |
|
|
70
|
-
| **motion scale** | Closed duration steps (`--duration-fast` … `--duration-slow`) and three curves (`--ease-standard`, `-enter`, `-exit`). Names by role, not by value (ADR-0047) | A step of a color
|
|
84
|
+
| Term | Meaning | Not to be confused with | Source | Also searched as |
|
|
85
|
+
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ------- | -------------------------------- |
|
|
86
|
+
| **token layer** | One of the four steps of the color chain: palette primitives → roles → component tokens → brand. A lower layer knows nothing about a higher one ([theming.md](theming.md#четыре-слоя)) | An overlay layer: a z-index step | DTCG | token tier |
|
|
87
|
+
| **palette primitive** | A layer 1 token `--od-<family>-<step>`: a color as a value, with no role and no theme. The consumer does not override it | A primitive: a kit component | DTCG | primitive token, base token |
|
|
88
|
+
| **color scale** | A row of palette primitives of one hue: the neutrals `slate`, `cloud`, `navy` and seven tone scales. Within a scale the step number increases with lightness; 1 is the darkest | A component family | Radix | color family, color ramp |
|
|
89
|
+
| **role** | A layer 2 token: what is painted with what — `--surface-*`, `--text-*`, `--accent*`, tones. A theme changes only roles | A Tailwind class: it is built on a role, not the other way round | M3 | color role, semantic token |
|
|
90
|
+
| **component token** | A layer 3 token — how one component family differs from the shared role (`--overlay-scrim`, `--topbar-bg`). The list is closed | A role | DTCG | — |
|
|
91
|
+
| **theme** | A set of role values on `<html data-theme>`: `dark` (default), `light`, `dim` | An accent: it is an independent axis. The Editor's Paper | common | color scheme, appearance (Radix) |
|
|
92
|
+
| **accent** | The color of action and highlight on `<html data-accent>`: `blue` (default), `violet` | The `accent` tone: it takes the accent's value, but it is a component axis | Radix | accent color |
|
|
93
|
+
| **brand** | Layer 4: a brand block `[data-brand]` on top of roles and component tokens — the consumer's own palette as a single CSS block | A theme: a brand works in any theme | own | — |
|
|
94
|
+
| **surface** | A background role: `--surface-app`, `--surface-panel`, `--surface-elevated` and the related roles; in components, the aliases `--bg-0…4` | The Editor's `surface` prop: it chooses the Paper | M3 | — |
|
|
95
|
+
| **inverse surface** | A group of roles for a pill placed directly on a Document that differs from it by polarity, not by a single step: light in `dark` and `dim`, dark in `light` (`--surface-inverse`, `--text-on-inverse`) | The `--surface-contrast` surface: it is a step of the same theme | M3 | — |
|
|
96
|
+
| **tone** | A semantic color from the `Tone` vocabulary: `neutral`, `accent`, `success`, `warning`, `danger`. A tone has two roles: `--<tone>` is the fill under text, `--<tone>-strong` is text and border on a background | A variant (`variant`): it controls how prominent the tone is | Polaris | status color, intent |
|
|
97
|
+
| **density** | The default vertical rhythm of tables through `UiProvider`: `comfortable` or `compact`; a table prop overrides it | A size (`size`): it is the axis of one component | MUI | compact mode |
|
|
98
|
+
| **motion scale** | Closed duration steps (`--duration-fast` … `--duration-slow`) and three curves (`--ease-standard`, `-enter`, `-exit`). Names by role, not by value (ADR-0047) | A step of a color scale | M3 | motion tokens, duration, easing |
|
|
71
99
|
|
|
72
100
|
## Prop axes
|
|
73
101
|
|
|
74
|
-
| Term | Meaning | Not to be confused with |
|
|
75
|
-
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
|
|
76
|
-
| **axis** | An independent prop with a closed set of values shared across the whole kit: `size`, `tone`, `variant`. An axis is turned on by an explicit prop | A state (`selected`, `disabled`, `loading`): it is boolean and named positively |
|
|
77
|
-
| **variant** | The `variant` axis: how prominent the tone is — `solid`, `soft`, `outline`, `ghost`, one set across the kit | The appearance (`appearance`) |
|
|
78
|
-
| **appearance** | The `appearance` prop, outside the axes: a different form of the same component — `appearance="card"` adds a border, an indicator and a description inside the label | The variant: it changes how prominent the tone is, not the form |
|
|
102
|
+
| Term | Meaning | Not to be confused with | Source | Also searched as |
|
|
103
|
+
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------ | ---------------- |
|
|
104
|
+
| **axis** | An independent prop with a closed set of values shared across the whole kit: `size`, `tone`, `variant`. An axis is turned on by an explicit prop | A state (`selected`, `disabled`, `loading`): it is boolean and named positively | own | — |
|
|
105
|
+
| **variant** | The `variant` axis: how prominent the tone is — `solid`, `soft`, `outline`, `ghost`, one set across the kit | The appearance (`appearance`) | Radix | — |
|
|
106
|
+
| **appearance** | The `appearance` prop, outside the axes: a different form of the same component — `appearance="card"` adds a border, an indicator and a description inside the label | The variant: it changes how prominent the tone is, not the form | own | — |
|
|
79
107
|
|
|
80
108
|
The meaning of each axis and the props outside the axes (`appearance`, `active`, `level`) are in the
|
|
81
109
|
[semantic prop vocabulary](conventions.md#семантический-словарь-пропсов).
|
|
@@ -84,51 +112,52 @@ The meaning of each axis and the props outside the axes (`appearance`, `active`,
|
|
|
84
112
|
|
|
85
113
|
The words pages use to describe how a component is operated with a mouse, a finger and the keyboard.
|
|
86
114
|
|
|
87
|
-
| Term | Meaning | Not to be confused with
|
|
88
|
-
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
89
|
-
| **hit area** | The area that accepts a press; it can be larger than the visible control. The lower bound is WCAG 2.5.8, 24 × 24 px | Size (`size`): it changes the look, while the hit area can stay the same
|
|
90
|
-
| **drag handle** | A separate button on a row that moves the row with a mouse, a finger or the keyboard: `SortableList`, `EditableList` | The Editor's Block handle and the resize handle
|
|
91
|
-
| **resize handle** | The strip along the bottom edge of a field with `resizable` that changes its height; from the keyboard it works like a slider | The drag handle
|
|
92
|
-
| **mask guide** | The mask that an empty `MaskedInput` shows in full (`__.__.____`) and that input replaces character by character. Decorative: `aria-hidden` | The Editor's Skeleton: the look of the field before Readiness
|
|
93
|
-
| **item** | One entry of `items` in a collection component: a menu item, a list row, a tree node | A DOM element: write "element" only for markup
|
|
94
|
-
| **disabled** | The `disabled` state: the action cannot be performed now, the control is dimmed and presses do nothing | Read-only (`readOnly`): the value is visible and can be copied, but not changed
|
|
95
|
-
| **
|
|
96
|
-
| **selection** | The records the user has checked (`selectedKeys`) | The
|
|
115
|
+
| Term | Meaning | Not to be confused with | Source | Also searched as |
|
|
116
|
+
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------- | ---------------------------- |
|
|
117
|
+
| **hit area** | The area that accepts a press; it can be larger than the visible control. The lower bound is WCAG 2.5.8, 24 × 24 px | Size (`size`): it changes the look, while the hit area can stay the same | common | touch target, target size |
|
|
118
|
+
| **drag handle** | A separate button on a row that moves the row with a mouse, a finger or the keyboard: `SortableList`, `EditableList` | The Editor's Block handle and the resize handle | common | grip |
|
|
119
|
+
| **resize handle** | The strip along the bottom edge of a field with `resizable` that changes its height; from the keyboard it works like a slider | The drag handle | common | — |
|
|
120
|
+
| **mask guide** | The mask that an empty `MaskedInput` shows in full (`__.__.____`) and that input replaces character by character. Decorative: `aria-hidden` | The Editor's Skeleton: the look of the field before Readiness | text-mask | mask placeholder |
|
|
121
|
+
| **item** | One entry of `items` in a collection component: a menu item, a list row, a tree node | A DOM element: write "element" only for markup | React Aria | — |
|
|
122
|
+
| **disabled** | The `disabled` state: the action cannot be performed now, the control is dimmed and presses do nothing | Read-only (`readOnly`): the value is visible and can be copied, but not changed | MDN | — |
|
|
123
|
+
| **filtered rows** | The records left after the filters; the consumer computes it | The selection | common | result set, filtered results |
|
|
124
|
+
| **selection** | The records the user has checked (`selectedKeys`) | The filtered rows: a filter narrows the filtered rows, the selection is what is checked inside it | React Aria | — |
|
|
97
125
|
|
|
98
126
|
## Layers on top
|
|
99
127
|
|
|
100
|
-
| Term | Meaning | Not to be confused with |
|
|
101
|
-
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
|
|
102
|
-
| **overlay** | A kit element on top of the page: dialog, drawer, menu, popover, tooltip, suggestion list | A portal: an overlay can also sit in the owner's DOM, like the Editor's floating Toolbar |
|
|
103
|
-
| **overlay layer** | A named z-index step from `OVERLAY_LAYER`: `modal` — scrim and dialog, `alert` — a confirmation above a dialog, `popover` — menus, popovers, lists. Do not write z-index numbers outside this scale (ADR-0041) | A token layer |
|
|
104
|
-
| **Escape stack** | The stack of open kit overlays (`src/lib/overlay-layer.ts`), shared by Radix and react-aria overlays: only the top one handles Escape, nested ones close one at a time | An overlay layer: the top of the stack is determined by position in the document, not by z-index |
|
|
128
|
+
| Term | Meaning | Not to be confused with | Source | Also searched as |
|
|
129
|
+
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------ | ------------------------- |
|
|
130
|
+
| **overlay** | A kit element on top of the page: dialog, drawer, menu, popover, tooltip, suggestion list | A portal: an overlay can also sit in the owner's DOM, like the Editor's floating Toolbar | common | — |
|
|
131
|
+
| **overlay layer** | A named z-index step from `OVERLAY_LAYER`: `modal` — scrim and dialog, `alert` — a confirmation above a dialog, `popover` — menus, popovers, lists. Do not write z-index numbers outside this scale (ADR-0041) | A token layer | own | z-index scale |
|
|
132
|
+
| **Escape stack** | The stack of open kit overlays (`src/lib/overlay-layer.ts`), shared by Radix and react-aria overlays: only the top one handles Escape, nested ones close one at a time | An overlay layer: the top of the stack is determined by position in the document, not by z-index | own | dismissable layer (Radix) |
|
|
105
133
|
|
|
106
134
|
## Components in prose
|
|
107
135
|
|
|
108
136
|
How a component is named in prose. Do not use the words listed after "Do not write:": readers
|
|
109
137
|
search for a single word.
|
|
110
138
|
|
|
111
|
-
| Term
|
|
112
|
-
|
|
|
113
|
-
| **dialog**
|
|
114
|
-
| **drawer**
|
|
115
|
-
| **popover**
|
|
116
|
-
| **tooltip**
|
|
117
|
-
| **hint**
|
|
118
|
-
| **placeholder**
|
|
119
|
-
| **toast**
|
|
120
|
-
| **checkbox**
|
|
121
|
-
| **table
|
|
122
|
-
| **menu
|
|
123
|
-
| **segmented control**
|
|
124
|
-
| **tag**
|
|
125
|
-
| **
|
|
126
|
-
| **
|
|
127
|
-
| **
|
|
128
|
-
| **
|
|
129
|
-
| **category
|
|
130
|
-
| **
|
|
131
|
-
| **
|
|
139
|
+
| Term | Meaning | Not to be confused with | Source | Also searched as |
|
|
140
|
+
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------------ |
|
|
141
|
+
| **dialog** | `Dialog`: a modal surface with a scrim | A drawer. A browser window, which is simply called a "browser window". Do not write: modal | WAI-ARIA | modal |
|
|
142
|
+
| **drawer** | `Drawer`: a modal panel that slides in from an edge | A dialog. Do not write: sheet, slide-out panel | MUI | sheet, side panel |
|
|
143
|
+
| **popover** | `Popover`: a non-modal panel next to the button that opened it | A tooltip: it has no interactivity. Do not write: popup | Radix | — |
|
|
144
|
+
| **tooltip** | `Tooltip`: short text on hover and focus | A popover | WAI-ARIA | — |
|
|
145
|
+
| **hint** | `hint` on `FormField` and neighboring fields: text under the field that helps to fill it in | A tooltip and a placeholder | common | helper text, description |
|
|
146
|
+
| **placeholder** | `placeholder`: an example value shown in an empty field that disappears on input | A hint and a tooltip | MDN | — |
|
|
147
|
+
| **toast** | A global notification `toast()` in `Toaster` | The Editor's Field notice: it is tied to a field | React Aria | snackbar |
|
|
148
|
+
| **checkbox** | `Checkbox`: a yes/no choice within a set | The `Toggle` switch (`role="switch"`): one boolean property, not a choice within a set | WAI-ARIA | — |
|
|
149
|
+
| **table toolbar** | The `toolbar` slot of `DataTable`, usually `TableToolbar` | The Editor's Toolbar and the `Toolbar` primitive. Do not write a bare toolbar | Carbon | table bar, batch actions bar |
|
|
150
|
+
| **menu button** | The button that opens a menu: the right part of `SplitButton`, the `Menu` button | A popover: that is the panel that opened. Do not write: disclosure | WAI-ARIA | menu trigger |
|
|
151
|
+
| **segmented control** | `Segmented`: a row of buttons of which exactly one is selected | `Tabs` (they switch panels) and `ToggleGroup` (zero or more selected) | Apple HIG | segmented button, toggle group |
|
|
152
|
+
| **tag** | `Tag` in `TagGroup` and `TagInput`: a compact element with text and an optional remove button | The Editor's Mark and a field label. A chip: that one is toggled, not removed | React Aria | removable chip |
|
|
153
|
+
| **chip** | `Chip`: a compact filter button that is switched on and off (`selected`, `aria-pressed`), with an optional `count` | A tag: a tag is removed, while a chip is toggled. A segmented control: that one picks one option out of several | M3 | filter chip, toggle button |
|
|
154
|
+
| **close button** | The button with an "×" that closes a dialog, drawer, popover or notification; in a search field it is the **clear button** | A "Cancel" button. Do not write: cross | WAI-ARIA | — |
|
|
155
|
+
| **keyboard shortcuts dialog** | `ShortcutsHelp`: a dialog with a list of keyboard shortcuts | The Editor's Keyboard shortcuts popover: that one opens from the Toolbar and describes the Editor's shortcuts | common | shortcut list, cheat sheet |
|
|
156
|
+
| **mega menu** | `MegaMenu`: a category column and the flyout of the hovered category, an Amazon-style catalog | `Menu`: that one is for commands, not navigation. Do not write: mega dropdown | common | — |
|
|
157
|
+
| **category** | `MegaMenuCategory`: a row of the category column with a label, an icon and its own flyout | A menu item (`MenuItem`) | own | department |
|
|
158
|
+
| **category column** | The vertical list of categories in a mega menu | `SideNav`: that one expands branches in place | own | — |
|
|
159
|
+
| **flyout** | The area next to the category column with the open category's content: link columns, promos. Before 4.3.0 it was called the showcase; the width prop is still `showcaseWidth` | The showcase: that is the kit's Storybook. The Editor toolbar, a popover | common | — |
|
|
160
|
+
| **menu aim** | Deferring the category switch while the pointer cuts diagonally toward the open flyout | An opening delay: menu aim never slows down a direct hover | Ben Kamens | aim, safe triangle |
|
|
132
161
|
|
|
133
162
|
## Editor
|
|
134
163
|
|
|
@@ -136,58 +165,58 @@ Terms of `RichTextEditor` and `RichTextView` (the `@olddevs/ui/editor` entry poi
|
|
|
136
165
|
especially easy to borrow a word from a neighboring editor (plugin, service, node) — and that
|
|
137
166
|
introduces a second meaning.
|
|
138
167
|
|
|
139
|
-
| Term
|
|
140
|
-
|
|
|
141
|
-
| **Editor**
|
|
142
|
-
| **View**
|
|
143
|
-
| **Table of contents**
|
|
144
|
-
| **Document**
|
|
145
|
-
| **JSON envelope**
|
|
146
|
-
| **Schema**
|
|
147
|
-
| **Block**
|
|
148
|
-
| **Mark**
|
|
149
|
-
| **Atom**
|
|
150
|
-
| **Atom text**
|
|
151
|
-
| **
|
|
152
|
-
| **Wrapper**
|
|
153
|
-
| **
|
|
154
|
-
| **Collapsible block**
|
|
155
|
-
| **Toolbar**
|
|
156
|
-
| **
|
|
157
|
-
| **
|
|
158
|
-
| **Block handle**
|
|
159
|
-
| **Insert item**
|
|
160
|
-
| **Block action**
|
|
161
|
-
| **
|
|
162
|
-
| **
|
|
163
|
-
| **Glass**
|
|
164
|
-
| **UI contribution**
|
|
165
|
-
| **Slot**
|
|
166
|
-
| **Preset**
|
|
167
|
-
| **Tool**
|
|
168
|
-
| **custom Tool**
|
|
169
|
-
| **Tool options**
|
|
170
|
-
| **Configured Tool**
|
|
171
|
-
| **Tool state**
|
|
172
|
-
| **Tool commands**
|
|
173
|
-
| **Consumer prefix**
|
|
174
|
-
| **HTML convention**
|
|
175
|
-
| **Block trait**
|
|
176
|
-
| **Extensions**
|
|
177
|
-
| **Loader**
|
|
178
|
-
| **Handle**
|
|
179
|
-
| **Readiness**
|
|
180
|
-
| **Field focus**
|
|
181
|
-
| **
|
|
182
|
-
| **
|
|
183
|
-
| **Skeleton**
|
|
184
|
-
| **Status
|
|
185
|
-
| **Field notice**
|
|
186
|
-
| **Text card**
|
|
187
|
-
| **Trigger character**
|
|
188
|
-
| **Paper**
|
|
189
|
-
| **Island**
|
|
190
|
-
| **Mount point**
|
|
168
|
+
| Term | Meaning | Not to be confused with | Source | Also searched as |
|
|
169
|
+
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------ |
|
|
170
|
+
| **Editor** | `RichTextEditor` — a rich text input field | A code editor: the kit has none, code is displayed with `CodeView` | Tiptap | rich text editor, WYSIWYG |
|
|
171
|
+
| **View** | `RichTextView` — read-only display of a saved Document | The Editor's `readOnly` mode: that one carries the engine, the View does not | own | renderer |
|
|
172
|
+
| **Table of contents** | `RichTextToc`: the list of a Document's headings next to the View or the Editor. Collapsed, it is a strip of strokes; expanded, a list; a click on an item goes to the heading | The kit's `Heading` and the navigation of the documentation site | common | TOC, outline |
|
|
173
|
+
| **Document** | The Editor's value: an HTML string constrained by the Schema | The ProseMirror JSON tree in the engine — it is internal; it comes out only as a JSON envelope | ProseMirror | doc, content |
|
|
174
|
+
| **JSON envelope** | A Document as JSON for a file and a template: `{ format: "olddevs-rich-text", version, doc }` (`getJSON()`, `setJSON()`, `defaultValue`), lossless and through the Schema | The Editor's value — the value stays HTML; the bare tree `editor.getJSON()` without an envelope | own | getJSON |
|
|
175
|
+
| **Schema** | An allowlist of Blocks, Marks and attributes that the Editor accepts and returns | Server-side sanitization — the consumer does it (`sanitizeRichText`) | ProseMirror | allowlist |
|
|
176
|
+
| **Block** | A structural element of a Document: paragraph, heading, list, table, image… | A Mark | ProseMirror | block node |
|
|
177
|
+
| **Mark** | Inline formatting inside a Block: bold, link, color… | A Block | ProseMirror | — |
|
|
178
|
+
| **Atom** | A Block or inline element that is selected, moved and deleted as a whole: an image (the caption inside it is editable), a divider, a soft break, a mention. Always makes the field non-empty | An empty Block: a paragraph without text is not an Atom and does not count as content | ProseMirror | atom node |
|
|
179
|
+
| **Atom text** | The string that represents an Atom in the Document's text: `getText` and `getSelectedText` return it, its length is the Atom's weight in `maxLength`, and it is how the Atom is exported to Markdown without rules of its own. For an image it is the caption text, for a divider an empty string | A Block attribute | Tiptap | renderText, leafText |
|
|
180
|
+
| **Column layout** | A Block of columns (the `layout` Tool): six variants — from one to four equal columns, 60/40 and 40/60. Top level only, does not nest into itself; a column for its Blocks is the same as a Document | A table: it has data rows and cells, while the columns of a Column layout are the Document's page structure. The kit's `Grid`: a screen grid, not a Block | BlockNote | columns, layout |
|
|
181
|
+
| **Wrapper** | A Block that gathers a group of Blocks (the `wrapper` Tool, a `div` with `data-block="wrapper"`): they are moved, duplicated and deleted as one Block. Without a Callout tone it has no look of its own — the dashed outline exists only in the Editor. Neither a Wrapper nor a Column layout nests into a Wrapper | A quote: it has its own look and meaning in the Document, while a Wrapper without a tone is only grouping | own | container, group |
|
|
182
|
+
| **Callout tone** | The styling of a Wrapper as a note (`data-tone`): a background and a stripe on the left in one of five tones of the `Tone` vocabulary — "Note", "Tip", "Important", "Warning", "Caution". Chosen in the "Tone ›" item of the Block handle, the same in the Editor and the View, exported to Markdown as a GitHub alert (what GitHub and Notion call a callout) | The tone of a Field notice (`status` or `error`). Meaning: the tone carries no roles or `aria-*`; the meaning of a note is written as a word in the text | GitHub | callout, alert, admonition |
|
|
183
|
+
| **Collapsible block** | A Block made of a title and content that the reader opens and closes (the `details` Tool, the Details extension from Tiptap; the `details` and `summary` tags). The content is Blocks; there are no Column layouts or Wrappers in it. Only the `persist` option writes the open state into the Document | A Wrapper: it groups Blocks and hides nothing. The kit's `Accordion`: that is a screen component, not a Block of the Document | Tiptap | details, toggle block, accordion |
|
|
184
|
+
| **Toolbar** | A set of formatting buttons; its look is set by `toolbar`. **Fixed** (`fixed`, the default) — above the field, sticks on scroll; **floating** (`floating`) — the same buttons above a non-empty selection. With `bubble` there is no Toolbar — the Bubble menu takes its place, with `none` there is neither. On a touch screen the Toolbar is always fixed | The kit's `Toolbar` — the primitive that the Toolbar is built from | common | formatting toolbar, fixed menu |
|
|
185
|
+
| **Slash menu** | The "Insert" and "Turn into" list: opens on `/` in the text and on the "+" button | The browser context menu | BlockNote | insert menu, slash command |
|
|
186
|
+
| **Bubble menu** | A compact pill on an inverse surface above a non-empty selection: "¶", lists, bold, italic, underline, color, "…", link, emoji; its contents are fixed by the kit. Appears in place of the Toolbar with `toolbar="bubble"` and on top of the fixed Toolbar — there `selectionMenu={false}` turns it off. Absent on a touch screen | The floating Toolbar: it has the full set of buttons | Tiptap | selection menu, BubbleMenu |
|
|
187
|
+
| **Block handle** | The "⋮" on the Block that holds the caret, and its menu of actions on the whole Block: "Add ›", "Format ›", "Move up", "Move down", "Duplicate", "Delete" | The Toolbar: it works with the selection, not with a Block | BlockNote | drag handle, side menu |
|
|
188
|
+
| **Insert item** | A row of the Slash menu: inserts a Block or turns the current one into another. One item is visible on `/`, on "+" and in the Block handle | A Toolbar button | BlockNote | suggestion item |
|
|
189
|
+
| **Block action** | An item of the Block handle menu that works with the whole Block, for example "Duplicate" | A button: it works with the selection | own | block menu |
|
|
190
|
+
| **Keyboard shortcuts popover** | A read-only "command — shortcut" popover behind the last button of the fixed Toolbar. The rows are the commands of the enabled Tools, including custom ones; on a phone there is no button | The kit's `CommandPalette`: the rows of the Keyboard shortcuts popover are not clickable. The kit's `ShortcutsHelp`: it lists screen shortcuts, not Editor ones | common | shortcuts reference, cheat sheet |
|
|
191
|
+
| **Source mode** | The mode of the `source` Tool: the "HTML" button on the fixed Toolbar replaces the Document with a field holding its HTML. The field text passes through the Schema and becomes the Document in a single edit — on leaving the mode, on `blur`, on form submit and on reading through the Handle | The HTML convention: that is the form of custom content in a Document, not a mode. `CodeView`: it displays code, while the HTML field is editable | CKEditor | HTML mode, source editing |
|
|
192
|
+
| **Glass** | A semi-transparent background that blurs what is behind it on everything the Editor shows above the Document: the floating Toolbar, the Bubble menu, menus, popovers, the Text card. The color is the token of its own surface; with `prefers-reduced-transparency`, `prefers-contrast: more` and on iOS the background is solid | The kit's `Menu` and `Popover` outside the Editor: they stay solid | common | glassmorphism, frosted glass |
|
|
193
|
+
| **UI contribution** | A UI element of a custom Tool, described as data: a button, an Insert item, a Block action or a Text card. The kit renders it in a Slot; a disabled Tool removes its UI contributions as well | A React node in the interface: arbitrary React is allowed only inside the content of a button popover and a Text card | own | — |
|
|
194
|
+
| **Slot** | One place on a surface where the UI contributions of custom Tools appear, in `tools` order: the Toolbar group before "Undo", the end of a Slash menu section, the Block handle section before "Delete" | A position relative to a built-in button: the ids of built-ins are not public API | own | — |
|
|
195
|
+
| **Preset** | A ready-made set of built-in Tools: `full` or `basic` (`RICH_TEXT_PRESETS`). Not a frozen list: a new built-in arrives in it in a minor version | An exact `tools` list: only the screen changes its composition | Tiptap | StarterKit |
|
|
196
|
+
| **Tool** | One capability of the Editor: its Blocks and Marks, their rules in the Schema and their place in the UI, for example `table`. A built-in one is set by name, a custom one by a description | A button: disabling a Tool also removes its Block from the Schema. A Redactor plugin: that is a class of behavior over the DOM without a Schema | own | extension, plugin |
|
|
197
|
+
| **custom Tool** | A Tool that the consumer describes (`CustomTool`): Schema rules as data, Extensions and UI contributions. It is passed in `tools` mixed in with the kit's names | The kit's internal description: that is a superset of the public shape for built-ins and is not exported | own | custom extension |
|
|
198
|
+
| **Tool options** | What the screen sets on a Tool before the engine is created: the starting flags of Find, `offsetVar`, `levels` and `listWidth` of the Table of contents, the `defaults` of a custom Tool (`defineTool`). The screen sets them with a `tool(…)` entry and the kit reads them once, when the engine is created | `options` of a Tiptap extension: the extension's author sets those and the extension itself reads them, while Tool options are set by the screen and read by the kit. The Editor's props (`preset`, `maxHeight`): those configure the field, not a Tool | Tiptap | options, configure |
|
|
199
|
+
| **Configured Tool** | An entry of `tools` returned by `tool(name, options)` or `tool(definition, options)`: a Tool together with its options. It switches a Tool on without the name in `tools` and wins over a bare name from a Preset | A `defineTool` definition: that describes a Tool, while a Configured Tool is its activation with options. The description of a built-in Tool: it is not exported, and the entry only names the Tool and carries the options | Tiptap | configure |
|
|
200
|
+
| **Tool state** | A data snapshot the screen reads with the `useRichTextToolState(ref, name)` hook: for Find, whether the panel is open, the query, the number of matches and the current one; for the Table of contents, the headings and the current section. The screen re-renders only when the snapshot changes | `storage` of a Tiptap extension: that is a mutable store inside the engine, while Tool state is read-only. `useRichTextEditorState`: that takes a slice of the live Tiptap `editor`, not a Tool's contract | Tiptap | storage |
|
|
201
|
+
| **Tool commands** | What the screen calls on a Tool through `handle.tool(name)`: `tool("search")?.open()`, `tool("toc")?.jumpTo(2)`. Each returns a `boolean`; `null` instead of the commands object means the Tool is not in the set, has no commands, or the engine has not been created yet | Handle methods (`insertHTML`, `focus`): those are common to any `tools`, while Tool commands exist only while the Tool is enabled. `editor.commands` and `commands` in Tiptap: those are engine commands and follow its major | Tiptap | commands |
|
|
202
|
+
| **Consumer prefix** | The start of the name of everything custom — a Tool, its Blocks, Marks and attributes — up to the underscore: `acme_mergeTag`, `data-acme_size`. Kit names have no underscore, so custom names and built-in ones never collide, either in a set or in a Document | A Preset: that is a set of built-in Tools, not a namespace | own | namespace |
|
|
203
|
+
| **HTML convention** | The form of custom content in a Document: a Block is a `div` or `span` with `data-block`, a Mark is a `span` with `data-mark`, attributes are `data-<prefix>_<name>`. Frozen: extended only by adding | The kit's Schema tags (`p`, `table`, `img`): a custom Block cannot take them | own | parseHTML, renderHTML |
|
|
204
|
+
| **Block trait** | A Block property that only the kit understands, not the engine: "container" (children get their own handle), "can be turned into", "Atom without a formatting menu" | A Block attribute: that one is stored in the Document | own | NodeSpec |
|
|
205
|
+
| **Extensions** | The Tiptap extensions in a Tool description (the `engine` field): Node, Mark, Extension, ProseMirror plugins and NodeView. Supplied directly or through a Loader | Schema rules: those are data, read by the server and the View without an engine. "Engine part": the former name (ADR-0058 uses it) | Tiptap | extensions |
|
|
206
|
+
| **Loader** | A function with a dynamic import in place of the Extensions themselves: `engine: () => import(…)`. The heavy built-ins outside `basic` load the same way — the code Block and the table | Preloading (`modulepreload`): the kit does not publish it, the consumer sets it up | own | lazy loading, dynamic import |
|
|
207
|
+
| **Handle** | Imperative access from screen code to the Editor through `ref`: insert at the caret, read, focus, history, the commands of Tools (`tool(name)`) | Redactor services: those are engine internals, not screen API | React | imperative handle, ref |
|
|
208
|
+
| **Readiness** | The moment when the engine is created and the Loaders of all enabled Tools, custom and built-in, have finished: from then on Handle methods take effect instead of doing nothing. Happens once per mount; `onReady` reports it | Hydration: after it the engine may still be waiting for Loaders | own | onCreate |
|
|
209
|
+
| **Field focus** | Focus inside the Editor as a whole: the Document, the Toolbar, the kit's popovers, the HTML field. Moving between them does not lose Field focus; `onFocus` and `onBlur` are about it | Document focus (the engine's `focus` and `blur`): a click in the Toolbar removes it | common | focus within |
|
|
210
|
+
| **User edit** | A change to the Document equal to typing on a keyboard: a history step, `onChange` after a delay, the character limit applies. This also covers insert, undo and redo from the Handle | A Programmatic replacement | own | — |
|
|
211
|
+
| **Programmatic replacement** | Replacing the whole Document (`value`, `clear()`, `setMarkdown()`, `setJSON()`): the character limit does not truncate it; `onChange` fires immediately for `clear()`, `setMarkdown()` and `setJSON()`, but not for a new `value` | A User edit | Tiptap | setContent |
|
|
212
|
+
| **Skeleton** | The Editor's look before Readiness: the field frame, a placeholder for the Toolbar and a Document: sanitized by the Schema, it is rendered as static HTML with the same class and rhythm as the engine's Document, without input. On the server — the frame without a Document. A Loader failure turns the Skeleton into a field error with "Retry" | The View: that is a separate read-only component, while the Skeleton is a state of the Editor that the engine replaces. The kit's `Skeleton` component: a loading placeholder | common | skeleton screen, loading placeholder |
|
|
213
|
+
| **Status bar** | A line inside the field frame under the Document: on the left the screen's content (`status`: word count, "Saved", co-author), on the right the kit's character counter | A Field notice: the line shows a lasting state of the screen, not an event | common | status line, footer |
|
|
214
|
+
| **Field notice** | One event tied to the field (`showNotice`): tone `status` (only announced) or `error` (a visible line under the field until the next User edit). A new one replaces the previous one | The kit's toast: that one is global and not tied to a field | own | field message, error message |
|
|
215
|
+
| **Text card** | A non-modal card under a range of the Document, declared by a custom Tool (`textCards`): a comment, a hint from checking the text. Opens when the caret enters it or on click, focus stays in the text | A button popover: a button opens that one, while a Text card is opened by a place in the Document | own | comment, annotation |
|
|
216
|
+
| **Trigger character** | A character of a custom Tool (`trigger`) that opens a list of items at the caret when typed at the start of a Block or after a space, like `/`: `@` for mentions, `#` for tags. Picking an item replaces the typed `@query` with a custom node | The Slash menu on `/`: that one is built in, while a custom character is set by a Tool | Tiptap | suggestion char, mention |
|
|
217
|
+
| **Paper** | A light area of the Document in any app theme (`surface="paper"`) — for text that leaves the app on a light background: an email, print, PDF. The Toolbar, menus and field frame stay in the app theme; the View with the same `surface` shows the same Paper | The `light` theme: it changes the whole app, the Paper only the Document | own | page, canvas |
|
|
218
|
+
| **Island** | A client-side piece of the View that, after mounting, brings a Block in already rendered HTML to life: the "Copy" button on a code Block, the `island` of a custom Block | A node view: it lives only in the Editor engine | Astro | islands architecture |
|
|
219
|
+
| **Mount point** | A place in already rendered HTML where an Island mounts a live element: the code Block header that receives the "Copy" button | A Slot: that is a place in the Editor UI for the UI contributions of Tools | React | — |
|
|
191
220
|
|
|
192
221
|
## Tiptap
|
|
193
222
|
|
|
@@ -197,21 +226,24 @@ second meaning next to Block and Tool. The author of a custom Tool writes Extens
|
|
|
197
226
|
and reads Tiptap's documentation — the table connects the engine's word to the kit's. In the "Meaning"
|
|
198
227
|
column, first what the word means in Tiptap, then what corresponds to it in the kit.
|
|
199
228
|
|
|
200
|
-
| Term | Meaning | Not to be confused with |
|
|
201
|
-
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
202
|
-
| **Extension** | A unit of the Tiptap engine: nodes, Marks, commands, keyboard shortcuts and ProseMirror plugins in one class (`Extension.create`; `Node` and `Mark` are its kinds). The kit uses the same word: the Extensions of a Tool are its Tiptap extensions, and a capability as a whole is a Tool. An Extension without a Schema is a Tool without a Block (`search`, `toc`) | A Tool: that one also carries Schema rules, Markdown, the View and UI contributions, while an Extension is only the engine. A Tiptap extension is not passed in `tools`: it goes into the Extensions of a custom Tool |
|
|
203
|
-
| **Node** | A node type in the Tiptap Schema: paragraph, heading, table, image; block or inline. In the kit a block node corresponds to a Block, and an inline node without content to an inline Atom (a mention) | A Block as a whole: a Block is Schema rules as data plus Block traits, which the server and the View read, while a Node is only one of its Extensions |
|
|
204
|
-
| **Mark** | Inline formatting in the Tiptap Schema: bold, link, color. In the kit it is a Mark: Schema rules as data and a `Mark` in the Extensions | The `mark` tag: only the `highlight` Mark renders it. Tiptap's Text Style (an empty `span` for styles) is the base of the `color` Mark, not a Tool of its own |
|
|
205
|
-
| **StarterKit**, **Kit** | A set of Tiptap extensions in one package: StarterKit, ListKit, TableKit, TextStyleKit; each extension of the set is configured or switched off by a key in `configure`. In the kit StarterKit is an internal detail of the engine build: the description of each built-in Tool contributes its share of keys (`starterKit`), the shares are merged into one `StarterKit.configure`, and a key with no share is switched off. What comes out to the screen is a Preset | A Preset (`full`, `basic`): that one is a set of Tools, not of engine extensions, and it is not frozen. The kit of this glossary — the `@olddevs/ui` design system: the word Kit in Tiptap's names has nothing to do with it. `StarterKit` cannot be enabled through `tools` |
|
|
206
|
-
| **options** (`configure`) | Settings of a Tiptap extension: its author declares them in `addOptions`, the consumer changes them with `configure({…})`. In the kit these are Tool options: `tool(name, options)` for `search` and `toc`, `defaults` and `tool(definition, options)` for a custom Tool (`defineTool`). Merging works as in Tiptap v3's `configure`: nested objects are merged, arrays and functions are replaced | The options of Tiptap extensions inside the Extensions: the kit assembles built-in ones itself and does not open them to the screen. The Editor's props (`preset`, `maxHeight`): those configure the field, not a Tool |
|
|
207
|
-
| **storage** | A mutable store of an extension inside the engine (`editor.storage.<name>`): search results, the character count. In the kit it is Tool state: a snapshot that the screen reads with the `useRichTextToolState(ref, name)` hook; a custom Tool declares it with the `state` function in `defineTool` | `editor.storage`: Tool state is read-only, while storage is changed by the extension itself. Storage is part of the engine and follows its major |
|
|
208
|
-
| **commands** | The commands of a Tiptap extension (`addCommands`): `editor.commands`, the `editor.chain()` chain, the `editor.can()` check. In the kit these are Tool commands: `handle.tool(name)`, each returns a `boolean`; a custom Tool declares them with the `commands` function in `defineTool` | `editor.commands` and `chain()`: those are engine commands and follow its major. Handle methods (`insertHTML`, `focus`): those are common to any `tools`, while Tool commands exist only while the Tool is enabled |
|
|
209
|
-
| **`extend`** | The way to change an existing Tiptap extension: `Bold.extend({…})`. The kit has no counterpart: a built-in Tool is not replaced (ADR-0058, item 1.5). If you need other behavior, switch the built-in one off and add your own under a name with the Consumer prefix | `configure`: that one changes options, not behavior; the kit has its counterpart — Tool options. A custom Tool "instead of" a built-in one: it has its own name, its own Blocks and Marks |
|
|
210
|
-
| **`priority`** | A number on a Tiptap extension: the larger it is, the earlier the extension stands in the queue and the earlier its plugins are asked. The kit has no number: the order of built-in Tools is set by the kit itself (the rank of Marks, and with it their nesting in HTML, paste and keys depend on it), and custom ones follow the built-in ones in `tools` order, so their paste and drop handlers are asked before the built-in ones | The order of entries in the Toolbar and the
|
|
211
|
-
| **NodeView** | A custom look of a node in the Editor: instead of `renderHTML`, the node is drawn by JavaScript or React code. In the kit it is the node view in the Extensions; in the View, where there is no engine, an Island is its counterpart | An Island: that one brings a Block in already rendered HTML to life without an engine, while a NodeView lives only in the Editor. `renderHTML`: it produces the Document's HTML, while a NodeView is only the look on screen |
|
|
212
|
-
| **MarkView** | The same for a Mark: a custom look of a Mark in the Editor. In the kit it is the Mark's view in the Extensions; a Mark has no Island, and in the View it stays sanitized HTML | NodeView: that one draws a whole node, while a MarkView draws a stretch of text with a Mark. An Island: an Island exists only for a Block |
|
|
213
|
-
| **Decoration** | Styling on top of the Document that does not change it: a highlight, a class on a node, a widget (ProseMirror's `Decoration`). The kit uses the same word: a Decoration lives in the Extensions and does not enter the Document — this is how code highlighting, Find matches and the image upload marker work | A Mark: a Mark is stored in the Document and goes into `value`, a Decoration does not. A Block attribute |
|
|
214
|
-
| **Input rule** | An input rule: typed text matching a pattern is replaced with a node or a Mark (`# ` — a heading, `**…**` — bold). The kit has no separate term: the rule lives in the Extensions of a Block or Mark, and the author of the text sees it as a Markdown shortcut while typing | Markdown export (`getMarkdown`, `setMarkdown`): that converts the whole Document, while an input rule fires on the typed fragment. An Insert item |
|
|
215
|
-
| **Paste rule** | A paste rule: on paste or drop, text matching a pattern (most often a link) becomes a node or a Mark. The kit has the same: a rule in the Extensions of a Tool | Parsing a paste through the Schema: that cuts off what the Schema does not know, while a Paste rule turns matched text into a node. A `parseHTML` rule: that one is about HTML, not text |
|
|
216
|
-
| **Schema** | A description of the nodes and Marks allowed in ProseMirror: which exist and what goes inside what; Tiptap assembles it from extensions. In the kit the Schema has the same meaning plus the allowlist for the sanitizer and the View: the rules lie in a Tool's description as data, and the server and the View read them without an engine, while the engine's Schema is assembled from Extensions | Server-side sanitization: the consumer does it (`sanitizeRichText`). The ProseMirror JSON tree: it is internal |
|
|
217
|
-
| **Transaction** | One change of the ProseMirror engine state: steps over the Document, the selection and metadata; the `chain().run()` chain is one transaction. The kit has no word for it: Tool state is recomputed on every transaction, and an edit made by the `run` of a Block action is one transaction, that is, one undo |
|
|
229
|
+
| Term | Meaning | Not to be confused with | Source | Also searched as |
|
|
230
|
+
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------------- |
|
|
231
|
+
| **Extension** | A unit of the Tiptap engine: nodes, Marks, commands, keyboard shortcuts and ProseMirror plugins in one class (`Extension.create`; `Node` and `Mark` are its kinds). The kit uses the same word: the Extensions of a Tool are its Tiptap extensions, and a capability as a whole is a Tool. An Extension without a Schema is a Tool without a Block (`search`, `toc`) | A Tool: that one also carries Schema rules, Markdown, the View and UI contributions, while an Extension is only the engine. A Tiptap extension is not passed in `tools`: it goes into the Extensions of a custom Tool | Tiptap | — |
|
|
232
|
+
| **Node** | A node type in the Tiptap Schema: paragraph, heading, table, image; block or inline. In the kit a block node corresponds to a Block, and an inline node without content to an inline Atom (a mention) | A Block as a whole: a Block is Schema rules as data plus Block traits, which the server and the View read, while a Node is only one of its Extensions | Tiptap | — |
|
|
233
|
+
| **Mark** | Inline formatting in the Tiptap Schema: bold, link, color. In the kit it is a Mark: Schema rules as data and a `Mark` in the Extensions | The `mark` tag: only the `highlight` Mark renders it. Tiptap's Text Style (an empty `span` for styles) is the base of the `color` Mark, not a Tool of its own | Tiptap | — |
|
|
234
|
+
| **StarterKit**, **Kit** | A set of Tiptap extensions in one package: StarterKit, ListKit, TableKit, TextStyleKit; each extension of the set is configured or switched off by a key in `configure`. In the kit StarterKit is an internal detail of the engine build: the description of each built-in Tool contributes its share of keys (`starterKit`), the shares are merged into one `StarterKit.configure`, and a key with no share is switched off. What comes out to the screen is a Preset | A Preset (`full`, `basic`): that one is a set of Tools, not of engine extensions, and it is not frozen. The kit of this glossary — the `@olddevs/ui` design system: the word Kit in Tiptap's names has nothing to do with it. `StarterKit` cannot be enabled through `tools` | Tiptap | bundle |
|
|
235
|
+
| **options** (`configure`) | Settings of a Tiptap extension: its author declares them in `addOptions`, the consumer changes them with `configure({…})`. In the kit these are Tool options: `tool(name, options)` for `search` and `toc`, `defaults` and `tool(definition, options)` for a custom Tool (`defineTool`). Merging works as in Tiptap v3's `configure`: nested objects are merged, arrays and functions are replaced | The options of Tiptap extensions inside the Extensions: the kit assembles built-in ones itself and does not open them to the screen. The Editor's props (`preset`, `maxHeight`): those configure the field, not a Tool | Tiptap | — |
|
|
236
|
+
| **storage** | A mutable store of an extension inside the engine (`editor.storage.<name>`): search results, the character count. In the kit it is Tool state: a snapshot that the screen reads with the `useRichTextToolState(ref, name)` hook; a custom Tool declares it with the `state` function in `defineTool` | `editor.storage`: Tool state is read-only, while storage is changed by the extension itself. Storage is part of the engine and follows its major | Tiptap | — |
|
|
237
|
+
| **commands** | The commands of a Tiptap extension (`addCommands`): `editor.commands`, the `editor.chain()` chain, the `editor.can()` check. In the kit these are Tool commands: `handle.tool(name)`, each returns a `boolean`; a custom Tool declares them with the `commands` function in `defineTool` | `editor.commands` and `chain()`: those are engine commands and follow its major. Handle methods (`insertHTML`, `focus`): those are common to any `tools`, while Tool commands exist only while the Tool is enabled | Tiptap | — |
|
|
238
|
+
| **`extend`** | The way to change an existing Tiptap extension: `Bold.extend({…})`. The kit has no counterpart: a built-in Tool is not replaced (ADR-0058, item 1.5). If you need other behavior, switch the built-in one off and add your own under a name with the Consumer prefix | `configure`: that one changes options, not behavior; the kit has its counterpart — Tool options. A custom Tool "instead of" a built-in one: it has its own name, its own Blocks and Marks | Tiptap | — |
|
|
239
|
+
| **`priority`** | A number on a Tiptap extension: the larger it is, the earlier the extension stands in the queue and the earlier its plugins are asked. The kit has no number: the order of built-in Tools is set by the kit itself (the rank of Marks, and with it their nesting in HTML, paste and keys depend on it), and custom ones follow the built-in ones in `tools` order, so their paste and drop handlers are asked before the built-in ones | The order of entries in the Toolbar and the Slash menu: the kit sets it, while the UI contributions of custom Tools stand in a Slot in `tools` order. `priority` of a `parseHTML` rule: that one is the order of parse rules of a single node | Tiptap | — |
|
|
240
|
+
| **NodeView** | A custom look of a node in the Editor: instead of `renderHTML`, the node is drawn by JavaScript or React code. In the kit it is the node view in the Extensions; in the View, where there is no engine, an Island is its counterpart | An Island: that one brings a Block in already rendered HTML to life without an engine, while a NodeView lives only in the Editor. `renderHTML`: it produces the Document's HTML, while a NodeView is only the look on screen | Tiptap | — |
|
|
241
|
+
| **MarkView** | The same for a Mark: a custom look of a Mark in the Editor. In the kit it is the Mark's view in the Extensions; a Mark has no Island, and in the View it stays sanitized HTML | NodeView: that one draws a whole node, while a MarkView draws a stretch of text with a Mark. An Island: an Island exists only for a Block | Tiptap | — |
|
|
242
|
+
| **Decoration** | Styling on top of the Document that does not change it: a highlight, a class on a node, a widget (ProseMirror's `Decoration`). The kit uses the same word: a Decoration lives in the Extensions and does not enter the Document — this is how code highlighting, Find matches and the image upload marker work | A Mark: a Mark is stored in the Document and goes into `value`, a Decoration does not. A Block attribute | ProseMirror | — |
|
|
243
|
+
| **Input rule** | An input rule: typed text matching a pattern is replaced with a node or a Mark (`# ` — a heading, `**…**` — bold). The kit has no separate term: the rule lives in the Extensions of a Block or Mark, and the author of the text sees it as a Markdown shortcut while typing | Markdown export (`getMarkdown`, `setMarkdown`): that converts the whole Document, while an input rule fires on the typed fragment. An Insert item | Tiptap | — |
|
|
244
|
+
| **Paste rule** | A paste rule: on paste or drop, text matching a pattern (most often a link) becomes a node or a Mark. The kit has the same: a rule in the Extensions of a Tool | Parsing a paste through the Schema: that cuts off what the Schema does not know, while a Paste rule turns matched text into a node. A `parseHTML` rule: that one is about HTML, not text | Tiptap | — |
|
|
245
|
+
| **Schema** | A description of the nodes and Marks allowed in ProseMirror: which exist and what goes inside what; Tiptap assembles it from extensions. In the kit the Schema has the same meaning plus the allowlist for the sanitizer and the View: the rules lie in a Tool's description as data, and the server and the View read them without an engine, while the engine's Schema is assembled from Extensions | Server-side sanitization: the consumer does it (`sanitizeRichText`). The ProseMirror JSON tree: it is internal | ProseMirror | — |
|
|
246
|
+
| **Transaction** | One change of the ProseMirror engine state: steps over the Document, the selection and metadata; the `chain().run()` chain is one transaction. The kit has no word for it: Tool state is recomputed on every transaction, and an edit made by the `run` of a Block action is one transaction, that is, one undo | A User edit: that is a change to the Document equal to typing, while a transaction can also happen without changing the Document (selection, metadata). Re-rendering: Tool state re-renders the screen only when the snapshot changed, not on every transaction | ProseMirror | — |
|
|
247
|
+
| **BubbleMenu** | A Tiptap menu above selected text (the Bubble Menu extension). The kit builds the Bubble menu (`toolbar="bubble"`) and the floating Toolbar (`toolbar="floating"`) on it: they share the condition for showing and the position | FloatingMenu: that menu appears at an empty line. The kit's `floating` value is the floating Toolbar above a selection, not Tiptap's FloatingMenu | Tiptap | — |
|
|
248
|
+
| **FloatingMenu** | A Tiptap menu at an empty line: it appears when the caret is in an empty Block (the Floating Menu extension). The kit has no such menu: the Slash menu opens on `/` and from the "+" button of the Toolbar | The floating Toolbar (`toolbar="floating"`): that one appears above a selection and is built on BubbleMenu | Tiptap | — |
|
|
249
|
+
| **Suggestion** | The Tiptap utility for a list opened by a character (`@tiptap/suggestion`): a typed `char` opens a list at the caret, and picking an item replaces what was typed. The kit's Slash menu on `/` and the Trigger character of a custom Tool are built on it | The Slash menu as a whole: the "+" button opens it too, without a character | Tiptap | — |
|