@folijs/react 0.0.0-stage → 0.2.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.
package/package.json CHANGED
@@ -1,6 +1,47 @@
1
1
  {
2
2
  "name": "@folijs/react",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.2.0",
4
+ "description": "React components for the Foli document editor.",
5
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/josep-audenis/foli.git",
9
+ "directory": "packages/react"
10
+ },
11
+ "homepage": "https://github.com/josep-audenis/foli#readme",
12
+ "bugs": "https://github.com/josep-audenis/foli/issues",
13
+ "type": "module",
14
+ "sideEffects": [
15
+ "*.css"
16
+ ],
17
+ "exports": {
18
+ ".": {
19
+ "types": "./dist/index.d.ts",
20
+ "default": "./dist/index.js"
21
+ },
22
+ "./styles.css": "./styles.css"
23
+ },
24
+ "files": [
25
+ "dist",
26
+ "CHANGELOG.md",
27
+ "src",
28
+ "styles.css",
29
+ "!src/**/*.test.*"
30
+ ],
31
+ "dependencies": {
32
+ "@folijs/core": "^0.2.0",
33
+ "@folijs/view": "^0.2.0"
34
+ },
35
+ "peerDependencies": {
36
+ "react": "^18.2.0 || ^19.0.0",
37
+ "react-dom": "^18.2.0 || ^19.0.0"
38
+ },
39
+ "devDependencies": {
40
+ "react": "^19.3.1",
41
+ "react-dom": "^19.3.1"
42
+ },
43
+ "scripts": {
44
+ "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
45
+ "typecheck": "tsc -p tsconfig.json --noEmit"
46
+ }
6
47
  }
