@uxf/wysiwyg 11.125.0 → 11.127.0

package/README.md

@@ -80,10 +80,7 @@ To enable only some plugins, compose them yourself with `createPluginsWithUi`:
 ```tsx
 import { createBoldPluginWithUi, createHeadingsPluginWithUi, createPluginsWithUi } from "@uxf/wysiwyg";
 
-const plugins = createPluginsWithUi([
-    createHeadingsPluginWithUi({ disabledLevels: [1] }),
-    createBoldPluginWithUi(),
-]);
+const plugins = createPluginsWithUi([createHeadingsPluginWithUi({ disabledLevels: [1] }), createBoldPluginWithUi()]);
 ```
 
 ## Content model
@@ -113,55 +110,56 @@ 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
 
 `createPluginsWithUi` / `createAllPluginsWithUi` return the `UxfPlatePlugin[]` you pass to `WysiwygEditor`. Both inject the base plugins automatically (paragraph, exit-break, reset-node, soft-break, node-id, select-on-backspace, trailing-block), so pass only the feature builders below — not raw Plate plugins.
 
-| Export | Signature | Notes |
-| --- | --- | --- |
-| `createPluginsWithUi` | `(plugins: Array<WysiwygPlugin \| WysiwygRecursivePlugin<string>>, options?: { overrideByKey?: MyOverrideByKey }) => UxfPlatePlugin[]` | Compose a custom subset. |
-| `createAllPluginsWithUi` | `(options: CreateAllPluginsOptions) => UxfPlatePlugin[]` | Enable every plugin. |
-| `createHeadingsPluginWithUi` | `(options?: HeadingsPluginOptions) => WysiwygRecursivePlugin` | `disabledLevels?: (1..6)[]`. |
-| `createBoldPluginWithUi` | `() => WysiwygPlugin` | |
-| `createItalicPluginWithUi` | `() => WysiwygPlugin` | |
-| `createUnderlinePluginWithUi` | `() => WysiwygPlugin` | |
-| `createCodePluginWithUi` | `() => WysiwygPlugin` | |
-| `createHighlightPluginWithUi` | `(color?: CSSProperties["color"]) => WysiwygPlugin` | Defaults to `twColors.yellow[300]`. |
-| `createBlockquotePluginWithUi` | `() => WysiwygPlugin` | |
-| `createListPluginWithUi` | `() => WysiwygRecursivePlugin` | Renders `ul` / `ol` / `li`. |
-| `createLinkPluginWithUi` | `() => WysiwygPlugin` | |
-| `createImagePluginWithUi` | `(options: UxfImagePluginOptions) => WysiwygPlugin` | See options below. |
-| `createVideoPluginWithUi` | `() => WysiwygPlugin` | |
-| `createButtonPluginWithUi` | `() => WysiwygPlugin` | |
+| Export                         | Signature                                                                                                                              | Notes                               |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| `createPluginsWithUi`          | `(plugins: Array<WysiwygPlugin \| WysiwygRecursivePlugin<string>>, options?: { overrideByKey?: MyOverrideByKey }) => UxfPlatePlugin[]` | Compose a custom subset.            |
+| `createAllPluginsWithUi`       | `(options: CreateAllPluginsOptions) => UxfPlatePlugin[]`                                                                               | Enable every plugin.                |
+| `createHeadingsPluginWithUi`   | `(options?: HeadingsPluginOptions) => WysiwygRecursivePlugin`                                                                          | `disabledLevels?: (1..6)[]`.        |
+| `createBoldPluginWithUi`       | `() => WysiwygPlugin`                                                                                                                  |                                     |
+| `createItalicPluginWithUi`     | `() => WysiwygPlugin`                                                                                                                  |                                     |
+| `createUnderlinePluginWithUi`  | `() => WysiwygPlugin`                                                                                                                  |                                     |
+| `createCodePluginWithUi`       | `() => WysiwygPlugin`                                                                                                                  |                                     |
+| `createHighlightPluginWithUi`  | `(color?: CSSProperties["color"]) => WysiwygPlugin`                                                                                    | Defaults to `twColors.yellow[300]`. |
+| `createBlockquotePluginWithUi` | `() => WysiwygPlugin`                                                                                                                  |                                     |
+| `createListPluginWithUi`       | `() => WysiwygRecursivePlugin`                                                                                                         | Renders `ul` / `ol` / `li`.         |
+| `createLinkPluginWithUi`       | `() => WysiwygPlugin`                                                                                                                  |                                     |
+| `createImagePluginWithUi`      | `(options: UxfImagePluginOptions) => WysiwygPlugin`                                                                                    | See options below.                  |
+| `createVideoPluginWithUi`      | `() => WysiwygPlugin`                                                                                                                  |                                     |
+| `createButtonPluginWithUi`     | `() => WysiwygPlugin`                                                                                                                  |                                     |
 
 `CreateAllPluginsOptions`:
 
-| Key | Type | Required | Description |
-| --- | --- | --- | --- |
-| `image` | `UxfImagePluginOptions` | yes | Image plugin options (pass `{}` to enable without upload handlers). |
-| `headings` | `HeadingsPluginOptions` | no | e.g. `{ disabledLevels: [1] }`. |
-| `highlightColor` | `CSSProperties["color"]` | no | Highlight mark color. |
+| Key              | Type                     | Required | Description                                                         |
+| ---------------- | ------------------------ | -------- | ------------------------------------------------------------------- |
+| `image`          | `UxfImagePluginOptions`  | yes      | Image plugin options (pass `{}` to enable without upload handlers). |
+| `headings`       | `HeadingsPluginOptions`  | no       | e.g. `{ disabledLevels: [1] }`.                                     |
+| `highlightColor` | `CSSProperties["color"]` | no       | Highlight mark color.                                               |
 
 `UxfImagePluginOptions` (extends Plate's `MediaPlugin`):
 
-| Key | Type | Description |
-| --- | --- | --- |
-| `uploadImage` | `(file: File) => Promise<FileResponse>` | Upload handler; returns a `FileResponse` (`@uxf/core/types`). |
-| `getImageUrl` | `(file: FileResponse) => string` | Resolves the display URL for an uploaded file. |
-| `disableUploadOnPasteImageUrl` | `boolean` | Disable auto-upload when an image URL is pasted. |
-| `disableUploadOnPasteImage` | `boolean` | Disable auto-upload when an image blob is pasted. |
+| Key                            | Type                                    | Description                                                   |
+| ------------------------------ | --------------------------------------- | ------------------------------------------------------------- |
+| `uploadImage`                  | `(file: File) => Promise<FileResponse>` | Upload handler; returns a `FileResponse` (`@uxf/core/types`). |
+| `getImageUrl`                  | `(file: FileResponse) => string`        | Resolves the display URL for an uploaded file.                |
+| `disableUploadOnPasteImageUrl` | `boolean`                               | Disable auto-upload when an image URL is pasted.              |
+| `disableUploadOnPasteImage`    | `boolean`                               | Disable auto-upload when an image blob is pasted.             |
 
 ### Hooks
 
@@ -183,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
@@ -192,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.125.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.124.0",
-        "@uxf/core-react": "11.125.0",
-        "@uxf/ui": "11.125.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.124.0",
-        "@uxf/core-react": "11.125.0",
-        "@uxf/ui": "11.125.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;