@atlaskit/editor-plugin-guideline 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @atlaskit/editor-plugin-guideline
 
+## 0.3.2
+
+### Patch Changes
+
+- [`73b5128036b`](https://bitbucket.org/atlassian/atlassian-frontend/commits/73b5128036b) - [ED-17082] Mark package as a singleton one
+- Updated dependencies
+
+## 0.3.1
+
+### Patch Changes
+
+- [`7cd4abcdc0d`](https://bitbucket.org/atlassian/atlassian-frontend/commits/7cd4abcdc0d) - Fix workaround in `editor-plugin-width`. This involved removing `WidthEmitter` in `editor-core`, removing `containerWidth` from `WidthPluginState`. This change also introduces `usePluginHook` for an `EditorPlugin` - this enables a react hook to be mounted for plugins (in all appearances).
+- Updated dependencies
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -4,6 +4,101 @@ guideline plugin for @atlaskit/editor-core
 
 ## Usage
 
-`import EditorPluginGuideline from '@atlaskit/editor-plugin-guideline';`
+See `packages/editor/editor-plugin-guideline/src/types.ts` for detailed guideline config interface.
+
+Example usage:
+
+```
+pluginInjectionApi?.dependencies?.guideline?.actions?.displayGuideline(view)({
+  guidelines: [{
+    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"
+    position: {
+      x: 300
+    };
+    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.
+
+
+
+## Position:
+
+The following diagram shows:
+- The layout of the guideline display area
+- The position of a guideline for a given X value.
+<pre>
+
+
+
+  │                   editor width                    │
+  │------------------- max 1800px --------------------│
+  │                                                   │
+  │          center line (when position x=0)          │
+  │                         │                         │
+  │--------- x < 0 ---------│--------- x > 0 ---------│
+  │                         │                         │
+  ┌────────────┬────────────┬────────────┬────────────┐
+  │            │            │            │            │
+  │            │            │            │            │
+  │            │            │            │            │
+  │            │-- 380px ---│--- 380px --│            │
+  │            │            │            │            │
+  │            │            │            │            │
+  │            │            │            │            │
+  └────────────┴────────────┴────────────┴────────────┘
+               │      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)
+
+
+## State/Style
+
+We have the follow state/style configurations
+```
+type GuidelineConfig = {
+  ...
+  active?: boolean;
+  show?: boolean;
+  style?: 'dashed' | 'solid'; // default solid
+  color?: string;
+};
+```
+
+- `active` default `false`, equivalent to the `highlight` state in the `grid` plugin.
+- `style` default `solid`, and we also support `dashed`
+- `show` default `true` and you can also hide a guideline, could be useful when you need animations.
+- `color`: default `undefined` you can override the color of a guideline with a valid `css` color
+
+## 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.
 
-Detailed docs and example usage can be found [here](https://atlaskit.atlassian.com/packages/editor/editor-plugin-guideline).

package/dist/cjs/plugin.js

@@ -59,7 +59,7 @@ var ContentComponent = function ContentComponent(_ref) {
   var _useSharedPluginState = (0, _hooks.useSharedPluginState)(api, ['width', 'guideline']),
     widthState = _useSharedPluginState.widthState,
     guidelineState = _useSharedPluginState.guidelineState;
-  if (!widthState || !widthState.containerWidth || !widthState.lineLength || !guidelineState || !guidelineState.guidelines || guidelineState.guidelines.length === 0) {
+  if (!widthState || !widthState.width || !widthState.lineLength || !guidelineState || !guidelineState.guidelines || guidelineState.guidelines.length === 0) {
     return null;
   }
   return (0, _react.jsx)("div", {
@@ -68,7 +68,7 @@ var ContentComponent = function ContentComponent(_ref) {
     guidelines: guidelineState.guidelines,
     height: editorView.dom.scrollHeight,
     centerOffset: (0, _utils.getEditorCenterX)(editorView),
-    containerWidth: widthState.containerWidth,
+    width: widthState.width,
     editorWidth: widthState.lineLength
   }));
 };

package/dist/cjs/version.json

@@ -1,5 +1,5 @@
 {
 	"name": "@atlaskit/editor-plugin-guideline",
-	"version": "0.3.0",
+	"version": "0.3.2",
 	"sideEffects": false
 }

package/dist/es2019/plugin.js

@@ -53,7 +53,7 @@ const ContentComponent = ({
     widthState,
     guidelineState
   } = useSharedPluginState(api, ['width', 'guideline']);
-  if (!widthState || !widthState.containerWidth || !widthState.lineLength || !guidelineState || !guidelineState.guidelines || guidelineState.guidelines.length === 0) {
+  if (!widthState || !widthState.width || !widthState.lineLength || !guidelineState || !guidelineState.guidelines || guidelineState.guidelines.length === 0) {
     return null;
   }
   return jsx("div", {
@@ -62,7 +62,7 @@ const ContentComponent = ({
     guidelines: guidelineState.guidelines,
     height: editorView.dom.scrollHeight,
     centerOffset: getEditorCenterX(editorView),
-    containerWidth: widthState.containerWidth,
+    width: widthState.width,
     editorWidth: widthState.lineLength
   }));
 };

package/dist/es2019/version.json

@@ -1,5 +1,5 @@
 {
 	"name": "@atlaskit/editor-plugin-guideline",
-	"version": "0.3.0",
+	"version": "0.3.2",
 	"sideEffects": false
 }

package/dist/esm/plugin.js

@@ -51,7 +51,7 @@ var ContentComponent = function ContentComponent(_ref) {
   var _useSharedPluginState = useSharedPluginState(api, ['width', 'guideline']),
     widthState = _useSharedPluginState.widthState,
     guidelineState = _useSharedPluginState.guidelineState;
-  if (!widthState || !widthState.containerWidth || !widthState.lineLength || !guidelineState || !guidelineState.guidelines || guidelineState.guidelines.length === 0) {
+  if (!widthState || !widthState.width || !widthState.lineLength || !guidelineState || !guidelineState.guidelines || guidelineState.guidelines.length === 0) {
     return null;
   }
   return jsx("div", {
@@ -60,7 +60,7 @@ var ContentComponent = function ContentComponent(_ref) {
     guidelines: guidelineState.guidelines,
     height: editorView.dom.scrollHeight,
     centerOffset: getEditorCenterX(editorView),
-    containerWidth: widthState.containerWidth,
+    width: widthState.width,
     editorWidth: widthState.lineLength
   }));
 };

package/dist/esm/version.json

@@ -1,5 +1,5 @@
 {
 	"name": "@atlaskit/editor-plugin-guideline",
-	"version": "0.3.0",
+	"version": "0.3.2",
 	"sideEffects": false
 }

package/dist/types/guildelineContainer.d.ts

@@ -4,7 +4,7 @@ type ContainerProps = {
     guidelines: GuidelineConfig[];
     height: number;
     centerOffset: number;
-    containerWidth: number;
+    width: number;
     editorWidth: number;
 };
 export declare const GuidelineContainer: (props: ContainerProps) => jsx.JSX.Element;

package/dist/types-ts4.5/guildelineContainer.d.ts

@@ -4,7 +4,7 @@ type ContainerProps = {
     guidelines: GuidelineConfig[];
     height: number;
     centerOffset: number;
-    containerWidth: number;
+    width: number;
     editorWidth: number;
 };
 export declare const GuidelineContainer: (props: ContainerProps) => jsx.JSX.Element;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlaskit/editor-plugin-guideline",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "guideline plugin for @atlaskit/editor-core",
   "author": "Atlassian Pty Ltd",
   "license": "Apache-2.0",
@@ -8,8 +8,9 @@
     "registry": "https://registry.npmjs.org/"
   },
   "atlassian": {
-    "team": "Editor",
-    "releaseModel": "scheduled"
+    "team": "Editor Media Experience: Porygon",
+    "singleton": true,
+    "releaseModel": "continuous"
   },
   "repository": "https://bitbucket.org/atlassian/atlassian-frontend",
   "main": "dist/cjs/index.js",
@@ -22,11 +23,11 @@
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@atlaskit/editor-common": "^74.4.0",
-    "@atlaskit/editor-plugin-width": "^0.0.1",
+    "@atlaskit/editor-common": "^74.9.0",
+    "@atlaskit/editor-plugin-width": "^0.1.0",
     "@atlaskit/editor-shared-styles": "^2.4.0",
     "@atlaskit/theme": "^12.5.0",
-    "@atlaskit/tokens": "^1.4.2",
+    "@atlaskit/tokens": "^1.9.0",
     "@babel/runtime": "^7.0.0",
     "@emotion/react": "^11.7.1",
     "prosemirror-state": "1.3.4",
@@ -36,12 +37,6 @@
     "react": "^16.8.0"
   },
   "devDependencies": {
-    "@atlaskit/docs": "*",
-    "@atlaskit/editor-core": "^185.1.0",
-    "@atlaskit/editor-test-helpers": "^18.5.0",
-    "@atlaskit/ssr": "*",
-    "@atlaskit/visual-regression": "*",
-    "@atlaskit/webdriver-runner": "*",
     "@atlassian/atlassian-frontend-prettier-config-1.0.0": "npm:@atlassian/atlassian-frontend-prettier-config@1.0.0",
     "@testing-library/react": "^12.1.5",
     "react-dom": "^16.8.0",

package/report.api.md

@@ -28,23 +28,13 @@ type DisplayGuideline = (view: EditorView) => DisplayGrid;
 // @public (undocumented)
 export type GuidelineConfig = {
   key: string;
-  position: GuidelinePosition;
+  position: Position;
   active?: boolean;
   show?: boolean;
   style?: 'dashed' | 'solid';
   color?: string;
 };
 
-// @public (undocumented)
-enum GuidelineContainerArea {
-  // (undocumented)
-  EditorContent = 'editorContent',
-  // (undocumented)
-  EditorLeftMargin = 'editorLeftMargin',
-  // (undocumented)
-  EditorRightMargin = 'editorRightMargin',
-}
-
 // @public (undocumented)
 export const guidelinePlugin: NextEditorPlugin<
   'guideline',
@@ -63,23 +53,9 @@ type GuidelinePluginState = {
 };
 
 // @public (undocumented)
-type GuidelinePosition = {
-  containerArea?: GuidelineContainerArea;
-} & PositionSide;
-
-// @public (undocumented)
-type PositionSide =
-  | {
-      left: PositionValue;
-      right?: never;
-    }
-  | {
-      right: PositionValue;
-      left?: never;
-    };
-
-// @public (undocumented)
-type PositionValue = 0 | `${number}%` | `${number}px`;
+type Position = {
+  x: number;
+};
 
 // (No @packageDocumentation comment for this package)
 ```

package/tmp/api-report-tmp.d.ts

@@ -0,0 +1,48 @@
+## API Report File for "@atlaskit/editor-plugin-guideline"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { EditorView } from 'prosemirror-view';
+import { NextEditorPlugin } from '@atlaskit/editor-common/types';
+import type { widthPlugin } from '@atlaskit/editor-plugin-width';
+
+// @public (undocumented)
+type DisplayGrid = (props: Required<GuidelinePluginState>) => boolean;
+
+// @public (undocumented)
+type DisplayGuideline = (view: EditorView) => DisplayGrid;
+
+// @public (undocumented)
+export type GuidelineConfig = {
+    key: string;
+    position: Position;
+    active?: boolean;
+    show?: boolean;
+    style?: 'dashed' | 'solid';
+    color?: string;
+};
+
+// @public (undocumented)
+export const guidelinePlugin: NextEditorPlugin<'guideline', {
+    dependencies: [typeof widthPlugin];
+    sharedState: GuidelinePluginState | null;
+    actions: {
+        displayGuideline: DisplayGuideline;
+    };
+}>;
+
+// @public (undocumented)
+type GuidelinePluginState = {
+    guidelines: GuidelineConfig[];
+};
+
+// @public (undocumented)
+type Position = {
+    x: number;
+};
+
+// (No @packageDocumentation comment for this package)
+
+```