@mog-sdk/spreadsheet-contracts 0.1.12

package/dist/objects/floating-objects.d.ts

@@ -0,0 +1,742 @@
+/**
+ * Floating Objects Contracts
+ *
+ * Type definitions for pictures, text boxes, shapes, and other floating objects
+ * that overlay the cell grid. These objects anchor to cells but render on a
+ * separate layer (z-index 5 per renderer architecture).
+ *
+ * Architecture Notes:
+ * - Objects render on overlay layer (z-index 5) per renderer docs
+ * - Requires object-interaction-machine for selection/drag/resize states
+ * - Coordinator manages cross-coordination with selection-machine
+ * - Hit testing determines which object (if any) is under cursor
+ *
+ * Cell Identity Model:
+ * - CellAnchor uses CellId references, NOT row/col positions
+ * - This ensures anchors survive concurrent row/col insert/delete operations
+ * - Position resolution happens at render time via CellPositionLookup
+ * - Same pattern as IdentityFormula refs for formulas
+ */
+import type { CellId, CellIdRange } from '../cells/cell-identity';
+import type { CellFormat } from '../core/core';
+import type { Equation, EquationStyle } from '../equation/types';
+import type { DrawingObject } from '../ink/types';
+import type { SmartArtDiagram } from '../smartart/types';
+import type { OuterShadowEffect } from '../wordart/effects';
+import type { WordArtConfig } from '../wordart/types';
+import type { CanvasObject, CanvasObjectGroup } from './canvas-object';
+/**
+ * How the object anchors to the sheet.
+ * Determines behavior when rows/columns are resized.
+ */
+export type ObjectAnchorType = 'twoCell' | 'oneCell' | 'absolute';
+/**
+ * Cell anchor point with pixel offset.
+ * Used for precise positioning relative to cell boundaries.
+ *
+ * Cell Identity Model:
+ * Uses CellId for stable references that survive row/col insert/delete.
+ * Position is resolved at render time via CellPositionLookup.
+ *
+ * @example
+ * // User places image at B5
+ * const anchor: CellAnchor = {
+ *   cellId: 'abc-123...',  // CellId of B5
+ *   xOffset: 10,           // 10px from cell left edge
+ *   yOffset: 5             // 5px from cell top edge
+ * };
+ * // After inserting row at row 3, the CellId is unchanged
+ * // but resolves to position (row: 5, col: 1) → image moves down
+ */
+export interface CellAnchor {
+    /**
+     * Stable cell reference that survives row/col insert/delete.
+     * Resolve to current position via CellPositionLookup.getPosition().
+     */
+    cellId: CellId;
+    /** Horizontal offset from cell top-left in pixels */
+    xOffset: number;
+    /** Vertical offset from cell top-left in pixels */
+    yOffset: number;
+}
+/**
+ * Object position configuration.
+ * Supports cell-anchored and absolute positioning modes.
+ */
+export interface ObjectPosition {
+    /** Anchor type determines how object moves/resizes with cells */
+    anchorType: ObjectAnchorType;
+    /** Start anchor (top-left corner) - required for all anchor types */
+    from: CellAnchor;
+    /** End anchor (bottom-right corner) - only for twoCell anchor */
+    to?: CellAnchor;
+    /** Absolute X position in pixels (only for absolute anchor) */
+    x?: number;
+    /** Absolute Y position in pixels (only for absolute anchor) */
+    y?: number;
+    /** Width in pixels (for oneCell and absolute anchors) */
+    width?: number;
+    /** Height in pixels (for oneCell and absolute anchors) */
+    height?: number;
+    /** Rotation angle in degrees (0-360) */
+    rotation?: number;
+    /** Flip horizontally (mirror along vertical axis) */
+    flipH?: boolean;
+    /** Flip vertically (mirror along horizontal axis) */
+    flipV?: boolean;
+}
+/**
+ * Object type discriminator.
+ * Used for type narrowing in union types.
+ *
+ * Extends CanvasObjectType (which is `string`) with a specific union for
+ * spreadsheet object types. This ensures backward compatibility: any code
+ * expecting FloatingObjectType still gets the specific union, while
+ * CanvasObjectType-based code accepts it as a string.
+ *
+ * Note: 'slicer' is defined here for the FloatingObjectType union,
+ * but the full SlicerConfig type is in contracts/src/slicers.ts
+ * because slicers have significant additional properties.
+ */
+export type FloatingObjectType = 'shape' | 'connector' | 'picture' | 'textbox' | 'chart' | 'camera' | 'equation' | 'smartart' | 'drawing' | 'oleObject' | 'formControl' | 'slicer';
+/**
+ * Base interface for all floating objects.
+ * Contains common properties shared by all object types.
+ *
+ * Extends CanvasObject<ObjectPosition> to inherit universal canvas object
+ * properties. The spreadsheet anchor type is ObjectPosition (cell-based).
+ *
+ * Transition note: `sheetId` is kept for backward compatibility during
+ * migration. It aliases `containerId` from CanvasObject. Both fields should
+ * be set to the same value. `sheetId` will be removed in a future phase.
+ */
+export interface FloatingObjectBase extends CanvasObject<ObjectPosition> {
+    /** Object type discriminator (narrows CanvasObject.type to spreadsheet types) */
+    type: FloatingObjectType;
+    /** Sheet containing the object (spreadsheet-specific alias for containerId) */
+    sheetId: string;
+    /**
+     * Container scope (inherited from CanvasObject).
+     * For spreadsheets, this is the same as sheetId.
+     * Set both sheetId and containerId to the same value during the transition.
+     */
+    containerId: string;
+    /**
+     * Position and sizing configuration.
+     * This is the spreadsheet-specific name for the anchor from CanvasObject.
+     * Both `position` and `anchor` should reference the same ObjectPosition.
+     */
+    position: ObjectPosition;
+    /**
+     * App-specific anchor (inherited from CanvasObject<ObjectPosition>).
+     * For spreadsheets, this is the same as `position`.
+     */
+    anchor: ObjectPosition;
+}
+/**
+ * Image crop settings.
+ * Values are percentages (0-100) of original dimension to crop from each side.
+ */
+export interface PictureCrop {
+    /** Percentage to crop from top (0-100) */
+    top: number;
+    /** Percentage to crop from right (0-100) */
+    right: number;
+    /** Percentage to crop from bottom (0-100) */
+    bottom: number;
+    /** Percentage to crop from left (0-100) */
+    left: number;
+}
+/**
+ * Image adjustment settings.
+ * Values mirror Excel's picture format options.
+ */
+export interface PictureAdjustments {
+    /** Brightness adjustment (-100 to 100, 0 = normal) */
+    brightness?: number;
+    /** Contrast adjustment (-100 to 100, 0 = normal) */
+    contrast?: number;
+    /** Transparency (0 = opaque, 100 = fully transparent) */
+    transparency?: number;
+}
+/**
+ * Border style for floating objects.
+ */
+export interface ObjectBorder {
+    /** Border line style */
+    style: 'none' | 'solid' | 'dashed' | 'dotted';
+    /** Border color (CSS color string) */
+    color: string;
+    /** Border width in pixels */
+    width: number;
+}
+/**
+ * Picture/image floating object.
+ * Supports images from various sources with cropping and adjustments.
+ */
+export interface PictureObject extends FloatingObjectBase {
+    type: 'picture';
+    /** Image source (data URL, blob URL, or external URL) */
+    src: string;
+    /** Original image width in pixels (before scaling) */
+    originalWidth: number;
+    /** Original image height in pixels (before scaling) */
+    originalHeight: number;
+    /** Crop settings (percentage-based) */
+    crop?: PictureCrop;
+    /** Image adjustments (brightness, contrast, transparency) */
+    adjustments?: PictureAdjustments;
+    /** Border around the image */
+    border?: ObjectBorder;
+}
+/**
+ * Fill type for shapes, text boxes, and connectors.
+ * Matches the Rust `FillType` enum in `domain-types`.
+ */
+export type FillType = 'solid' | 'gradient' | 'none';
+/**
+ * Gradient direction type.
+ * Matches the Rust `GradientType` enum in `domain-types`.
+ */
+export type GradientType = 'linear' | 'radial';
+/**
+ * A single color stop in a gradient.
+ * Matches the Rust `GradientStop` struct in `domain-types`.
+ */
+export interface GradientStop {
+    /** Position of the stop (0.0 to 1.0) */
+    offset: number;
+    /** CSS color string */
+    color: string;
+}
+/**
+ * Gradient fill configuration.
+ * Matches the Rust `GradientFill` struct in `domain-types`.
+ */
+export interface GradientFill {
+    /** Gradient type */
+    type: GradientType;
+    /** Gradient color stops */
+    stops: GradientStop[];
+    /** Gradient angle in degrees (for linear gradients) */
+    angle?: number;
+}
+/**
+ * Fill configuration for shapes and text boxes.
+ * Matches the Rust `ObjectFill` struct in `domain-types`.
+ */
+export interface ObjectFill {
+    /** Fill type */
+    type: FillType;
+    /** Solid fill color (CSS color string) */
+    color?: string;
+    /** Gradient configuration */
+    gradient?: GradientFill;
+    /** Fill transparency (0 = opaque, 1 = fully transparent). Maps to OfficeJS Shape.fill.transparency. */
+    transparency?: number;
+}
+/**
+ * Text box border with optional corner radius.
+ */
+export interface TextBoxBorder extends ObjectBorder {
+    /** Corner radius in pixels (for rounded corners) */
+    radius?: number;
+}
+/**
+ * Text margins within a text box or shape.
+ */
+export interface TextMargins {
+    /** Top margin in pixels */
+    top: number;
+    /** Right margin in pixels */
+    right: number;
+    /** Bottom margin in pixels */
+    bottom: number;
+    /** Left margin in pixels */
+    left: number;
+}
+/**
+ * Text box floating object.
+ * A rectangular container for rich text content.
+ */
+export interface TextBoxObject extends FloatingObjectBase {
+    type: 'textbox';
+    /** Rich text content (HTML or structured format) */
+    content: string;
+    /** Default text formatting for new text */
+    defaultFormat?: CellFormat;
+    /** Fill color/gradient for the text box background */
+    fill?: ObjectFill;
+    /** Border around the text box */
+    border?: TextBoxBorder;
+    /** Text margins within the box */
+    margins?: TextMargins;
+    /** Vertical text alignment */
+    verticalAlign?: 'top' | 'middle' | 'bottom';
+    /** Optional WordArt configuration for styled text effects */
+    wordArt?: WordArtConfig;
+}
+/**
+ * Available shape types.
+ * Matches common Excel/Office shape categories.
+ */
+export type ShapeType = 'rect' | 'roundRect' | 'ellipse' | 'triangle' | 'rtTriangle' | 'diamond' | 'pentagon' | 'hexagon' | 'octagon' | 'parallelogram' | 'trapezoid' | 'nonIsoscelesTrapezoid' | 'heptagon' | 'decagon' | 'dodecagon' | 'teardrop' | 'pie' | 'pieWedge' | 'blockArc' | 'donut' | 'noSmoking' | 'plaque' | 'round1Rect' | 'round2SameRect' | 'round2DiagRect' | 'snip1Rect' | 'snip2SameRect' | 'snip2DiagRect' | 'snipRoundRect' | 'rightArrow' | 'leftArrow' | 'upArrow' | 'downArrow' | 'leftRightArrow' | 'upDownArrow' | 'quadArrow' | 'chevron' | 'leftArrowCallout' | 'rightArrowCallout' | 'upArrowCallout' | 'downArrowCallout' | 'leftRightArrowCallout' | 'upDownArrowCallout' | 'quadArrowCallout' | 'bentArrow' | 'uturnArrow' | 'circularArrow' | 'leftCircularArrow' | 'leftRightCircularArrow' | 'curvedRightArrow' | 'curvedLeftArrow' | 'curvedUpArrow' | 'curvedDownArrow' | 'swooshArrow' | 'star4' | 'star5' | 'star6' | 'star7' | 'star8' | 'star10' | 'star12' | 'star16' | 'star24' | 'star32' | 'ribbon' | 'ribbon2' | 'ellipseRibbon' | 'ellipseRibbon2' | 'leftRightRibbon' | 'banner' | 'wedgeRectCallout' | 'wedgeRoundRectCallout' | 'wedgeEllipseCallout' | 'cloud' | 'callout1' | 'callout2' | 'callout3' | 'borderCallout1' | 'borderCallout2' | 'borderCallout3' | 'accentCallout1' | 'accentCallout2' | 'accentCallout3' | 'accentBorderCallout1' | 'accentBorderCallout2' | 'accentBorderCallout3' | 'line' | 'lineArrow' | 'lineDoubleArrow' | 'curve' | 'arc' | 'connector' | 'bentConnector2' | 'bentConnector3' | 'bentConnector4' | 'bentConnector5' | 'curvedConnector2' | 'curvedConnector3' | 'curvedConnector4' | 'curvedConnector5' | 'flowChartProcess' | 'flowChartDecision' | 'flowChartInputOutput' | 'flowChartPredefinedProcess' | 'flowChartInternalStorage' | 'flowChartDocument' | 'flowChartMultidocument' | 'flowChartTerminator' | 'flowChartPreparation' | 'flowChartManualInput' | 'flowChartManualOperation' | 'flowChartConnector' | 'flowChartPunchedCard' | 'flowChartPunchedTape' | 'flowChartSummingJunction' | 'flowChartOr' | 'flowChartCollate' | 'flowChartSort' | 'flowChartExtract' | 'flowChartMerge' | 'flowChartOfflineStorage' | 'flowChartOnlineStorage' | 'flowChartMagneticTape' | 'flowChartMagneticDisk' | 'flowChartMagneticDrum' | 'flowChartDisplay' | 'flowChartDelay' | 'flowChartAlternateProcess' | 'flowChartOffpageConnector' | 'heart' | 'lightningBolt' | 'sun' | 'moon' | 'smileyFace' | 'foldedCorner' | 'bevel' | 'frame' | 'halfFrame' | 'corner' | 'diagStripe' | 'chord' | 'can' | 'cube' | 'plus' | 'cross' | 'irregularSeal1' | 'irregularSeal2' | 'homePlate' | 'funnel' | 'verticalScroll' | 'horizontalScroll' | 'actionButtonBlank' | 'actionButtonHome' | 'actionButtonHelp' | 'actionButtonInformation' | 'actionButtonForwardNext' | 'actionButtonBackPrevious' | 'actionButtonEnd' | 'actionButtonBeginning' | 'actionButtonReturn' | 'actionButtonDocument' | 'actionButtonSound' | 'actionButtonMovie' | 'leftBracket' | 'rightBracket' | 'leftBrace' | 'rightBrace' | 'bracketPair' | 'bracePair' | 'mathPlus' | 'mathMinus' | 'mathMultiply' | 'mathDivide' | 'mathEqual' | 'mathNotEqual' | 'gear6' | 'gear9' | 'cornerTabs' | 'squareTabs' | 'plaqueTabs' | 'chartX' | 'chartStar' | 'chartPlus';
+/** Arrowhead/line-end type for connector endpoints. Maps to ST_LineEndType (ECMA-376, dml-main.xsd). Canonical source; re-exported by drawing-canvas scene/types. */
+export type LineEndType = 'none' | 'triangle' | 'stealth' | 'diamond' | 'oval' | 'arrow';
+/** Arrowhead/line-end size for connector endpoints. Maps to ST_LineEndLength/ST_LineEndWidth (ECMA-376, dml-main.xsd). Canonical source; re-exported by drawing-canvas scene/types. */
+export type LineEndSize = 'sm' | 'med' | 'lg';
+/**
+ * Detailed line dash pattern.
+ * Matches OfficeJS ShapeLineFormat.dashStyle and Rust `LineDash` enum.
+ * Uses the same 11 variants as OOXML ST_PresetLineDashVal.
+ */
+export type LineDash = 'solid' | 'dot' | 'dash' | 'dashDot' | 'lgDash' | 'lgDashDot' | 'lgDashDotDot' | 'sysDash' | 'sysDot' | 'sysDashDot' | 'sysDashDotDot';
+/**
+ * Shape outline/stroke configuration.
+ */
+export interface ShapeOutline {
+    /** Outline style */
+    style: 'none' | 'solid' | 'dashed' | 'dotted';
+    /** Outline color (CSS color string) */
+    color: string;
+    /** Outline width in pixels */
+    width: number;
+    /** Head (start) arrowhead configuration */
+    headEnd?: {
+        type: LineEndType;
+        width?: LineEndSize;
+        length?: LineEndSize;
+    };
+    /** Tail (end) arrowhead configuration */
+    tailEnd?: {
+        type: LineEndType;
+        width?: LineEndSize;
+        length?: LineEndSize;
+    };
+    /** Detailed dash pattern (overrides coarse `style` when set). Matches OfficeJS 12 dash styles. */
+    dash?: LineDash;
+    /** Outline transparency (0 = opaque, 1 = fully transparent). */
+    transparency?: number;
+}
+/**
+ * Text content inside a shape.
+ */
+export interface ShapeText {
+    /** Text content */
+    content: string;
+    /** Text formatting */
+    format?: CellFormat;
+    /** Vertical alignment of text within shape */
+    verticalAlign?: 'top' | 'middle' | 'bottom';
+    /** Horizontal alignment of text within shape */
+    horizontalAlign?: 'left' | 'center' | 'right';
+}
+/**
+ * Shape floating object.
+ * A geometric shape with optional fill, outline, and text.
+ */
+export interface ShapeObject extends FloatingObjectBase {
+    type: 'shape';
+    /** Type of shape to render */
+    shapeType: ShapeType;
+    /** Fill configuration */
+    fill?: ObjectFill;
+    /** Outline/stroke configuration */
+    outline?: ShapeOutline;
+    /** Text content inside the shape */
+    text?: ShapeText;
+    /** Shadow effect (outer shadow / drop shadow) */
+    shadow?: OuterShadowEffect;
+    /**
+     * Shape-specific adjustments.
+     * Keys depend on shape type (e.g., 'cornerRadius' for roundRect,
+     * 'arrowHeadSize' for arrows, 'starPoints' for stars).
+     */
+    adjustments?: Record<string, number>;
+}
+/**
+ * Connector floating object.
+ * A line or connector shape that links two objects (or floats freely).
+ * Connectors have optional arrowheads and connection site bindings.
+ */
+export interface ConnectorObject extends FloatingObjectBase {
+    type: 'connector';
+    /** Connector shape preset (e.g., straightConnector1, bentConnector3) */
+    shapeType: ShapeType;
+    /** Start connection binding (which shape and site index) */
+    startConnection?: {
+        shapeId: string;
+        siteIndex: number;
+    };
+    /** End connection binding (which shape and site index) */
+    endConnection?: {
+        shapeId: string;
+        siteIndex: number;
+    };
+    /** Fill configuration */
+    fill?: ObjectFill;
+    /** Outline/stroke configuration (includes arrowheads) */
+    outline?: ShapeOutline;
+}
+/**
+ * Supported chart types for the ChartObject.
+ * Matches the ChartType from charts package but defined here for contracts.
+ */
+export type ChartObjectType = 'bar' | 'column' | 'line' | 'area' | 'pie' | 'doughnut' | 'scatter' | 'bubble' | 'combo' | 'radar' | 'stock' | 'funnel' | 'waterfall';
+/**
+ * Chart floating object.
+ *
+ * Integrates charts with the FloatingObjectManager to provide:
+ * - Hit-testing for selection
+ * - Drag/resize/z-order operations
+ * - Consistent interaction model with other floating objects
+ *
+ * Architecture Notes:
+ * - Uses Cell Identity Model with CellIdRange references (CRDT-safe)
+ * - Full chart configuration lives in the Charts domain module
+ * - This interface provides the FloatingObject layer for interactions
+ * - Position resolution happens at render time via CellPositionLookup
+ *
+ * @example
+ * // Chart data range A1:D10
+ * const chart: ChartObject = {
+ *   id: 'chart-1',
+ *   type: 'chart',
+ *   sheetId: 'sheet-abc',
+ *   position: { anchorType: 'oneCell', from: { cellId: '...', xOffset: 0, yOffset: 0 }, width: 400, height: 300 },
+ *   zIndex: 1,
+ *   locked: false,
+ *   printable: true,
+ *   chartType: 'column',
+ *   anchorMode: 'oneCell',
+ *   widthCells: 8,
+ *   heightCells: 15,
+ *   chartConfig: { series: [], axes: {} },
+ *   dataRangeIdentity: { topLeftCellId: '...', bottomRightCellId: '...' }
+ * };
+ */
+export interface ChartObject extends FloatingObjectBase {
+    type: 'chart';
+    /**
+     * The type of chart (bar, line, pie, etc.)
+     */
+    chartType: ChartObjectType;
+    /**
+     * How chart anchors to cells - affects resize behavior.
+     * - 'oneCell': Chart moves with anchor cell, but doesn't resize with cell changes
+     * - 'twoCell': Chart moves and resizes with both anchor cells
+     */
+    anchorMode: 'oneCell' | 'twoCell';
+    /**
+     * Width in cell units (for oneCell mode sizing).
+     * In twoCell mode, width is determined by the anchor cell positions.
+     */
+    widthCells: number;
+    /**
+     * Height in cell units (for oneCell mode sizing).
+     * In twoCell mode, height is determined by the anchor cell positions.
+     */
+    heightCells: number;
+    /**
+     * Full chart configuration (series, axes, legend, colors, etc.).
+     * Stored directly on the floating object as a sub-object field, following the
+     * same pattern as fill/outline/shadow on shapes.
+     */
+    chartConfig: Record<string, unknown>;
+    /**
+     * Chart data range using CellId corners (CRDT-safe).
+     * Automatically expands when rows/cols inserted between corners.
+     * Optional because some charts may have inline data or external sources.
+     */
+    dataRangeIdentity?: CellIdRange;
+    /**
+     * Series labels range using CellId corners (CRDT-safe).
+     * Used to label each data series in the chart.
+     */
+    seriesRangeIdentity?: CellIdRange;
+    /**
+     * Category labels range using CellId corners (CRDT-safe).
+     * Used for x-axis labels in most chart types.
+     */
+    categoryRangeIdentity?: CellIdRange;
+}
+/**
+ * Equation floating object.
+ * Contains a mathematical equation rendered as a floating object.
+ */
+export interface EquationObject extends FloatingObjectBase {
+    type: 'equation';
+    /** The equation data */
+    equation: Equation;
+}
+/**
+ * SmartArt floating object.
+ *
+ * SmartArt provides visual representations of information like organization charts,
+ * process flows, relationship diagrams, and hierarchies. The diagram data contains
+ * the nodes and their relationships, while layout/styling is computed at render time.
+ *
+ * Architecture Notes:
+ * - Diagram data (nodes, relationships) is persisted in Yjs via the bridge layer
+ * - Selection state (selectedNodeIds, editingNodeId) lives in XState context, NOT here
+ * - Computed layout is a runtime cache, managed by the bridge
+ * - Uses existing object-interaction-machine for selection/drag/resize
+ */
+export interface SmartArtObject extends FloatingObjectBase {
+    type: 'smartart';
+    /**
+     * The SmartArt diagram data including nodes, relationships, and styling.
+     * This is the persisted data - layout is computed at runtime.
+     */
+    diagram: SmartArtDiagram;
+}
+/**
+ * OLE (Object Linking and Embedding) floating object.
+ *
+ * Represents embedded or linked objects from other applications (e.g., Word
+ * documents, PDF files, Visio drawings). The object may have a preview image
+ * (PNG/JPEG) or display as an icon. EMF/WMF previews are not supported and
+ * will have a null previewImageSrc.
+ *
+ * Architecture Notes:
+ * - Preview image is extracted during OOXML parsing and stored as a blob URL
+ * - Linked objects reference external files (isLinked); embedded objects are self-contained
+ * - dvAspect determines whether the object renders as content or as an icon
+ * - progId identifies the source application (e.g., "Word.Document.12", "AcroExch.Document")
+ */
+export interface OleObjectObject extends FloatingObjectBase {
+    type: 'oleObject';
+    /** OLE ProgID identifying the source application (e.g., "Word.Document.12") */
+    progId: string;
+    /** Display aspect: 'content' renders the object preview, 'icon' shows an application icon */
+    dvAspect: 'content' | 'icon';
+    /** Whether the object links to an external file */
+    isLinked: boolean;
+    /** Whether the object data is embedded in the workbook */
+    isEmbedded: boolean;
+    /** Blob URL for the preview image (PNG/JPEG), null for EMF/WMF or missing previews */
+    previewImageSrc: string | null;
+    /** Descriptive text for accessibility */
+    altText: string;
+}
+/**
+ * Union of all floating object types.
+ * Use type narrowing on the 'type' discriminator to access specific properties.
+ */
+export type FloatingObject = PictureObject | TextBoxObject | ShapeObject | ConnectorObject | ChartObject | DrawingObject | EquationObject | SmartArtObject | OleObjectObject;
+/**
+ * A group of floating objects that move/resize together.
+ * Groups can contain other groups for nested grouping.
+ *
+ * Extends CanvasObjectGroup to inherit universal group properties.
+ *
+ * Transition note: `sheetId` is kept for backward compatibility.
+ * It aliases `containerId` from CanvasObjectGroup. Both fields should
+ * be set to the same value. `sheetId` will be removed in a future phase.
+ */
+export interface FloatingObjectGroup extends CanvasObjectGroup {
+    /** Sheet containing the group (spreadsheet-specific alias for containerId) */
+    sheetId: string;
+    /**
+     * Container scope (inherited from CanvasObjectGroup).
+     * For spreadsheets, this is the same as sheetId.
+     */
+    containerId: string;
+    /** Bounding box position for the group */
+    position: ObjectPosition;
+    /** Whether the group is locked (non-optional override of CanvasObjectGroup.locked) */
+    locked: boolean;
+}
+/**
+ * Regions of an object that can be hit-tested.
+ * Used to determine cursor and interaction behavior.
+ */
+export type ObjectHitRegion = 'body' | 'border' | 'resize-nw' | 'resize-n' | 'resize-ne' | 'resize-e' | 'resize-se' | 'resize-s' | 'resize-sw' | 'resize-w' | 'rotation' | 'warp-adjust';
+/**
+ * Result of hit-testing a point against floating objects.
+ * Used by coordinator to route events to object-interaction-machine.
+ */
+export interface ObjectHitTestResult {
+    /** ID of the object that was hit */
+    objectId: string;
+    /** Which region of the object was hit */
+    region: ObjectHitRegion;
+    /** Whether this is a group */
+    isGroup: boolean;
+}
+/**
+ * States for the object-interaction-machine.
+ * Defines all possible interaction modes with floating objects.
+ *
+ * State transitions:
+ * - idle → selected (click on object)
+ * - selected → operating (mouse down on body/handle triggers START_DRAG/START_RESIZE/START_ROTATE)
+ * - selected → editingText (double-click on textbox/shape with text)
+ * - selected → wordArtEditing (double-click on WordArt object)
+ * - selected → adjustingWarp (drag warp-adjust handle on WordArt)
+ * - selected → idle (click outside or Escape)
+ * - operating → selected (COMPLETE_OPERATION/CANCEL_OPERATION)
+ * - editingText → selected (click outside text or Escape)
+ * - wordArtEditing → selected (STOP_EDITING or click outside)
+ * - adjustingWarp → selected (POINTER_UP or ESCAPE)
+ */
+export type ObjectInteractionState = 'idle' | 'selected' | 'multiSelected' | 'operating' | 'editingText' | 'inserting' | 'wordArtEditing' | 'adjustingWarp';
+/**
+ * Context for the object-interaction-machine.
+ * Maintained by the coordinator.
+ */
+export interface ObjectInteractionContext {
+    /** Currently selected object IDs (empty if idle) */
+    selectedIds: string[];
+    /** Active resize handle (if resizing) */
+    activeHandle?: ObjectHitRegion;
+}
+/**
+ * Options for creating a picture object.
+ */
+export interface CreatePictureOptions {
+    /** Optional name for the object */
+    name?: string;
+    /** Alt text for accessibility */
+    altText?: string;
+    /** Whether object is locked */
+    locked?: boolean;
+    /** Whether object appears in print */
+    printable?: boolean;
+    /** Initial crop settings */
+    crop?: PictureCrop;
+    /** Initial adjustments */
+    adjustments?: PictureAdjustments;
+    /** Border configuration */
+    border?: ObjectBorder;
+}
+/**
+ * Options for creating a text box object.
+ */
+export interface CreateTextBoxOptions {
+    /** Optional name for the object */
+    name?: string;
+    /** Alt text for accessibility */
+    altText?: string;
+    /** Whether object is locked */
+    locked?: boolean;
+    /** Whether object appears in print */
+    printable?: boolean;
+    /** Default text formatting */
+    defaultFormat?: CellFormat;
+    /** Fill configuration */
+    fill?: ObjectFill;
+    /** Border configuration */
+    border?: TextBoxBorder;
+    /** Text margins */
+    margins?: TextMargins;
+    /** Vertical text alignment */
+    verticalAlign?: 'top' | 'middle' | 'bottom';
+    /** Optional WordArt configuration for styled text effects */
+    wordArt?: WordArtConfig;
+}
+/**
+ * Options for creating a WordArt object (text box with WordArt configuration).
+ * Extends CreateTextBoxOptions with the required WordArt configuration.
+ */
+export interface CreateWordArtOptions extends Omit<CreateTextBoxOptions, 'wordArt'> {
+    /** Initial WordArt configuration (required for WordArt objects) */
+    wordArt: WordArtConfig;
+}
+/**
+ * Options for creating a shape object.
+ */
+export interface CreateShapeOptions {
+    /** Optional name for the object */
+    name?: string;
+    /** Alt text for accessibility */
+    altText?: string;
+    /** Whether object is locked */
+    locked?: boolean;
+    /** Whether object appears in print */
+    printable?: boolean;
+    /** Fill configuration */
+    fill?: ObjectFill;
+    /** Outline configuration */
+    outline?: ShapeOutline;
+    /** Initial text content */
+    text?: ShapeText;
+    /** Shadow effect (outer shadow / drop shadow) */
+    shadow?: OuterShadowEffect;
+    /** Shape-specific adjustments */
+    adjustments?: Record<string, number>;
+}
+/**
+ * Options for creating a chart as a floating object.
+ *
+ * This is used by the FloatingObjectManager's createChart method to create
+ * a ChartObject that integrates with the unified floating object system.
+ * The chart-specific configuration is managed by the Charts domain module.
+ */
+export interface CreateChartAsFloatingObjectOptions {
+    /** Optional name for the chart object */
+    name?: string;
+    /** Alt text for accessibility */
+    altText?: string;
+    /** Whether chart is locked (can't be moved/resized) */
+    locked?: boolean;
+    /** Whether chart appears in print output */
+    printable?: boolean;
+    /** How chart anchors to cells */
+    anchorMode?: 'oneCell' | 'twoCell';
+    /** Width in cell units (for oneCell mode) */
+    widthCells?: number;
+    /** Height in cell units (for oneCell mode) */
+    heightCells?: number;
+    /** Initial data range using CellId corners */
+    dataRangeIdentity?: CellIdRange;
+    /** Initial series labels range using CellId corners */
+    seriesRangeIdentity?: CellIdRange;
+    /** Initial category labels range using CellId corners */
+    categoryRangeIdentity?: CellIdRange;
+}
+/**
+ * Options for creating an equation object.
+ */
+export interface CreateEquationOptions {
+    /** Optional name for the object */
+    name?: string;
+    /** Alt text for accessibility */
+    altText?: string;
+    /** Whether object is locked */
+    locked?: boolean;
+    /** Whether object appears in print */
+    printable?: boolean;
+    /** LaTeX string for the equation (if not using omml) */
+    latex?: string;
+    /** OMML XML string (if not using latex) */
+    omml?: string;
+    /** Equation style overrides */
+    style?: Partial<EquationStyle>;
+}
+/**
+ * Options for creating a SmartArt object.
+ *
+ * Based on the pattern from CreatePictureOptions and CreateChartAsFloatingObjectOptions.
+ * The layoutId is required to determine the diagram type (hierarchy, process, etc.).
+ */
+export interface CreateSmartArtOptions {
+    /** Optional name for the object */
+    name?: string;
+    /** Alt text for accessibility */
+    altText?: string;
+    /** Whether object is locked */
+    locked?: boolean;
+    /** Whether object appears in print */
+    printable?: boolean;
+    /** Quick style ID (e.g., 'subtle-effect', 'moderate-effect') */
+    quickStyleId?: string;
+    /** Color theme ID (e.g., 'colorful-1', 'accent-1') */
+    colorThemeId?: string;
+    /** Initial nodes to populate the diagram with */
+    initialNodes?: Array<{
+        text: string;
+        level: number;
+    }>;
+}
+//# sourceMappingURL=floating-objects.d.ts.map