@atlaskit/editor-common 110.15.1 → 110.15.2

package/dist/types/experiences/Experience.d.ts

@@ -0,0 +1,41 @@
+import type { ExperienceCheck } from './ExperienceCheck';
+type ExperienceOptions = {
+    /**
+     * Checks used to determine experience completion, either success, or failure.
+     */
+    checks?: ExperienceCheck[];
+};
+type ExperienceFailureOptions = {
+    reason?: string;
+};
+export declare class Experience {
+    private readonly id;
+    private readonly options;
+    private _ufoExperience;
+    private check;
+    constructor(id: string, options?: ExperienceOptions);
+    private get ufoExperience();
+    private startCheck;
+    private stopCheck;
+    private isInProgress;
+    /**
+     * Starts UFO experience tracking and starts all checks which monitor for completion of the experience.
+     */
+    start(): void;
+    /**
+     * Manually mark the experience as successful and stop any ongoing checks.
+     */
+    success(): void;
+    /**
+     * Manually abort the experience and stop any ongoing checks.
+     *
+     * Typically used when the experience did not complete due to user action and should not be marked as success or failure,
+     * for example on unmount or when navigating away from a page.
+     */
+    abort(): void;
+    /**
+     * Manually mark the experience as failed and stop any ongoing checks.
+     */
+    failure({ reason }?: ExperienceFailureOptions): void;
+}
+export {};

package/dist/types/experiences/ExperienceCheck.d.ts

@@ -0,0 +1,14 @@
+type ExperienceCheckSuccessResult = {
+    status: 'success';
+};
+type ExperienceCheckFailureResult = {
+    reason?: string;
+    status: 'failure';
+};
+export type ExperienceCheckResult = ExperienceCheckSuccessResult | ExperienceCheckFailureResult;
+export type ExperienceCheckCallback = (result: ExperienceCheckResult) => void;
+export interface ExperienceCheck {
+    start: (callback: ExperienceCheckCallback) => void;
+    stop: () => void;
+}
+export {};

package/dist/types/experiences/ExperienceCheckComposite.d.ts

@@ -0,0 +1,12 @@
+import type { ExperienceCheck, ExperienceCheckCallback } from './ExperienceCheck';
+/**
+ * Composite check that combines multiple checks.
+ *
+ * Starts and stops all contained checks.
+ */
+export declare class ExperienceCheckComposite implements ExperienceCheck {
+    private checks;
+    constructor(checks: ExperienceCheck[]);
+    start(callback: ExperienceCheckCallback): void;
+    stop(): void;
+}

package/dist/types/experiences/ExperienceCheckDomMutation.d.ts

@@ -0,0 +1,53 @@
+import type { ExperienceCheck, ExperienceCheckCallback, ExperienceCheckResult } from './ExperienceCheck';
+export type ExperienceDomMutationCheckOptions = {
+    mutations: MutationRecord[];
+};
+export type ExperienceCheckDomMutationObserveConfig = {
+    /**
+     * MutationObserver options specifying what types of mutations to observe
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/observe
+     */
+    options: MutationObserverInit;
+    /**
+     * Target element to observe for mutations
+     */
+    target: Node;
+};
+export type ExperienceCheckDomMutationConfig = {
+    /**
+     * Callback that returns the MutationObserver configuration
+     *
+     * This is a callback to ensure consumers make explicit, conscious decisions about:
+     * - What element to observe (performance: smaller scope = better performance)
+     * - What mutations to monitor (performance: fewer types = better performance)
+     *
+     * IMPORTANT: Return null if the target element cannot be found.
+     * This will immediately fail the experience with reason 'target-not-found'.
+     *
+     * Common patterns:
+     * - Safe fallback: { target: document.querySelector('[data-testid="toolbar"]') ?? document.body, options: {...} }
+     * - Explicit null: const target = document.querySelector('[data-testid="toolbar"]'); return target ? { target, options: {...} } : null;
+     */
+    observeConfig: () => ExperienceCheckDomMutationObserveConfig | null;
+    /**
+     * Callback invoked when DOM mutations are detected
+     * Return a result to complete the experience, or undefined to continue observing
+     */
+    onDomMutation: (options: ExperienceDomMutationCheckOptions) => ExperienceCheckResult | undefined;
+};
+/**
+ * Check for the completion of an experience based on DOM mutations
+ *
+ * Uses a MutationObserver to monitor DOM changes and invokes the provided
+ * callback when relevant mutations are detected.
+ *
+ * Will result in success or failure based on the outcome of the callback.
+ */
+export declare class ExperienceCheckDomMutation implements ExperienceCheck {
+    private mutationObserver;
+    private onDomMutation;
+    private observeConfig;
+    constructor({ onDomMutation, observeConfig }: ExperienceCheckDomMutationConfig);
+    start(callback: ExperienceCheckCallback): void;
+    stop(): void;
+}

