@univerjs-pro/engine-shape 0.15.5 → 0.16.0-insiders.20260228-a20b9a7

package/README.md

@@ -1,232 +1,82 @@
-# EngineShape
-
+# @univerjs-pro/engine-shape
 
 [![npm version](https://img.shields.io/npm/v/@univerjs-pro/engine-shape)](https://npmjs.org/packages/@univerjs-pro/engine-shape)
 [![license](https://img.shields.io/npm/l/@univerjs-pro/engine-shape)](https://img.shields.io/npm/l/@univerjs-pro/engine-shape)
-![CSS Included](https://img.shields.io/badge/CSS_Included-blue?logo=CSS3)
-![i18n](https://img.shields.io/badge/zh--CN%20%7C%20en--US-cornflowerblue?label=i18n)
 
-This plugin provide the basic preset shape like excel.
+## Introduction
+
+Engine Shape is the core shape definition and rendering engine for Univer. It provides 180+ preset shapes compatible with Excel/OOXML, covering basic shapes, arrows, flowcharts, callouts, connectors, and more. This package handles shape geometry computation, path rendering, fill/stroke styling, adjust points, connection sites, and connector routing.
 
+## Usage
 
 ### Installation
 
-Shape Feature provide the ability to rendering basic shape like excel.
+```shell
+# Using npm
+npm install @univerjs-pro/engine-shape
+
+# Using pnpm
+pnpm add @univerjs-pro/engine-shape
+```
 
-This feature includes the following packages:
+## Features
 
-- `@univerjs-pro/engine-shape` - Basic shape define and render.
+### Preset Shapes
 
-```shell npm2yarn
-npm install  @univerjs-pro/engine-shape
-```
+The library provides 180+ preset shape types organized into the following categories:
 
+| Category | Examples |
+|---|---|
+| **Basic Shapes** | Rectangle, RoundRectangle, Ellipse, Diamond, Triangle, Hexagon, Octagon, Star, etc. |
+| **Arrows** | RightArrow, LeftArrow, UpArrow, BentArrow, CurvedArrow, StripedRightArrow, Chevron, etc. |
+| **Flowcharts** | Process, Decision, InputOutput, Document, Terminator, Preparation, ManualInput, etc. |
+| **Callouts** | WedgeRectCallout, WedgeEllipseCallout, CloudCallout, BorderCallout, AccentCallout, etc. |
+| **Stars & Ribbons** | Star4–Star32, Ribbon, EllipseRibbon, VerticalScroll, HorizontalScroll, Wave, etc. |
+| **Math** | MathPlus, MathMinus, MathMultiply, MathDivide, MathEqual, MathNotEqual |
+| **Connectors** | StraightConnector, BentConnector (2–5), CurvedConnector (2–5), Line |
+| **Action Buttons** | Home, Help, Information, Return, BackPrevious, ForwardNext, etc. |
+| **Others** | Cube, Can, Heart, Sun, Moon, SmileyFace, Cloud, Funnel, Gear, etc. |
 
-### Preset shapes
-
-This lib provide about 180+ kind of shapes.
-
-```typescript
-export enum ShapeTypeEnum {
-    // Basic Shapes
-    Rectangle = 'rect',
-    RoundRectangle = 'roundRect',
-    Ellipse = 'ellipse',
-    Diamond = 'diamond',
-    Triangle = 'triangle',
-    RightTriangle = 'rtTriangle',
-    Parallelogram = 'parallelogram',
-    Trapezoid = 'trapezoid',
-    Hexagon = 'hexagon', 
-    Octagon = 'octagon',
-    Plus = 'plus',
-    Star5 = 'star5',
-    Star6 = 'star6',
-    Star7 = 'star7',
-    Star8 = 'star8',
-    Star10 = 'star10',
-    Star12 = 'star12',
-    Star16 = 'star16',
-    Star24 = 'star24',
-    Star32 = 'star32',
-    Round1Rect = 'round1Rect',
-    Round2SameRect = 'round2SameRect',
-    Round2DiagRect = 'round2DiagRect',
-    SnipRectangle1 = 'snip1Rect',
-    SnipRoundRectangle1 = 'snipRoundRect',
-    SnipRectangle2Same = 'snip2SameRect',
-    SnipRectangle2Diagonal = 'snip2DiagRect',
-    Plaque = 'plaque',
-    Frame = 'frame',
-    HalfFrame = 'halfFrame',
-    Corner = 'corner',
-    DiagStripe = 'diagStripe',
-    Chord = 'chord',
-    Arc = 'arc',
-    LeftCircularArrow = 'leftCircularArrow',
-    LeftRightCircularArrow = 'leftRightCircularArrow',
-    SwooshArrow = 'swooshArrow',
-    LeftRightRibbon = 'leftRightRibbon',
-    TextBox = 'textBox',
-    Circle = 'circle',
-    Heptagon = 'heptagon',
-    HomePlate = 'homePlate',
-
-    RightArrow = 'rightArrow',
-    LeftArrow = 'leftArrow',
-    UpArrow = 'upArrow',
-    DownArrow = 'downArrow',
-    LeftRightArrow = 'leftRightArrow',
-    UpDownArrow = 'upDownArrow',
-    QuadArrow = 'quadArrow',
-    LeftRightUpArrow = 'leftRightUpArrow',
-    BentArrow = 'bentArrow',
-    UturnArrow = 'uturnArrow',
-    LeftUpArrow = 'leftUpArrow',
-    BentUpArrow = 'bentUpArrow',
-    CurvedRightArrow = 'curvedRightArrow',
-    CurvedLeftArrow = 'curvedLeftArrow',
-    CurvedUpArrow = 'curvedUpArrow',
-    CurvedDownArrow = 'curvedDownArrow',
-    StripedRightArrow = 'stripedRightArrow',
-    NotchedRightArrow = 'notchedRightArrow',
-    Pentagon = 'pentagon',
-    Chevron = 'chevron',
-    RightArrowCallout = 'rightArrowCallout',
-    DownArrowCallout = 'downArrowCallout',
-    LeftArrowCallout = 'leftArrowCallout',
-    UpArrowCallout = 'upArrowCallout',
-    LeftRightArrowCallout = 'leftRightArrowCallout',
-    QuadArrowCallout = 'quadArrowCallout',
-    CircularArrow = 'circularArrow',
-
-    MathPlus = 'mathPlus',
-    MathMinus = 'mathMinus',
-    MathMultiply = 'mathMultiply',
-    MathDivide = 'mathDivide',
-    MathEqual = 'mathEqual',
-    MathNotEqual = 'mathNotEqual',
-
-    FlowchartProcess = 'flowChartProcess',
-    FlowchartAlternateProcess = 'flowChartAlternateProcess',
-    FlowchartDecision = 'flowChartDecision',
-    FlowChartInputOutput = 'flowChartInputOutput',
-    FlowchartPredefinedProcess = 'flowChartPredefinedProcess',
-    FlowchartInternalStorage = 'flowChartInternalStorage',
-    FlowchartDocument = 'flowChartDocument',
-    FlowchartMultiDocument = 'flowChartMultidocument',
-    FlowchartTerminator = 'flowChartTerminator',
-    FlowchartPreparation = 'flowChartPreparation',
-    FlowchartManualInput = 'flowChartManualInput',
-    FlowchartManualOperation = 'flowChartManualOperation',
-    FlowchartConnector = 'flowChartConnector',
-    FlowchartOffPageConnector = 'flowChartOffpageConnector',
-    FlowchartPunchedCard = 'flowChartPunchedCard',
-    FlowchartPunchedTape = 'flowChartPunchedTape',
-    FlowchartSummingJunction = 'flowChartSummingJunction',
-    FlowchartOr = 'flowChartOr',
-    FlowchartCollate = 'flowChartCollate',
-    FlowchartSort = 'flowChartSort',
-    FlowchartExtract = 'flowChartExtract',
-    FlowchartMerge = 'flowChartMerge',
-    FlowchartOnlineStorage = 'flowChartOnlineStorage',
-    FlowchartDelay = 'flowChartDelay',
-    FlowchartMagneticTape = 'flowChartMagneticTape',
-    FlowchartMagneticDisk = 'flowChartMagneticDisk',
-    FlowchartMagneticDrum = 'flowChartMagneticDrum',
-    FlowchartDisplay = 'flowChartDisplay',
-
-    WedgeRectCallout = 'wedgeRectCallout',
-    WedgeRoundRectCallout = 'wedgeRoundRectCallout',
-    WedgeEllipseCallout = 'wedgeEllipseCallout',
-    CloudCallout = 'cloudCallout',
-    BorderCallout1 = 'borderCallout1',
-    BorderCallout2 = 'borderCallout2',
-    BorderCallout3 = 'borderCallout3',
-    AccentCallout1 = 'accentCallout1',
-    AccentCallout2 = 'accentCallout2',
-    AccentCallout3 = 'accentCallout3',
-    Callout1 = 'callout1',
-    Callout2 = 'callout2',
-    Callout3 = 'callout3',
-    AccentBorderCallout1 = 'accentBorderCallout1',
-    AccentBorderCallout2 = 'accentBorderCallout2',
-    AccentBorderCallout3 = 'accentBorderCallout3',
-
-
-    Ribbon = 'ribbon',
-    Ribbon2 = 'ribbon2',
-    EllipseRibbon = 'ellipseRibbon',
-    EllipseRibbon2 = 'ellipseRibbon2',
-    VerticalScroll = 'verticalScroll',
-    HorizontalScroll = 'horizontalScroll',
-    Wave = 'wave',
-    DoubleWave = 'doubleWave',
-
-    Cube = 'cube',
-    Can = 'can',
-    LightningBolt = 'lightningBolt',
-    Heart = 'heart',
-    Sun = 'sun',
-    Moon = 'moon', 
-    SmileyFace = 'smileyFace',
-    IrregularSeal1 = 'irregularSeal1',
-    IrregularSeal2 = 'irregularSeal2',
-    FoldedCorner = 'folderCorner',
-    Bevel = 'bevel',
-    Donut = 'donut', 
-    NoSmoking = 'noSmoking',
-    BlockArc = 'blockArc',
-
-    Teardrop = 'teardrop', 
-    PieWedge = 'pieWedge',
-    Pie = 'pie',
-    Funnel = 'funnel', 
-    Gear6 = 'gear6',
-    Gear9 = 'gear9',
-    Decagon = 'decagon',
-    Dodecagon = 'dodecagon',
-    CornerTabs = 'cornerTabs',
-    LeftBrace = 'leftBrace',
-    RightBrace = 'rightBrace',
-    LeftBracket = 'leftBracket',
-    RightBracket = 'rightBracket',
-    ActionButtonBackPrevious = 'actionButtonBackPrevious',
-    ActionButtonForwardNext = 'actionButtonForwardNext',
-    ActionButtonBeginning = 'actionButtonBeginning',
-    ActionButtonEnd = 'actionButtonEnd',
-    ActionButtonHome = 'actionButtonHome',
-    ActionButtonInformation = 'actionButtonInformation',
-    ActionButtonReturn = 'actionButtonReturn',
-    ActionButtonMovie = 'actionButtonMovie',
-    ActionButtonDocument = 'actionButtonDocument',
-    ActionButtonSound = 'actionButtonSound',
-    ActionButtonHelp = 'actionButtonHelp',
-    ActionButtonBlank = 'actionButtonBlank',
-
-    BracePair = 'bracePair',
-    BracketPair = 'bracketPair',
-    ChartPlus = 'chartPlus', 
-    ChartStar = 'chartStar', 
-    ChartX = 'chartX',
-    Cloud = 'cloud',
-    FlowChartOfflineStorage = 'flowChartOfflineStorage',
-    LineInv = 'lineInv',
-    NonIsoscelesTrapezoid = 'nonIsoscelesTrapezoid',
-    PlaqueTabs = 'plaqueTabs',
-    SquareTabs = 'squareTabs',
-    Star4 = 'star4',
-    UpDownArrowCallout = 'upDownArrowCallout',
-
-    Line = 'line',
-    StraightConnector1 = 'straightConnector1',
-    BentConnector2 = 'bentConnector2',
-    BentConnector3 = 'bentConnector3',
-    BentConnector4 = 'bentConnector4',
-    BentConnector5 = 'bentConnector5',
-    CurvedConnector2 = 'curvedConnector2',
-    CurvedConnector3 = 'curvedConnector3',
-    CurvedConnector4 = 'curvedConnector4',
-    CurvedConnector5 = 'curvedConnector5',
-}
-```
+### Fill & Stroke
+
+All shapes support three fill modes:
+
+- **No fill** — transparent background.
+- **Solid fill** — a single solid color.
+- **Gradient fill** — linear or radial gradients.
+
+Stroke styling is fully configurable, including color, width, dash patterns (solid, dash, dot, etc.), and line join/cap styles.
+
+### Text in Shapes
+
+Most shapes support inline text editing via double-click. Rich text formatting is supported within shape text, including font size, color, bold, italic, and alignment.
+
+### Adjust Points
+
+Adjust points provide parameterized editing of shape geometry. Each shape may have zero or more adjust points, which fall into the following types:
+
+- **XY adjust points** — control position offsets along the X/Y axes.
+- **Angle adjust points** — control angular parameters.
+- **Radius adjust points** — control radial dimensions.
+
+Adjust points can be manipulated through the UI (drag handles) or programmatically via API. For example, the `SmileyFace` shape has an adjust point that controls the mouth curvature — dragging it can turn a smile into a frown.
+
+### Connection Sites
+
+Connection sites are predefined anchor points on a shape's boundary, used for snapping connectors. When a connector is attached to a connection site, moving the shape automatically updates the connector's path.
+
+### Connectors
+
+Three connector line types are supported:
+
+- **Straight** — a direct line between two points.
+- **Bent (elbow)** — an orthogonal polyline with right-angle bends.
+- **Curved** — a smooth Bezier curve.
+
+All connectors feature:
+
+- **Auto-routing** — automatically computes the optimal path around obstacles, similar to Excel.
+- **Shape binding** — attach connector endpoints to connection sites on shapes; moving the shape updates the connector path automatically. Dragging the connector itself detaches it from the bound shape.
+- **Arrow heads** — configurable start and end arrow styles.
+- **Dash styles** — solid, dashed, dotted, and other dash patterns.
+- **Adjust points** — fine-tune the connector path by dragging intermediate control points.