@uxf/wysiwyg 11.126.0 → 11.127.0

package/README.md

@@ -110,17 +110,18 @@ Everything below is exported from the package root (`@uxf/wysiwyg`) unless a dee
 
 `import { WysiwygEditor } from "@uxf/wysiwyg";`
 
-| Prop                          | Type                              | Required | Description                                                                                                                                                                                          |
-| ----------------------------- | --------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id`                          | `string`                          | yes      | Unique Plate instance id. Must be unique per editor on the page.                                                                                                                                     |
-| `initialValue`                | `WysiwygContent \| undefined`     | yes      | Document the editor is seeded with on mount.                                                                                                                                                         |
-| `onChange`                    | `(value: WysiwygContent) => void` | yes      | Called on every edit with the full document.                                                                                                                                                         |
-| `plugins`                     | `UxfPlatePlugin[]`                | yes      | Build with `createAllPluginsWithUi` / `createPluginsWithUi`.                                                                                                                                         |
-| `className`                   | `string`                          | no       | Class on the editor root wrapper.                                                                                                                                                                    |
-| `editableProps`               | `TEditableProps<WysiwygContent>`  | no       | Passed to Plate's editable area (`placeholder`, `readOnly`, `autoFocus`, `spellCheck`, `className`, …). Defaults: `autoFocus: false`, `readOnly: false`, `spellCheck: false`, localized placeholder. |
-| `customPluginsToolbarButtons` | `ReactNode`                       | no       | Extra toolbar buttons appended to the built-in ones.                                                                                                                                                 |
-| `toolbarLeftElement`          | `ReactNode`                       | no       | Node rendered at the toolbar's left edge.                                                                                                                                                            |
-| `toolbarRightElement`         | `ReactNode`                       | no       | Node rendered at the toolbar's right edge.                                                                                                                                                           |
+| Prop                          | Type                                | Required | Description                                                                                                                                                                                          |
+| ----------------------------- | ----------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                          | `string`                            | yes      | Unique Plate instance id. Must be unique per editor on the page.                                                                                                                                     |
+| `initialValue`                | `WysiwygContent \| undefined`       | yes      | Document the editor is seeded with on mount.                                                                                                                                                         |
+| `onChange`                    | `(value: WysiwygContent) => void`   | yes      | Called on every edit with the full document.                                                                                                                                                         |
+| `plugins`                     | `UxfPlatePlugin[]`                  | yes      | Build with `createAllPluginsWithUi` / `createPluginsWithUi`.                                                                                                                                         |
+| `className`                   | `string`                            | no       | Class on the editor root wrapper.                                                                                                                                                                    |
+| `editableProps`               | `TEditableProps<WysiwygContent>`    | no       | Passed to Plate's editable area (`placeholder`, `readOnly`, `autoFocus`, `spellCheck`, `className`, …). Defaults: `autoFocus: false`, `readOnly: false`, `spellCheck: false`, localized placeholder. |
+| `editorRef`                   | `ForwardedRef<WysiwygEditorHandle>` | no       | Imperative handle exposing `focus()`, which selects the end of the document and then focuses the editable area.                                                                                      |
+| `customPluginsToolbarButtons` | `ReactNode`                         | no       | Extra toolbar buttons appended to the built-in ones.                                                                                                                                                 |
+| `toolbarLeftElement`          | `ReactNode`                         | no       | Node rendered at the toolbar's left edge.                                                                                                                                                            |
+| `toolbarRightElement`         | `ReactNode`                         | no       | Node rendered at the toolbar's right edge.                                                                                                                                                           |
 
 ### Plugin builders
 
@@ -180,6 +181,21 @@ serializeToPlaintext(value); // keepIndentation defaults to true (joins blocks w
 
 ### Types
 
+`WysiwygEditorHandle` — the shape behind `editorRef`:
+
+```tsx
+import { WysiwygEditor } from "@uxf/wysiwyg";
+// deep import: this type is not re-exported from the package index
+import { WysiwygEditorHandle } from "@uxf/wysiwyg/wysiwyg-editor";
+import { useRef } from "react";
+
+const editorRef = useRef<WysiwygEditorHandle>(null);
+
+<WysiwygEditor editorRef={editorRef} id="body" initialValue={value} onChange={setValue} plugins={plugins} />;
+
+editorRef.current?.focus(); // caret goes to the end of the document
+```
+
 The full node model and editor types are re-exported, including: `WysiwygContent`, `WysiwygRootBlock`, `RichText`, the element interfaces (`UxfParagraphElement`, `UxfHeadingElement`, `UxfBlockQuoteElement`, `UxfLinkElement`, `UxfImageElement`, `UxfVideoElement`, `UxfButtonElement`, `UxfUnorderedListElement`, `UxfOrderedListElement`, `LiElement`, `LicElement`), plus `UxfEditor`, `UxfPlatePlugin`, `WysiwygPlugin`, `WysiwygRecursivePlugin`, and the render prop/component types (`RenderElementProps`, `ElementUiComponent`, `RenderLeafProps`, `LeafUiComponent`, `RenderAfterEditable`, `MyOverrideByKey`, `UiComponents`).
 
 ## Gotchas
@@ -189,6 +205,7 @@ The full node model and editor types are re-exported, including: `WysiwygContent
 - **Build plugins with the provided factories.** Pass only the results of `createPluginsWithUi` / `createAllPluginsWithUi` to `plugins`; they inject the required base plugins. Do not hand-assemble raw Plate plugin arrays.
 - **CSS is required and Tailwind-dependent.** Without `@uxf/wysiwyg/styles/styles.css` the editor is unstyled; the file relies on your Tailwind/PostCSS setup and `@uxf/ui`'s `uxf-typo-*` utilities.
 - **Translations are required.** Register `@uxf/wysiwyg/translations/translations`, otherwise labels/tooltips render as raw keys.