package/dist/types/experiences/ExperienceCheckTimeout.d.ts

@@ -0,0 +1,13 @@
+import type { ExperienceCheck, ExperienceCheckCallback } from './ExperienceCheck';
+/**
+ * Check for the completion of an experience based on a timeout
+ *
+ * Will always result in failure after the timeout duration
+ */
+export declare class ExperienceCheckTimeout implements ExperienceCheck {
+    private timeoutId;
+    private maxDurationMs;
+    constructor(maxDurationMs: number);
+    start(callback: ExperienceCheckCallback): void;
+    stop(): void;
+}

package/dist/types/experiences/consts.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Built-in failure reasons for experience checks
+ *
+ * These are used by the various ExperienceCheck implementations to
+ * provide consistent, well-known failure reasons for analytics and debugging.
+ */
+export declare const EXPERIENCE_FAILURE_REASON: {
+    /**
+     * Experience timed out before completion
+     */
+    readonly TIMEOUT: "timeout";
+    /**
+     * Target element could not be found when starting DOM mutation observation
+     */
+    readonly DOM_MUTATION_TARGET_NOT_FOUND: "dom-mutation-target-not-found";
+    /**
+     * Error occurred during DOM mutation check execution
+     */
+    readonly DOM_MUTATION_CHECK_ERROR: "dom-mutation-check-error";
+};

package/dist/types/experiences/index.d.ts

@@ -0,0 +1,7 @@
+export { Experience } from './Experience';
+export { EXPERIENCE_FAILURE_REASON } from './consts';
+export { ExperienceCheckComposite } from './ExperienceCheckComposite';
+export { ExperienceCheckDomMutation } from './ExperienceCheckDomMutation';
+export { ExperienceCheckTimeout } from './ExperienceCheckTimeout';
+export type { ExperienceCheck, ExperienceCheckCallback, ExperienceCheckResult, } from './ExperienceCheck';
+export type { ExperienceCheckDomMutationConfig, ExperienceCheckDomMutationObserveConfig, ExperienceDomMutationCheckOptions, } from './ExperienceCheckDomMutation';

package/dist/types-ts4.5/block-menu/block-link.d.ts

@@ -0,0 +1,17 @@
+export declare const DEFAULT_BLOCK_LINK_HASH_PREFIX = "block-";
+/**
+ * Matches hashes that start with the block link prefix followed by a UUID
+ *
+ * @param hash The hash string to check (e.g., '#block-123e4567-e89b-12d3-a456-426614174000' or 'block-123e4567-e89b-12d3-a456-426614174000')
+ * @param prefix The prefix to look for (default is 'block-')
+ * @returns True if the hash matches the block link pattern, false otherwise
+ */
+export declare const isBlockLinkHash: (hash: string, prefix?: string) => boolean;
+/**
+ * Extracts the block ID from a block link hash.
+ *
+ * @param hash The hash string to extract the block ID from (e.g., '#block-123e4567-e89b-12d3-a456-426614174000' or 'block-123e4567-e89b-12d3-a456-426614174000')
+ * @param prefix The prefix to look for (default is 'block-')
+ * @returns The extracted block ID if the hash is valid, null otherwise
+ */
+export declare const extractBlockIdFromLinkHash: (hash: string, prefix?: string) => string | null;

package/dist/types-ts4.5/block-menu/index.d.ts

@@ -1,3 +1,4 @@
 export { messages } from './messages';
 export { FORMAT_HEADING_1_MENU_ITEM, FORMAT_HEADING_2_MENU_ITEM, FORMAT_HEADING_3_MENU_ITEM, FORMAT_HEADING_4_MENU_ITEM, FORMAT_HEADING_5_MENU_ITEM, FORMAT_HEADING_6_MENU_ITEM, FORMAT_PARAGRAPH_MENU_ITEM, FORMAT_QUOTE_MENU_ITEM, FORMAT_EXPAND_MENU_ITEM, FORMAT_LAYOUT_MENU_ITEM, FORMAT_PANEL_MENU_ITEM, FORMAT_CODE_BLOCK_MENU_ITEM, FORMAT_BULLETED_LIST_MENU_ITEM, FORMAT_NUMBERED_LIST_MENU_ITEM, FORMAT_TASK_LIST_MENU_ITEM, NESTED_FORMAT_MENU_SECTION, COPY_MENU_SECTION, DELETE_MENU_SECTION, MOVE_UP_DOWN_MENU_SECTION, FORMAT_MENU_ITEM, COPY_BLOCK_MENU_ITEM, COPY_LINK_MENU_ITEM, MOVE_UP_MENU_ITEM, MOVE_DOWN_MENU_ITEM, DELETE_MENU_ITEM, NESTED_FORMAT_MENU, PRIMARY_MENU_SECTION, ADD_BLOCKS_MENU_SECTION, CREATE_SYNCED_BLOCK_MENU_ITEM, } from './key';
 export { FORMAT_NESTED_MENU_RANK, FORMAT_NESTED_MENU_RANK_REVISED, BLOCK_MENU_SECTION_RANK, PRIMARY_MENU_SECTION_RANK, COPY_MENU_SECTION_RANK, DELETE_SECTION_RANK, MOVE_BLOCK_SECTION_RANK, ADD_BLOCKS_MENU_SECTION_RANK, } from './rank';
