Parcourir la source

Other review part. Lots of docs improvements. Expose config with amount of columns drawed in color table dropdown.

Mateusz Samsel il y a 6 ans
Parent
commit
1bc1a85b89

+ 96 - 0
packages/ckeditor5-font/src/fontbackgroundcolor.js

@@ -11,6 +11,15 @@ import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
 import FontBackgroundColorEditing from './fontbackgroundcolor/fontbackgroundcolorediting';
 import FontBackgroundColorUI from './fontbackgroundcolor/fontbackgroundcolorui';
 
+/**
+ * The font background color plugin.
+ *
+ * This is a "glue" plugin which loads
+ * the {@link module:font/fontbackgroundcolor/fontbackgroundcolorediting~FontBackgroundColorEditing} and
+ * {@link module:font/fontbackgroundcolor/fontbackgroundcolorui~FontBackgroundColorUI} features in the editor.
+ *
+ * @extends module:core/plugin~Plugin
+ */
 export default class FontBackgroundColor extends Plugin {
 	/**
 	 * @inheritDoc
@@ -26,3 +35,90 @@ export default class FontBackgroundColor extends Plugin {
 		return 'FontBackgroundColor';
 	}
 }
+
+/**
+ * The configuration of the font background color feature.
+ * This option is used by the {@link module:font/fontbackgroundcolor/fontbackgroundcolorediting~FontBackgroundColorEditing} feature.
+ *
+ *		ClassicEditor
+ *			.create( {
+ * 				fontBackgroundColor: ... // Font family feature configuration.
+ *			} )
+ *			.then( ... )
+ *			.catch( ... );
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+ *
+ * @interface module:font/fontbackgroundcolor~FontBackgroundColorConfig
+ */
+
+/**
+ * Available 'font background color' colors defined as an array of strings or objects. The default value is:
+ *
+ *		const fontBackgroundColorConfig = {
+ *			colors: [
+ *				{
+ *					color: 'hsl(0, 0%, 0%)',
+ *					label: 'Black'
+ *				}, {
+ *					color: 'hsl(0, 0%, 30%)',
+ *					label: 'Dim grey'
+ *				}, {
+ *					color: 'hsl(0, 0%, 60%)',
+ *					label: 'Grey'
+ *				}, {
+ *					color: 'hsl(0, 0%, 90%)',
+ *					label: 'Light grey'
+ *				}, {
+ *					color: 'hsl(0, 0%, 100%)',
+ *					label: 'White',
+ *					hasBorder: true
+ *				}, {
+ *					color: 'hsl(0, 75%, 60%)',
+ *					label: 'Red'
+ *				}, {
+ *					color: 'hsl(30, 75%, 60%)',
+ *					label: 'Orange'
+ *				}, {
+ *					color: 'hsl(60, 75%, 60%)',
+ *					label: 'Yellow'
+ *				}, {
+ *					color: 'hsl(90, 75%, 60%)',
+ *					label: 'Light green'
+ *				}, {
+ *					color: 'hsl(120, 75%, 60%)',
+ *					label: 'Green'
+ *				}, {
+ *					color: 'hsl(150, 75%, 60%)',
+ *					label: 'Aquamarine'
+ *				}, {
+ *					color: 'hsl(180, 75%, 60%)',
+ *					label: 'Turquoise'
+ *				}, {
+ *					color: 'hsl(210, 75%, 60%)',
+ *					label: 'Light blue'
+ *				}, {
+ *					color: 'hsl(240, 75%, 60%)',
+ *					label: 'Blue'
+ *				}, {
+ *					color: 'hsl(270, 75%, 60%)',
+ *					label: 'Purple'
+ *				}
+ *			]
+ *		};
+ *
+ * which configures 15 default colors. Each color is used in dropdown as available color to choose from dropdown.
+ *
+ * @member {Array.<String|Object>} module:font/fontbackgroundcolor~FontBackgroundColorConfig#colors
+ */
+
+/**
+ * Value represent amount of drawn columns in color panel. It also represent amount of visible recently used colors.
+ * The default value is:
+ *
+ * 		const fontBackgroundColorConfig = {
+ * 			columns: 5
+ * 		}
+ *
+ * @member {Numebr} module:font/fontbackgroundcolor~FontBackgroundColorConfig#columns
+ */

+ 3 - 2
packages/ckeditor5-font/src/fontbackgroundcolor/fontbackgroundcolorediting.js

@@ -17,7 +17,7 @@ import { FONT_BACKGROUND_COLOR, renderDowncastElement, renderUpcastAttribute } f
  * It introduces the {@link module:font/fontbackgroundcolor/fontbackgroundcolorcommand~FontBackgroundColorCommand command} and
  * the `fontBackgroundColor` attribute in the {@link module:engine/model/model~Model model} which renders
  * in the {@link module:engine/view/view view} as an inline `<span>` element (`<span style="background-color: hsl(0, 0%, 100%)">`),
- * depending on the {@link module:font/fontbackgroundcolor~FontBackgroundColortConfig configuration}.
+ * depending on the {@link module:font/fontbackgroundcolor~FontBackgroundColorConfig configuration}.
  *
  * @extends module:core/plugin~Plugin
  */
@@ -77,7 +77,8 @@ export default class FontBackgroundColorEditing extends Plugin {
 					color: 'hsl(270, 75%, 60%)',
 					label: 'Purple'
 				}
-			]
+			],
+			columns: 5
 		} );
 
 		editor.conversion.for( 'upcast' ).elementToAttribute( {

+ 2 - 2
packages/ckeditor5-font/src/fontbackgroundcolor/fontbackgroundcolorui.js

@@ -4,7 +4,7 @@
  */
 
 /**
- * @module font/fontcolor/fontcolorui
+ * @module font/fontbackgroundcolor/fontbackgroundcolorui
  */
 
 import ColorUI from '../ui/colorui';
@@ -16,7 +16,7 @@ import fontBackgroundColorIcon from '../../theme/icons/font-background.svg';
  *
  * @extends module:core/plugin~Plugin
  */
-export default class FontColorUI extends ColorUI {
+export default class FontBackgroundColorUI extends ColorUI {
 	constructor( editor ) {
 		super( editor, {
 			commandName: FONT_BACKGROUND_COLOR,

+ 95 - 0
packages/ckeditor5-font/src/fontcolor.js

@@ -11,6 +11,14 @@ import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
 import FontColorEditing from './fontcolor/fontcolorediting';
 import FontColorUI from './fontcolor/fontcolorui';
 
+/**
+ * The font color plugin.
+ *
+ * This is a "glue" plugin which loads the {@link module:font/fontcolor/fontcolorediting~FontColorEditing} and
+ * {@link module:font/fontcolor/fontcolorui~FontColorUI} features in the editor.
+ *
+ * @extends module:core/plugin~Plugin
+ */
 export default class FontColor extends Plugin {
 	/**
 	 * @inheritDoc
@@ -26,3 +34,90 @@ export default class FontColor extends Plugin {
 		return 'FontColor';
 	}
 }
+
+/**
+ * The configuration of the font color feature.
+ * This option is used by the {@link module:font/fontcolor/fontcolorediting~FontColorEditing} feature.
+ *
+ *		ClassicEditor
+ *			.create( {
+ * 				fontColor: ... // Font family feature configuration.
+ *			} )
+ *			.then( ... )
+ *			.catch( ... );
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
+ *
+ * @interface module:font/fontcolor~FontColorConfig
+ */
+
+/**
+ * Available 'font color' colors defined as an array of strings or objects. The default value is:
+ *
+ *		const fontColorConfig = {
+ *			colors: [
+ *				{
+ *					color: 'hsl(0, 0%, 0%)',
+ *					label: 'Black'
+ *				}, {
+ *					color: 'hsl(0, 0%, 30%)',
+ *					label: 'Dim grey'
+ *				}, {
+ *					color: 'hsl(0, 0%, 60%)',
+ *					label: 'Grey'
+ *				}, {
+ *					color: 'hsl(0, 0%, 90%)',
+ *					label: 'Light grey'
+ *				}, {
+ *					color: 'hsl(0, 0%, 100%)',
+ *					label: 'White',
+ *					hasBorder: true
+ *				}, {
+ *					color: 'hsl(0, 75%, 60%)',
+ *					label: 'Red'
+ *				}, {
+ *					color: 'hsl(30, 75%, 60%)',
+ *					label: 'Orange'
+ *				}, {
+ *					color: 'hsl(60, 75%, 60%)',
+ *					label: 'Yellow'
+ *				}, {
+ *					color: 'hsl(90, 75%, 60%)',
+ *					label: 'Light green'
+ *				}, {
+ *					color: 'hsl(120, 75%, 60%)',
+ *					label: 'Green'
+ *				}, {
+ *					color: 'hsl(150, 75%, 60%)',
+ *					label: 'Aquamarine'
+ *				}, {
+ *					color: 'hsl(180, 75%, 60%)',
+ *					label: 'Turquoise'
+ *				}, {
+ *					color: 'hsl(210, 75%, 60%)',
+ *					label: 'Light blue'
+ *				}, {
+ *					color: 'hsl(240, 75%, 60%)',
+ *					label: 'Blue'
+ *				}, {
+ *					color: 'hsl(270, 75%, 60%)',
+ *					label: 'Purple'
+ *				}
+ *			]
+ *		};
+ *
+ * which configures 15 default colors. Each color is used in dropdown as available color to choose from dropdown.
+ *
+ * @member {Array.<String|Object>} module:font/fontcolor~FontColorConfig#colors
+ */
+
+/**
+ * Value represent amount of drawn columns in color panel. It also represents amount of visible recently used colors.
+ * The default value is:
+ *
+ * 		const fontColorConfig = {
+ * 			columns: 5
+ * 		}
+ *
+ * @member {Numebr} module:font/fontcolor~FontColorConfig#columns
+ */

+ 3 - 2
packages/ckeditor5-font/src/fontcolor/fontcolorediting.js

@@ -17,7 +17,7 @@ import { FONT_COLOR, renderDowncastElement, renderUpcastAttribute } from '../uti
  * It introduces the {@link module:font/fontcolor/fontcolorcommand~FontColorCommand command} and
  * the `fontColor` attribute in the {@link module:engine/model/model~Model model} which renders
  * in the {@link module:engine/view/view view} as an inline `<span>` element (`<span style="color: hsl(0, 0%, 100%)">`),
- * depending on the {@link module:font/fontcolor~FontColortConfig configuration}.
+ * depending on the {@link module:font/fontcolor~FontColorConfig configuration}.
  *
  * @extends module:core/plugin~Plugin
  */
@@ -77,7 +77,8 @@ export default class FontColorEditing extends Plugin {
 					color: 'hsl(270, 75%, 60%)',
 					label: 'Purple'
 				}
-			]
+			],
+			columns: 5
 		} );
 
 		editor.conversion.for( 'upcast' ).elementToAttribute( {

+ 4 - 2
packages/ckeditor5-font/src/ui/colorgrid.js

@@ -15,6 +15,8 @@ import KeystrokeHandler from '@ckeditor/ckeditor5-utils/src/keystrokehandler';
 
 /**
  * It keeps nicely collection of {@link module:font/ui/colortile~ColorTile}.
+ *
+ * @extends module:ui/view~View
  */
 export default class ColorGrid extends View {
 	/**
@@ -22,7 +24,7 @@ export default class ColorGrid extends View {
 	 *
 	 * @param {module:utils/locale~Locale} [locale] The localization services instance.
 	 * @param {Object} config Configuration
-	 * @param {Array.<module:font/ui/colorgrid~colorsDefinition} colorsDefinition Array with definitions
+	 * @param {Array.<module:font/ui/colorgrid~ColorDefinition>} colorsDefinition Array with definitions
 	 * required to build {@link module:font/ui/colortile~ColorTile}.
 	 */
 	constructor( locale, { colorsDefinition = [] } = {} ) {
@@ -158,7 +160,7 @@ export default class ColorGrid extends View {
  * 			}
  * 		}
  *
- * @typedef module:font/ui/colorgrid~colorsDefinition
+ * @typedef {Object} module:font/ui/colorgrid~ColorDefinition
  * @type Object
  *
  * @property {String} color String representing inserted color.

+ 114 - 22
packages/ckeditor5-font/src/ui/colortableview.js

@@ -3,6 +3,10 @@
  * For licensing, see LICENSE.md.
  */
 
+/**
+ * @module font/ui/colortableview
+ */
+
 import View from '@ckeditor/ckeditor5-ui/src/view';
 import ButtonView from '@ckeditor/ckeditor5-ui/src/button/buttonview';
 import ColorTile from './colortile';
@@ -14,35 +18,87 @@ import KeystrokeHandler from '@ckeditor/ckeditor5-utils/src/keystrokehandler';
 import removeButtonIcon from '@ckeditor/ckeditor5-core/theme/icons/eraser.svg';
 import '../../theme/fontcolor.css';
 
+/**
+ * Class which represents view with {@link module:font/ui/colorgrid~ColorGrid}
+ * and remove buttons inside {@link module:ui/dropdown/dropdownview~DropdownView}.
+ *
+ * @extends module:ui/view~View
+ */
 export default class ColorTableView extends View {
-	constructor( locale, { colors } ) {
+	/**
+	 * Construct view which will be inserted as child of {@link module:ui/dropdown/dropdownview~DropdownView}
+	 * @param {module:utils/locale~Locale} [locale] The localization services instance.
+	 * @param {Object} config Configuration object
+	 * @param {Array.<Object>} config.colors Array with objects drawn as static set of available colors in color table.
+	 * @param {Number} config.colorColumns Number of columns in color grid. Determines how many recent color will be displayed.
+	 * @param {String} config.removeButtonTooltip Description of button responsible for removing color attributes.
+	 */
+	constructor( locale, { colors, colorColumns, removeButtonTooltip } ) {
 		super( locale );
-		this.locale = locale;
+
+		/**
+		 * Collection of the child list views.
+		 *
+		 * @readonly
+		 * @member {module:ui/viewcollection~ViewCollection}
+		 */
 		this.items = this.createCollection();
 
+		/**
+		 * Array with objects representing color to be drawn in color grid.
+		 * @type {Arrray.<Object>}
+		 */
 		this.colorsDefinition = colors;
+
+		/**
+		 * Tracks information about DOM focus in the list.
+		 *
+		 * @readonly
+		 * @member {module:utils/focustracker~FocusTracker}
+		 */
 		this.focusTracker = new FocusTracker();
+
+		/**
+		 * Instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+		 *
+		 * @readonly
+		 * @member {module:utils/keystrokehandler~KeystrokeHandler}
+		 */
 		this.keystrokes = new KeystrokeHandler();
 
+		/**
+		 * Keeps value of command for current selection.
+		 * @type {String}
+		 */
 		this.set( 'selectedColor' );
-		this.set( 'removeButtonTooltip' );
-		this.set( 'colorColumns', 5 );
-		this.set( 'recentlyUsedColors', new Collection() );
-
-		this.initRecentCollection();
-
-		this.setTemplate( {
-			tag: 'div',
-			attributes: {
-				class: [ 'ck-color-table' ]
-			},
-			children: this.items
-		} );
-
-		this.items.add( this.removeColorButton() );
-		this.items.add( this.createColorTableTemplate() );
-		this.items.add( this.recentlyUsed() );
 
+		/**
+		 * Description of button responsible for removing color attributes.
+		 * @type {String}
+		 */
+		this.removeButtonTooltip = removeButtonTooltip;
+
+		/**
+		 * Number of columns in color grid. Determines how many recent color will be displayed.
+		 * @type {Number}
+		 */
+		this.colorColumns = colorColumns;
+
+		/**
+		 * Collection kept model of colors used for Recent Colors section.
+		 *
+		 * @readonly
+		 * @member {module:utils/collection~Collection}
+		 */
+		this.recentlyUsedColors = new Collection();
+
+		/**
+		 * Helps cycling over focusable {@link #items} in the list.
+		 *
+		 * @readonly
+		 * @protected
+		 * @member {module:ui/focuscycler~FocusCycler}
+		 */
 		this._focusCycler = new FocusCycler( {
 			focusables: this.items,
 			focusTracker: this.focusTracker,
@@ -55,16 +111,34 @@ export default class ColorTableView extends View {
 				focusNext: 'arrowdown',
 			}
 		} );
+
+		this.initRecentCollection();
+		this.setTemplate( {
+			tag: 'div',
+			attributes: {
+				class: [ 'ck-color-table' ]
+			},
+			children: this.items
+		} );
+
+		this.items.add( this.removeColorButton() );
+		this.items.add( this.createStaticColorTable() );
+		this.items.add( this.recentlyUsed() );
 	}
 
+	/**
+	 * Adds remove color button as child for current view.
+	 *
+	 * @private
+	 */
 	removeColorButton() {
 		const btnView = new ButtonView();
 		btnView.set( {
 			withText: true,
 			icon: removeButtonIcon,
-			tooltip: true
+			tooltip: true,
+			label: this.removeButtonTooltip
 		} );
-		btnView.bind( 'label' ).to( this, 'removeButtonTooltip' );
 		btnView.class = 'ck-color-table__remove-color';
 		btnView.on( 'execute', () => {
 			this.fire( 'execute', { value: null } );
@@ -72,12 +146,20 @@ export default class ColorTableView extends View {
 		return btnView;
 	}
 
-	createColorTableTemplate() {
+	/**
+	 * Creates static color table grid based on editor config.
+	 * @private
+	 */
+	createStaticColorTable() {
 		const colorGrid = new ColorGrid( this.locale, { colorsDefinition: this.colorsDefinition } );
 		colorGrid.delegate( 'execute' ).to( this );
 		return colorGrid;
 	}
 
+	/**
+	 * Adds recently used color section view and bind it to {@link #recentlyUsedColors}.
+	 * @private
+	 */
 	recentlyUsed() {
 		const recentViews = new ColorGrid( this.locale );
 
@@ -118,6 +200,10 @@ export default class ColorTableView extends View {
 		return recentViews;
 	}
 
+	/**
+	 * Populate {@link #recentlyUsedColors} with empty non-clickable buttons, which represents space for colors.
+	 * @private
+	 */
 	initRecentCollection() {
 		for ( let i = 0; i < this.colorColumns; i++ ) {
 			this.recentlyUsedColors.add( {
@@ -151,10 +237,16 @@ export default class ColorTableView extends View {
 		this.keystrokes.listenTo( this.element );
 	}
 
+	/**
+	 * Focuses the first focusable in {@link #items}.
+	 */
 	focus() {
 		this._focusCycler.focusFirst();
 	}
 
+	/**
+	 * Focuses the last focusable in {@link #items}.
+	 */
 	focusLast() {
 		this._focusCycler.focusLast();
 	}

+ 15 - 8
packages/ckeditor5-font/src/ui/colorui.js

@@ -54,6 +54,12 @@ export default class ColorUI extends Plugin {
 		 * @type {String}
 		 */
 		this.dropdownLabel = dropdownLabel;
+
+		/**
+		 * Number of columns in color grid. Determines how many recent color will be displayed.
+		 * @type {Number}
+		 */
+		this.colorColumns = editor.config.get( `${ this.componentName }.columns` );
 	}
 
 	/**
@@ -69,17 +75,18 @@ export default class ColorUI extends Plugin {
 		// Register UI component.
 		editor.ui.componentFactory.add( this.componentName, locale => {
 			const dropdownView = createDropdown( locale );
-			const colorTableView = addColorsToDropdown(
+			const colorTableView = addColorsToDropdown( {
 				dropdownView,
-				options.map( element => ( {
+				colors: options.map( element => ( {
 					label: element.label,
 					color: element.model,
 					options: {
 						hasBorder: element.hasBorder
 					}
-				} ) )
-			);
-			colorTableView.set( 'removeButtonTooltip', t( 'Remove color' ) );
+				} ) ),
+				colorColumns: this.colorColumns,
+				removeButtonTooltip: t( 'Remove color' )
+			} );
 
 			colorTableView.bind( 'selectedColor' ).to( command, 'value' );
 
@@ -111,14 +118,14 @@ export default class ColorUI extends Plugin {
 
 	/**
 	 * Returns options as defined in `config` but processed to account for
-	 * editor localization, i.e. to display {@link module:font/fontColor~FontColorOption}
-	 * or {@link module:font/fontBackgroundColor~FontBackgroundColorOption} in the correct language.
+	 * editor localization, i.e. to display {@link module:font/fontcolor~FontColorConfig}
+	 * or {@link module:font/fontbackgroundcolor~FontBackgroundColorConfig} in the correct language.
 	 *
 	 * Note: The reason behind this method is that there is no way to use {@link module:utils/locale~Locale#t}
 	 * when the user configuration is defined because the editor does not exist yet.
 	 *
 	 * @private
-	 * @returns {Array.<module:font/fontbackgroundcolor~FontBackgroundColorOption>}.
+	 * @returns {Array.<module:font/fontbackgroundcolor~FontBackgroundColorConfig>|Array.<module:font/fontcolor~FontColorConfig>}.
 	 */
 	_getLocalizedOptions() {
 		const editor = this.editor;

+ 36 - 2
packages/ckeditor5-font/src/utils.js

@@ -38,9 +38,23 @@ export function buildDefinition( modelAttributeKey, options ) {
 	return definition;
 }
 
+/**
+ * Name of font color plugin
+ */
 export const FONT_COLOR = 'fontColor';
+
+/**
+ * Name of font background color plugin.
+ */
 export const FONT_BACKGROUND_COLOR = 'fontBackgroundColor';
 
+/**
+ * Function for font color and font background color plugins
+ * which is responsible for upcasting data to model.
+ * styleAttr should eqaul to `'color'` or `'background-color'`.
+ *
+ * @param {String} styleAttr
+ */
 export function renderUpcastAttribute( styleAttr ) {
 	return viewElement => {
 		const fontColor = viewElement.getStyle( styleAttr );
@@ -48,6 +62,13 @@ export function renderUpcastAttribute( styleAttr ) {
 	};
 }
 
+/**
+ * Function for font color and font background color plugins
+ * which is responsible for downcasting color attribute to span element.
+ * styleAttr should eqaul to `'color'` or `'background-color'`.
+ *
+ * @param {String} styleAttr
+ */
 export function renderDowncastElement( styleAttr ) {
 	return ( modelAttributeValue, viewWriter ) => viewWriter.createAttributeElement( 'span', {
 		style: `${ styleAttr }:${ modelAttributeValue }`
@@ -58,6 +79,12 @@ function normalizeColorCode( value ) {
 	return value.replace( /\s/g, '' );
 }
 
+/**
+ * Creates model of color from configuration option. It keeps them coherent,
+ * regardles how user define them in config.
+ *
+ * @param {String|Object} colorRow
+ */
 export function normalizeOptions( colorRow ) {
 	return colorRow
 		.map( getColorsDefinition )
@@ -93,9 +120,16 @@ function getColorsDefinition( color ) {
 	}
 }
 
-export function addColorsToDropdown( dropdownView, colors ) {
+/**
+ * Helper which add {@link module:font/ui/colortableview~ColorTableView} to dropdown with proper initial values.
+ * @param {Object} config Configuration object
+ * @param {module:ui/dropdown/dropdownview~DropdownView} config.dropdownView Dropdown view to which
+ * will be added {@link module:font/ui/colortableview~ColorTableView}.
+ * @param {Array.<Object>}  Array with objects representing color to be drawn in color grid.
+ */
+export function addColorsToDropdown( { dropdownView, colors, colorColumns, removeButtonTooltip } ) {
 	const locale = dropdownView.locale;
-	const colorTableView = new ColorTableView( locale, { colors } );
+	const colorTableView = new ColorTableView( locale, { colors, colorColumns, removeButtonTooltip } );
 	dropdownView.colorTableView = colorTableView;
 	dropdownView.panelView.children.add( colorTableView );