refactor(contracts): extract shared ImageHyperlink type (#2738)

Author: caio-pizzol

packages/layout-engine/contracts/src/index.ts

@@ -287,6 +287,9 @@ export type ImageLuminanceAdjustment = {
   contrast?: number;
 };
 
+/** Hyperlink metadata from OOXML a:hlinkClick on a DrawingML image. */
+export type ImageHyperlink = { url: string; tooltip?: string };
+
 /**
  * Inline image run for images that flow with text on the same line.
  * Unlike ImageBlock (anchored/floating images), ImageRun is part of the paragraph's run array
@@ -362,7 +365,7 @@ export type ImageRun = {
   grayscale?: boolean; // Apply grayscale filter to image
   lum?: ImageLuminanceAdjustment; // DrawingML luminance adjustment from a:lum
   /** Image hyperlink from OOXML a:hlinkClick. When set, clicking the image opens the URL. */
-  hyperlink?: { url: string; tooltip?: string };
+  hyperlink?: ImageHyperlink;
 };
 
 export type BreakRun = {
@@ -638,7 +641,7 @@ export type ImageBlock = {
   flipH?: boolean; // Horizontal flip
   flipV?: boolean; // Vertical flip
   /** Image hyperlink from OOXML a:hlinkClick. When set, clicking the image opens the URL. */
-  hyperlink?: { url: string; tooltip?: string };
+  hyperlink?: ImageHyperlink;
 };
 
 export type DrawingKind = 'image' | 'vectorShape' | 'shapeGroup' | 'chart';

packages/layout-engine/painters/dom/src/index.test.ts

@@ -5,6 +5,7 @@ import type { DomPainterOptions, DomPainterInput, PaintSnapshot } from './index.
 import { resolveListMarkerGeometry } from '../../../../../shared/common/list-marker-utils.js';
 import type {
   FlowBlock,
+  ImageHyperlink,
   Measure,
   Layout,
   Line,
@@ -7693,7 +7694,7 @@ describe('ImageFragment (block-level images)', () => {
   });
 
   describe('hyperlink (DrawingML a:hlinkClick)', () => {
-    const makePainter = (hyperlink?: { url: string; tooltip?: string }) => {
+    const makePainter = (hyperlink?: ImageHyperlink) => {
       const block: FlowBlock = {
         kind: 'image',
         id: 'linked-img',

packages/layout-engine/painters/dom/src/renderer.ts

@@ -14,6 +14,7 @@ import type {
   ImageBlock,
   ImageDrawing,
   ImageFragment,
+  ImageHyperlink,
   ImageRun,
   Layout,
   Line,
@@ -3698,7 +3699,7 @@ export class DomPainter {
    */
   private buildImageHyperlinkAnchor(
     imageEl: HTMLElement,
-    hyperlink: { url: string; tooltip?: string } | undefined,
+    hyperlink: ImageHyperlink | undefined,
     display: 'block' | 'inline-block',
   ): HTMLElement {
     if (!hyperlink?.url || !this.doc) return imageEl;

packages/layout-engine/pm-adapter/src/utilities.ts

@@ -10,6 +10,7 @@ import type {
   DrawingBlock,
   DrawingContentSnapshot,
   ImageBlock,
+  ImageHyperlink,
   ShapeGroupChild,
   ShapeGroupDrawing,
   ShapeGroupImageChild,
@@ -231,7 +232,7 @@ export const normalizeString = (value: unknown): string | undefined => {
  * `{ url, tooltip? }` shape used by ImageBlock and ImageRun. Empty or invalid
  * URLs are dropped, and tooltip text is trimmed before inclusion.
  */
-export const readImageHyperlink = (value: unknown): { url: string; tooltip?: string } | undefined => {
+export const readImageHyperlink = (value: unknown): ImageHyperlink | undefined => {
   const hyperlink = isPlainObject(value) ? value : undefined;
   const url = normalizeString(hyperlink?.url);
   if (!url) {

packages/super-editor/src/editors/v1/extensions/types/node-attributes.ts

@@ -14,7 +14,7 @@ import type {
   InlineNodeAttributes,
   ShapeNodeAttributes,
 } from '../../core/types/NodeCategories.js';
-import type { StructuredContentLockMode } from '@superdoc/contracts';
+import type { ImageHyperlink, StructuredContentLockMode } from '@superdoc/contracts';
 
 // ============================================
 // SHARED TYPES
@@ -512,7 +512,7 @@ export interface ImageAttrs extends ShapeNodeAttributes {
   /** Decorative image flag. Maps to OOXML adec:decorative. */
   decorative?: boolean;
   /** Image hyperlink. Maps to OOXML pic:cNvPr > a:hlinkClick. */
-  hyperlink?: { url: string; tooltip?: string } | null;
+  hyperlink?: ImageHyperlink | null;
 }
 
 // ============================================