Browse Source

Tests: Added tests for LabeledView utils. Added some docs.

Aleksander Nowodzinski 5 years ago
parent
commit
72812b7c1d

+ 0 - 45
packages/ckeditor5-ui/src/labeledview/creators.js

@@ -1,45 +0,0 @@
-/**
- * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-
-/**
- * @module ui/labeledview/creators
- */
-
-import InputTextView from '@ckeditor/ckeditor5-ui/src/inputtext/inputtextview';
-import { createDropdown } from '@ckeditor/ckeditor5-ui/src/dropdown/utils';
-
-export function labeledInputCreator( labeledView, viewUid, statusUid ) {
-	const inputView = new InputTextView( labeledView.locale );
-
-	inputView.set( {
-		id: viewUid,
-		ariaDescribedById: statusUid
-	} );
-
-	inputView.bind( 'isReadOnly' ).to( labeledView, 'isEnabled', value => !value );
-	inputView.bind( 'hasError' ).to( labeledView, 'errorText', value => !!value );
-
-	inputView.on( 'input', () => {
-		// UX: Make the error text disappear and disable the error indicator as the user
-		// starts fixing the errors.
-		labeledView.errorText = null;
-	} );
-
-	return inputView;
-}
-
-export function labeledDropdownCreator( labeledView, viewUid, statusUid ) {
-	const dropdownView = createDropdown( labeledView.locale );
-
-	dropdownView.set( {
-		id: viewUid,
-		ariaDescribedById: statusUid
-	} );
-
-	dropdownView.bind( 'isEnabled' ).to( labeledView );
-	dropdownView.bind( 'hasError' ).to( labeledView, 'errorText', value => !!value );
-
-	return dropdownView;
-}

+ 7 - 5
packages/ckeditor5-ui/src/labeledview/labeledview.js

@@ -45,7 +45,8 @@ import '../../theme/components/labeledview/labeledview.css';
  *
  *		document.body.append( labeledInputView.element );
  *
- * See {@link module:ui/labeledview/creators} to learn more about labeled input helpers.
+ * See {@link module:ui/labeledview/utils} to discover ready–to–use labeled input helpers for common
+ * UI components.
  *
  * @extends module:ui/view~View
  */