+- **`WysiwygEditorHandle` is not on the package index.** `index.ts` exports only the `WysiwygEditor` component, so the ref type has to come from the deep import `@uxf/wysiwyg/wysiwyg-editor` — which is what `@uxf/cms`'s own `WysiwygInput` does.
 - **Pinned peers.** Plate/Slate and `@uxf/*` peer versions are pinned exactly (see `package.json`); mismatched versions will not work.
 
 ## Links

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@uxf/wysiwyg",
-    "version": "11.126.0",
+    "version": "11.127.0",
     "description": "UXF Wysiwyg editor",
     "author": "Robin Dvorak <dvorak@uxf.cz>",
     "homepage": "https://gitlab.com/uxf-npm/wysiwyg",
@@ -31,9 +31,9 @@
         "@udecode/slate": "19.8.0",
         "@udecode/slate-react": "19.7.1",
         "@udecode/slate-utils": "19.7.1",
-        "@uxf/core": "11.126.0",
-        "@uxf/core-react": "11.126.0",
-        "@uxf/ui": "11.126.0",
+        "@uxf/core": "11.127.0",
+        "@uxf/core-react": "11.127.0",
+        "@uxf/ui": "11.127.0",
         "react": ">=18.2.0",
         "react-dom": ">=18.2.0",
         "slate": "0.90.0",
@@ -62,9 +62,9 @@
         "@udecode/slate": "19.8.0",
         "@udecode/slate-react": "19.7.1",
         "@udecode/slate-utils": "19.7.1",
-        "@uxf/core": "11.126.0",
-        "@uxf/core-react": "11.126.0",
-        "@uxf/ui": "11.126.0",
+        "@uxf/core": "11.127.0",
+        "@uxf/core-react": "11.127.0",
+        "@uxf/ui": "11.127.0",
         "react": "18.3.1",
         "react-dom": "18.3.1",
         "slate": "0.90.0",

package/wysiwyg-editor.d.ts

@@ -1,10 +1,15 @@
 import { TEditableProps } from "@udecode/plate-core";
