@sveltia/ui 0.20.2 → 0.21.0

package/package/components/text-editor/core.d.ts

@@ -1,3 +1,5 @@
-export function initEditor(): import("lexical").LexicalEditor;
+export function initEditor({ components }?: {
+    components?: import("../../typedefs").TextEditorComponent[] | undefined;
+} | undefined): import("lexical").LexicalEditor;
 export function convertMarkdown(editor: import("lexical").LexicalEditor, value: string): Promise<void>;
 export function focusEditor(editor: import("lexical").LexicalEditor): Promise<void>;

package/package/components/text-editor/core.js

@@ -43,6 +43,8 @@ import {
 } from 'lexical';
 import { blockButtonTypes, textFormatButtonTypes } from '.';
 
+const allTransformers = [...TRANSFORMERS];
+
 /**
  * Lexical editor configuration.
  * @type {import('lexical').CreateEditorArgs}
@@ -78,27 +80,28 @@ const editorConfig = {
 };
 
 /**
- * Listen to changes on the editor.
- * @param {import('lexical').LexicalEditor} editor - Editor instance.
+ * Get the current selection’s block and inline level types.
+ * @returns {{ blockType: import('../../typedefs').TextEditorBlockType,
+ * inlineTypes: import('../../typedefs').TextEditorInlineType[] }} Types.
  */
