@atlaskit/editor-common 111.11.7 → 111.11.9

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

@@ -1,25 +1,37 @@
 export declare const DEFAULT_BLOCK_LINK_HASH_PREFIX = "block-";
 /**
- * Matches hashes that start with the block link prefix followed by a UUID
+ * Matches hashes that start with the block link prefix followed by either:
+ * - A UUID (e.g., '123e4567-e89b-12d3-a456-426614174000')
+ * - A short hex ID (e.g., 'ab2366c43b52')
  *
- * @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
+ * Short hex IDs are 12-character hexadecimal strings without dashes, used in some contexts
+ * as a compact alternative to full UUIDs. Both formats are valid block identifiers.
+ *
+ * Note: The short ID pattern matches exactly 12 hex characters. While this could theoretically
+ * match heading IDs or other anchors, block links are typically generated programmatically
+ * with known ID formats, minimizing collision risk.
+ *
+ * @param hash - The hash string to check (e.g., '#block-123e4567-e89b-12d3-a456-426614174000', '#block-ab2366c43b52', or without '#').
+ * @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
+ * Supports both UUID format (e.g., '123e4567-e89b-12d3-a456-426614174000') and
+ * short hex ID format (e.g., 'ab2366c43b52').
+ *
+ * @param hash - The hash string to extract the block ID from (e.g., '#block-123e4567-e89b-12d3-a456-426614174000', '#block-ab2366c43b52', or without '#').
+ * @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;
 /**
  * Creates a block link hash from a given block ID.
  *
- * @param blockId The block ID to create the hash from (e.g., '123e4567-e89b-12d3-a456-426614174000')
- * @param prefix The prefix to use (default is 'block-')
- * @returns The constructed block link hash value (e.g., 'block-123e4567-e89b-12d3-a456-426614174000')
+ * @param blockId - The block ID to create the hash from (e.g., '123e4567-e89b-12d3-a456-426614174000').
+ * @param prefix - The prefix to use (default is 'block-').
+ * @returns The constructed block link hash value (e.g., 'block-123e4567-e89b-12d3-a456-426614174000').
  */
 export declare const createBlockLinkHashValue: (blockId: string, prefix?: string) => string;

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