-import { FC, ReactNode } from "react";
+import { Noop } from "@uxf/core/types";
+import { FC, ForwardedRef, ReactNode } from "react";
 import { UxfPlatePlugin, WysiwygContent } from "./types";
+export interface WysiwygEditorHandle {
+    focus: Noop;
+}
 export interface WysiwygEditorProps {
     className?: string;
     customPluginsToolbarButtons?: ReactNode;
     editableProps?: TEditableProps<WysiwygContent>;
+    editorRef?: ForwardedRef<WysiwygEditorHandle>;
     id: string;
     initialValue: WysiwygContent | undefined;
     onChange: (value: WysiwygContent) => void;

package/wysiwyg-editor.js

@@ -1,8 +1,38 @@
 "use strict";
 "use client";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.WysiwygEditor = void 0;
 const plate_core_1 = require("@udecode/plate-core");
@@ -10,9 +40,30 @@ const classes_1 = require("@uxf/core/constants/classes");
 const use_is_mounted_1 = require("@uxf/core-react/hooks/use-is-mounted");
 const translations_1 = require("@uxf/core-react/translations");
 const loader_1 = require("@uxf/ui/loader");
-const react_1 = __importDefault(require("react"));
+const react_1 = __importStar(require("react"));
+const slate_1 = require("slate");
+const hooks_1 = require("./hooks");
 const toolbar_1 = require("./ui/toolbar/toolbar");
+const utils_1 = require("./utils");
 const CLASS_NAME = "uxf-wysiwyg";
+/**
+ * Component that accesses the editor from Slate context and exposes focus method via ref
+ * Must be rendered inside Plate component
+ */
+const EditorRefHandler = (0, react_1.forwardRef)((props, ref) => {
+    const editor = (0, hooks_1.useUxfEditorRef)();
+    (0, react_1.useImperativeHandle)(ref, () => ({
+        focus: () => {
+            // Select the end of the document first
+            const end = slate_1.Editor.end(editor, []);
+            slate_1.Transforms.select(editor, end);
+            // Then focus the editor
+            (0, utils_1.focusEditor)(editor);
+        },
+    }));
+    return null;
+});
+EditorRefHandler.displayName = "EditorRefHandler";
 const Editor = (props) => {
     var _a, _b;
     const t = (0, translations_1.useUxfTranslation)();
@@ -26,7 +77,8 @@ const Editor = (props) => {
                     spellCheck: false,
                     ...props.editableProps,
                     className: `${CLASS_NAME}__editable ${(_b = (_a = props.editableProps) === null || _a === void 0 ? void 0 : _a.className) !== null && _b !== void 0 ? _b : ""}`,
-                }, id: props.plateId, normalizeInitialValue: true }))));
+                }, id: props.plateId, normalizeInitialValue: true }),
+            props.editorRef && react_1.default.createElement(EditorRefHandler, { ref: props.editorRef }))));
 };
 const WysiwygEditor = (props) => {
     var _a, _b;
@@ -37,6 +89,6 @@ const WysiwygEditor = (props) => {
     }
     return (react_1.default.createElement("div", { className: `${CLASS_NAME} ${(_b = props.className) !== null && _b !== void 0 ? _b : ""}` },
         react_1.default.createElement(plate_core_1.PlateProvider, { id: props.id, initialValue: props.initialValue, onChange: props.onChange, plugins: props.plugins },
-            react_1.default.createElement(Editor, { customPluginsToolbarButtons: props.customPluginsToolbarButtons, editableProps: props.editableProps, plateId: props.id, toolbarLeftElement: props.toolbarLeftElement, toolbarRightElement: props.toolbarRightElement }))));
+            react_1.default.createElement(Editor, { customPluginsToolbarButtons: props.customPluginsToolbarButtons, editableProps: props.editableProps, editorRef: props.editorRef, plateId: props.id, toolbarLeftElement: props.toolbarLeftElement, toolbarRightElement: props.toolbarRightElement }))));
 };
 exports.WysiwygEditor = WysiwygEditor;