@oakjs/addon-lexical 0.0.0-stage → 4.0.0-alpha.0

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.
Files changed (56) hide show
  1. package/README.md +125 -2
  2. package/dist/addons-DQNB8pRc.js +1365 -0
  3. package/dist/addons-DQNB8pRc.js.map +1 -0
  4. package/dist/addons-Pp5mwM60.cjs +1406 -0
  5. package/dist/addons-Pp5mwM60.cjs.map +1 -0
  6. package/dist/addons.cjs +5 -0
  7. package/dist/addons.js +2 -0
  8. package/dist/index.cjs +10 -0
  9. package/dist/index.js +2 -0
  10. package/dist/oak-addon-lexical.min.css +2 -0
  11. package/dist/oak-addon-lexical.min.css.map +1 -0
  12. package/dist/types/Field/ColorDropdown.d.ts +9 -0
  13. package/dist/types/Field/ColorDropdown.d.ts.map +1 -0
  14. package/dist/types/Field/Cursors.d.ts +24 -0
  15. package/dist/types/Field/Cursors.d.ts.map +1 -0
  16. package/dist/types/Field/Icon.d.ts +14 -0
  17. package/dist/types/Field/Icon.d.ts.map +1 -0
  18. package/dist/types/Field/LinkDropdown.d.ts +9 -0
  19. package/dist/types/Field/LinkDropdown.d.ts.map +1 -0
  20. package/dist/types/Field/MenuItem.d.ts +10 -0
  21. package/dist/types/Field/MenuItem.d.ts.map +1 -0
  22. package/dist/types/Field/SyncPlugin.d.ts +17 -0
  23. package/dist/types/Field/SyncPlugin.d.ts.map +1 -0
  24. package/dist/types/Field/TableSizePicker.d.ts +11 -0
  25. package/dist/types/Field/TableSizePicker.d.ts.map +1 -0
  26. package/dist/types/Field/Toolbar.d.ts +12 -0
  27. package/dist/types/Field/Toolbar.d.ts.map +1 -0
  28. package/dist/types/Field/ToolbarButton.d.ts +11 -0
  29. package/dist/types/Field/ToolbarButton.d.ts.map +1 -0
  30. package/dist/types/Field/ToolbarDropdown.d.ts +21 -0
  31. package/dist/types/Field/ToolbarDropdown.d.ts.map +1 -0
  32. package/dist/types/Field/context.d.ts +16 -0
  33. package/dist/types/Field/context.d.ts.map +1 -0
  34. package/dist/types/Field/html.d.ts +17 -0
  35. package/dist/types/Field/html.d.ts.map +1 -0
  36. package/dist/types/Field/index.d.ts +21 -0
  37. package/dist/types/Field/index.d.ts.map +1 -0
  38. package/dist/types/Field/measure.d.ts +12 -0
  39. package/dist/types/Field/measure.d.ts.map +1 -0
  40. package/dist/types/Field/positions.d.ts +24 -0
  41. package/dist/types/Field/positions.d.ts.map +1 -0
  42. package/dist/types/Field/testUtils.d.ts +3 -0
  43. package/dist/types/Field/testUtils.d.ts.map +1 -0
  44. package/dist/types/Field/theme.d.ts +7 -0
  45. package/dist/types/Field/theme.d.ts.map +1 -0
  46. package/dist/types/Field/types.d.ts +19 -0
  47. package/dist/types/Field/types.d.ts.map +1 -0
  48. package/dist/types/Field/useToolbarState.d.ts +22 -0
  49. package/dist/types/Field/useToolbarState.d.ts.map +1 -0
  50. package/dist/types/addons.d.ts +12 -0
  51. package/dist/types/addons.d.ts.map +1 -0
  52. package/dist/types/index.d.ts +7 -0
  53. package/dist/types/index.d.ts.map +1 -0
  54. package/dist/types/types.d.ts +20 -0
  55. package/dist/types/types.d.ts.map +1 -0
  56. package/package.json +84 -4