@@ -4,4 +4,6 @@ export { FORMAT_HEADING_1_MENU_ITEM, FORMAT_HEADING_2_MENU_ITEM, FORMAT_HEADING_
 export { MAIN_BLOCK_MENU_SECTION_RANK, TRANSFORM_MENU_SECTION_RANK, TRANSFORM_MENU_ITEM_RANK, TRANSFORM_HEADINGS_MENU_SECTION_RANK, TRANSFORM_STRUCTURE_MENU_SECTION_RANK, TRANSFORM_CLEAR_MENU_SECTION_RANK, BLOCK_ACTIONS_MENU_SECTION_RANK, POSITION_MENU_SECTION_RANK, DELETE_MENU_SECTION_RANK, TRANSFORM_SUGGESTED_MENU_SECTION_RANK, TRANSFORM_CREATE_MENU_SECTION_RANK, } from './rank';
 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-deprecated';
 export { createBlockLinkHashValue, DEFAULT_BLOCK_LINK_HASH_PREFIX, extractBlockIdFromLinkHash, isBlockLinkHash, } from './block-link';
+export { expandAllParentsThenScroll, findParentExpands, isExpandCollapsed, expandElement, findNodeWithExpandParents, SCROLL_TO_BLOCK_TIMING, getLocalIdSelector, } from './scroll-to-block-utils';
+export type { NodeWithExpandParents } from './scroll-to-block-utils';
 export type { BlockMenuPlacement } from './placement';

package/dist/types-ts4.5/block-menu/scroll-to-block-utils.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Shared utilities for scrolling to block elements with expand node support.
+ * Used by both Confluence's useScrollOnUrlChange and platform renderer's useScrollToBlock.
+ */
+import type { DocNode } from '@atlaskit/adf-schema';
+/**
+ * Timing constants for expand animation and DOM update delays.
+ * These values are tuned for the expand component's behavior and React's update cycle.
+ */
+export declare const SCROLL_TO_BLOCK_TIMING: {
+    /** Minimal delay for DOM/React updates after expanding (no animation in expand component). */
+    readonly DOM_UPDATE_DELAY: 50;
+    /** Delay when expand operation fails and needs retry. */
+    readonly RETRY_DELAY: 100;
+    /** Maximum number of retry attempts before giving up and scrolling anyway. */
+    readonly MAX_ATTEMPTS: 5;
+    /** Maximum depth of nested expands to search (prevents infinite loops). */
+    readonly MAX_EXPAND_DEPTH: 2;
+};
+export type NodeWithExpandParents = {
+    /** Array of expand parent localIds (empty if no expand parents, ordered from outermost to innermost). */
+    expandParentLocalIds: string[];
+};
+/**
+ * Find a node by its localId in an ADF document and determine if it has expand or nestedExpand parents.
+ * This is used to identify nodes that may be hidden inside collapsed expands.
+ *
+ * @param adfDoc - The ADF document to search
+ * @param targetLocalId - The localId to search for
+ * @returns NodeWithExpandParents if found, undefined otherwise
+ */
+export declare function findNodeWithExpandParents(adfDoc: DocNode, targetLocalId: string): NodeWithExpandParents | undefined;
+/**
+ * Find all parent expand elements that contain the target element.
+ * Searches up the DOM tree to find expand or nestedExpand containers.
+ *
+ * This function limits the search depth to prevent infinite loops and performance issues.
+ * The default maxDepth of 2 is chosen because:
+ * - Most use cases have 0-2 levels of nesting
+ * - Searching deeper can impact performance
+ * - Users rarely nest expands more than 2 levels deep
+ *
+ * @param element - The target element to find parents for.
+ * @param maxDepth - Maximum depth to search (default: 2). This is the maximum number of
+ *                   expand ancestors to find, starting from the target element.
+ * @returns Array of expand containers ordered from outermost to innermost.
+ *          For example, if element is inside expand B which is inside expand A,
+ *          this returns [expandA, expandB].
+ */
+export declare const findParentExpands: (element: HTMLElement, maxDepth?: number) => HTMLElement[];
+/**
+ * Check if an expand node is currently collapsed.
+ *
+ * Uses two methods to determine collapse state:
+ * 1. First checks aria-expanded attribute on the toggle button (most reliable).
+ * 2. Falls back to checking content div visibility via computed styles.
+ *
+ * @param expandContainer - The expand container element.
+ * @returns True if the expand is collapsed, false if expanded or state cannot be determined.
+ */
+export declare const isExpandCollapsed: (expandContainer: HTMLElement) => boolean;
+/**
+ * Expand a collapsed expand node by clicking its toggle button.
+ *
+ * This function finds the toggle button with aria-expanded="false" and programmatically
+ * clicks it to expand the node. It does not wait for the expansion to complete.
+ *
+ * @param expandContainer - The expand container element.
+ * @returns True if the toggle button was found and clicked, false otherwise.
+ */
+export declare const expandElement: (expandContainer: HTMLElement) => boolean;
+/**
+ * Expand all parent expands then scroll to the element.
+ *
+ * This is the main entry point for scrolling to elements that may be hidden inside collapsed expands.
+ * It handles nested expands by expanding them one at a time from outermost to innermost,
+ * waiting for DOM updates between each expansion.
+ *
+ * The function uses a recursive approach with retry logic to handle:
+ * - Nested expands that need sequential expansion
+ * - DOM updates that may take time to reflect
+ * - Failed expand operations (e.g., if toggle button is temporarily unavailable)
+ * - Disconnected elements (removed from DOM)
+ *
+ * After all parent expands are open (or max attempts reached), scrolls the element into view
+ * with smooth behavior and centered in the viewport.
+ *
+ * @param element - The target element to scroll to.
+ * @param attempt - Current attempt number (used internally for retry logic, starts at 0).
+ * @returns A cleanup function that cancels any pending timeouts. Call this when the operation
+ *          should be aborted (e.g., component unmount, navigation, or new scroll request).
+ */
+export declare const expandAllParentsThenScroll: (element: HTMLElement, attempt?: number) => (() => void);
+export declare const getLocalIdSelector: (localId: string, container: HTMLElement) => HTMLElement | null;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/editor-common",
-	"version": "111.11.7",
+	"version": "111.11.9",
 	"description": "A package that contains common classes and components for editor and renderer",
 	"publishConfig": {
 		"registry": "https://registry.npmjs.org/"
@@ -74,14 +74,14 @@
 		"@atlaskit/prosemirror-history": "^0.2.0",
 		"@atlaskit/react-ufo": "^5.1.0",
 		"@atlaskit/section-message": "^8.12.0",
-		"@atlaskit/smart-card": "^43.23.0",
+		"@atlaskit/smart-card": "^43.24.0",
 		"@atlaskit/smart-user-picker": "^8.9.0",
 		"@atlaskit/spinner": "^19.0.0",
 		"@atlaskit/status": "^3.1.0",
 		"@atlaskit/task-decision": "^19.2.0",
 		"@atlaskit/textfield": "^8.2.0",
 		"@atlaskit/theme": "^21.0.0",
-		"@atlaskit/tmp-editor-statsig": "^21.0.0",
+		"@atlaskit/tmp-editor-statsig": "^22.0.0",
 		"@atlaskit/tokens": "^11.0.0",
 		"@atlaskit/tooltip": "^20.14.0",
 		"@atlaskit/width-detector": "^5.0.0",