-const onEditorUpdate = (editor) => {
+const getSelectionTypes = () => {
   const selection = getSelection();
 
   if (!isRangeSelection(selection)) {
-    return;
+    return { blockType: 'paragraph', inlineTypes: [] };
   }
 
   const anchor = selection.anchor.getNode();
   /** @type {ElementNode | null} */
   let parent = null;
   /** @type {import('../../typedefs').TextEditorInlineType[]} */
-  const selectionInlineTypes = textFormatButtonTypes.filter((type) => selection.hasFormat(type));
+  const inlineTypes = textFormatButtonTypes.filter((type) => selection.hasFormat(type));
 
   if (anchor.getType() !== 'root') {
     parent = anchor instanceof ElementNode ? anchor : getNearestNodeOfType(anchor, ElementNode);
 
     if (isLinkNode(parent)) {
-      selectionInlineTypes.push('link');
+      inlineTypes.push('link');
       parent = getNearestNodeOfType(parent, ElementNode);
     }
 
@@ -107,7 +110,7 @@ const onEditorUpdate = (editor) => {
     }
   }
 
-  const selectionBlockType = /** @type {import('../../typedefs').TextEditorBlockType} */ (
+  const blockType = /** @type {import('../../typedefs').TextEditorBlockType} */ (
     (() => {
       if (!parent) {
         return 'paragraph';
@@ -135,15 +138,25 @@ const onEditorUpdate = (editor) => {
     })()
   );
 
+  return { blockType, inlineTypes };
+};
+
+/**
+ * Listen to changes made on the editor and trigger the Update event.
+ * @param {import('lexical').LexicalEditor} editor - Editor instance.
+ */
+const onEditorUpdate = (editor) => {
+  const { blockType, inlineTypes } = getSelectionTypes();
+
   editor.getRootElement()?.dispatchEvent(
     new CustomEvent('Update', {
       detail: {
         value: convertToMarkdownString(
           // Use underscores for italic text in Markdown instead of asterisks
-          TRANSFORMERS.filter((/** @type {any} */ { tag }) => tag !== '*'),
+          allTransformers.filter((/** @type {any} */ { tag }) => tag !== '*'),
         ),
-        selectionBlockType,
-        selectionInlineTypes,
+        selectionBlockType: blockType,
+        selectionInlineTypes: inlineTypes,
       },
     }),
   );
@@ -151,9 +164,16 @@ const onEditorUpdate = (editor) => {
 
 /**
  * Initialize the Lexical editor.
+ * @param {object} [options] - Options.
+ * @param {import('../../typedefs').TextEditorComponent[]} [options.components] - Editor components.
  * @returns {import('lexical').LexicalEditor} Editor instance.
  */
-export const initEditor = () => {
+export const initEditor = ({ components } = {}) => {
+  components?.forEach(({ node, transformer }) => {
+    /** @type {any[]} */ (editorConfig.nodes).unshift(node);
+    allTransformers.unshift(transformer);
+  });
+
   const editor = createEditor(editorConfig);
 
   registerRichText(editor);
@@ -254,10 +274,10 @@ export const convertMarkdown = async (editor, value) =>
   new Promise((resolve, reject) => {
     editor.update(() => {
       try {
-        convertFromMarkdownString(value, TRANSFORMERS);
+        convertFromMarkdownString(value, allTransformers);
         resolve(void 0);
-      } catch {
-        reject(new Error('Failed to convert Markdown'));
+      } catch (ex) {
+        reject(new Error('Failed to convert Markdown', { cause: ex }));
       }
     });
   });

package/package/components/text-editor/lexical-root.svelte

@@ -1,5 +1,4 @@
 <script>
-  import { $createParagraphNode as createParagraphNode, $getRoot as getRoot } from 'lexical';
   import { getContext, onMount } from 'svelte';
 
   /**
@@ -97,11 +96,6 @@
   $effect(() => {
     if ($editor && lexicalRoot) {
       $editor.setRootElement(lexicalRoot);
-      // We should avoid an empty editor; there should be at least one `<p>`
-      // @see https://github.com/facebook/lexical/issues/2308
-      $editor.update(() => {
-        getRoot().append(createParagraphNode());
-      });
     }
   });
 </script>

package/package/components/text-editor/text-editor.svelte

@@ -22,6 +22,7 @@
    * @property {import('../../typedefs').TextEditorMode[]} [modes] - Enabled modes.
    * @property {(import('../../typedefs').TextEditorBlockType |
    * import('../../typedefs').TextEditorInlineType)[]} [buttons] - Enabled buttons.
+   * @property {import('../../typedefs').TextEditorComponent[]} [components] - Editor components.
    * @property {string} [class] - The `class` attribute on the wrapper element.
    * @property {boolean} [hidden] - Whether to hide the widget.
    * @property {boolean} [disabled] - Whether to disable the widget. An alias of the `aria-disabled`
@@ -44,6 +45,7 @@
     flex = false,
     modes = ['rich-text', 'plain-text'],
     buttons = [...inlineButtonTypes, ...blockButtonTypes],
+    components = [],
     hidden = false,
     disabled = false,
     readonly = false,
@@ -69,7 +71,7 @@
    * restore the original value when there is an error while conversion.
    */
   const convertMarkdown = async () => {
-    if (!$editor) {
+    if (!$editor?.getRootElement()) {
       return;
     }
 
@@ -80,16 +82,16 @@
       // string if the `value` is `undefined`
       // @see https://github.com/facebook/lexical/issues/2308
       await convertMarkdownToLexical($editor, inputValue ?? '');
-    } catch {
+    } catch (ex) {
       $hasConverterError = true;
       inputValue = originalValue;
+      // eslint-disable-next-line no-console
+      console.error(ex);
     }
   };
 
   $effect(() => {
-    if (!$editor) {
-      return;
-    }
+    void $editor;
 
     const newValue = value;
 
@@ -129,7 +131,7 @@
 
   // The editor has to be initialized in the browser
   onMount(() => {
-    $editor = initEditor();
+    $editor = initEditor({ components });
   });
 
   setContext(
@@ -143,6 +145,7 @@
       useRichText,
       hasConverterError,
       enabledButtons: buttons,
+      components,
       convertMarkdown,
     }),
   );

package/package/components/text-editor/text-editor.svelte.d.ts

@@ -21,6 +21,10 @@ declare const TextEditor: import("svelte").Component<{
      * - Enabled buttons.
      */
     buttons?: (import("../../typedefs").TextEditorBlockType | import("../../typedefs").TextEditorInlineType)[] | undefined;
+    /**
+     * - Editor components.
+     */
+    components?: import("../../typedefs").TextEditorComponent[] | undefined;
     /**
      * - The `class` attribute on the wrapper element.
      */
@@ -71,6 +75,10 @@ type Props = {
      * - Enabled buttons.
      */
     buttons?: (import("../../typedefs").TextEditorBlockType | import("../../typedefs").TextEditorInlineType)[] | undefined;
+    /**
+     * - Editor components.
+     */
+    components?: import("../../typedefs").TextEditorComponent[] | undefined;
     /**
      * - The `class` attribute on the wrapper element.
      */

package/package/components/text-editor/toolbar/editor-toolbar.svelte

@@ -12,7 +12,9 @@
   import Menu from '../../menu/menu.svelte';
   import Toolbar from '../../toolbar/toolbar.svelte';
   import FormatTextButton from './format-text-button.svelte';
+  import InsertImageButton from './insert-image-button.svelte';
   import InsertLinkButton from './insert-link-button.svelte';
+  import InsertMenuButton from './insert-menu-button.svelte';
   import ToggleBlockMenuItem from './toggle-block-menu-item.svelte';
 
   /**
@@ -45,9 +47,13 @@
     useRichText,
     hasConverterError,
     enabledButtons,
+    components,
     convertMarkdown,
   } = getContext('state');
 
+  const imageComponent = $derived(components.find(({ id }) => id === 'image'));
+  const otherComponents = $derived(components.filter(({ id }) => id !== 'image'));
+
   /**
    * Enabled block level buttons.
    * @type {import('../../../typedefs').TextEditorBlockType[]}
@@ -100,6 +106,15 @@
         {/each}
       </ButtonGroup>
     {/if}
+    {#if components.length}
+      <Divider orientation="vertical" />
+      {#if imageComponent}
+        <InsertImageButton component={imageComponent} />
+      {/if}
+      {#if otherComponents.length}
+        <InsertMenuButton components={otherComponents} />
+      {/if}
+    {/if}
     <Spacer flex />
     {#if modes.length > 1}
       <Button

package/package/components/text-editor/toolbar/insert-image-button.svelte

@@ -0,0 +1,43 @@
+<script>
+  import {
+    $createParagraphNode as createParagraphNode,
+    $insertNodes as insertNodes,
+  } from 'lexical';
+  import { getContext } from 'svelte';
+  import Button from '../../button/button.svelte';
+  import Icon from '../../icon/icon.svelte';
+
+  /**
+   * @typedef {object} Props
+   * @property {import('../../../typedefs').TextEditorComponent} component - Image editor component.
+   */
+
+  /** @type {Props} */
+  let {
+    /* eslint-disable prefer-const */
+    component,
+    /* eslint-enable prefer-const */
+  } = $props();
+
+  /**
+   * Text editor state.
+   * @type {import('../../../typedefs').TextEditorState}
+   */
+  const { editor, editorId, useRichText } = getContext('state');
+</script>
+
+<Button
+  iconic
+  aria-label={component.label}
+  aria-controls="{$editorId}-lexical-root"
+  disabled={!$useRichText}
+  onclick={() => {
+    $editor.update(() => {
+      insertNodes([component.createNode(), createParagraphNode()]);
+    });
+  }}
+>
+  {#snippet startIcon()}
+    <Icon name={component.icon} />
+  {/snippet}
+</Button>

package/package/components/text-editor/toolbar/insert-image-button.svelte.d.ts

@@ -0,0 +1,17 @@
+export default InsertImageButton;
+type InsertImageButton = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<Props>): void;
+};
+declare const InsertImageButton: import("svelte").Component<{
+    /**
+     * - Image editor component.
+     */
+    component: import("../../../typedefs").TextEditorComponent;
+}, {}, "">;
+type Props = {
+    /**
+     * - Image editor component.
+     */
+    component: import("../../../typedefs").TextEditorComponent;
+};

package/package/components/text-editor/toolbar/insert-menu-button.svelte

@@ -0,0 +1,53 @@
+<script>
+  import { $insertNodes as insertNodes } from 'lexical';
+  import { getContext } from 'svelte';
+  import { _ } from 'svelte-i18n';
+  import Icon from '../../icon/icon.svelte';
+  import MenuButton from '../../menu/menu-button.svelte';
+  import MenuItem from '../../menu/menu-item.svelte';
+  import Menu from '../../menu/menu.svelte';
+
+  /**
+   * @typedef {object} Props
+   * @property {import('../../../typedefs').TextEditorComponent[]} components - Editor components.
+   */
+
+  /** @type {Props} */
+  let {
+    /* eslint-disable prefer-const */
+    components,
+    /* eslint-enable prefer-const */
+  } = $props();
+
+  /**
+   * Text editor state.
+   * @type {import('../../../typedefs').TextEditorState}
+   */
+  const { editor, useRichText } = getContext('state');
+</script>
+
+<MenuButton disabled={!$useRichText} label={$_('_sui.insert')}>
+  {#snippet endIcon()}
+    <Icon name="arrow_drop_down" class="small-arrow" />
+  {/snippet}
+  {#snippet popup()}
+    <Menu>
+      {#each components as { id, label, icon, createNode } (id)}
+        <MenuItem
+          {label}
+          onclick={() => {
+            $editor.update(() => {
+              insertNodes([createNode()]);
+            });
+          }}
+        >
+          {#snippet startIcon()}
+            {#if icon}
+              <Icon name={icon} />
+            {/if}
+          {/snippet}
+        </MenuItem>
+      {/each}
+    </Menu>
+  {/snippet}
+</MenuButton>

package/package/components/text-editor/toolbar/insert-menu-button.svelte.d.ts

@@ -0,0 +1,17 @@
+export default InsertMenuButton;
+type InsertMenuButton = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<Props>): void;
+};
+declare const InsertMenuButton: import("svelte").Component<{
+    /**
+     * - Editor components.
+     */
+    components: import("../../../typedefs").TextEditorComponent[];
+}, {}, "">;
+type Props = {
+    /**
+     * - Editor components.
+     */
+    components: import("../../../typedefs").TextEditorComponent[];
+};

package/package/typedefs.d.ts

@@ -549,6 +549,33 @@ export type TextEditorBlockType = "paragraph" | "heading-1" | "heading-2" | "hea
 export type TextEditorFormatType = "bold" | "italic" | "code";
 export type TextEditorInlineType = TextEditorFormatType | "link";
 export type TextEditorMode = "rich-text" | "plain-text";
+export type TextEditorComponent = {
+    /**
+     * - Component ID.
+     */
+    id: string;
+    /**
+     * - Component label.
+     */
+    label: string;
+    /**
+     * - Material Symbols icon name.
+     */
+    icon?: string | undefined;
+    /**
+     * - Lexical node class implementation.
+     */
+    node: import("lexical").LexicalNode;
+    /**
+     * - Function
+     * to create a new node instance.
+     */
+    createNode: (props?: Record<string, any>) => import("lexical").LexicalNode;
+    /**
+     * - Node transformer.
+     */
+    transformer: import("@lexical/markdown").Transformer;
+};
 export type TextEditorState = {
     /**
      * - Lexical
@@ -588,6 +615,10 @@ export type TextEditorState = {
      * the editor.
      */
     enabledButtons: (TextEditorBlockType | TextEditorInlineType)[];
+    /**
+     * - Editor components.
+     */
+    components: TextEditorComponent[];
     /**
      * - Function to trigger the Lexical converter.
      */

package/package/typedefs.js

@@ -227,6 +227,17 @@
  * @typedef {'rich-text' | 'plain-text'} TextEditorMode
  */
 
+/**
+ * @typedef {object} TextEditorComponent
+ * @property {string} id - Component ID.
+ * @property {string} label - Component label.
+ * @property {string} [icon] - Material Symbols icon name.
+ * @property {import('lexical').LexicalNode} node - Lexical node class implementation.
+ * @property {(props?: Record<string, any>) => import('lexical').LexicalNode} createNode - Function
+ * to create a new node instance.
+ * @property {import('@lexical/markdown').Transformer} transformer - Node transformer.
+ */
+
 /**
  * @typedef {object} TextEditorState
  * @property {import('svelte/store').Writable<import('lexical').LexicalEditor>} editor - Lexical
@@ -243,6 +254,7 @@
  * error while converting Markdown to Lexical nodes.
  * @property {(TextEditorBlockType | TextEditorInlineType)[]} enabledButtons - Enabled buttons for
  * the editor.
+ * @property {TextEditorComponent[]} components - Editor components.
  * @property {Function} convertMarkdown - Function to trigger the Lexical converter.
  */
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sveltia/ui",
-  "version": "0.20.2",
+  "version": "0.21.0",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -38,16 +38,16 @@
     "@lexical/selection": "^0.21.0",
     "@lexical/table": "^0.21.0",
     "@lexical/utils": "^0.21.0",
-    "@sveltia/utils": "^0.5.0",
+    "@sveltia/utils": "^0.6.0",
     "lexical": "^0.21.0"
   },
   "peerDependencies": {
     "svelte": "^5.0.0"
   },
   "devDependencies": {
-    "@playwright/test": "^1.49.0",
+    "@playwright/test": "^1.49.1",
     "@sveltejs/adapter-auto": "^3.3.1",
-    "@sveltejs/kit": "^2.9.0",
+    "@sveltejs/kit": "^2.10.1",
     "@sveltejs/package": "^2.3.7",
     "@sveltejs/vite-plugin-svelte": "5.0.1",
     "cspell": "^8.16.1",
@@ -55,7 +55,7 @@
     "eslint-config-airbnb-base": "^15.0.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-import": "^2.31.0",
-    "eslint-plugin-jsdoc": "^50.6.0",
+    "eslint-plugin-jsdoc": "^50.6.1",
     "eslint-plugin-svelte": "^2.46.1",
     "postcss": "^8.4.49",
     "postcss-html": "^1.7.0",
@@ -65,7 +65,7 @@
     "stylelint": "^16.11.0",
     "stylelint-config-recommended-scss": "^14.1.0",
     "stylelint-scss": "^6.10.0",
-    "svelte": "5.7.1",
+    "svelte": "5.11.2",
     "svelte-check": "^4.1.1",
     "svelte-i18n": "^4.0.1",
     "svelte-preprocess": "^6.0.3",