@byline/richtext-lexical 5.2.0 → 6.0.1

package/dist/field/normalize/declared-conversions.js

@@ -0,0 +1,93 @@
+const BLOCK_TYPES = new Set([
+    'paragraph',
+    'heading',
+    'quote',
+    'code',
+    'list',
+    'listitem',
+    'table',
+    'tablerow',
+    'tablecell',
+    'layout-container',
+    'layout-item',
+    'admonition',
+    'horizontalrule',
+    'youtube',
+    'vimeo'
+]);
+function isBlockType(type) {
+    return BLOCK_TYPES.has(type);
+}
+const INLINE_TYPES = new Set([
+    'text',
+    'linebreak',
+    'tab',
+    'link',
+    'autolink',
+    'mark',
+    'overflow',
+    'code-highlight',
+    'inline-image'
+]);
+function isInlineType(type) {
+    return INLINE_TYPES.has(type);
+}
+const urlText = (node)=>{
+    const attributes = node.attributes;
+    const url = 'string' == typeof node.url ? node.url : attributes?.url;
+    return 'string' == typeof url && url.length > 0 ? url : void 0;
+};
+const DECLARED_CONVERSIONS = {
+    heading: {
+        kind: 'to-paragraph'
+    },
+    quote: {
+        kind: 'to-paragraph'
+    },
+    code: {
+        kind: 'to-paragraph'
+    },
+    listitem: {
+        kind: 'to-paragraph'
+    },
+    table: {
+        kind: 'lift-blocks'
+    },
+    tablerow: {
+        kind: 'lift-blocks'
+    },
+    tablecell: {
+        kind: 'lift-blocks'
+    },
+    list: {
+        kind: 'lift-blocks'
+    },
+    'layout-container': {
+        kind: 'lift-blocks'
+    },
+    'layout-item': {
+        kind: 'lift-blocks'
+    },
+    admonition: {
+        kind: 'lift-blocks',
+        preserveText: (node)=>'string' == typeof node.title && node.title.length > 0 ? node.title : void 0
+    },
+    'code-highlight': {
+        kind: 'to-text'
+    },
+    link: {
+        kind: 'unwrap-inline',
+        preserveText: urlText
+    },
+    autolink: {
+        kind: 'unwrap-inline',
+        preserveText: urlText
+    },
+    horizontalrule: {
+        kind: 'drop'
+    }
+};
+function conversionFor(type) {
+    return DECLARED_CONVERSIONS[type];
+}
+export { BLOCK_TYPES, DECLARED_CONVERSIONS, INLINE_TYPES, conversionFor, isBlockType, isInlineType };

package/dist/field/normalize/normalization-status.d.ts

@@ -0,0 +1,33 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import type * as React from 'react';
+export type NormalizationStatus = {
+    kind: 'ok';
+} | {
+    kind: 'adapted';
+    convertedTypes: string[];
+} | {
+    kind: 'refused';
+    unsupportedTypes: string[];
+};
+interface ContextValue {
+    status: NormalizationStatus;
+    setStatus: (status: NormalizationStatus) => void;
+}
+/**
+ * Carries how the stored value fared against this field's capabilities.
+ *
+ * Provided ABOVE the composer, like the other shared contexts, so the
+ * surface that renders the notice sits outside the editor while the
+ * plugin that discovers the status sits inside it.
+ */
+export declare function NormalizationStatusProvider({ children, }: {
+    children: React.ReactNode;
+}): React.JSX.Element;
+export declare function useNormalizationStatus(): ContextValue;
+export {};

package/dist/field/normalize/normalization-status.js

@@ -0,0 +1,28 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo, useState } from "react";
+const Context = /*#__PURE__*/ createContext({
+    status: {
+        kind: 'ok'
+    },
+    setStatus: ()=>{}
+});
+function NormalizationStatusProvider({ children }) {
+    const [status, setStatus] = useState({
+        kind: 'ok'
+    });
+    const value = useMemo(()=>({
+            status,
+            setStatus
+        }), [
+        status
+    ]);
+    return /*#__PURE__*/ jsx(Context.Provider, {
+        value: value,
+        children: children
+    });
+}
+function useNormalizationStatus() {
+    return useContext(Context);
+}
+export { NormalizationStatusProvider, useNormalizationStatus };