+export { DEFAULT_BLOCK_LINK_HASH_PREFIX, isBlockLinkHash, extractBlockIdFromLinkHash, } from './block-link';

package/dist/types-ts4.5/experiences/Experience.d.ts

@@ -0,0 +1,41 @@
+import type { ExperienceCheck } from './ExperienceCheck';
+type ExperienceOptions = {
+    /**
+     * Checks used to determine experience completion, either success, or failure.
+     */
+    checks?: ExperienceCheck[];
+};
+type ExperienceFailureOptions = {
+    reason?: string;
+};
+export declare class Experience {
+    private readonly id;
+    private readonly options;
+    private _ufoExperience;
+    private check;
+    constructor(id: string, options?: ExperienceOptions);
+    private get ufoExperience();
+    private startCheck;
+    private stopCheck;
+    private isInProgress;
+    /**
+     * Starts UFO experience tracking and starts all checks which monitor for completion of the experience.
+     */
+    start(): void;
+    /**
+     * Manually mark the experience as successful and stop any ongoing checks.
+     */
+    success(): void;
+    /**
+     * Manually abort the experience and stop any ongoing checks.
+     *
+     * Typically used when the experience did not complete due to user action and should not be marked as success or failure,
+     * for example on unmount or when navigating away from a page.
+     */
+    abort(): void;
+    /**
+     * Manually mark the experience as failed and stop any ongoing checks.
+     */
+    failure({ reason }?: ExperienceFailureOptions): void;
+}
+export {};

package/dist/types-ts4.5/experiences/ExperienceCheck.d.ts

@@ -0,0 +1,14 @@
+type ExperienceCheckSuccessResult = {
+    status: 'success';
+};
+type ExperienceCheckFailureResult = {
+    reason?: string;
+    status: 'failure';
+};
+export type ExperienceCheckResult = ExperienceCheckSuccessResult | ExperienceCheckFailureResult;
+export type ExperienceCheckCallback = (result: ExperienceCheckResult) => void;
+export interface ExperienceCheck {
+    start: (callback: ExperienceCheckCallback) => void;
+    stop: () => void;
+}
+export {};

package/dist/types-ts4.5/experiences/ExperienceCheckComposite.d.ts

@@ -0,0 +1,12 @@
+import type { ExperienceCheck, ExperienceCheckCallback } from './ExperienceCheck';
+/**
+ * Composite check that combines multiple checks.
+ *
+ * Starts and stops all contained checks.
+ */
+export declare class ExperienceCheckComposite implements ExperienceCheck {
+    private checks;
+    constructor(checks: ExperienceCheck[]);
+    start(callback: ExperienceCheckCallback): void;
+    stop(): void;
+}

package/dist/types-ts4.5/experiences/ExperienceCheckDomMutation.d.ts

@@ -0,0 +1,53 @@
+import type { ExperienceCheck, ExperienceCheckCallback, ExperienceCheckResult } from './ExperienceCheck';
+export type ExperienceDomMutationCheckOptions = {
+    mutations: MutationRecord[];
+};
+export type ExperienceCheckDomMutationObserveConfig = {
+    /**
+     * MutationObserver options specifying what types of mutations to observe
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/observe
+     */
+    options: MutationObserverInit;
+    /**
+     * Target element to observe for mutations
+     */
+    target: Node;
+};
+export type ExperienceCheckDomMutationConfig = {
+    /**
+     * Callback that returns the MutationObserver configuration
+     *
+     * This is a callback to ensure consumers make explicit, conscious decisions about:
+     * - What element to observe (performance: smaller scope = better performance)
+     * - What mutations to monitor (performance: fewer types = better performance)
+     *
+     * IMPORTANT: Return null if the target element cannot be found.
+     * This will immediately fail the experience with reason 'target-not-found'.
+     *
+     * Common patterns:
+     * - Safe fallback: { target: document.querySelector('[data-testid="toolbar"]') ?? document.body, options: {...} }
+     * - Explicit null: const target = document.querySelector('[data-testid="toolbar"]'); return target ? { target, options: {...} } : null;
+     */
+    observeConfig: () => ExperienceCheckDomMutationObserveConfig | null;
+    /**
+     * Callback invoked when DOM mutations are detected
+     * Return a result to complete the experience, or undefined to continue observing
+     */
+    onDomMutation: (options: ExperienceDomMutationCheckOptions) => ExperienceCheckResult | undefined;
+};
+/**
+ * Check for the completion of an experience based on DOM mutations
+ *
+ * Uses a MutationObserver to monitor DOM changes and invokes the provided
+ * callback when relevant mutations are detected.
+ *
+ * Will result in success or failure based on the outcome of the callback.
+ */
+export declare class ExperienceCheckDomMutation implements ExperienceCheck {
+    private mutationObserver;
+    private onDomMutation;
+    private observeConfig;
+    constructor({ onDomMutation, observeConfig }: ExperienceCheckDomMutationConfig);
+    start(callback: ExperienceCheckCallback): void;
+    stop(): void;
+}

