@atlaskit/editor-plugin-guideline 8.0.3 → 8.0.4

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @atlaskit/editor-plugin-guideline
 
+## 8.0.4
+
+### Patch Changes
+
+- [`3da5fc5ff18bc`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/3da5fc5ff18bc) -
+  Update README.md and 0-intro.tsx
+- Updated dependencies
+
 ## 8.0.3
 
 ### Patch Changes

package/README.md

@@ -1,52 +1,68 @@
-# EditorPluginGuideline
+# Editor Plugin Guideline
 
-guideline plugin for @atlaskit/editor-core
+Guideline plugin for @atlaskit/editor-core
 
-## Usage
+## Overview
+
+The Guideline plugin provides the ability to display vertical guidelines in the editor. Guidelines are rendered as vertical lines at specified positions and can be customized with different styles and states. This plugin was designed to contain only basic logic to render guidelines. Commonly used configurations and utilities reside in the `editor-common` package.
+
+## Key features
 
-See `packages/editor/editor-plugin-guideline/src/types.ts` for detailed guideline config interface.
+- **Display guidelines** - Render vertical guidelines at specified positions within the editor
+- **Flexible positioning** - Position guidelines using coordinate values relative to the editor center
+- **Customizable styles** - Configure line style (solid/dashed), color, and cap style
+- **State management** - Control visibility and active states of individual guidelines
+- **Plugin integration** - Works with the width plugin to calculate correct positioning
 
-Example usage:
+## Install
 
 ```
+yarn add @atlaskit/editor-plugin-guideline
+```
+
+- **npm** - [@atlaskit/editor-plugin-guideline](https://www.npmjs.com/package/@atlaskit/editor-plugin-guideline)
+- **Source** - [Bitbucket](https://bitbucket.org/atlassian/atlassian-frontend/src/master/packages/editor/editor-plugin-guideline)
+
+## Usage
+
+### Basic Example
+
+```typescript
 pluginInjectionApi?.dependencies?.guideline?.actions?.displayGuideline(view)({
   guidelines: [{
-    key: "guideline_01"
+    key: "guideline_01",
     position: {
       x: -100
-    }; // The position of the guideline
+    },
     active: true,
     style: "dashed",
     color: "rgba(0, 0, 0, 0.2)"
   }, 
   {
-    key: "guideline_02"
+    key: "guideline_02",
     position: {
       x: 300
-    };
-    show: false,
+    },
+    show: false
   }]
 });
-```  
-
-A guideline config consists of three parts:
-  - A unique key (required)
-  - Position (required)
-  - State/Style (optional)
-
-This plugin was designed to be "dumb". Meaning that it only contains very basic logics to render the guidelines. Commonly used configurations and utils will be reside in the `editor-common` package.
+```
 
+### Guideline Configuration
 
+A guideline config consists of three parts:
 
-## Position:
+- **Key** (required) - A unique identifier for the guideline
+- **Position** (required) - The x-coordinate position of the guideline
+- **State/Style** (optional) - Display state and styling options
 
-The following diagram shows:
-- The layout of the guideline display area
-- The position of a guideline for a given X value.
-<pre>
+### Position
 
+The position value is defined as: `type Position = { x: number };`
 
+Position diagram:
 
+```
   │                   editor width                    │
   │------------------- max 1800px --------------------│
   │                                                   │
@@ -66,43 +82,40 @@ The following diagram shows:
                │      editor content     │
                │-------- max 760px ------│
   │---------- or 1800px in full-width mode  ----------│
-               
-</pre>
+```
 
-The position value is defined as follow:
-  `type Position = { x: number };`
-* When x is 0, a vertical line is displayed at the center of the editor (see the diagram above). 
-* A negative value will move the line to the left, up to minus half of the editor width.
-* A positive value will move the line to the right, up to half of the editor width.
-* If a `x` value is outside of the visible range, if will be ignored. (See the todo section)
+- When `x` is 0, a vertical line is displayed at the center of the editor
+- Negative values move the line left (up to minus half of the editor width)
+- Positive values move the line right (up to half of the editor width)
+- Guidelines outside the visible range are ignored
 
+### State and Style
 
-## State/Style
+Configure guidelines with the following state and style options:
 
-We have the follow state/style configurations
-```
+```typescript
 type GuidelineConfig = {
-  ...
-  active?: boolean;
-  show?: boolean;
-  styles: {
-    lineStyle?: 'dashed' | 'solid'; // default solid
-    color?: CSSToken;
-    capStyle?: 'line'
+  // ...
+  active?: boolean;           // default false
+  show?: boolean;             // default true
+  styles?: {
+    lineStyle?: 'dashed' | 'solid';  // default 'solid'
+    color?: CSSToken;                // default undefined
+    capStyle?: 'line'                // default undefined
   }
 };
 ```
 
-- `active` default `false`, equivalent to the `highlight` state in the `grid` plugin.
-- `show` default `true` and you can also hide a guideline, could be useful when you need animations.
-- `styles.color`: default `undefined` you can override the color of a guideline with a valid `css` color
-- `styles.lineStyle` default `solid`, and we also support `dashed`
-- `styles.capStyle` default undefined, and support `line`
+- `active` - Equivalent to the highlight state in the grid plugin
+- `show` - Hide a guideline (useful for animations)
+- `styles.color` - Override the guideline color with a valid CSS color
+- `styles.lineStyle` - Line style can be 'solid' or 'dashed'
+- `styles.capStyle` - Line cap style, supports 'line'
+
+## Support
+
+For internal Atlassian, visit the slack channel [#help-editor](https://atlassian.slack.com/archives/CFG3PSQ9E) for support or visit [go/editor-help](https://go/editor-help) to submit a bug.
 
-## TODO
-- [ ] Add unit/vr tests
-- [ ] Handle guidelines which are outside of visitable range. 
-- [ ] Implement the Grid plug option, `shouldCalcBreakoutGridLines?: boolean;`
-- [ ] Retire the exist Grid plugin. and replace it with this plugin. Plugins currently use the grid plugin: media, table and card.
-- [ ] Investigate a better way to handle the `color` attribute, to avoid a fragmented experiences in the Editor.
+## License
 
+Please see [Atlassian Frontend - License](https://hello.atlassian.net/wiki/spaces/AF/pages/2589099144/Documentation#License) for more licensing information.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/editor-plugin-guideline",
-	"version": "8.0.3",
+	"version": "8.0.4",
 	"description": "guideline plugin for @atlaskit/editor-core",
 	"author": "Atlassian Pty Ltd",
 	"license": "Apache-2.0",