@xplor-education/core-stencil-components 3.1.2 → 3.1.4

package/dist/types/components.d.ts

@@ -9,21 +9,25 @@ import { AssistantErrorEvent, AssistantMessageReceivedEvent, AssistantMessageSen
 import { AutocompleteItem } from "./components/xplor-autocomplete/xplor-autocomplete";
 import { Booking, BookingItem } from "./components/xplor-badge-session-booking/xplor-badge-session-booking";
 import { MenuOption } from "./components/xplor-btn-menu/xplor-btn-menu";
+import { Shape } from "./components/xplor-canvas-editor/xplor-canvas-editor";
 import { ComboboxItem } from "./components/xplor-combobox/xplor-combobox";
 import { DatatableColumn, DatatablePagination } from "./components/xplor-datatable/xplor-datatable";
 import { UploadedFile } from "./components/xplor-file-upload/xplor-file-upload";
 import { SelectOption } from "./components/xplor-input-select/xplor-input-select";
 import { NavTabItem } from "./components/xplor-nav-tabs/xplor-nav-tabs";
+import { RteChangePayload } from "./components/xplor-rich-text-editor/xplor-rich-text-editor";
 import { TooltipPosition, TooltipTrigger } from "./components/xplor-tooltip/xplor-tooltip";
 export { AssistantErrorEvent, AssistantMessageReceivedEvent, AssistantMessageSentEvent, AssistantSessionEvent } from "./components/xplor-assistant/internal/types";
 export { AutocompleteItem } from "./components/xplor-autocomplete/xplor-autocomplete";
 export { Booking, BookingItem } from "./components/xplor-badge-session-booking/xplor-badge-session-booking";
 export { MenuOption } from "./components/xplor-btn-menu/xplor-btn-menu";
+export { Shape } from "./components/xplor-canvas-editor/xplor-canvas-editor";
 export { ComboboxItem } from "./components/xplor-combobox/xplor-combobox";
 export { DatatableColumn, DatatablePagination } from "./components/xplor-datatable/xplor-datatable";
 export { UploadedFile } from "./components/xplor-file-upload/xplor-file-upload";
 export { SelectOption } from "./components/xplor-input-select/xplor-input-select";
 export { NavTabItem } from "./components/xplor-nav-tabs/xplor-nav-tabs";
+export { RteChangePayload } from "./components/xplor-rich-text-editor/xplor-rich-text-editor";
 export { TooltipPosition, TooltipTrigger } from "./components/xplor-tooltip/xplor-tooltip";
 export namespace Components {
     interface XplorAlertDialog {
@@ -480,6 +484,11 @@ export namespace Components {
           * @default false
          */
         "disabled": boolean;
+        /**
+          * Whether the button stretches to full width of its container
+          * @default false
+         */
+        "fullWidth": boolean;
         /**
           * Icon to display (defaults to plus sign)
           * @default '+'
@@ -502,6 +511,31 @@ export namespace Components {
          */
         "type": 'minimal' | 'primary' | 'secondary' | 'ghost' | 'disabled' | 'success' | 'text';
     }
+    interface XplorCanvasEditor {
+        /**
+          * Removes all shapes and clears the selection
+         */
+        "clearAll": () => Promise<void>;
+        /**
+          * Returns a shallow copy of all current shapes
+         */
+        "getShapes": () => Promise<Shape[]>;
+        /**
+          * Height of the SVG canvas in pixels
+          * @default 500
+         */
+        "height": number;
+        /**
+          * Initially active tool. The consumer can switch tool programmatically by updating this prop; the internal `activeTool` state takes over once the component mounts.
+          * @default 'select'
+         */
+        "tool": 'select' | 'rect' | 'circle' | 'line';
+        /**
+          * Width of the SVG canvas in pixels
+          * @default 800
+         */
+        "width": number;
+    }
     interface XplorChatWidget {
         "apiKey": string;
         /**
@@ -1435,6 +1469,93 @@ export namespace Components {
          */
         "value": string;
     }
+    interface XplorRichTextEditor {
+        /**
+          * Accessible label for the editor region. Used when no `label` prop or `ariaLabelledBy` is provided.
+          * @default ''
+         */
+        "ariaLabel": string;
+        /**
+          * ID of an external element that labels this editor (aria-labelledby).
+          * @default ''
+         */
+        "ariaLabelledBy": string;
+        /**
+          * Clears all content from the editor.
+         */
+        "clearContent": () => Promise<void>;
+        /**
+          * Whether the editor is disabled. Content cannot be edited or interacted with.
+          * @default false
+         */
+        "disabled": boolean;
+        /**
+          * Validation error message. Turns the editor border red and shows the message below.
+          * @default ''
+         */
+        "error": string;
+        /**
+          * Programmatically focuses the editor.
+         */
+        "focusEditor": () => Promise<void>;
+        /**
+          * Returns the current content as an HTML string.
+         */
+        "getHTMLContent": () => Promise<string>;
+        /**
+          * Returns the current content as plain text (all markup stripped).
+         */
+        "getText": () => Promise<string>;
+        /**
+          * Helper text shown below the editor when there is no error.
+          * @default ''
+         */
+        "helperText": string;
+        /**
+          * Visible label above the editor.
+          * @default ''
+         */
+        "label": string;
+        /**
+          * Stringified Slate 0.42.x document JSON for backwards compatibility. When supplied, this takes precedence over `value` as the initial content.
+          * @default ''
+         */
+        "legacySlateDocument": string;
+        /**
+          * Maximum character count. When set, a character counter is shown below the editor.
+          * @default undefined
+         */
+        "maxLength": number | undefined;
+        /**
+          * Placeholder text shown when the editor is empty.
+          * @default 'Start typing…'
+         */
+        "placeholder": string;
+        /**
+          * Whether the editor is in read-only mode. Content is visible but not editable. The toolbar is hidden in this mode.
+          * @default false
+         */
+        "readonly": boolean;
+        /**
+          * Marks the field as required. Adds an asterisk to the label.
+          * @default false
+         */
+        "required": boolean;
+        /**
+          * Replaces the editor content with the provided HTML string.
+         */
+        "setContent": (html: string) => Promise<void>;
+        /**
+          * Controls which toolbar buttons are rendered. - `full`    — All formatting options (default) - `minimal` — Text style buttons only (bold, italic, underline, strike, code) - `none`    — No toolbar; editor acts as a plain rich-text input
+          * @default 'full'
+         */
+        "toolbar": 'full' | 'minimal' | 'none';
+        /**
+          * HTML string content of the editor. Supports two-way binding via xplorChange.
+          * @default ''
+         */
+        "value": string;
+    }
     interface XplorSectionCard {
         /**
           * @default true
@@ -1709,6 +1830,10 @@ export interface XplorBtnToggleSecondaryCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLXplorBtnToggleSecondaryElement;
 }
+export interface XplorCanvasEditorCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLXplorCanvasEditorElement;
+}
 export interface XplorCheckboxCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLXplorCheckboxElement;
@@ -1797,6 +1922,10 @@ export interface XplorRadioBtnCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLXplorRadioBtnElement;
 }
+export interface XplorRichTextEditorCustomEvent<T> extends CustomEvent<T> {
+    detail: T;
+    target: HTMLXplorRichTextEditorElement;
+}
 export interface XplorTableCustomEvent<T> extends CustomEvent<T> {
     detail: T;
     target: HTMLXplorTableElement;
@@ -2077,6 +2206,25 @@ declare global {
         prototype: HTMLXplorButtonElement;
         new (): HTMLXplorButtonElement;
     };
+    interface HTMLXplorCanvasEditorElementEventMap {
+        "xplorShapeAdd": Shape;
+        "xplorShapeRemove": string;
+        "xplorShapeChange": Shape;
+    }
+    interface HTMLXplorCanvasEditorElement extends Components.XplorCanvasEditor, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLXplorCanvasEditorElementEventMap>(type: K, listener: (this: HTMLXplorCanvasEditorElement, ev: XplorCanvasEditorCustomEvent<HTMLXplorCanvasEditorElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLXplorCanvasEditorElementEventMap>(type: K, listener: (this: HTMLXplorCanvasEditorElement, ev: XplorCanvasEditorCustomEvent<HTMLXplorCanvasEditorElementEventMap[K]>) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    }
+    var HTMLXplorCanvasEditorElement: {
+        prototype: HTMLXplorCanvasEditorElement;
+        new (): HTMLXplorCanvasEditorElement;
+    };
     interface HTMLXplorChatWidgetElement extends Components.XplorChatWidget, HTMLStencilElement {
     }
     var HTMLXplorChatWidgetElement: {
@@ -2500,6 +2648,25 @@ declare global {
         prototype: HTMLXplorRadioBtnElement;
         new (): HTMLXplorRadioBtnElement;
     };
+    interface HTMLXplorRichTextEditorElementEventMap {
+        "xplorChange": RteChangePayload;
+        "xplorFocus": void;
+        "xplorBlur": void;
+    }
+    interface HTMLXplorRichTextEditorElement extends Components.XplorRichTextEditor, HTMLStencilElement {
+        addEventListener<K extends keyof HTMLXplorRichTextEditorElementEventMap>(type: K, listener: (this: HTMLXplorRichTextEditorElement, ev: XplorRichTextEditorCustomEvent<HTMLXplorRichTextEditorElementEventMap[K]>) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLXplorRichTextEditorElementEventMap>(type: K, listener: (this: HTMLXplorRichTextEditorElement, ev: XplorRichTextEditorCustomEvent<HTMLXplorRichTextEditorElementEventMap[K]>) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof DocumentEventMap>(type: K, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    }
+    var HTMLXplorRichTextEditorElement: {
+        prototype: HTMLXplorRichTextEditorElement;
+        new (): HTMLXplorRichTextEditorElement;
+    };
     interface HTMLXplorSectionCardElement extends Components.XplorSectionCard, HTMLStencilElement {
     }
     var HTMLXplorSectionCardElement: {
@@ -2607,6 +2774,7 @@ declare global {
         "xplor-btn-toggle-secondary": HTMLXplorBtnToggleSecondaryElement;
         "xplor-btn-tooltip": HTMLXplorBtnTooltipElement;
         "xplor-button": HTMLXplorButtonElement;
+        "xplor-canvas-editor": HTMLXplorCanvasEditorElement;
         "xplor-chat-widget": HTMLXplorChatWidgetElement;
         "xplor-checkbox": HTMLXplorCheckboxElement;
         "xplor-combobox": HTMLXplorComboboxElement;
@@ -2633,6 +2801,7 @@ declare global {
         "xplor-modal-persistent": HTMLXplorModalPersistentElement;
         "xplor-nav-tabs": HTMLXplorNavTabsElement;
         "xplor-radio-btn": HTMLXplorRadioBtnElement;
+        "xplor-rich-text-editor": HTMLXplorRichTextEditorElement;
         "xplor-section-card": HTMLXplorSectionCardElement;
         "xplor-section-heading": HTMLXplorSectionHeadingElement;
         "xplor-table": HTMLXplorTableElement;
@@ -3134,6 +3303,11 @@ declare namespace LocalJSX {
           * @default false
          */
         "disabled"?: boolean;
+        /**
+          * Whether the button stretches to full width of its container
+          * @default false
+         */
+        "fullWidth"?: boolean;
         /**
           * Icon to display (defaults to plus sign)
           * @default '+'
@@ -3156,6 +3330,35 @@ declare namespace LocalJSX {
          */
         "type"?: 'minimal' | 'primary' | 'secondary' | 'ghost' | 'disabled' | 'success' | 'text';
     }
+    interface XplorCanvasEditor {
+        /**
+          * Height of the SVG canvas in pixels
+          * @default 500
+         */
+        "height"?: number;
+        /**
+          * Emitted when a new shape is committed to the canvas
+         */
+        "onXplorShapeAdd"?: (event: XplorCanvasEditorCustomEvent<Shape>) => void;
+        /**
+          * Emitted when a shape's bounds are updated via resize
+         */
+        "onXplorShapeChange"?: (event: XplorCanvasEditorCustomEvent<Shape>) => void;
+        /**
+          * Emitted when a shape is removed; payload is the shape id
+         */
+        "onXplorShapeRemove"?: (event: XplorCanvasEditorCustomEvent<string>) => void;
+        /**
+          * Initially active tool. The consumer can switch tool programmatically by updating this prop; the internal `activeTool` state takes over once the component mounts.
+          * @default 'select'
+         */
+        "tool"?: 'select' | 'rect' | 'circle' | 'line';
+        /**
+          * Width of the SVG canvas in pixels
+          * @default 800
+         */
+        "width"?: number;
+    }
     interface XplorChatWidget {
         "apiKey"?: string;
         /**
@@ -4206,6 +4409,85 @@ declare namespace LocalJSX {
          */
         "value"?: string;
     }
+    interface XplorRichTextEditor {
+        /**
+          * Accessible label for the editor region. Used when no `label` prop or `ariaLabelledBy` is provided.
+          * @default ''
+         */
+        "ariaLabel"?: string;
+        /**
+          * ID of an external element that labels this editor (aria-labelledby).
+          * @default ''
+         */
+        "ariaLabelledBy"?: string;
+        /**
+          * Whether the editor is disabled. Content cannot be edited or interacted with.
+          * @default false
+         */
+        "disabled"?: boolean;
+        /**
+          * Validation error message. Turns the editor border red and shows the message below.
+          * @default ''
+         */
+        "error"?: string;
+        /**
+          * Helper text shown below the editor when there is no error.
+          * @default ''
+         */
+        "helperText"?: string;
+        /**
+          * Visible label above the editor.
+          * @default ''
+         */
+        "label"?: string;
+        /**
+          * Stringified Slate 0.42.x document JSON for backwards compatibility. When supplied, this takes precedence over `value` as the initial content.
+          * @default ''
+         */
+        "legacySlateDocument"?: string;
+        /**
+          * Maximum character count. When set, a character counter is shown below the editor.
+          * @default undefined
+         */
+        "maxLength"?: number | undefined;
+        /**
+          * Emitted when the editor loses focus.
+         */
+        "onXplorBlur"?: (event: XplorRichTextEditorCustomEvent<void>) => void;
+        /**
+          * Emitted whenever the content changes. Payload: `{ html: string; text: string; isEmpty: boolean }`
+         */
+        "onXplorChange"?: (event: XplorRichTextEditorCustomEvent<RteChangePayload>) => void;
+        /**
+          * Emitted when the editor gains focus.
+         */
+        "onXplorFocus"?: (event: XplorRichTextEditorCustomEvent<void>) => void;
+        /**
+          * Placeholder text shown when the editor is empty.
+          * @default 'Start typing…'
+         */
+        "placeholder"?: string;
+        /**
+          * Whether the editor is in read-only mode. Content is visible but not editable. The toolbar is hidden in this mode.
+          * @default false
+         */
+        "readonly"?: boolean;
+        /**
+          * Marks the field as required. Adds an asterisk to the label.
+          * @default false
+         */
+        "required"?: boolean;
+        /**
+          * Controls which toolbar buttons are rendered. - `full`    — All formatting options (default) - `minimal` — Text style buttons only (bold, italic, underline, strike, code) - `none`    — No toolbar; editor acts as a plain rich-text input
+          * @default 'full'
+         */
+        "toolbar"?: 'full' | 'minimal' | 'none';
+        /**
+          * HTML string content of the editor. Supports two-way binding via xplorChange.
+          * @default ''
+         */
+        "value"?: string;
+    }
     interface XplorSectionCard {
         /**
           * @default true
@@ -4486,6 +4768,7 @@ declare namespace LocalJSX {
         "xplor-btn-toggle-secondary": XplorBtnToggleSecondary;
         "xplor-btn-tooltip": XplorBtnTooltip;
         "xplor-button": XplorButton;
+        "xplor-canvas-editor": XplorCanvasEditor;
         "xplor-chat-widget": XplorChatWidget;
         "xplor-checkbox": XplorCheckbox;
         "xplor-combobox": XplorCombobox;
@@ -4512,6 +4795,7 @@ declare namespace LocalJSX {
         "xplor-modal-persistent": XplorModalPersistent;
         "xplor-nav-tabs": XplorNavTabs;
         "xplor-radio-btn": XplorRadioBtn;
+        "xplor-rich-text-editor": XplorRichTextEditor;
         "xplor-section-card": XplorSectionCard;
         "xplor-section-heading": XplorSectionHeading;
         "xplor-table": XplorTable;
@@ -4550,6 +4834,7 @@ declare module "@stencil/core" {
             "xplor-btn-toggle-secondary": LocalJSX.XplorBtnToggleSecondary & JSXBase.HTMLAttributes<HTMLXplorBtnToggleSecondaryElement>;
             "xplor-btn-tooltip": LocalJSX.XplorBtnTooltip & JSXBase.HTMLAttributes<HTMLXplorBtnTooltipElement>;
             "xplor-button": LocalJSX.XplorButton & JSXBase.HTMLAttributes<HTMLXplorButtonElement>;
+            "xplor-canvas-editor": LocalJSX.XplorCanvasEditor & JSXBase.HTMLAttributes<HTMLXplorCanvasEditorElement>;
             "xplor-chat-widget": LocalJSX.XplorChatWidget & JSXBase.HTMLAttributes<HTMLXplorChatWidgetElement>;
             "xplor-checkbox": LocalJSX.XplorCheckbox & JSXBase.HTMLAttributes<HTMLXplorCheckboxElement>;
             "xplor-combobox": LocalJSX.XplorCombobox & JSXBase.HTMLAttributes<HTMLXplorComboboxElement>;
@@ -4576,6 +4861,7 @@ declare module "@stencil/core" {
             "xplor-modal-persistent": LocalJSX.XplorModalPersistent & JSXBase.HTMLAttributes<HTMLXplorModalPersistentElement>;
             "xplor-nav-tabs": LocalJSX.XplorNavTabs & JSXBase.HTMLAttributes<HTMLXplorNavTabsElement>;
             "xplor-radio-btn": LocalJSX.XplorRadioBtn & JSXBase.HTMLAttributes<HTMLXplorRadioBtnElement>;
+            "xplor-rich-text-editor": LocalJSX.XplorRichTextEditor & JSXBase.HTMLAttributes<HTMLXplorRichTextEditorElement>;
             "xplor-section-card": LocalJSX.XplorSectionCard & JSXBase.HTMLAttributes<HTMLXplorSectionCardElement>;
             "xplor-section-heading": LocalJSX.XplorSectionHeading & JSXBase.HTMLAttributes<HTMLXplorSectionHeadingElement>;
             "xplor-table": LocalJSX.XplorTable & JSXBase.HTMLAttributes<HTMLXplorTableElement>;

package/dist/types/utils/slate-legacy-converter.d.ts

@@ -0,0 +1,83 @@
+/**
+ * slate-legacy-converter.ts
+ *
+ * Converts old Slate 0.42.x document JSON format into an HTML string.
+ * This is the backwards-compatibility layer for the xplor-rich-text-editor component.
+ *
+ * Old Slate 0.42.x document shape:
+ * {
+ *   document: {
+ *     nodes: [
+ *       {
+ *         object: 'block',
+ *         type: 'paragraph',
+ *         nodes: [
+ *           {
+ *             object: 'text',
+ *             text: 'Hello world',
+ *             marks: [{ type: 'bold' }]
+ *           }
+ *         ]
+ *       }
+ *     ]
+ *   }
+ * }
+ *
+ * No Slate runtime dependency required — this is a pure transformation function.
+ */
+export interface LegacySlateMark {
+    type: string;
+    data?: Record<string, unknown>;
+}
+export interface LegacySlateTextNode {
+    object: 'text';
+    text: string;
+    marks?: LegacySlateMark[];
+    leaves?: LegacySlateLeaf[];
+}
+/** Older Slate versions used "leaves" inside text nodes */
+export interface LegacySlateLeaf {
+    object?: 'leaf';
+    text: string;
+    marks?: LegacySlateMark[];
+}
+export interface LegacySlateInlineNode {
+    object: 'inline';
+    type: string;
+    data?: Record<string, unknown>;
+    nodes?: LegacySlateChildNode[];
+}
+export interface LegacySlateBlockNode {
+    object: 'block';
+    type: string;
+    data?: Record<string, unknown>;
+    nodes?: LegacySlateChildNode[];
+}
+export type LegacySlateChildNode = LegacySlateBlockNode | LegacySlateInlineNode | LegacySlateTextNode;
+export interface LegacySlateDocument {
+    object?: 'document';
+    nodes?: LegacySlateChildNode[];
+}
+export interface LegacySlateValue {
+    document: LegacySlateDocument;
+}
+/**
+ * Converts a Slate 0.42.x document value to an HTML string.
+ *
+ * @param value - The full Slate value object `{ document: { nodes: [...] } }`
+ *                or just the document object `{ nodes: [...] }` — both are accepted.
+ * @returns An HTML string, or an empty string if the input is null / invalid.
+ *
+ * @example
+ * const html = convertLegacySlateToHtml(JSON.parse(savedSlateJson));
+ * // '<p>Hello <strong>world</strong></p>'
+ */
+export declare function convertLegacySlateToHtml(value: LegacySlateValue | LegacySlateDocument | null | undefined): string;
+/**
+ * Safely parses a JSON string and converts it to HTML.
+ * Catches any parse errors and returns an empty string rather than throwing.
+ *
+ * @param json - A JSON string representing a Slate 0.42.x document
+ * @returns An HTML string, or an empty string if parsing fails.
+ */
+export declare function convertLegacySlateJsonToHtml(json: string): string;