package/dist/field/normalize/normalize-value.d.ts

@@ -0,0 +1,38 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import type { SerializedEditorState } from 'lexical';
+export type NormalizeResult = {
+    status: 'unchanged';
+} | {
+    status: 'adapted';
+    value: SerializedEditorState;
+    convertedTypes: string[];
+} | {
+    status: 'refused';
+    unsupportedTypes: string[];
+};
+/**
+ * Adapt a stored value to what an editor can actually accept.
+ *
+ * Lexical throws `parseEditorState: type "X" + not found` on an
+ * unregistered type and the text is unrecoverable, so a field that no
+ * longer supports a structure would otherwise open blank and erroring.
+ *
+ * Only the unsupported nodes are converted. A supported node is copied
+ * with its own properties intact — it was already in a valid position in
+ * the saved document, so its position is never changed — while its
+ * children are still inspected, because a supported parent may hold an
+ * unsupported descendant. Re-encoding supported content to fix an
+ * unrelated structure is exactly what this must not do: an inline image
+ * sitting beside a heading would lose its media relation and its
+ * nested-editor caption as collateral.
+ *
+ * The input is never mutated. Refusal wins over any conversion, so the
+ * whole tree is walked before a decision is returned.
+ */
+export declare function normalizeValue(value: SerializedEditorState, supportedTypes: ReadonlySet<string>): NormalizeResult;

package/dist/field/normalize/normalize-value.js

@@ -0,0 +1,132 @@
+import { conversionFor, isBlockType, isInlineType } from "./declared-conversions.js";
+const textNode = (text)=>({
+        detail: 0,
+        format: 0,
+        mode: 'normal',
+        style: '',
+        text,
+        type: 'text',
+        version: 1
+    });
+const textFromNode = (node)=>({
+        detail: 'number' == typeof node.detail ? node.detail : 0,
+        format: 'number' == typeof node.format ? node.format : 0,
+        mode: 'string' == typeof node.mode ? node.mode : 'normal',
+        style: 'string' == typeof node.style ? node.style : '',
+        text: 'string' == typeof node.text ? node.text : '',
+        type: 'text',
+        version: 1
+    });
+const paragraphNode = (children)=>({
+        children,
+        direction: null,
+        format: '',
+        indent: 0,
+        type: 'paragraph',
+        version: 1
+    });
+function normalizeValue(value, supportedTypes) {
+    const converted = new Set();
+    const refused = new Set();
+    function groupIntoBlocks(nodes) {
+        const out = [];
+        let run = [];
+        const flush = ()=>{
+            if (run.length > 0) {
+                out.push(paragraphNode(run));
+                run = [];
+            }
+        };
+        for (const node of nodes){
+            if (isInlineType(node.type)) {
+                run.push(node);
+                continue;
+            }
+            if (!isBlockType(node.type)) refused.add(node.type);
+            flush();
+            out.push(node);
+        }
+        flush();
+        return out;
+    }
+    function visit(node) {
+        const children = Array.isArray(node.children) ? node.children : void 0;
+        if ('root' === node.type || supportedTypes.has(node.type)) return null == children ? [
+            node
+        ] : [
+            {
+                ...node,
+                children: children.flatMap(visit)
+            }
+        ];
+        const conversion = conversionFor(node.type);
+        if (null == conversion) {
+            refused.add(node.type);
+            return [
+                node
+            ];
+        }
+        converted.add(node.type);
+        const preserved = conversion.preserveText?.(node);
+        const inner = (children ?? []).flatMap(visit);
+        switch(conversion.kind){
+            case 'drop':
+                return [];
+            case 'to-paragraph':
+                {
+                    const children = null != preserved ? [
+                        ...inner,
+                        textNode(` ${preserved}`)
+                    ] : inner;
+                    const grouped = groupIntoBlocks(children);
+                    return grouped.length > 0 ? grouped : [
+                        paragraphNode([])
+                    ];
+                }
+            case 'to-text':
+                return [
+                    textFromNode(node)
+                ];
+            case 'lift-blocks':
+                return null != preserved ? [
+                    paragraphNode([
+                        textNode(preserved)
+                    ]),
+                    ...inner
+                ] : inner;
+            case 'unwrap-inline':
+                return null != preserved ? [
+                    ...inner,
+                    textNode(` ${preserved}`)
+                ] : inner;
+        }
+    }
+    const visited = visit(value.root)[0];
+    if (refused.size > 0) return {
+        status: 'refused',
+        unsupportedTypes: [
+            ...refused
+        ]
+    };
+    if (0 === converted.size) return {
+        status: 'unchanged'
+    };
+    const children = Array.isArray(visited.children) ? visited.children : [];
+    const nextRoot = {
+        ...visited,
+        children: children.length > 0 ? children : [
+            paragraphNode([])
+        ]
+    };
+    return {
+        status: 'adapted',
+        value: {
+            ...value,
+            root: nextRoot
+        },
+        convertedTypes: [
+            ...converted
+        ]
+    };
+}
+export { normalizeValue };

