Преглед на файлове

Docs: LabeledView docs.

Aleksander Nowodzinski преди 5 години
родител
ревизия
4b5a31549c
променени са 1 файла, в които са добавени 47 реда и са изтрити 13 реда
  1. 47 13
      packages/ckeditor5-ui/src/labeledview/labeledview.js

+ 47 - 13
packages/ckeditor5-ui/src/labeledview/labeledview.js

@@ -13,16 +13,53 @@ import LabelView from '../label/labelview';
 import '../../theme/components/labeledview/labeledview.css';
 
 /**
- * The labeled view class.
+ * The labeled view class. It can be used to enhance any view with the following features:
+ *
+ * * a label,
+ * * (optional) an error message,
+ * * (optional) an info (status) text,
+ *
+ * all bound logically by proper DOM attributes for UX and accessibility.  It also provides an interface
+ * (e.g. observable properties) that allows controlling those additional features.
+ *
+ * The constructor of this class requires a callback that returns a view to be labeled. The callback
+ * is called with unique ids that allow binding of DOM properties:
+ *
+ *		const labeledInputView = new LabeledView( locale, ( 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 );
+ *
+ *			return inputView;
+ *		} );
+ *
+ *		labeledInputView.label = 'User name';
+ *		labeledInputView.infoText = 'Full name like for instance, John Doe.';
+ *		labeledInputView.render();
+ *
+ *		document.body.append( labeledInputView.element );
+ *
+ * See {@link module:ui/labeledview/creators} to learn more about labeled input helpers.
  *
  * @extends module:ui/view~View
  */
 export default class LabeledView extends View {
 	/**
-	 * Creates an instance of the labeled view class.
+	 * Creates an instance of the labeled view class using a provided creator function
+	 * that provides the view to be labeled.
 	 *
 	 * @param {module:utils/locale~Locale} locale The locale instance.
-	 * @param {Function} viewCreator TODO
+	 * @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:
+	 *
+	 * * 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
 	 */
 	constructor( locale, viewCreator ) {
 		super( locale );
@@ -55,30 +92,26 @@ export default class LabeledView extends View {
 
 		/**
 		 * The validation error text. When set, it will be displayed
-		 * next to the {@link #field} as a typical validation error message.
+		 * next to the {@link #view} as a typical validation error message.
 		 * Set it to `null` to hide the message.
 		 *
 		 * **Note:** Setting this property to anything but `null` will automatically
 		 * make the `hasError` of the {@link #view} `true`.
 		 *
-		 * **Note:** Typing in the {@link #field} which fires the
-		 * {@link module:ui/inputtext/inputtextview~InputTextView#event:input `input` event}
-		 * resets this property back to `null`, indicating that the input field can be re–validated.
-		 *
 		 * @observable
 		 * @member {String|null} #errorText
 		 */
 		this.set( 'errorText', null );
 
 		/**
-		 * The additional information text displayed next to the {@link #field} which can
-		 * be used to inform the user about the purpose of the input, provide help or hints.
+		 * The additional information text displayed next to the {@link #view} which can
+		 * be used to inform the user about its purpose, provide help or hints.
 		 *
 		 * Set it to `null` to hide the message.
 		 *
 		 * **Note:** This text will be displayed in the same place as {@link #errorText} but the
 		 * latter always takes precedence: if the {@link #errorText} is set, it replaces
-		 * {@link #errorText} for as long as the value of the input is invalid.
+		 * {@link #infoText}.
 		 *
 		 * @observable
 		 * @member {String|null} #infoText
@@ -167,7 +200,8 @@ export default class LabeledView extends View {
 	 * next to the {@link #view}. See {@link #_statusText}.
 	 *
 	 * @private
-	 * @param {String} statusUid Unique id of the status, shared with the input's `aria-describedby` attribute.
+	 * @param {String} statusUid Unique id of the status, shared with the {@link #view view's}
+	 * `aria-describedby` attribute.
 	 * @returns {module:ui/view~View}
 	 */
 	_createStatusView( statusUid ) {
@@ -197,7 +231,7 @@ export default class LabeledView extends View {
 	}
 
 	/**
-	 * Focuses the input.
+	 * Focuses the {@link #view}.
 	 */
 	focus() {
 		this.view.focus();