Merge pull request #17 from GreenTeaCake/add-disabled-property

Add disabled property

src/components/switch/readme.md

@@ -4,14 +4,31 @@
 
 ## Overview
 
-Switch component documentation.
+A switch is an input widget that allows users to choose one of two values: on or off.
+Switches are similar to checkboxes and toggle buttons. But switches can only be used for binary
+input while checkboxes and toggle buttons allow implementations the option of supporting a third
+middle state. Checkboxes can be checked or not checked and can optionally also allow for a
+partially checked state. Toggle buttons can be pressed or not pressed and can optionally allow
+for a partially pressed state.
+
+Specifications:
+
+- [`switch` role](https://w3c.github.io/aria/#switch)
+- [Switch Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/)
+- [Switch Example: A switch based on a div element](https://www.w3.org/WAI/ARIA/apg/patterns/switch/examples/switch/)
+- [ARIA: switch role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role)
+
+`gtc-switch` custom element implements the switch specification behaviour. It is a stateless controlled component.
+Please use `checked` property to control the component's state and attach event listener for custom `gtcChange`
+event to be notified about the state changes.
 
 ## Properties
 
-| Property             | Attribute | Description                                                                                               | Type      | Default     |
-| -------------------- | --------- | --------------------------------------------------------------------------------------------------------- | --------- | ----------- |
-| `checked`            | `checked` | The reflective property that allows to control the state of the switch. If `true`, the switch is checked. | `boolean` | `false`     |
-| `label` _(required)_ | `label`   | Text value used for `aria-label` property.                                                                | `string`  | `undefined` |
+| Property             | Attribute  | Description                                                                                               | Type      | Default     |
+| -------------------- | ---------- | --------------------------------------------------------------------------------------------------------- | --------- | ----------- |
+| `checked`            | `checked`  | The reflective property that allows to control the state of the switch. If `true`, the switch is checked. | `boolean` | `false`     |
+| `disabled`           | `disabled` | If `true`, the switch is disabled.                                                                        | `boolean` | `false`     |
+| `label` _(required)_ | `label`    | Text value used for `aria-label` property. The minimal length is 1.                                       | `string`  | `undefined` |
 
 ## Events
 

src/components/switch/switch.scss

@@ -2,7 +2,15 @@ $switch-width: 40px;
 $switch-height: 20px;
 
 $marker-size: 16px;
-$marker-color: #ffffff;
+
+$background-color-default: #c7c7c7;
+$background-color-checked: #398368;
+$background-color-disabled: #e3e3e3;
+
+$marker-color-default: #ffffff;
+$marker-color-disabled: #c7c7c7;
+
+$highlight-color-default: #112c9f;
 
 $spacing: calc(($switch-height - $marker-size) / 2);
 
@@ -15,28 +23,47 @@ $spacing: calc(($switch-height - $marker-size) / 2);
     width: $switch-width;
     height: $switch-height;
     border-radius: calc($switch-height / 2);
-    background-color: #c9c7c7;
+    background-color: $background-color-default;
     position: relative;
     cursor: pointer;
 
+    &:hover {
+      outline: 2px solid $highlight-color-default;
+      outline-offset: 2px;
+    }
+
     .gtc-switch-marker {
       display: inline-block;
       width: $marker-size;
       height: $marker-size;
       border-radius: calc($marker-size / 2);
-      background-color: $marker-color;
+      background-color: $marker-color-default;
 
       position: absolute;
       top: $spacing;
       left: $spacing;
     }
 
     &__checked {
-      background-color: #398368;
+      background-color: $background-color-checked;
 
       .gtc-switch-marker {
         left: calc($switch-width - $marker-size - $spacing);
       }
     }
+
+    &__disabled {
+      pointer-events: none;
+      cursor: not-allowed;
+      background-color: $background-color-disabled;
+
+      &:hover {
+        outline: none;
+      }
+
+      .gtc-switch-marker {
+        background-color: $marker-color-disabled;
+      }
+    }
   }
 }

src/components/switch/switch.stories.ts

