Allow KTextbox label to be passed via slot

Fixes #1166

Author: MisRob

docs/pages/ktextbox.vue

@@ -19,6 +19,7 @@
       <DocsSubNav
         :items="[
           { text: 'Input with label', href: '#with-label' },
+          { text: 'Visually hidden label', href: '#visually-hidden-label' },
           { text: 'Valid and invalid input', href: '#validation' },
           { text: 'Character limit', href: '#charlimit' },
           { text: 'Disabled input', href: '#disabled' },
@@ -37,15 +38,32 @@
         <DocsAnchorTarget anchor="#with-label" />
       </h3>
       <p>
-        This text box includes a visible label, providing clear guidance and context to the user
-        about the expected input.
+        The label can be provided via the <code>label</code> prop or the <code>label</code> slot. A
+        visible label is preferred.
       </p>
       <DocsExample
         loadExample="KTextbox/WithLabel.vue"
         exampleId="ktextbox-label"
         block
       />
 
+      <h3>
+        Visually hidden label
+        <DocsAnchorTarget anchor="#visually-hidden-label" />
+      </h3>
+
+      <p>
+        Although a visible label is preferred, occasionaly it may need to be hidden. Use the
+        <code>label</code> slot together with the <code>visuallyhidden</code> class to ensure the
+        label remains accessible to assistive technologies.
+      </p>
+
+      <DocsExample
+        loadExample="KTextbox/VisuallyHiddenLabel.vue"
+        exampleId="ktextbox-visually-hidden-label"
+        block
+      />
+
       <h3>
         Valid and invalid input
         <DocsAnchorTarget anchor="#validation" />

examples/KTextbox/VisuallyHiddenLabel.vue

@@ -0,0 +1,9 @@
+<template>
+
+  <KTextbox>
+    <template #label>
+      <span class="visuallyhidden">Label text</span>
+    </template>
+  </KTextbox>
+
+</template>

examples/KTextbox/WithLabel.vue

@@ -1,5 +1,11 @@
 <template>
 
-  <KTextbox label="Input with label" />
+  <div>
+    <KTextbox label="Label via prop" />
+
+    <KTextbox>
+      <template #label>Label via slot</template>
+    </KTextbox>
+  </div>
 
 </template>

lib/KTextbox/__tests__/KTextbox.spec.js

