@univerjs-pro/engine-shape 1.0.0-alpha.2 → 1.0.0-alpha.3

package/lib/types/shape-enum.d.ts

@@ -128,196 +128,387 @@ export declare enum ShapeOperatorEnum {
     Sat2 = "sat2"
 }
 /**
- * Shape type enum, it defines almost excel supported shape types
+ * Built-in vector shape types supported by the Univer shape engine.
+ *
+ * Board facade callers should access these values through `univerAPI.Enum.ShapeTypeEnum` so generated scripts remain
+ * copy-pasteable and do not need package-level imports.
  */
 export declare enum ShapeTypeEnum {
+    /** No rendered geometry; reserve this value for an explicitly empty shape. */
     None = "none",
+    /** Rectangle for generic process steps, cards, and diagram nodes. */
     Rect = "rect",
+    /** Rounded rectangle for friendly process steps, states, and cards. */
     RoundRect = "roundRect",
+    /** Ellipse for events, states, and circular diagram nodes. */
     Ellipse = "ellipse",
+    /** Diamond for decisions, conditions, and branching points. */
     Diamond = "diamond",
+    /** Upward-pointing triangle. */
     Triangle = "triangle",
+    /** Right triangle with one vertical and one horizontal edge. */
     RightTriangle = "rtTriangle",
+    /** Parallelogram commonly used for input and output steps. */
     Parallelogram = "parallelogram",
+    /** Symmetric trapezoid. */
     Trapezoid = "trapezoid",
+    /** Adjustable hexagon commonly used for preparation steps. */
     Hexagon = "hexagon",// 这个跟Heptagon 不一样的点在于调节点
+    /** Eight-sided polygon commonly used for stop or warning nodes. */
     Octagon = "octagon",
+    /** Plus-sign shape. */
     Plus = "plus",
+    /** 5-point star shape. */
     Star5 = "star5",
+    /** 6-point star shape. */
     Star6 = "star6",
+    /** 7-point star shape. */
     Star7 = "star7",
+    /** 8-point star shape. */
     Star8 = "star8",
+    /** 10-point star shape. */
     Star10 = "star10",
+    /** 12-point star shape. */
     Star12 = "star12",
+    /** 16-point star shape. */
     Star16 = "star16",
+    /** 24-point star shape. */
     Star24 = "star24",
+    /** 32-point star shape. */
     Star32 = "star32",
+    /** Round 1 rect shape. */
     Round1Rect = "round1Rect",
+    /** Round 2 same rect shape. */
     Round2SameRect = "round2SameRect",
+    /** Round 2 diag rect shape. */
     Round2DiagRect = "round2DiagRect",
+    /** Snip 1 rect shape. */
     Snip1Rect = "snip1Rect",
+    /** Snip round rect shape. */
     SnipRoundRect = "snipRoundRect",
+    /** Snip 2 same rect shape. */
     Snip2SameRect = "snip2SameRect",
+    /** Snip 2 diag rect shape. */
     Snip2DiagRect = "snip2DiagRect",
+    /** Plaque shape. */
     Plaque = "plaque",
+    /** Rectangular frame with an open center. */
     Frame = "frame",
+    /** Two-sided partial frame. */
     HalfFrame = "halfFrame",
+    /** Right-angle corner shape. */
     Corner = "corner",
+    /** Diag stripe shape. */
     DiagStripe = "diagStripe",
+    /** Circular segment bounded by a chord. */
     Chord = "chord",
+    /** Open circular arc. */
     Arc = "arc",
+    /** Left circular arrow shape for directional diagrams. */
     LeftCircularArrow = "leftCircularArrow",
+    /** Left right circular arrow shape for directional diagrams. */
     LeftRightCircularArrow = "leftRightCircularArrow",
+    /** Swoosh arrow shape for directional diagrams. */
     SwooshArrow = "swooshArrow",
+    /** Left right ribbon shape. */
     LeftRightRibbon = "leftRightRibbon",
+    /** Seven-sided polygon. */
     Heptagon = "heptagon",
+    /** Home-plate pentagon for directional process nodes. */
     HomePlate = "homePlate",
+    /** Right arrow shape for directional diagrams. */
     RightArrow = "rightArrow",
+    /** Left arrow shape for directional diagrams. */
     LeftArrow = "leftArrow",
+    /** Up arrow shape for directional diagrams. */
     UpArrow = "upArrow",
+    /** Down arrow shape for directional diagrams. */
     DownArrow = "downArrow",
+    /** Left right arrow shape for directional diagrams. */
     LeftRightArrow = "leftRightArrow",
+    /** Up down arrow shape for directional diagrams. */
     UpDownArrow = "upDownArrow",
+    /** Quad arrow shape for directional diagrams. */
     QuadArrow = "quadArrow",
+    /** Left right up arrow shape for directional diagrams. */
     LeftRightUpArrow = "leftRightUpArrow",
+    /** Bent arrow shape for directional diagrams. */
     BentArrow = "bentArrow",
+    /** Uturn arrow shape for directional diagrams. */
     UturnArrow = "uturnArrow",
+    /** Left up arrow shape for directional diagrams. */
     LeftUpArrow = "leftUpArrow",
+    /** Bent up arrow shape for directional diagrams. */
     BentUpArrow = "bentUpArrow",
+    /** Curved right arrow shape for directional diagrams. */
     CurvedRightArrow = "curvedRightArrow",
+    /** Curved left arrow shape for directional diagrams. */
     CurvedLeftArrow = "curvedLeftArrow",
+    /** Curved up arrow shape for directional diagrams. */
     CurvedUpArrow = "curvedUpArrow",
+    /** Curved down arrow shape for directional diagrams. */
     CurvedDownArrow = "curvedDownArrow",
+    /** Striped right arrow shape for directional diagrams. */
     StripedRightArrow = "stripedRightArrow",
+    /** Notched right arrow shape for directional diagrams. */
     NotchedRightArrow = "notchedRightArrow",
+    /** Five-sided polygon or home-style process node. */
     Pentagon = "pentagon",
+    /** Chevron for sequences, progress, and directional stages. */
     Chevron = "chevron",
+    /** Right arrow callout shape for directional diagrams. */
     RightArrowCallout = "rightArrowCallout",
+    /** Down arrow callout shape for directional diagrams. */
     DownArrowCallout = "downArrowCallout",
+    /** Left arrow callout shape for directional diagrams. */
     LeftArrowCallout = "leftArrowCallout",
+    /** Up arrow callout shape for directional diagrams. */
     UpArrowCallout = "upArrowCallout",
+    /** Left right arrow callout shape for directional diagrams. */
     LeftRightArrowCallout = "leftRightArrowCallout",
+    /** Quad arrow callout shape for directional diagrams. */
     QuadArrowCallout = "quadArrowCallout",
+    /** Circular arrow for cycles and repeated processes. */
     CircularArrow = "circularArrow",
+    /** Equation symbol for plus. */
     MathPlus = "mathPlus",
+    /** Equation symbol for minus. */
     MathMinus = "mathMinus",
+    /** Equation symbol for multiply. */
     MathMultiply = "mathMultiply",
+    /** Equation symbol for divide. */
     MathDivide = "mathDivide",
+    /** Equation symbol for equal. */
     MathEqual = "mathEqual",
+    /** Equation symbol for not equal. */
     MathNotEqual = "mathNotEqual",
+    /** Flowchart process symbol for a standard operation. */
     FlowchartProcess = "flowChartProcess",
+    /** Flowchart alternate-process symbol. */
     FlowchartAlternateProcess = "flowChartAlternateProcess",
+    /** Flowchart decision symbol for branching conditions. */
     FlowchartDecision = "flowChartDecision",
+    /** Flowchart input/output symbol for data entering or leaving a process. */
     FlowChartInputOutput = "flowChartInputOutput",
+    /** Flowchart predefined-process symbol for a named subprocess. */
     FlowchartPredefinedProcess = "flowChartPredefinedProcess",
+    /** Flowchart internal-storage symbol. */
     FlowchartInternalStorage = "flowChartInternalStorage",
+    /** Flowchart document symbol for one document artifact. */
     FlowchartDocument = "flowChartDocument",
+    /** Flowchart multiple-documents symbol. */
     FlowchartMultiDocument = "flowChartMultidocument",
+    /** Flowchart terminator symbol for a start or end state. */
     FlowchartTerminator = "flowChartTerminator",
+    /** Flowchart preparation symbol for initialization or setup. */
     FlowchartPreparation = "flowChartPreparation",
+    /** Flowchart manual-input symbol. */
     FlowchartManualInput = "flowChartManualInput",
+    /** Flowchart manual-operation symbol. */
     FlowchartManualOperation = "flowChartManualOperation",
+    /** Flowchart on-page connector symbol. */
     FlowchartConnector = "flowChartConnector",
+    /** Flowchart off-page connector symbol. */
     FlowchartOffPageConnector = "flowChartOffpageConnector",
+    /** Flowchart punched-card data symbol. */
     FlowchartPunchedCard = "flowChartPunchedCard",
+    /** Flowchart punched-tape data symbol. */
     FlowchartPunchedTape = "flowChartPunchedTape",
+    /** Flowchart summing-junction symbol. */
     FlowchartSummingJunction = "flowChartSummingJunction",
+    /** Flowchart logical OR junction symbol. */
     FlowchartOr = "flowChartOr",
+    /** Flowchart collate symbol. */
     FlowchartCollate = "flowChartCollate",
+    /** Flowchart sort symbol. */
     FlowchartSort = "flowChartSort",
+    /** Flowchart extract symbol. */
     FlowchartExtract = "flowChartExtract",
+    /** Flowchart merge symbol. */
     FlowchartMerge = "flowChartMerge",
+    /** Flowchart online-storage symbol. */
     FlowchartOnlineStorage = "flowChartOnlineStorage",
+    /** Flowchart delay or wait symbol. */
     FlowchartDelay = "flowChartDelay",
+    /** Flowchart sequential-access magnetic-tape storage symbol. */
     FlowchartMagneticTape = "flowChartMagneticTape",
+    /** Flowchart magnetic-disk storage symbol. */
     FlowchartMagneticDisk = "flowChartMagneticDisk",
+    /** Flowchart direct-access magnetic-drum storage symbol. */
     FlowchartMagneticDrum = "flowChartMagneticDrum",
+    /** Flowchart display or screen output symbol. */
     FlowchartDisplay = "flowChartDisplay",
+    /** Wedge rect callout shape for annotated content. */
     WedgeRectCallout = "wedgeRectCallout",
+    /** Wedge round rect callout shape for annotated content. */
     WedgeRoundRectCallout = "wedgeRoundRectCallout",
+    /** Wedge ellipse callout shape for annotated content. */
     WedgeEllipseCallout = "wedgeEllipseCallout",
+    /** Cloud callout shape for annotated content. */
     CloudCallout = "cloudCallout",
+    /** Border callout 1 shape for annotated content. */
     BorderCallout1 = "borderCallout1",
+    /** Border callout 2 shape for annotated content. */
     BorderCallout2 = "borderCallout2",
+    /** Border callout 3 shape for annotated content. */
     BorderCallout3 = "borderCallout3",
+    /** Accent callout 1 shape for annotated content. */
     AccentCallout1 = "accentCallout1",
+    /** Accent callout 2 shape for annotated content. */
     AccentCallout2 = "accentCallout2",
+    /** Accent callout 3 shape for annotated content. */
     AccentCallout3 = "accentCallout3",
+    /** Callout 1 shape for annotated content. */
     Callout1 = "callout1",
+    /** Callout 2 shape for annotated content. */
     Callout2 = "callout2",
+    /** Callout 3 shape for annotated content. */
     Callout3 = "callout3",
+    /** Accent border callout 1 shape for annotated content. */
     AccentBorderCallout1 = "accentBorderCallout1",
+    /** Accent border callout 2 shape for annotated content. */
     AccentBorderCallout2 = "accentBorderCallout2",
+    /** Accent border callout 3 shape for annotated content. */
     AccentBorderCallout3 = "accentBorderCallout3",
+    /** Ribbon shape. */
     Ribbon = "ribbon",
+    /** Ribbon 2 shape. */
     Ribbon2 = "ribbon2",
+    /** Ellipse ribbon shape. */
     EllipseRibbon = "ellipseRibbon",
+    /** Ellipse ribbon 2 shape. */
     EllipseRibbon2 = "ellipseRibbon2",
+    /** Vertical scroll shape. */
     VerticalScroll = "verticalScroll",
+    /** Horizontal scroll shape. */
     HorizontalScroll = "horizontalScroll",
+    /** Wave shape. */
     Wave = "wave",
+    /** Double wave shape. */
     DoubleWave = "doubleWave",
+    /** Cube shape. */
     Cube = "cube",
+    /** Can shape. */
     Can = "can",
+    /** Lightning bolt shape. */
     LightningBolt = "lightningBolt",
+    /** Heart shape. */
     Heart = "heart",
+    /** Sun shape. */
     Sun = "sun",
+    /** Moon shape. */
     Moon = "moon",
+    /** Smiley face shape. */
     SmileyFace = "smileyFace",
+    /** Irregular seal 1 shape. */
     IrregularSeal1 = "irregularSeal1",
+    /** Irregular seal 2 shape. */
     IrregularSeal2 = "irregularSeal2",
+    /** Folded corner shape. */
     FoldedCorner = "foldedCorner",
+    /** Bevel shape. */
     Bevel = "bevel",
+    /** Donut shape. */
     Donut = "donut",
+    /** No smoking shape. */
     NoSmoking = "noSmoking",
+    /** Block arc shape. */
     BlockArc = "blockArc",
+    /** Teardrop shape. */
     Teardrop = "teardrop",
+    /** Pie wedge shape. */
     PieWedge = "pieWedge",
+    /** Pie shape. */
     Pie = "pie",
+    /** Funnel shape. */
     Funnel = "funnel",
+    /** Gear 6 shape. */
     Gear6 = "gear6",
+    /** Gear 9 shape. */
     Gear9 = "gear9",
+    /** Decagon shape. */
     Decagon = "decagon",
+    /** Dodecagon shape. */
     Dodecagon = "dodecagon",
+    /** Corner tabs shape. */
     CornerTabs = "cornerTabs",
+    /** Left brace shape. */
     LeftBrace = "leftBrace",
+    /** Right brace shape. */
     RightBrace = "rightBrace",
+    /** Left bracket shape. */
     LeftBracket = "leftBracket",
+    /** Right bracket shape. */
     RightBracket = "rightBracket",
+    /** Action button for back previous. */
     ActionButtonBackPrevious = "actionButtonBackPrevious",
+    /** Action button for forward next. */
     ActionButtonForwardNext = "actionButtonForwardNext",
+    /** Action button for beginning. */
     ActionButtonBeginning = "actionButtonBeginning",
+    /** Action button for end. */
     ActionButtonEnd = "actionButtonEnd",
+    /** Action button for home. */
     ActionButtonHome = "actionButtonHome",
+    /** Action button for information. */
     ActionButtonInformation = "actionButtonInformation",
+    /** Action button for return. */
     ActionButtonReturn = "actionButtonReturn",
+    /** Action button for movie. */
     ActionButtonMovie = "actionButtonMovie",
+    /** Action button for document. */
     ActionButtonDocument = "actionButtonDocument",
+    /** Action button for sound. */
     ActionButtonSound = "actionButtonSound",
+    /** Action button for help. */
     ActionButtonHelp = "actionButtonHelp",
+    /** Action button for blank. */
     ActionButtonBlank = "actionButtonBlank",
+    /** Brace pair shape. */
     BracePair = "bracePair",
+    /** Bracket pair shape. */
     BracketPair = "bracketPair",
+    /** Chart plus shape. */
     ChartPlus = "chartPlus",
+    /** Chart star shape. */
     ChartStar = "chartStar",
+    /** Chart x shape. */
     ChartX = "chartX",
+    /** Cloud shape. */
     Cloud = "cloud",
+    /** Flowchart offline-storage symbol. */
     FlowChartOfflineStorage = "flowChartOfflineStorage",
+    /** Line inv shape. */
     LineInv = "lineInv",
+    /** Non isosceles trapezoid shape. */
     NonIsoscelesTrapezoid = "nonIsoscelesTrapezoid",
+    /** Plaque tabs shape. */
     PlaqueTabs = "plaqueTabs",
+    /** Square tabs shape. */
     SquareTabs = "squareTabs",
+    /** 4-point star shape. */
     Star4 = "star4",
+    /** Up down arrow callout shape for directional diagrams. */
     UpDownArrowCallout = "upDownArrowCallout",
+    /** Simple line shape. */
     Line = "line",
+    /** Straight connector shape with one segment. */
     StraightConnector1 = "straightConnector1",
+    /** Orthogonal connector shape with two segments. */
     BentConnector2 = "bentConnector2",
+    /** Orthogonal connector shape with three segments. */
     BentConnector3 = "bentConnector3",
+    /** Orthogonal connector shape with four segments. */
     BentConnector4 = "bentConnector4",
+    /** Orthogonal connector shape with five segments. */
     BentConnector5 = "bentConnector5",
+    /** Curved connector shape with two control sections. */
     CurvedConnector2 = "curvedConnector2",
+    /** Curved connector shape with three control sections. */
     CurvedConnector3 = "curvedConnector3",
+    /** Curved connector shape with four control sections. */
     CurvedConnector4 = "curvedConnector4",
+    /** Curved connector shape with five control sections. */
     CurvedConnector5 = "curvedConnector5"
 }
 /**

package/lib/types/shape-type.d.ts

@@ -552,6 +552,13 @@ export interface IShapePath {
     dataArray?: IPathCommand[];
 }
 export type ShapeTextDirection = 'horz' | 'vert' | 'vert270' | 'wordArtVert' | 'eaVert' | 'mongolianVert' | 'wordArtVertRtl';
+export type ShapeTextHorizontalAnchor = 'center';
+export type ShapeTextWrapType = 'none' | 'square';
+export declare enum ShapeTextAutoFitType {
+    NoAutofit = "noAutofit",
+    NormAutofit = "normAutofit",
+    SpAutoFit = "spAutoFit"
+}
 export interface IShapeTextAlign {
     isHorizontal: boolean;
     textDirection?: ShapeTextDirection;
@@ -562,7 +569,24 @@ export interface IShapeTextRectPadding {
     right: number;
     bottom: number;
 }
-export interface IShapeText extends IShapeTextAlign {
+export interface IShapeTextBodyBehavior {
+    horizontalAnchor?: ShapeTextHorizontalAnchor;
+    textWrap?: ShapeTextWrapType;
+    autoFitType?: ShapeTextAutoFitType;
+    /**
+     * Legacy compatibility. New data should use `autoFitType`.
+     */
+    autoFit?: boolean;
+    /**
+     * OOXML normAutofit fontScale. 100000 means 100%.
+     */
+    fontScale?: number;
+    /**
+     * OOXML normAutofit lnSpcReduction.
+     */
+    lineSpaceReduction?: number;
+}
+export interface IShapeText extends IShapeTextAlign, IShapeTextBodyBehavior {
     isRichText: false;
     text?: string;
     color?: string;
@@ -572,9 +596,28 @@ export interface IShapeText extends IShapeTextAlign {
     italic?: boolean;
     underline?: boolean;
 }
-export interface ICustomShapeTextData extends IShapeTextAlign {
-    dataModel?: unknown;
+/**
+ * Shared rich shape text model.
+ *
+ * `engine-shape` owns the shape-text contract, but does not depend on a concrete
+ * document package. Products can specialize the generic parameters with their
+ * document and alignment types, for example
+ * `IShapeTextDataModel<IDocumentData, HorizontalAlign, VerticalAlign>`.
+ */
+export interface IShapeTextDataModel<TDocument = unknown, THorizontalAlign = unknown, TVerticalAlign = unknown> {
+    doc?: TDocument;
+    ha?: THorizontalAlign;
+    va?: TVerticalAlign;
+}
+export interface ICustomShapeTextData<TDocument = unknown, THorizontalAlign = unknown, TVerticalAlign = unknown> extends IShapeTextAlign, IShapeTextBodyBehavior {
+    /**
+     * Plain-text summary used by search, measurement, fallback rendering, and
+     * product-level display. Formatted content lives in `dataModel.doc`.
+     */
+    text?: string;
+    dataModel?: IShapeTextDataModel<TDocument, THorizontalAlign, TVerticalAlign>;
 }
+export type IShapeTextData<TDocument = unknown, THorizontalAlign = unknown, TVerticalAlign = unknown> = IShapeText | ICustomShapeTextData<TDocument, THorizontalAlign, TVerticalAlign>;
 /**
  * A shape outer-shadow effect. Distances and blur radius use slide drawing
  * units; direction is in degrees where 0 points right and 90 points down.
@@ -669,7 +712,7 @@ export interface IBasicShapeData {
     customGeometry?: IPresetShapeConfig;
     /** Basic outer shadow effect applied while rendering the shape path. */
     outerShadow?: IShapeShadowEffect;
-    shapeText?: IShapeText | ICustomShapeTextData;
+    shapeText?: IShapeTextData;
     /**
      * Text box inset used to calculate the editable/rendered text rect.
      * Values use the same drawing units as the shape rect.

package/lib/types/utils/shape-text-behavior.util.d.ts

@@ -0,0 +1,13 @@
+import type { IShapeData, IShapeTextRectPadding, ShapeTextHorizontalAnchor, ShapeTextWrapType } from '../shape-type';
+import { ShapeTextAutoFitType } from '../shape-type';
+export interface IResolvedShapeTextBodyBehavior {
+    autoFitType: ShapeTextAutoFitType;
+    fontScale?: number;
+    horizontalAnchor?: ShapeTextHorizontalAnchor;
+    isTextBox: boolean;
+    lineSpaceReduction?: number;
+    textRectPadding: IShapeTextRectPadding;
+    textWrap: ShapeTextWrapType;
+}
+export declare function resolveShapeTextBodyBehavior(shapeData: IShapeData): IResolvedShapeTextBodyBehavior;
+export declare function shouldUseFullShapeTextRectForAutoFit(shapeData: IShapeData): boolean;