@@ -56,10 +57,11 @@ export default class LabeledView extends View {
 	 *
 	 * @param {module:utils/locale~Locale} locale The locale instance.
 	 * @param {Function} viewCreator A function that returns a {@link module:ui/view~View}
-	 * that will be labeled. Two strings are passed to the creator function:
+	 * that will be labeled. The following arguments are passed to the creator function:
 	 *
-	 * * an UID string that allows DOM binding of the {@link #labelView label} and the labeled view,
-	 * * an UID string that allows DOM binding of the {@link #statusView status} and the labeled view
+	 * * an instance of the `LabeledView` to allow binding observable properties,
+	 * * an UID string that connects the {@link #labelView label} and the labeled view in DOM,
+	 * * an UID string that connects the {@link #statusView status} and the labeled view in DOM.
 	 */
 	constructor( locale, viewCreator ) {
 		super( locale );
@@ -127,7 +129,7 @@ export default class LabeledView extends View {
 		this.set( 'class' );
 
 		/**
-		 * The label view.
+		 * The label view instance that describes the entire view.
 		 *
 		 * @member {module:ui/label/labelview~LabelView} #labelView
 		 */

+ 92 - 0
packages/ckeditor5-ui/src/labeledview/utils.js

@@ -0,0 +1,92 @@
+/**
+ * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module ui/labeledview/utils
+ */
+
+import InputTextView from '@ckeditor/ckeditor5-ui/src/inputtext/inputtextview';
+import { createDropdown } from '@ckeditor/ckeditor5-ui/src/dropdown/utils';
+
+/**
+ * A helper for creating labeled dropdowns.
+ *
+ * It creates an instance of a {@link module:ui/inputtext/inputtextview~InputTextView input text} that is
+ * logically related to a {@link module:ui/labeledview/labeledview~LabeledView labeled view} in DOM.
+ *
+ * The helper does the following:
+ *
+ * * It sets input's `id` and `ariaDescribedById` attributes.
+ * * It binds input's `isReadOnly` to the labeled view.
+ * * It binds input's `hasError` to the labeled view.
+ * * It enables a logic that cleans up the error when user starts typing in the input..
+ *
+ * Usage:
+ *
+ *		const labeledInputView = new LabeledView( locale, createLabeledDropdown );
+ *		console.log( labeledInputView.view ); // An input instance.
+ *
+ * @param {module:ui/input/labeledview~LabeledView} labeledView The instance of the labeled view.
+ * @param {String} viewUid An UID string that allows DOM logical connection between the
+ * {@link module:ui/labeledview/labeledview~LabeledView#labelView labeled view's label} and the input.
+ * @param {String} statusUid An UID string that allows DOM logical connection between the
+ * {@link module:ui/labeledview/labeledview~LabeledView#statusView labeled view's status} and the input.
+ * @returns {module:ui/inputtext/inputtextview~InputTextView} The input text view instance.
+ */
+export function createLabeledInputText( labeledView, viewUid, statusUid ) {
+	const inputView = new InputTextView( labeledView.locale );
+
+	inputView.set( {
+		id: viewUid,
+		ariaDescribedById: statusUid
+	} );
+
+	inputView.bind( 'isReadOnly' ).to( labeledView, 'isEnabled', value => !value );
+	inputView.bind( 'hasError' ).to( labeledView, 'errorText', value => !!value );
+
+	inputView.on( 'input', () => {
+		// UX: Make the error text disappear and disable the error indicator as the user
+		// starts fixing the errors.
+		labeledView.errorText = null;
+	} );
+
+	return inputView;
+}
+
+/**
+ * A helper for creating labeled dropdowns.
+ *
+ * It creates an instance of a {@link module:ui/dropdown/dropdownview~DropdownView dropdown} that is
+ * logically related to a {@link module:ui/labeledview/labeledview~LabeledView labeled view}.
+ *
+ * The helper does the following:
+ *
+ * * It sets dropdown's `id` and `ariaDescribedById` attributes.
+ * * It binds input's `isEnabled` to the labeled view.
+ *
+ * Usage:
+ *
+ *		const labeledInputView = new LabeledView( locale, createLabeledDropdown );
+ *		console.log( labeledInputView.view ); // A dropdown instance.
+ *
+ * @param {module:ui/labeledview/labeledview~LabeledView} labeledView The instance of the labeled view.
+ * @param {String} viewUid An UID string that allows DOM logical connection between the
+ * {@link module:ui/labeledview/labeledview~LabeledView#labelView labeled view label} and the dropdown.
+ * @param {String} statusUid An UID string that allows DOM logical connection between the
+ * {@link module:ui/labeledview/labeledview~LabeledView#statusView labeled view status} and the dropdown.
+ * @returns {module:ui/dropdown/dropdownview~DropdownView} The dropdown view instance.
+ */
+export function createLabeledDropdown( labeledView, viewUid, statusUid ) {
+	const dropdownView = createDropdown( labeledView.locale );
+
+	dropdownView.set( {
+		id: viewUid,
+		ariaDescribedById: statusUid
+	} );
+
+	dropdownView.bind( 'isEnabled' ).to( labeledView );
+
+	return dropdownView;
+}

+ 5 - 1
packages/ckeditor5-ui/tests/labeledview/labeledview.js

@@ -26,6 +26,10 @@ describe( 'LabeledView', () => {
 		labeledView.render();
 	} );
 
+	afterEach( () => {
+		labeledView.destroy();
+	} );
+
 	describe( 'constructor()', () => {
 		it( 'should set labeledView#locale', () => {
 			expect( labeledView.locale ).to.deep.equal( locale );
@@ -151,7 +155,7 @@ describe( 'LabeledView', () => {
 	} );
 
 	describe( 'focus()', () => {
-		it( 'focuses the #view in DOM', () => {
+		it( 'should focus the #view in DOM', () => {
 			const spy = sinon.spy( view, 'focus' );
 
 			labeledView.focus();

+ 111 - 0
packages/ckeditor5-ui/tests/labeledview/utils.js

@@ -0,0 +1,111 @@
+/**
+ * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+import {
+	createLabeledInputText,
+	createLabeledDropdown
+} from '../../src/labeledview/utils';
+
+import LabeledView from '../../src/labeledview/labeledview';
+import testUtils from '@ckeditor/ckeditor5-core/tests/_utils/utils';
+import InputTextView from '../../src/inputtext/inputtextview';
+import DropdownView from '../../src/dropdown/dropdownview';
+
+describe( 'LabeledView utils', () => {
+	let locale;
+
+	testUtils.createSinonSandbox();
+
+	beforeEach( () => {
+		locale = { t: val => val };
+	} );
+
+	afterEach( () => {
+	} );
+
+	describe( 'createLabeledInputText()', () => {
+		let labeledView;
+
+		beforeEach( () => {
+			labeledView = new LabeledView( locale, createLabeledInputText );
+		} );
+
+		afterEach( () => {
+			labeledView.destroy();
+		} );
+
+		it( 'should create an InputTextView instance', () => {
+			expect( labeledView.view ).to.be.instanceOf( InputTextView );
+		} );
+
+		it( 'should pass the Locale to the input', () => {
+			expect( labeledView.view.locale ).to.equal( locale );
+		} );
+
+		it( 'should set input #id and #ariaDescribedById', () => {
+			labeledView.render();
+
+			expect( labeledView.view.id ).to.equal( labeledView.labelView.for );
+			expect( labeledView.view.ariaDescribedById ).to.equal( labeledView.statusView.element.id );
+		} );
+
+		it( 'should bind input\'s #isReadOnly to LabeledView#isEnabled', () => {
+			labeledView.isEnabled = true;
+			expect( labeledView.view.isReadOnly ).to.be.false;
+
+			labeledView.isEnabled = false;
+			expect( labeledView.view.isReadOnly ).to.be.true;
+		} );
+
+		it( 'should bind input\'s #hasError to LabeledView#errorText', () => {
+			labeledView.errorText = 'some error';
+			expect( labeledView.view.hasError ).to.be.true;
+
+			labeledView.errorText = null;
+			expect( labeledView.view.hasError ).to.be.false;
+		} );
+
+		it( 'should clean LabeledView#errorText upon input\'s DOM "update" event', () => {
+			labeledView.errorText = 'some error';
+			labeledView.view.fire( 'input' );
+			expect( labeledView.errorText ).to.be.null;
+		} );
+	} );
+
+	describe( 'createLabeledDropdown', () => {
+		let labeledView;
+
+		beforeEach( () => {
+			labeledView = new LabeledView( locale, createLabeledDropdown );
+		} );
+
+		afterEach( () => {
+			labeledView.destroy();
+		} );
+
+		it( 'should create a DropdownView', () => {
+			expect( labeledView.view ).to.be.instanceOf( DropdownView );
+		} );
+
+		it( 'should pass the Locale to the dropdown', () => {
+			expect( labeledView.view.locale ).to.equal( locale );
+		} );
+
+		it( 'should set dropdown\'s #id and #ariaDescribedById', () => {
+			labeledView.render();
+
+			expect( labeledView.view.id ).to.equal( labeledView.labelView.for );
+			expect( labeledView.view.ariaDescribedById ).to.equal( labeledView.statusView.element.id );
+		} );
+
+		it( 'should bind dropdown\'s #isEnabled to the labeled view', () => {
+			labeledView.isEnabled = true;
+			expect( labeledView.view.isEnabled ).to.be.true;
+
+			labeledView.isEnabled = false;
+			expect( labeledView.view.isEnabled ).to.be.false;
+		} );
+	} );
+} );