package/README.md CHANGED
@@ -1,3 +1,126 @@
1
- # Temporary Holding Version
1
+ <div align="center">
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="https://cdn.junipero.design/images/oak-logo-light.svg" />
5
+ <img src="https://cdn.junipero.design/images/oak-logo.svg" height="50" />
6
+ </picture>
7
+
8
+ <br />
9
+ <br />
10
+
11
+ [![GitHub](https://img.shields.io/github/license/p3ol/oak.svg)](https://github.com/p3ol/oak)
12
+ [![npm](https://img.shields.io/npm/v/@oakjs/addon-lexical.svg)](https://www.npmjs.com/package/@oakjs/addon-lexical)
13
+ [![CI](https://github.com/p3ol/oak/actions/workflows/ci.yml/badge.svg)](https://github.com/p3ol/oak/actions/workflows/ci.yml)
14
+
15
+ ### @oakjs/addon-lexical
16
+ An addon to use [Lexical](https://lexical.dev) as an oak rich text field
17
+
18
+ </div>
19
+
20
+ # Installation
21
+
22
+ ```sh
23
+ yarn add @oakjs/addon-lexical lexical @lexical/react @lexical/html \
24
+ @lexical/link @lexical/list @lexical/rich-text @lexical/selection \
25
+ @lexical/table @lexical/utils
26
+ ```
27
+
28
+ # Usage
29
+
30
+ The field works with both builders (`@oakjs/ash` & `@oakjs/react`): it only
31
+ relies on the options given to fields by the builder (`fieldOptions.t` for
32
+ translations, `fieldOptions.floatingsRef` to render its menus). Inside ash, it
33
+ follows the builder's colors (light & dark).
34
+
35
+ ```jsx
36
+ import { Builder, baseAddon } from '@oakjs/ash';
37
+ import { lexicalFieldAddon } from '@oakjs/addon-lexical';
38
+
39
+ import '@oakjs/ash/styles.css';
40
+ import '@oakjs/addon-lexical/dist/oak-addon-lexical.min.css';
41
+
42
+ const richTextAddon = {
43
+ overrides: [{
44
+ type: 'component',
45
+ targets: ['title', 'text', 'button'],
46
+ fields: [{ key: 'content', type: 'lexical' }],
47
+ }],
48
+ };
49
+
50
+ // Addons must be stable: define them once
51
+ const addons = [baseAddon(), lexicalFieldAddon(), richTextAddon];
52
+
53
+ export default () => (
54
+ <div style={{ height: '100vh' }}>
55
+ <Builder addons={addons} value={content} onChange={setContent} />
56
+ </div>
57
+ );
58
+ ```
59
+
60
+ With `@oakjs/react`, import `Builder` & `baseAddon` from `@oakjs/react` (and
61
+ `@oakjs/theme`'s stylesheet) instead.
62
+
63
+ # Editing
64
+
65
+ The default toolbar has the same items as `@oakjs/addon-ckeditor5-react`'s:
66
+
67
+ | Item | Description |
68
+ | --- | --- |
69
+ | `undo`, `redo` | History |
70
+ | `bold`, `italic`, `strikethrough`, `underline` | Text formats |
71
+ | `link` | Link, optionally opened in a new tab |
72
+ | `fontColor` | Junipero's color field (picker & hex/rgb input), or remove the color |
73
+ | `fontSize` | Tiny, small, default, big & huge (CKEditor's sizes) |
74
+ | `bulletedList`, `numberedList` | Lists (nested with `indent`) |
75
+ | `removeFormat` | Removes formats, colors & sizes from the selection |
76
+ | `outdent`, `indent` | Indentation |
77
+ | `alignment` | Left, center, right, justify |
78
+ | `horizontalLine` | Horizontal rule |
79
+ | `blockQuote` | Quote |
80
+ | `insertTable` | Table, sized by selecting cells (up to 6 × 6), then rows & columns insertion/deletion |
81
+ | `heading` | Paragraph & headings (not in the default toolbar) |
82
+ | `\|` | Separator |
83
+
84
+ Customize it with the addon's options:
85
+
86
+ ```js
87
+ lexicalFieldAddon({
88
+ toolbar: ['bold', 'italic', 'link', '|', 'heading', 'bulletedList'],
89
+ fontSizes: [
90
+ { label: 'Default', value: null },
91
+ { label: 'Large', value: '24px' },
92
+ ],
93
+ });
94
+ ```
95
+
96
+ `DEFAULT_TOOLBAR` & `DEFAULT_FONT_SIZES` are exported to
97
+ extend the defaults.
98
+
99
+ # Output
100
+
101
+ The field's value is an html string, made of tags & inline styles only (the
102
+ editor's classes are removed), so that it renders the same on your website
103
+ without any stylesheet:
104
+
105
+ ```html
106
+ <p style="text-align: center;">
107
+ Subscribe to <strong>The Daily Oak</strong>,
108
+ <span style="color: hsl(0, 75%, 60%); font-size: 1.4em;">today</span>
109
+ </p>
110
+ ```
111
+
112
+ Selecting an element doesn't change its content: Lexical's formatting of the
113
+ html is only emitted once the content is edited. Inline values (e.g. a
114
+ button's plain text) are wrapped in a paragraph once edited.
115
+
116
+ # Collaboration
117
+
118
+ With `@oakjs/ash`'s collaboration (e.g. `@oakjs/ash/yjs`), the field:
119
+
120
+ - applies changes made by other users while you type, without moving your
121
+ caret (it moves along with the text changed before it);
122
+ - shares your cursor, and displays the other users' carets & selections.
123
+
124
+ Lexical's undo history is made of snapshots of the whole document, so it is
125
+ cleared when another user changes the field (the builder's own undo/redo
126
+ still works).