@@ -0,0 +1,68 @@
1
+ import type { Editor } from "@folijs/core";
2
+ import { EditorView } from "@folijs/view";
3
+ import { forwardRef, useImperativeHandle, useRef } from "react";
4
+ import { useEditorOrContext, useIsomorphicLayoutEffect } from "./editor.js";
5
+
6
+ export interface FoliCanvasProps {
7
+ /** Default: the editor of the nearest `FoliEditorProvider`. */
8
+ editor?: Editor | undefined;
9
+ /** The user can read, select and copy, but not change the document. */
10
+ readOnly?: boolean | undefined;
11
+ /** Shown while the document is empty. */
12
+ placeholder?: string | undefined;
13
+ /** Accessible name of the editable area (default "Document"). */
14
+ label?: string | undefined;
15
+ className?: string | undefined;
16
+ }
17
+
18
+ /** What a `ref` on `FoliCanvas` gives. */
19
+ export interface FoliCanvasHandle {
20
+ /** Focuses the document and shows the editor's selection in it. */
21
+ focus(): void;
22
+ }
23
+
24
+ /**
25
+ * The editable document on real pages (size and margins from the document settings). The view
26
+ * owns the DOM inside it; React never renders children there.
27
+ */
28
+ export const FoliCanvas = forwardRef<FoliCanvasHandle, FoliCanvasProps>(function FoliCanvas(
29
+ { editor: given, readOnly = false, placeholder = "", label = "Document", className },
30
+ ref,
31
+ ) {
32
+ const editor = useEditorOrContext(given, "FoliCanvas");
33
+ const contentRef = useRef<HTMLDivElement>(null);
34
+ const viewRef = useRef<EditorView | null>(null);
35
+
36
+ useImperativeHandle(ref, () => ({ focus: () => viewRef.current?.focus() }), []);
37
+
38
+ useIsomorphicLayoutEffect(() => {
39
+ const host = contentRef.current;
40
+ if (!host) return;
41
+ const view = new EditorView(host, editor);
42
+ viewRef.current = view;
43
+ return () => {
44
+ view.destroy();
45
+ viewRef.current = null;
46
+ };
47
+ }, [editor]);
48
+
49
+ // Runs after the view is created (effects run in order): for a new view, and when the props change.
50
+ // biome-ignore lint/correctness/useExhaustiveDependencies: a new editor means a new view, which needs the options too.
51
+ useIsomorphicLayoutEffect(() => {
52
+ viewRef.current?.setOptions({ editable: !readOnly, placeholder });
53
+ }, [editor, readOnly, placeholder]);
54
+
55
+ return (
56
+ <div className={className ? `foli-canvas ${className}` : "foli-canvas"}>
57
+ {/* biome-ignore lint/a11y/useSemanticElements: EditorView makes this div a contenteditable rich-text box. */}
58
+ <div
59
+ ref={contentRef}
60
+ className="foli-content"
61
+ role="textbox"
62
+ aria-multiline="true"
63
+ aria-label={label}
64
+ tabIndex={0}
65
+ />
66
+ </div>
67
+ );
68
+ });
@@ -0,0 +1,103 @@
1
+ import {
2
+ createDocument,
3
+ type DocJSON,
4
+ type Editor,
5
+ type FoliDocument,
6
+ type Plugin,
7
+ type Transaction,
8
+ } from "@folijs/core";
9
+ import { forwardRef, type ReactNode, useImperativeHandle, useRef } from "react";
10
+ import { FoliEditorProvider, useFoliEditor, useIsomorphicLayoutEffect } from "./editor.js";
11
+ import { FoliCanvas, type FoliCanvasHandle, type FoliCanvasProps } from "./FoliCanvas.js";
12
+ import { FoliToolbar } from "./FoliToolbar.js";
13
+
14
+ /**
15
+ * A change to the document's content, as `FoliEditor` reports it. `document` is a getter:
16
+ * spreading the object or `JSON.stringify(change)` serializes the document (and walks `editor`).
17
+ */
18
+ export interface FoliChange {
19
+ readonly editor: Editor;
20
+ /** The transactions of this change (several when plugins append their own). */
21
+ readonly transactions: readonly Transaction[];
22
+ /**
23
+ * The whole document right after this change, serialized on first read (keep reads out of
24
+ * the hot path of typing: a debounced save reads only the last change's).
25
+ */
26
+ readonly document: FoliDocument;
27
+ }
28
+
29
+ export interface FoliEditorProps extends Omit<FoliCanvasProps, "editor"> {
30
+ /** Read once on mount. To load another document later: `editor.setDocument()` or a new `key`. */
31
+ initialContent?: FoliDocument | undefined;
32
+ /** Read once on mount. */
33
+ plugins?: readonly Plugin[] | undefined;
34
+ /**
35
+ * Called after every change to the document's content made through transactions (typing,
36
+ * commands, undo). Not for selection changes, and not for `editor.setDocument()`, whose
37
+ * caller already has the document.
38
+ */
39
+ onChange?: ((change: FoliChange) => void) | undefined;
40
+ /** Show the default `FoliToolbar` above the pages (default true). */
41
+ toolbar?: boolean | undefined;
42
+ /** Rendered between the toolbar and the pages, inside the editor's context. */
43
+ children?: ReactNode | undefined;
44
+ }
45
+
46
+ /** What a `ref` on `FoliEditor` gives: its editor (commands, `setDocument`…) and focus. */
47
+ export interface FoliEditorHandle extends FoliCanvasHandle {
48
+ readonly editor: Editor;
49
+ }
50
+
51
+ /**
52
+ * An editable document on real pages with a toolbar: creates its editor, provides it to
53
+ * `children` and shows it. Uncontrolled: the editor owns the document; React observes it
54
+ * through `onChange`, a parent reaches it through a `ref`.
55
+ */
56
+ export const FoliEditor = forwardRef<FoliEditorHandle, FoliEditorProps>(function FoliEditor(
57
+ { initialContent, plugins, onChange, toolbar = true, children, ...canvas },
58
+ ref,
59
+ ) {
60
+ const editor = useFoliEditor({ initialContent, plugins });
61
+ const onChangeRef = useRef(onChange);
62
+ const canvasRef = useRef<FoliCanvasHandle>(null);
63
+
64
+ useImperativeHandle(ref, () => ({ editor, focus: () => canvasRef.current?.focus() }), [editor]);
65
+
66
+ useIsomorphicLayoutEffect(() => {
67
+ onChangeRef.current = onChange;
68
+ });
69
+
70
+ useIsomorphicLayoutEffect(
71
+ () =>
72
+ editor.subscribe((state, transactions) => {
73
+ const listener = onChangeRef.current;
74
+ if (!listener || !transactions.some((tr) => tr.docChanged)) return;
75
+ // The state is immutable: keeping it makes a later read give this change's document.
76
+ const { settings } = editor;
77
+ let document: FoliDocument | undefined;
78
+ listener({
79
+ editor,
80
+ transactions,
81
+ get document() {
82
+ document ??= createDocument(state.doc.toJSON() as DocJSON, settings);
83
+ return document;
84
+ },
85
+ });
86
+ }),
87
+ [editor],
88
+ );
89
+
90
+ return (
91
+ <FoliEditorProvider editor={editor}>
92
+ {toolbar && (
93
+ <FoliToolbar
94
+ editor={editor}
95
+ disabled={canvas.readOnly}
96
+ onClickCommand={() => canvasRef.current?.focus()}
97
+ />
98
+ )}
99
+ {children}
100
+ <FoliCanvas ref={canvasRef} editor={editor} {...canvas} />
101
+ </FoliEditorProvider>
102
+ );
103
+ });