update color picker

docs/docs/components/color-picker.md

@@ -73,4 +73,12 @@ The color picker can be rendered as disabled.
 
 ```html {.example}
 <wa-color-picker disabled label="Select a color"></wa-color-picker>
+```
+
+### Help Text
+
+The color picker can be rendered as disabled.
+
+```html {.example}
+<wa-color-picker label="Select a color" help-text="Choose a color with appropate contrast!"></wa-color-picker>
 ```

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@shoelace-style/shoelace",
-  "version": "2.8.0",
+  "version": "3.0.0-alpha.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@shoelace-style/shoelace",
-      "version": "2.8.0",
+      "version": "3.0.0-alpha.1",
       "license": "MIT",
       "dependencies": {
         "@ctrl/tinycolor": "^4.0.2",

src/components/color-picker/color-picker.styles.ts

@@ -335,9 +335,14 @@ export default css`
     cursor: not-allowed;
   }
 
-  .color-dropdown__label {
+  .form-control.form-control--has-label .form-control__label {
     cursor: pointer;
-    padding-bottom: var(--spacing);
+    padding-bottom: 0.5em;
+    display: block;
+  }
+
+  .form-control__input {
+    display: block;
   }
 
   .color-dropdown__container {

src/components/color-picker/color-picker.ts

@@ -26,6 +26,8 @@ import styles from './color-picker.styles.js';
 import type { CSSResultGroup } from 'lit';
 import type WaDropdown from '../dropdown/dropdown.js';
 import type WaInput from '../input/input.js';
+import formControlStyles from '../../styles/form-control.styles.js';
+import { HasSlotController } from '../../internal/slot.js';
 
 const hasEyeDropper = 'EyeDropper' in window;
 
@@ -52,6 +54,7 @@ declare const EyeDropper: EyeDropperConstructor;
  * @dependency wa-visually-hidden
  *
  * @slot label - The color picker's form label. Alternatively, you can use the `label` attribute.
+ * @slot help-text - The color picker's form help text. Alternatively, you can use the `helpText` attribute.
  *
  * @event wa-blur - Emitted when the color picker loses focus.
  * @event wa-change - Emitted when the color picker's value changes.
@@ -105,7 +108,7 @@ declare const EyeDropper: EyeDropperConstructor;
  */
 @customElement('wa-color-picker')
 export default class WaColorPicker extends WebAwesomeFormAssociatedElement {
-  static styles: CSSResultGroup = [componentStyles, styles];
+  static styles: CSSResultGroup = [componentStyles, formControlStyles, styles];
 
   static shadowRootOptions = { ...WebAwesomeFormAssociatedElement.shadowRootOptions, delegatesFocus: true };
 
@@ -113,6 +116,8 @@ export default class WaColorPicker extends WebAwesomeFormAssociatedElement {
     return [...super.validators, RequiredValidator()];
   }
 
+  private readonly hasSlotController = new HasSlotController(this, 'help-text', 'label');
+
   private isSafeValue = false;
   private readonly localize = new LocalizeController(this);
 
@@ -161,13 +166,18 @@ export default class WaColorPicker extends WebAwesomeFormAssociatedElement {
    */
   @property() label = '';
 
+  /**
+   * The color picker's help text. If you need to display HTML, use the `help-text` slot instead.
+   */
+  @property({ attribute: "help-text" }) helpText = '';
+
   /**
    * The format to use. If opacity is enabled, these will translate to HEXA, RGBA, HSLA, and HSVA respectively. The color
    * picker will accept user input in any format (including CSS color names) and convert it to the desired format.
    */
   @property() format: 'hex' | 'rgb' | 'hsl' | 'hsv' = 'hex';
 
-  /** Determines the size of the color picker's trigger. This has no effect on inline color pickers. */
+  /** Determines the size of the color picker's trigger */
   @property({ reflect: true }) size: 'small' | 'medium' | 'large' = 'medium';
 
   /** Removes the button that lets users toggle between format.   */
@@ -785,7 +795,7 @@ export default class WaColorPicker extends WebAwesomeFormAssociatedElement {
   reportValidity() {
     // This won't get called when a form is submitted. This is only for manual calls.
     if (!this.validity.valid && !this.dropdown.open) {
-      // If the input is inline and invalid, show the dropdown so the browser can focus on it
+      // Show the dropdown so the browser can focus on it
       this.addEventListener('wa-after-show', () => this.reportValidity(), { once: true });
       this.dropdown.show();
 
@@ -807,6 +817,11 @@ export default class WaColorPicker extends WebAwesomeFormAssociatedElement {
   }
 
   render() {
+    const hasLabelSlot = this.hasSlotController.test('label');
+    const hasHelpTextSlot = this.hasSlotController.test('help-text');
+    const hasLabel = this.label ? true : !!hasLabelSlot;
+    const hasHelpText = this.helpText ? true : !!hasHelpTextSlot;
+
     const gridHandleX = this.saturation;
     const gridHandleY = 100 - this.brightness;
     const swatches = Array.isArray(this.swatches)
@@ -1043,15 +1058,28 @@ export default class WaColorPicker extends WebAwesomeFormAssociatedElement {
         @wa-after-show=${this.handleAfterShow}
         @wa-after-hide=${this.handleAfterHide}
       >
-        <div class="color-dropdown__container" part="trigger-container" slot="trigger">
-          <!-- Ideally this should be a <label> but it causes click event to fire twice causing the popup to open then close. -->
-          <div id="trigger-label" part="trigger-label" class="color-dropdown__label">
-            <slot name="label">${this.label}</slot>
-          </div>
+        <div
+          class=${classMap({
+            'color-dropdown__container': true,
+            'form-control': true,
+            'form-control--small': this.size === 'small',
+            'form-control--medium': this.size === 'medium',
+            'form-control--large': this.size === 'large',
+            'form-control--has-label': hasLabel,
+            'form-control--has-help-text': hasHelpText
+          })}
+          part="trigger-container form-control"
+          slot="trigger"
+        >
+          <div
+            part="form-control-label"
+            class="form-control__label"
+            id="form-control-label"
+          ><slot name="label">${this.label}</slot></div>
 
           <button
             id="trigger"
-            part="trigger"
+            part="trigger form-control-input"
             class=${classMap({
               'color-dropdown__trigger': true,
               'color-dropdown__trigger--disabled': this.disabled,
@@ -1060,14 +1088,22 @@ export default class WaColorPicker extends WebAwesomeFormAssociatedElement {
               'color-dropdown__trigger--large': this.size === 'large',
               'color-dropdown__trigger--empty': this.isEmpty,
               'color-dropdown__trigger--focused': this.hasFocus,
-              'color-picker__transparent-bg': true
+              'color-picker__transparent-bg': true,
+              'form-control-input': true,
             })}
             style=${styleMap({
               color: this.getHexString(this.hue, this.saturation, this.brightness, this.alpha)
             })}
             type="button"
-            aria-labelledby="trigger-label"
+            aria-labelledby="form-control-label"
+            aria-describedby="help-text"
           ></button>
+
+          <div
+            part="form-control-help-text"
+            id="help-text"
+            class="form-control__help-text"
+          ><slot name="help-text">${this.helpText}</slot></div>
         </div>
         ${colorPicker}
       </wa-dropdown>