@@ -8,8 +8,14 @@ const meta: Meta = {
   component: 'gtc-switch',
   tags: ['autodocs'],
   render: (args) => {
-    const { checked, label } = args;
-    return `<gtc-switch checked="${checked}" label="${label}" />`;
+    const { label, checked, disabled } = args;
+    return `
+      <gtc-switch
+        label="${label}"
+        checked="${checked}"
+        disabled="${disabled}"
+      />
+    `;
   },
   argTypes: DOCS.argTypes,
   parameters: {
@@ -26,7 +32,8 @@ export default meta;
 export const Primary: StoryObj = {
   name: 'Usage Example',
   args: {
-    checked: false,
     label: 'Switch',
+    checked: false,
+    disabled: false,
   },
 };

src/components/switch/switch.tsx

@@ -1,18 +1,38 @@
-import { Component, Event, type EventEmitter, Host, Prop, h } from '@stencil/core';
+import { Component, Event, type EventEmitter, Host, Prop, h, Watch } from '@stencil/core';
+
+const MIN_LABEL_LENGTH = 1;
 
 /**
- * Switch component documentation.
+ * A switch is an input widget that allows users to choose one of two values: on or off.
+ * Switches are similar to checkboxes and toggle buttons. But switches can only be used for binary
+ * input while checkboxes and toggle buttons allow implementations the option of supporting a third
+ * middle state. Checkboxes can be checked or not checked and can optionally also allow for a
+ * partially checked state. Toggle buttons can be pressed or not pressed and can optionally allow
+ * for a partially pressed state.
+ *
+ * Specifications:
+ * - [`switch` role](https://w3c.github.io/aria/#switch)
+ * - [Switch Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/)
+ * - [Switch Example: A switch based on a div element](https://www.w3.org/WAI/ARIA/apg/patterns/switch/examples/switch/)
+ * - [ARIA: switch role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role)
  *
- * @link https://www.w3.org/WAI/ARIA/apg/patterns/switch/
- * @link https://www.w3.org/WAI/ARIA/apg/patterns/switch/examples/switch/
- * @link https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role
+ * `gtc-switch` custom element implements the switch specification behaviour. It is a stateless controlled component.
+ * Please use `checked` property to control the component's state and attach event listener for custom `gtcChange`
+ * event to be notified about the state changes.
  */
 @Component({
   tag: 'gtc-switch',
   shadow: true,
   styleUrl: 'switch.scss',
 })
 export class Switch {
+  /**
+   * Text value used for `aria-label` property.
+   *
+   * The minimal length is 1.
+   */
+  @Prop({ reflect: true }) public label!: string;
+
   /**
    * The reflective property that allows to control the state of the switch.
    *
@@ -21,24 +41,28 @@ export class Switch {
   @Prop({ reflect: true }) public checked = false;
 
   /**
-   * Text value used for `aria-label` property.
+   * If `true`, the switch is disabled.
    */
-  @Prop() public label!: string;
+  @Prop({ reflect: true }) public disabled = false;
 
   /**
    * Is called when the value has changed.
    */
+  // event name is prefixed not to be confused/conflict with the native one
   @Event() private gtcChange: EventEmitter<boolean>;
 
   render() {
     return (
       <Host>
         <div
           aria-checked={this.checked ? 'true' : 'false'}
+          aria-disabled={this.disabled ? 'true' : 'false'}
           aria-label={this.label}
           class={{
+            // order matters
             'gtc-switch': true,
             'gtc-switch__checked': this.checked,
+            'gtc-switch__disabled': this.disabled,
           }}
           onClick={this.onClick}
           onKeyDown={this.onKeyDown}
@@ -51,9 +75,21 @@ export class Switch {
     );
   }
 
+  @Watch('label')
+  protected validateLabel(newLabelValue: string) {
+    if (typeof newLabelValue !== 'string' || newLabelValue === '') {
+      throw new Error('Switch has no label.');
+    }
+    if (newLabelValue.length < MIN_LABEL_LENGTH) {
+      throw new Error('Switch label is too short.');
+    }
+  }
+
   private toggleChecked(event: KeyboardEvent | MouseEvent) {
     event.preventDefault();
-    this.gtcChange.emit(!this.checked);
+    if (!this.disabled) {
+      this.gtcChange.emit(!this.checked);
+    }
   }
 
   private onClick = (event: MouseEvent) => {

src/components/switch/test/switch.e2e.ts

@@ -46,4 +46,66 @@ describe('gtc-switch', () => {
       expect(element.getAttribute('aria-checked')).toEqual(`false`);
     });
   });
+
+  describe('emits event and triggers callback if clicked', () => {
+    it('when checked', async () => {
+      const page = await newE2EPage();
+
+      await page.setContent('<gtc-switch checked="true"></gtc-switch>');
+
+      const gtcChange = await page.spyOnEvent('gtcChange');
+
+      const element = await page.find('gtc-switch >>> div.gtc-switch');
+      await element.click();
+      await page.waitForChanges();
+
+      expect(gtcChange).toHaveReceivedEventTimes(1);
+      expect(gtcChange).toHaveReceivedEventDetail(false);
+    });
+
+    it('when unchecked', async () => {
+      const page = await newE2EPage();
+
+      await page.setContent('<gtc-switch checked="false"></gtc-switch>');
+
+      const gtcChange = await page.spyOnEvent('gtcChange');
+
+      const element = await page.find('gtc-switch >>> div.gtc-switch');
+      await element.click();
+      await page.waitForChanges();
+
+      expect(gtcChange).toHaveReceivedEventTimes(1);
+      expect(gtcChange).toHaveReceivedEventDetail(true);
+    });
+  });
+
+  describe('emits no event if disabled', () => {
+    it('when checked', async () => {
+      const page = await newE2EPage();
+
+      await page.setContent('<gtc-switch checked="true" disabled="true"></gtc-switch>');
+
+      const gtcChange = await page.spyOnEvent('gtcChange');
+
+      const element = await page.find('gtc-switch >>> div.gtc-switch');
+      await element.click();
+      await page.waitForChanges();
+
+      expect(gtcChange).toHaveReceivedEventTimes(0);
+    });
+
+    it('when unchecked', async () => {
+      const page = await newE2EPage();
+
+      await page.setContent('<gtc-switch checked="false" disabled="true"></gtc-switch>');
+
+      const gtcChange = await page.spyOnEvent('gtcChange');
+
+      const element = await page.find('gtc-switch >>> div.gtc-switch');
+      await element.click();
+      await page.waitForChanges();
+
+      expect(gtcChange).toHaveReceivedEventTimes(0);
+    });
+  });
 });