Merge pull request #234 from US-CBP/Toggle

Requirements PR

packages/web-components/src/components/cbp-toggle/cbp-toggle.scss

@@ -0,0 +1,17 @@
+/**
+ * @Prop   --cbp-toggle-XXX
+ */
+
+// :root{ 
+//   --cbp-toggle-XXX: red;
+// }
+
+// [data-cbp-theme=light] cbp-toggle[context*=dark]:not([context=light-always]),
+// [data-cbp-theme=dark] cbp-toggle:not([context=dark-inverts]):not([context=light-always]) {
+
+//   // --cbp-tooltip-color-bg: var(--cbp-tooltip-color-bg-dark);
+// }
+
+cbp-toggle {
+  border: 1px solid red; //TODO: local testing, remove before push
+}

packages/web-components/src/components/cbp-toggle/cbp-toggle.specs.mdx

@@ -0,0 +1,50 @@
+import { Meta } from '@storybook/addon-docs';
+
+<Meta title="Components/Toggle/Specifications" />
+
+# cbp-toggle
+
+## Purpose
+
+* The toggle is a visual variant of a Boolean selection form control, representing an on/off toggle switch.
+
+## Functional Requirements
+
+* The Toggle component provides visual styling for a checkbox form control to appear as a toggle switch, including its various states, including hover, focus, disabled, and checked states.
+* The Toggle component is a native HTML `input type="checkbox"` under the hood, which is slotted.
+* The Toggle component places the label to the left of the control, unlike the Checkbox component.
+* The Toggle component requires a label for an accessible name for form control.
+* A Toggle may be used individually as a standalone toggle or within a list (in a `cbp-form-field` group).
+* An optional text display of the toggle status may be shown next to the control to reduce ambiguity.
+
+## Technical Specifications
+
+* disabled property is used to functionally & visual disable the control.
+* hideStatus boolean property is used to specify the display of the toggle status text
+  * interacts with the statusTextOn & statusTextOff label display
+* statusTextOn is used to determine the text value of the helper text of a toggle. default value is 'on'
+* statusTextOff is used to determine the text value of the helper text of a toggle. default value is 'off'
+* Width css property is used to specify the width of the control for 'stacked' vertical display
+  *TODO: might be managable via sx prop. possible this may not be needed, need to build it first to tell
+* Gap css property is used to specify the gap property of the control
+
+### User Interactions
+
+* The user interactions are that of a native checkbox (`input type="checkbox"`) element:
+  * Clicking anywhere on the form control or label text will place focus on the control and toggle its state.
+  * Toggle are keyboard accessible by tabbing onto them in either direction, placing focus onto the native form control (*not really native form control).
+  * Pressing the Spacebar will toggle the focused checkbox state, also emitting a custom event.
+
+### Responsiveness
+
+* The Toggle label will wrap as needed.
+* The Toggle control is sized in relative units and will respond to changes in the user's default text size.
+
+### Accessibility
+
+* The native checkbox (`input type="checkbox"`) element and label text are wrapped within a `label` tag, forming an implicit label association (no `id` needed).
+* Full keyboard navigation is supported, as detailed under "User Interactions" above.
+
+### Additional Notes and Considerations
+
+* TODO: 'Special toggles' not currently included, seems to need support for custom sliders/icons

packages/web-components/src/components/cbp-toggle/cbp-toggle.tsx

@@ -0,0 +1,56 @@
+import { Component, Element, Prop, Host, h } from '@stencil/core';
+import { setCSSProps } from '../../utils/utils';
+
+@Component({
+  tag: 'cbp-toggle',
+  styleUrl: 'cbp-toggle.scss',
+})
+export class CbpToggle {
+
+  @Element() host: HTMLElement;
+
+  /** Marks the toggle as checked by default when specified. */
+  @Prop() checked: boolean;
+
+  /** Marks the toggle in a disabled state when specified. */
+  @Prop() disabled: boolean;
+
+  /** Determines if the status text is visible for the render*/
+  @Prop() hideStatus: boolean = true;
+
+  /** Determines the status text for the true toggle*/
+  @Prop() statusTextOn: string = 'on';
+
+  /** Determines the status text for the false toggle*/
+  @Prop() statusTextOff: string = 'off';
+
+  /** Specifies the context of the component as it applies to the visual design and whether it inverts when light/dark mode is toggled. Default behavior is "light-inverts" and does not have to be specified. */
+  @Prop({ reflect: true }) context: "light-inverts" | "light-always" | "dark-inverts" | "dark-always";
+
+  /** Supports adding inline styles as an object */
+  @Prop() sx: any = {};
+
+  componentWillLoad() {
+    if (typeof this.sx == 'string') {
+      this.sx = JSON.parse(this.sx) || {};
+    }
+    setCSSProps(this.host, {
+      ...this.sx,
+    });
+  }
+
+  /** Event: toggles the control true/false & updates DOM accordingly*/
+  toggleEvent(){
+    //TODO: logic here
+  }
+
+  render() {
+    /**boilerplate HTML */
+    return (
+      <Host>
+        <slot></slot>
+      </Host>
+    );
+  }
+
+}