package/dist/types-ts4.5/experiences/ExperienceCheckTimeout.d.ts

@@ -0,0 +1,13 @@
+import type { ExperienceCheck, ExperienceCheckCallback } from './ExperienceCheck';
+/**
+ * Check for the completion of an experience based on a timeout
+ *
+ * Will always result in failure after the timeout duration
+ */
+export declare class ExperienceCheckTimeout implements ExperienceCheck {
+    private timeoutId;
+    private maxDurationMs;
+    constructor(maxDurationMs: number);
+    start(callback: ExperienceCheckCallback): void;
+    stop(): void;
+}

package/dist/types-ts4.5/experiences/consts.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Built-in failure reasons for experience checks
+ *
+ * These are used by the various ExperienceCheck implementations to
+ * provide consistent, well-known failure reasons for analytics and debugging.
+ */
+export declare const EXPERIENCE_FAILURE_REASON: {
+    /**
+     * Experience timed out before completion
+     */
+    readonly TIMEOUT: "timeout";
+    /**
+     * Target element could not be found when starting DOM mutation observation
+     */
+    readonly DOM_MUTATION_TARGET_NOT_FOUND: "dom-mutation-target-not-found";
+    /**
+     * Error occurred during DOM mutation check execution
+     */
+    readonly DOM_MUTATION_CHECK_ERROR: "dom-mutation-check-error";
+};

package/dist/types-ts4.5/experiences/index.d.ts

@@ -0,0 +1,7 @@
+export { Experience } from './Experience';
+export { EXPERIENCE_FAILURE_REASON } from './consts';
+export { ExperienceCheckComposite } from './ExperienceCheckComposite';
+export { ExperienceCheckDomMutation } from './ExperienceCheckDomMutation';
+export { ExperienceCheckTimeout } from './ExperienceCheckTimeout';
+export type { ExperienceCheck, ExperienceCheckCallback, ExperienceCheckResult, } from './ExperienceCheck';
+export type { ExperienceCheckDomMutationConfig, ExperienceCheckDomMutationObserveConfig, ExperienceDomMutationCheckOptions, } from './ExperienceCheckDomMutation';

package/experiences/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@atlaskit/editor-common/experiences",
+  "main": "../dist/cjs/experiences/index.js",
+  "module": "../dist/esm/experiences/index.js",
+  "module:es2019": "../dist/es2019/experiences/index.js",
+  "sideEffects": [
+    "**/*.compiled.css"
+  ],
+  "types": "../dist/types/experiences/index.d.ts",
+  "typesVersions": {
+    ">=4.5 <5.9": {
+      "*": [
+        "../dist/types-ts4.5/experiences/index.d.ts"
+      ]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/editor-common",
-	"version": "110.15.1",
+	"version": "110.15.2",
 	"description": "A package that contains common classes and components for editor and renderer",
 	"publishConfig": {
 		"registry": "https://registry.npmjs.org/"
@@ -54,7 +54,7 @@
 		"@atlaskit/icon": "^28.5.0",
 		"@atlaskit/icon-object": "^7.3.0",
 		"@atlaskit/link": "^3.2.0",
-		"@atlaskit/link-datasource": "^4.26.0",
+		"@atlaskit/link-datasource": "^4.27.0",
 		"@atlaskit/link-picker": "^3.16.0",
 		"@atlaskit/media-card": "^79.5.0",
 		"@atlaskit/media-client": "^35.5.0",
@@ -82,9 +82,10 @@
 		"@atlaskit/task-decision": "^19.2.0",
 		"@atlaskit/textfield": "^8.0.0",
 		"@atlaskit/theme": "^21.0.0",
-		"@atlaskit/tmp-editor-statsig": "^13.15.0",
+		"@atlaskit/tmp-editor-statsig": "^13.16.0",
 		"@atlaskit/tokens": "^7.0.0",
 		"@atlaskit/tooltip": "^20.6.0",
+		"@atlaskit/ufo": "^0.4.0",
 		"@atlaskit/width-detector": "^5.0.0",
 		"@babel/runtime": "^7.0.0",
 		"@compiled/react": "^0.18.6",