Merge pull request #7881 from ckeditor/i/7804

Docs: Documentation for the list styles feature. Closes #7804.

packages/ckeditor5-list/docs/_snippets/features/lists-basic.html

@@ -0,0 +1,20 @@
+<div id="snippet-lists-basic">
+    <h2>Unordered list</h2>
+    <p>Such a list can represent items where the order is not important, e.g. a list of ingredients required for preparing a dish or a drink.</p>
+    <p>Ingredients required for making a coffee:</p>
+    <ul>
+        <li>15g coffee ground</li>
+        <li>a cup</li>
+        <li>water</li>
+    </ul>
+    <h2>Ordered list</h2>
+    <p>The ordered list can be used if the order of the items matters, e.g. when describing an instruction. The order of steps that must be done is important.</p>
+    <p>How to prepare the coffee?</p>
+    <ol>
+        <li>Gather the ingredients</li>
+        <li>Put 15g of the coffee ground into the cup</li>
+        <li>Boil 200ml of water</li>
+        <li>Pour water into a cup</li>
+        <li>Optional: add milk as you wish</li>
+    </ol>
+</div>

packages/ckeditor5-list/docs/_snippets/features/lists-basic.js

@@ -0,0 +1,57 @@
+/**
+ * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals window, document, console, ClassicEditor */
+
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-lists-basic' ), {
+		toolbar: {
+			items: [
+				'heading',
+				'|',
+				'bold',
+				'italic',
+				'bulletedList',
+				'numberedList',
+				'|',
+				'outdent',
+				'indent',
+				'|',
+				'link',
+				'imageUpload',
+				'insertTable',
+				'|',
+				'undo',
+				'redo'
+			],
+			viewportTopOffset: window.getViewportTopOffsetConfig()
+		},
+		image: {
+			styles: [
+				'full',
+				'alignLeft',
+				'alignRight'
+			],
+			toolbar: [
+				'imageStyle:alignLeft',
+				'imageStyle:full',
+				'imageStyle:alignRight',
+				'|',
+				'imageTextAlternative'
+			]
+		},
+		table: {
+			contentToolbar: [ 'tableColumn', 'tableRow', 'mergeTableCells' ]
+		},
+		cloudServices: CS_CONFIG
+	} )
+	.then( editor => {
+		window.editorBasic = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

packages/ckeditor5-list/docs/_snippets/features/lists-source.js

@@ -0,0 +1,12 @@
+/**
+ * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals window */
+
+import ClassicEditor from '@ckeditor/ckeditor5-build-classic/src/ckeditor';
+import ListStyle from '@ckeditor/ckeditor5-list/src/liststyle';
+
+window.ClassicEditor = ClassicEditor;
+window.ListStyle = ListStyle;

packages/ckeditor5-list/docs/_snippets/features/lists-style.html

@@ -0,0 +1,17 @@
+<div id="snippet-lists-styles">
+    <p>Let's use the coffee recipe from the demo in section <a href="#demo">Ordered and unordered lists</a> and use the list styles feature.</p>
+    <p>Ingredients required for making a coffee:</p>
+    <ul style="list-style-type:circle;">
+        <li>15g coffee ground</li>
+        <li>a cup</li>
+        <li>water</li>
+    </ul>
+    <p>How to prepare the coffee?</p>
+    <ol style="list-style-type:decimal-leading-zero;">
+        <li>Gather the ingredients</li>
+        <li>Put 15g of the coffee ground into the cup</li>
+        <li>Boil 200ml of water</li>
+        <li>Pour water into a cup</li>
+        <li>Optional: add milk as you wish</li>
+    </ol>
+</div>

packages/ckeditor5-list/docs/_snippets/features/lists-style.js

@@ -0,0 +1,58 @@
+/**
+ * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/* globals window, document, console, ClassicEditor, ListStyle */
+
+import { CS_CONFIG } from '@ckeditor/ckeditor5-cloud-services/tests/_utils/cloud-services-config';
+
+ClassicEditor
+	.create( document.querySelector( '#snippet-lists-styles' ), {
+		extraPlugins: [ ListStyle ],
+		toolbar: {
+			items: [
+				'heading',
+				'|',
+				'bold',
+				'italic',
+				'bulletedList',
+				'numberedList',
+				'|',
+				'outdent',
+				'indent',
+				'|',
+				'link',
+				'imageUpload',
+				'insertTable',
+				'|',
+				'undo',
+				'redo'
+			],
+			viewportTopOffset: window.getViewportTopOffsetConfig()
+		},
+		image: {
+			styles: [
+				'full',
+				'alignLeft',
+				'alignRight'
+			],
+			toolbar: [
+				'imageStyle:alignLeft',
+				'imageStyle:full',
+				'imageStyle:alignRight',
+				'|',
+				'imageTextAlternative'
+			]
+		},
+		table: {
+			contentToolbar: [ 'tableColumn', 'tableRow', 'mergeTableCells' ]
+		},
+		cloudServices: CS_CONFIG
+	} )
+	.then( editor => {
+		window.editorStyles = editor;
+	} )
+	.catch( err => {
+		console.error( err.stack );
+	} );

packages/ckeditor5-list/docs/features/lists.md

@@ -0,0 +1,93 @@
+---
+category: features
+---
+
+# Lists
+
+The {@link module:list/list~List list} feature allows creating ordered and unordered lists in the editor.
+
+<info-box info>
+	The feature is enabled by default in all CKEditor 5 WYSIWYG editor builds.
+</info-box>
+
+{@snippet features/lists-source}
+
+## Ordered and unordered lists
+
+Use the editor below to see the list feature plugin in action.
+
+### Demo
+
+{@snippet features/lists-basic}
+
+## List styles
+
+The {@link module:list/liststyle~ListStyle list styles} feature allows customizing the list's marker.
+
+### Demo
+
+Use the editor below to see the list styles feature plugin in action.
+
+{@snippet features/lists-style}
+
+### Installation
+
+To add this feature to your editor, install the [`@ckeditor/ckeditor5-list`](https://www.npmjs.com/package/@ckeditor/ckeditor5-list) package:
+
+```bash
+npm install --save @ckeditor/ckeditor5-list
+```
+
+Then add the `ListStyle` plugin to your plugin list and the toolbar configuration:
+
+```js
+import ListStyle from '@ckeditor/ckeditor5-list/src/liststyle';
+
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		plugins: [ ListStyle, ... ],
+		toolbar: [ 'bulletedList', 'numberedList', ... ],
+	} )
+	.then( ... )
+	.catch( ... );
+```
+
+<info-box info>
+	Read more about {@link builds/guides/integration/installing-plugins installing plugins}.
+</info-box>
+
+<info-box warning>
+	The {@link module:list/liststyle~ListStyle} feature overrides UI button implementations from the {@link module:list/listui~ListUI}.
+</info-box>
+
+## To-do list
+
+You can read more about the feature in the {@link features/todo-lists To-do lists} feature guide.
+
+## Common API
+
+The {@link module:list/list~List} plugin registers:
+
+* The {@link module:list/listcommand~ListCommand `'numberedList'`} command.
+* The {@link module:list/listcommand~ListCommand `'bulletedList'`} command.
+* The {@link module:list/indentcommand~IndentCommand `'indentList'`} command.
+* The {@link module:list/indentcommand~IndentCommand `'outdentList'`} command.
+* The `'numberedList'` ui button.
+* The `'bulletedList'` ui button.
+
+The {@link module:list/liststyle~ListStyle} plugin registers:
+
+* The {@link module:list/liststylecommand~ListStyleCommand `'listStyle'`} command that accepts a `type` of a list style to set.
+    ```js
+    editor.execute( 'listStyle', { type: 'decimal' } );
+    ```
+    The available types are:
+
+    * For bulleted lists: `'disc'`, `'circle'`, and `'square'`.
+    * For numbered lists: `'decimal'`, `'decimal-leading-zero'`, `'lower-roman'`, `'upper-roman'`, `'lower-latin'`, and `'upper-latin'`.
+* The `'numberedList'` ui split button (it overrides UI button registered by the `List` plguin.
+* The `'bulletedList'` ui split button (it overrides UI button registered by the `List` plguin.
+
+## Contribute
+
+The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-list.

packages/ckeditor5-list/docs/features/todo-lists.md

@@ -88,6 +88,10 @@ From the technical point of view, to-do lists are built on top of the {@link mod
 <listItem listType="todo" todoListChecked="true">Bar</listItem>
 ```
 
+## Ordered and unordered lists
+
+You can read more about those features in the {@link features/lists Lists} feature guide.
+
 ## Contribute
 
 The source code of the feature is available on GitHub in https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-list.