package/dist/field/normalize/use-notice-text.d.ts

@@ -0,0 +1,11 @@
+export interface NoticeText {
+    t: (key: string, values?: Record<string, string>) => string;
+    locale: string;
+}
+/**
+ * Translate a notice, tolerating the absence of an I18nProvider.
+ *
+ * Reads `I18nContext` directly rather than calling `useTranslation`,
+ * which throws without a provider.
+ */
+export declare function useNoticeText(): NoticeText;

package/dist/field/normalize/use-notice-text.js

@@ -0,0 +1,34 @@
+"use client";
+import { useContext, useMemo } from "react";
+import { I18nContext } from "@byline/i18n/react";
+const FALLBACKS = {
+    'richtext.adapted.notice': 'This content contains formatting this editor no longer supports. Saving edits will use the supported formatting.',
+    'richtext.unsupported.notice': 'This content contains {items}, which this field no longer supports. The field is read-only so the content is not lost.',
+    'richtext.unsupported.action': 'Ask an administrator to restore support for it, or to migrate the content.',
+    'richtext.content.image': 'an image',
+    'richtext.content.youtube': 'a YouTube embed',
+    'richtext.content.vimeo': 'a Vimeo embed'
+};
+function useNoticeText() {
+    const context = useContext(I18nContext);
+    return useMemo(()=>{
+        if (null == context) return {
+            locale: 'en',
+            t: (key, values)=>interpolate(FALLBACKS[key] ?? key, values)
+        };
+        return {
+            locale: context.activeLocale,
+            t: (key, values)=>{
+                const translated = context.formatter.t('byline-admin', key, values);
+                return translated === key ? interpolate(FALLBACKS[key] ?? key, values) : translated;
+            }
+        };
+    }, [
+        context
+    ]);
+}
+function interpolate(template, values) {
+    if (null == values) return template;
+    return template.replace(/\{(\w+)\}/g, (match, name)=>values[name] ?? match);
+}
+export { useNoticeText };

package/dist/field/plugins/toolbar-plugin/index.d.ts

@@ -13,4 +13,27 @@
  *
  */
 import type * as React from 'react';
+import type { LexicalEditor } from 'lexical';
+export type BlockFormat = 'paragraph' | 'h1' | 'h2' | 'h3' | 'h4' | 'bullet' | 'number' | 'check' | 'quote' | 'code';
+/**
+ * Block formats this editor can actually produce. Paragraph is always
+ * available.
+ *
+ * Structural availability comes from REGISTERED NODES, not from whether
+ * an extension appears in the configuration list: table and list nodes
+ * arrive through `@lexical/table` and `@lexical/list` dependencies, so a
+ * membership test would be wrong for exactly those cases.
+ *
+ * Registered nodes are necessary but not always sufficient.
+ * `hasCheckListBehaviour` is passed in because check lists need
+ * `CheckListExtension` registered as well as the list nodes — removing
+ * that extension alone leaves `ListNode` and `ListItemNode` in place, so
+ * a node-only rule would keep offering a control that no longer works.
+ *
+ * This is a correctness concern rather than a cosmetic one: creating an
+ * unregistered node throws "Attempted to create node X that was not
+ * configured to be used on the editor", so an offered-but-unsupported
+ * format is a crash.
+ */
+export declare function availableBlockFormats(editor: LexicalEditor, hasCheckListBehaviour: boolean): BlockFormat[];
 export declare function ToolbarPlugin(): React.JSX.Element;