@@ -8,14 +8,33 @@ describe('KTextbox component', () => {
   });
 
   describe('props', () => {
-    it(`a label should appear`, () => {
+    it(`a label should appear when passed via prop`, () => {
       const wrapper = mount(KTextbox, {
         propsData: {
-          label: 'test',
+          label: 'test label',
         },
       });
-      expect(wrapper.find('label').text()).toEqual('test');
+      expect(wrapper.find('label').text()).toEqual('test label');
     });
+
+    it(`a label should appear when passed via slot`, () => {
+      const wrapper = mount(KTextbox, {
+        slots: {
+          label: 'test label',
+        },
+      });
+      expect(wrapper.find('label').text()).toEqual('test label');
+    });
+
+    it(`should show error when neither label prop nor slot is provided`, () => {
+      const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+      mount(KTextbox);
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        '[KTextbox] A label must be provided via prop or slot',
+      );
+      consoleErrorSpy.mockRestore();
+    });
+
     it(`value of the text field should appear when passed in`, () => {
       const initialValue = '1234paowiejfapwoeifjapwoeijf';
       const wrapper = mount(KTextbox, {
@@ -27,6 +46,7 @@ describe('KTextbox component', () => {
       const value = wrapper.find('input').element.value;
       expect(value).toBe(initialValue);
     });
+
     it(`invalidText is not displayed if showInvalidText is false`, () => {
       const wrapper = mount(KTextbox, {
         propsData: {
@@ -38,6 +58,7 @@ describe('KTextbox component', () => {
       const errorTextField = wrapper.find('.ui-textbox-feedback-text');
       expect(errorTextField.text()).not.toBe('error!');
     });
+
     it(`invalidText is displayed through error prop if invalid and showInvalidText are both true`, () => {
       const wrapper = mount(KTextbox, {
         propsData: {
@@ -49,6 +70,7 @@ describe('KTextbox component', () => {
       const errorTextField = wrapper.find('.ui-textbox-feedback-text');
       expect(errorTextField.text()).toBe('error!');
     });
+
     it(`text field is disabled when 'disabled' is true`, () => {
       const wrapper = mount(KTextbox, {
         propsData: {
@@ -57,6 +79,7 @@ describe('KTextbox component', () => {
       });
       expect(wrapper.find('input').attributes('disabled')).toBe('disabled');
     });
+
     it(`text field is readonly when 'readonly' is true`, () => {
       const wrapper = mount(KTextbox, {
         propsData: {
@@ -65,6 +88,7 @@ describe('KTextbox component', () => {
       });
       expect(wrapper.find('input').attributes('readonly')).toBe('readonly');
     });
+
     it(`text field is autofocused when 'autofocus' is true`, () => {
       const wrapper = shallowMount(KTextbox, {
         propsData: {
@@ -74,6 +98,7 @@ describe('KTextbox component', () => {
       const textField = wrapper.findComponent({ name: 'UiTextbox' });
       expect(textField.attributes('autofocus')).toBe('true');
     });
+
     it(`length of characters for value matches maxlength prop`, () => {
       const wrapper = shallowMount(KTextbox, {
         propsData: {
@@ -83,6 +108,7 @@ describe('KTextbox component', () => {
       const textField = wrapper.findComponent({ name: 'UiTextbox' });
       expect(textField.attributes('maxlength')).toBe('13');
     });
+
     it(`HTML autocomplete attribute is passed with autocomplete prop`, () => {
       const wrapper = shallowMount(KTextbox, {
         propsData: {
@@ -92,6 +118,7 @@ describe('KTextbox component', () => {
       const textField = wrapper.findComponent({ name: 'UiTextbox' });
       expect(textField.attributes('autocomplete')).toBe('current-password');
     });
+
     it(`HTML autocapitalize attribute is passed with autocapitalize prop`, () => {
       const wrapper = shallowMount(KTextbox, {
         propsData: {
@@ -101,6 +128,7 @@ describe('KTextbox component', () => {
       const textField = wrapper.findComponent({ name: 'UiTextbox' });
       expect(textField.attributes('autocapitalize')).toBe('sentences');
     });
+
     it(`input type is 'number' when type is set to 'number'`, () => {
       const wrapper = mount(KTextbox, {
         propsData: {
@@ -110,6 +138,7 @@ describe('KTextbox component', () => {
       expect(wrapper.find('input').attributes('number')).toBe('true');
       expect(wrapper.find('input').attributes('type')).toBe('number');
     });
+
     it(`input type is 'text' when type is set to 'text'`, () => {
       const wrapper = mount(KTextbox, {
         propsData: {
@@ -118,6 +147,7 @@ describe('KTextbox component', () => {
       });
       expect(wrapper.find('input').attributes('type')).toBe('text');
     });
+
     it(`min length of value is passed as an attribute by the 'min' prop`, () => {
       const wrapper = mount(KTextbox, {
         propsData: {
@@ -129,6 +159,7 @@ describe('KTextbox component', () => {
       expect(wrapper.find('input').attributes('number')).toBe('true');
       expect(wrapper.find('input').attributes('min')).toBe('50');
     });
+
     it(`max length of value is passed as an attribute by the 'max' prop`, () => {
       const wrapper = mount(KTextbox, {
         propsData: {
@@ -140,6 +171,7 @@ describe('KTextbox component', () => {
       expect(wrapper.find('input').attributes('number')).toBe('true');
       expect(wrapper.find('input').attributes('max')).toBe('50');
     });
+
     it(`when 'true', textarea element is rendered`, () => {
       const wrapper = mount(KTextbox, {
         propsData: {
@@ -149,6 +181,7 @@ describe('KTextbox component', () => {
       expect(wrapper.find('textarea').exists()).toBeTruthy();
     });
   });
+
   describe('event handling', () => {
     it('should emit a input when value is updated', () => {
       const wrapper = mount(KTextbox, {
@@ -163,6 +196,7 @@ describe('KTextbox component', () => {
       expect(wrapper.emitted().input).toBeTruthy();
     });
   });
+
   describe('KTextbox with clearable', () => {
     it('should have the clear button when clearable is true and there is text in the input', async () => {
       const wrapper = mount(KTextbox, {
@@ -177,6 +211,7 @@ describe('KTextbox component', () => {
       const clearButton = wrapper.find('[data-test="clearIcon"]');
       expect(clearButton.exists()).toBeTruthy();
     });
+
     it('should not show the clear button when clearable is true and there is no text in the input', async () => {
       const wrapper = mount(KTextbox, {
         propsData: {
@@ -203,6 +238,7 @@ describe('KTextbox component', () => {
       await wrapper.vm.$nextTick();
       expect(wrapper.find('[data-test="clearIcon"]').exists()).toBeFalsy();
     });
+
     it('should clear the input when clear button is clicked', async () => {
       const wrapper = mount(KTextbox, {
         propsData: {

lib/KTextbox/__tests__/components/KTextboxVisualTest.vue

@@ -85,6 +85,12 @@
       width="400px"
       loadExample="KTextbox/Combined.vue"
     />
+
+    <VisualTestExample
+      title="Label via slot"
+      width="400px"
+      loadExample="KTextbox/LabelSlot.vue"
+    />
   </VisualTestLayout>
 
 </template>

lib/KTextbox/index.vue

@@ -29,6 +29,13 @@
       @focus="emitFocus"
       @blur="emitBlur"
     >
+      <!--@slot Label. Alternative to the label prop. -->
+      <template
+        v-if="$slots.label"
+        #default
+      >
+        <slot name="label"></slot>
+      </template>
       <template #outerBefore>
         <!--@slot Places content before the input area-->
         <slot name="outerBefore"></slot>
@@ -68,7 +75,7 @@
        */
       label: {
         type: String,
-        required: true,
+        default: null,
       },
       /**
        * Value of the aria-label for clear button
@@ -215,6 +222,12 @@
         this.currentText = val;
       },
     },
+    created() {
+      if (!this.label && !this.$slots.label) {
+        // eslint-disable-next-line no-console
+        console.error('[KTextbox] A label must be provided via prop or slot');
+      }
+    },
     methods: {
       updateText() {
         /**