@kubex/zinc 0.0.2 → 1.0.0

package/src/components/checkbox-group/checkbox-group.component.ts

@@ -0,0 +1,351 @@
+import {classMap} from "lit/directives/class-map.js";
+import {type CSSResultGroup, html, unsafeCSS} from 'lit';
+import {
+  customErrorValidityState,
+  FormControlController,
+  validValidityState,
+  valueMissingValidityState
+} from "../../internal/form";
+import {HasSlotController} from '../../internal/slot';
+import {property, query, state} from 'lit/decorators.js';
+import {watch} from '../../internal/watch';
+import ZincElement from '../../internal/zinc-element';
+import type {ZincFormControl} from '../../internal/zinc-element';
+import type ZnCheckbox from "../checkbox";
+
+import styles from './checkbox-group.scss';
+
+/**
+ * @summary Shotrt summary of the component's intended use.
+ * @documentation https://zinc.style/components/checkbox-group
+ * @status experimental
+ * @since 1.0
+ *
+ * @slot - The default slot where `<zn-checkbox>` elements are placed.
+ * @slot label - The checkbox group's label. Required for proper accessibility. Alternatively, you can use the `label` attribute.
+ * @slot label-tooltip - Used to add text that is displayed in a tooltip next to the label. Alternatively, you can use the `label-tooltip` attribute.
+ * @slot help-text - Text that describes how to use the checkbox group. Alternatively, you can use the `help-text` attribute.
+ *
+ * @event zn-change - Emitted when the checkbox group's selected value changes.
+ * @event zn-input - Emitted when the checkbox group receives user input.
+ * @event zn-invalid - Emitted when the form control has been checked for validity and its constraints aren't satisfied.
+ *
+ * @csspart form-control - The form control that wraps the label, input, and help text.
+ * @csspart form-control-label - The label's wrapper.
+ * @csspart form-control-input - The input's wrapper.
+ * @csspart form-control-help-text - The help text's wrapper.
+ */
+export default class ZnCheckboxGroup extends ZincElement implements ZincFormControl {
+  static styles: CSSResultGroup = unsafeCSS(styles);
+
+  protected readonly formControlController = new FormControlController(this);
+  private readonly hasSlotController = new HasSlotController(this, 'help-text', 'label');
+  private customValidityMessage = '';
+  private validationTimeout: number;
+
+  @query('slot:not([name])') defaultSlot: HTMLSlotElement;
+  @query('.checkbox-group__validation-input') validationInput: HTMLInputElement;
+
+  @state() private errorMessage = '';
+
+  /**
+   * The checkbox group's label. Required for proper accessibility. If you need to display HTML, use the `label` slot instead. */
+  @property() label = '';
+
+  /** Text that appears in a tooltip next to the label. If you need to display HTML in the tooltip, use the `label-tooltip` slot instead. */
+  @property({attribute: 'label-tooltip'}) labelTooltip = '';
+
+  /** The checkbox groups's help text. If you need to display HTML, use the `help-text` slot instead. */
+  @property({attribute: 'help-text'}) helpText = '';
+
+  /** The name of the checkbox group, submitted as a name/value pair with form data. */
+  @property() name = '';
+
+  /**
+   * The current value of the checkbox group, submitted as a name/value pair with form data.
+   */
+  @property({type: Array, reflect: true}) value: string[] = [];
+
+  /** The checkbox group's size. This size will be applied to all child checkboxes. */
+  @property({reflect: true}) size: 'small' | 'medium' | 'large' = 'medium';
+
+  /** The checkbox group's orientation. Changes the group's layout from the default (vertical) to horizontal. */
+  @property({type: Boolean, reflect: true}) horizontal = false;
+
+  /** The checkbox group's style. Changes the group's style from the default (plain) style to the 'contained' style. This style will be applied to all child checkboxes. */
+  @property({type: Boolean, reflect: true}) contained = false;
+
+  /**
+   * By default, form controls are associated with the nearest containing `<form>` element. This attribute allows you
+   * to place the form control outside of a form and associate it with the form that has this `id`. The form must be in
+   * the same document or shadow root for this to work.
+   */
+  @property({reflect: true}) form = '';
+
+  /** Ensures at least one child checkbox is checked before allowing the containing form to submit. */
+  @property({type: Boolean, reflect: true}) required = false;
+
+  /** Gets the validity state object */
+  get validity() {
+    const anyCheckboxChecked = this.value.length > 0;
+    const isRequiredAndEmpty = this.required && !anyCheckboxChecked;
+    const hasCustomValidityMessage = this.customValidityMessage !== '';
+
+    if (hasCustomValidityMessage) {
+      return customErrorValidityState;
+    } else if (isRequiredAndEmpty) {
+      return valueMissingValidityState;
+    }
+
+    return validValidityState;
+  }
+
+  /** Gets the validation message */
+  get validationMessage() {
+    const anyCheckboxChecked = this.value.length > 0;
+    const isRequiredAndEmpty = this.required && !anyCheckboxChecked;
+    const hasCustomValidityMessage = this.customValidityMessage !== '';
+
+    if (hasCustomValidityMessage) {
+      return this.customValidityMessage;
+    } else if (isRequiredAndEmpty) {
+      return this.validationInput.validationMessage;
+    }
+
+    return '';
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.addEventListenerToCheckboxes();
+    this.getValueFromCheckboxes();
+  }
+
+  firstUpdated() {
+    this.updateCheckboxValidity();
+    this.formControlController.updateValidity();
+  }
+
+  private getAllCheckboxes() {
+    return [...this.querySelectorAll<ZnCheckbox>('zn-checkbox')];
+  }
+
+  private handleCheckboxClick(event: MouseEvent) {
+    const target = event.currentTarget as ZnCheckbox;
+
+    if (target.disabled) {
+      return;
+    }
+    this.getValueFromCheckboxes();
+    this.updateCheckboxValidity();
+
+    this.emit('zn-change');
+    this.emit('zn-input');
+    event.stopPropagation();
+  }
+
+  private handleInvalid(event: Event) {
+    this.formControlController.setValidity(false);
+    this.formControlController.emitInvalidEvent(event);
+  }
+
+  private async syncCheckboxElements() {
+    const checkboxes = this.getAllCheckboxes();
+    await Promise.all(
+      /** Sync the checkbox size, validity, and existence of 'contained' style */
+      checkboxes.map(async checkbox => {
+        await checkbox.updateComplete;
+        checkbox.size = this.size;
+        checkbox.horizontal = this.horizontal;
+
+        // Add class to checkboxes in a Checkbox Group so that we can style them without using :slotted
+        checkbox.classList.add('groupedCheckbox');
+
+        // If one checkbox in a group is 'contained' make sure they're all contained
+        const isAnyContained = checkboxes.some(containedCheckbox => containedCheckbox.contained);
+        if (isAnyContained) {
+          checkboxes.forEach(containedCheckbox => {
+            containedCheckbox.contained = true;
+          });
+
+          // Otherwise 'contained' is set through Checkbox Group
+        } else {
+          checkbox.contained = this.contained;
+        }
+
+        // Also get initial value of all nested checkboxes
+        this.getValueFromCheckboxes();
+      })
+    );
+  }
+
+  private syncCheckboxes() {
+    if (customElements.get('zn-checkbox')) {
+      this.syncCheckboxElements();
+    } else {
+      customElements.whenDefined('zn-checkbox').then(() => this.syncCheckboxes());
+    }
+  }
+
+  private updateCheckboxValidity() {
+    if (this.required) {
+      const anyCheckboxChecked = this.value.length > 0;
+      const checkboxes = this.getAllCheckboxes();
+      this.updateComplete.then(() => {
+        const checkboxGroupUserInvalid = this.dataset?.userInvalid !== undefined;
+        checkboxes.forEach(checkbox => {
+          checkbox.required = !anyCheckboxChecked;
+
+          // Add 'checkbox-user-invalid' class to all checkboxes in the group so they can be styled like 'data-user-invalid'
+          if (checkboxGroupUserInvalid) {
+            checkbox.classList.add('checkbox-user-invalid');
+          } else {
+            checkbox.classList.remove('checkbox-user-invalid');
+          }
+        });
+      });
+    }
+  }
+
+  private getValueFromCheckboxes() {
+    const checkboxes = this.getAllCheckboxes();
+    this.value = checkboxes.filter(checkbox => checkbox.checked).map(checkbox => checkbox.value);
+  }
+
+  private addEventListenerToCheckboxes() {
+    const checkboxes = this.getAllCheckboxes();
+    checkboxes.forEach(checkbox => {
+      checkbox.addEventListener('zn-change', this.handleCheckboxClick.bind(this));
+    });
+  }
+
+  @watch('size', {waitUntilFirstUpdate: true})
+  handleSizeChange() {
+    this.syncCheckboxes();
+  }
+
+  @watch('value')
+  handleValueChange() {
+    if (this.hasUpdated) {
+      this.getValueFromCheckboxes();
+      this.updateCheckboxValidity();
+    }
+  }
+
+  /** Checks for validity but does not show a validation message. Returns `true` when valid and `false` when invalid. */
+  checkValidity() {
+    const anyCheckboxChecked = this.value.length > 0;
+    const isRequiredAndEmpty = this.required && !anyCheckboxChecked;
+    const hasCustomValidityMessage = this.customValidityMessage !== '';
+
+    if (isRequiredAndEmpty || hasCustomValidityMessage) {
+      this.formControlController.emitInvalidEvent();
+      return false;
+    }
+
+    return true;
+  }
+
+  /** Gets the associated form, if one exists. */
+  getForm(): HTMLFormElement | null {
+    return this.formControlController.getForm();
+  }
+
+  /** Checks for validity and shows the browser's validation message if the control is invalid. */
+  reportValidity(): boolean {
+    const isValid = this.validity?.valid;
+
+    this.errorMessage = this.customValidityMessage || isValid ? '' : this.validationInput.validationMessage;
+    this.formControlController.setValidity(isValid);
+    this.validationInput.hidden = true;
+    clearTimeout(this.validationTimeout);
+
+    if (!isValid) {
+      // Show the browser's constraint validation message
+      this.validationInput.hidden = false;
+      this.validationInput.reportValidity();
+      this.validationTimeout = setTimeout(() => (this.validationInput.hidden = true), 10000) as unknown as number;
+    }
+
+    return isValid;
+  }
+
+  /** Sets a custom validation message. Pass an empty string to restore validity. */
+  setCustomValidity(message = '') {
+    this.customValidityMessage = message;
+    this.errorMessage = message;
+    this.validationInput.setCustomValidity(message);
+    this.formControlController.updateValidity();
+  }
+
+  render() {
+    const hasLabelSlot = this.hasSlotController.test('label');
+    const hasLabelTooltipSlot = this.hasSlotController.test('label-tooltip');
+    const hasHelpTextSlot = this.hasSlotController.test('help-text');
+    const hasLabel = this.label ? true : hasLabelSlot;
+    const hasLabelTooltip = this.labelTooltip ? true : hasLabelTooltipSlot;
+    const hasHelpText = this.helpText ? true : hasHelpTextSlot;
+    const defaultSlot = html`
+      <slot @slotchange=${this.syncCheckboxes}></slot> `;
+
+    return html`
+      <fieldset
+        part="form-control"
+        class=${classMap({
+          'form-control': true,
+          'form-control--small': this.size === 'small',
+          'form-control--medium': this.size === 'medium',
+          'form-control--large': this.size === 'large',
+          'form-control--checkbox-group': true,
+          'form-control--has-label': hasLabel,
+          'form-control--has-label-tooltip': hasLabelTooltip,
+          'form-control--has-help-text': hasHelpText
+        })}
+        role="listbox"
+        aria-labelledby="label"
+        aria-describedby="help-text"
+        aria-errormessage="error-message">
+        <label
+          part="form-control-label"
+          id="label"
+          class="form-control__label"
+          aria-hidden=${hasLabel ? 'false' : 'true'}>
+          <slot name="label">${this.label}</slot>
+          ${hasLabelTooltip
+            ? html`
+              <zn-tooltip class="form-control--label-tooltip">
+                <div slot="content">
+                  <slot name="label-tooltip">${this.labelTooltip}</slot>
+                </div>
+                <zn-icon src="info"></zn-icon>
+              </zn-tooltip>`
+            : ''}
+        </label>
+
+        <div part="form-control-input" class="form-control-input">
+          <div class="visually-hidden">
+            <div id="error-message" aria-live="assertive">${this.errorMessage}</div>
+            <label class="checkbox-group__validation">
+              <input
+                type="text"
+                class="checkbox-group__validation-input"
+                ?required=${this.required}
+                tabindex="-1"
+                hidden
+                @invalid=${this.handleInvalid}/>
+            </label>
+          </div>
+          ${defaultSlot}
+        </div>
+
+        <div
+          part="form-control-help-text"
+          id="help-text"
+          class="form-control__help-text"
+          aria-hidden=${hasHelpText ? 'false' : 'true'}>
+          <slot name="help-text">${this.helpText}</slot>
+        </div>
+      </fieldset>
+    `;
+  }
+}

package/src/components/checkbox-group/checkbox-group.scss

@@ -0,0 +1,60 @@
+@use "../../wc";
+@use "../../form-control";
+
+:host {
+  display: block;
+  line-height: var(--zn-line-height-dense);
+}
+
+:host([horizontal]) .form-control-input {
+  display: flex;
+  column-gap: var(--zn-spacing-2x-large);
+}
+
+:host([contained]) .form-control-input {
+  margin-top: var(--zn-spacing-medium);
+}
+
+:host([horizontal][contained]) .form-control-input {
+  margin-top: var(--zn-spacing-medium);
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(152px, 1fr));
+  gap: var(--zn-spacing-x-small);
+}
+
+::slotted(zn-checkbox) {
+  margin-top: var(--zn-spacing-medium);
+}
+
+::slotted(zn-checkbox[horizontal]),
+::slotted(zn-checkbox[contained]) {
+  margin-top: var(--zn-spacing-small);
+}
+
+::slotted(zn-checkbox[horizontal][contained]) {
+  margin-top: 0;
+  height: 100%;
+}
+
+.form-control {
+  position: relative;
+  border: none;
+  padding: 0;
+  margin: 0;
+}
+
+.form-control__label {
+  padding: 0;
+}
+
+.visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}

package/src/components/checkbox-group/checkbox-group.test.ts

@@ -0,0 +1,10 @@
+import '../../../dist/zn.min.js';
+import { expect, fixture, html } from '@open-wc/testing';
+
+describe('<zn-checkbox-group>', () => {
+  it('should render a component', async () => {
+    const el = await fixture(html` <zn-checkbox-group></zn-checkbox-group> `);
+
+    expect(el).to.exist;
+  });
+});

package/src/components/checkbox-group/index.ts

@@ -0,0 +1,12 @@
+import ZnCheckboxGroup from './checkbox-group.component';
+
+export * from './checkbox-group.component';
+export default ZnCheckboxGroup;
+
+ZnCheckboxGroup.define('zn-checkbox-group');
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'zn-checkbox-group': ZnCheckboxGroup;
+  }
+}

package/src/components/chip/chip.component.ts

@@ -0,0 +1,70 @@
+import {classMap} from "lit/directives/class-map.js";
+import {type CSSResultGroup, html, unsafeCSS} from 'lit';
+import {HasSlotController} from "../../internal/slot";
+import {property} from 'lit/decorators.js';
+import ZincElement from '../../internal/zinc-element';
+
+import styles from './chip.scss';
+
+/**
+ * @summary Short summary of the component's intended use.
+ * @documentation https://zinc.style/components/chip
+ * @status experimental
+ * @since 1.0
+ *
+ * @dependency zn-example
+ *
+ * @event zn-event-name - Emitted as an example.
+ *
+ * @slot - The default slot.
+ * @slot example - An example slot.
+ *
+ * @csspart base - The component's base wrapper.
+ *
+ * @cssproperty --example - An example CSS custom property.
+ */
+export default class ZnChip extends ZincElement {
+  static styles: CSSResultGroup = unsafeCSS(styles);
+
+  @property() icon: string = '';
+
+  @property() type: 'info' | 'success' | 'warning' | 'error' | 'primary' |
+    'transparent' | 'custom' | 'neutral' = 'neutral';
+
+  @property() size: 'small' | 'medium' | 'large'; // Defaults to base chip styling
+
+  @property({attribute: 'flush', type: Boolean, reflect: true}) flush: boolean = false;
+  @property({attribute: 'flush-x', type: Boolean, reflect: true}) flushX: boolean = false;
+  @property({attribute: 'flush-y', type: Boolean, reflect: true}) flushY: boolean = false;
+
+  private readonly hasSlotController = new HasSlotController(this, '[default]', 'action');
+
+  render() {
+    return html`
+      <div class=${classMap({
+        'chip': true,
+        'chip--flush': this.flush,
+        'chip--flush-x': this.flushX,
+        'chip--flush-y': this.flushY,
+        'chip--info': this.type === 'info',
+        'chip--success': this.type === 'success',
+        'chip--warning': this.type === 'warning',
+        'chip--error': this.type === 'error',
+        'chip--primary': this.type === 'primary',
+        'chip--transparent': this.type === 'transparent',
+        'chip--custom': this.type === 'custom',
+        'chip--neutral': this.type === 'neutral',
+        'chip--small': this.size === 'small',
+        'chip--medium': this.size === 'medium',
+        'chip--large': this.size === 'large',
+      })}>
+        ${this.icon ? html`
+          <zn-icon src="${this.icon}" size="18"></zn-icon>` : ''}
+        ${this.hasSlotController.test('[default]') ? html`
+          <slot></slot>` : ''}
+        ${this.hasSlotController.test('action') ? html`
+          <slot name="action" class="chip__action"></slot>` : ''}
+      </div>
+    `;
+  }
+}

package/src/components/chip/chip.scss

@@ -0,0 +1,101 @@
+@use "../../wc";
+
+:host {
+  display: inline-block;
+}
+
+.chip {
+  display: inline-flex;
+  border-radius: 7px;
+  padding: var(--zn-spacing-2x-small) var(--zn-spacing-x-small);
+  text-align: center;
+  font-size: 12px;
+  gap: 4px;
+  width: fit-content;
+  margin: 1px;
+  text-transform: capitalize;
+  justify-content: center;
+  align-items: center;
+  border: 1px solid transparent;
+  line-height: 24px;
+
+  &--flush {
+    padding: 0;
+  }
+
+  &--flush-x {
+    padding-inline: 0;
+  }
+
+  &--flush-y {
+    padding-block: 0;
+  }
+}
+
+.chip--primary {
+  color: rgba(var(--zn-primary), 0.9);
+  border-color: rgb(var(--zn-primary));
+  background: rgba(var(--zn-primary), .10);
+}
+
+.chip--error {
+  color: rgb(var(--zn-color-error));
+  border-color: rgb(var(--zn-color-error));
+  background: rgba(var(--zn-color-error), .10);
+}
+
+.chip--info {
+  color: rgb(var(--zn-color-info));
+  border-color: rgb(var(--zn-color-info));
+  background: rgba(var(--zn-color-info), .10);
+}
+
+.chip--warning {
+  color: rgb(var(--zn-color-warning));
+  border-color: rgb(var(--zn-color-warning));
+  background: rgba(var(--zn-color-warning), .10);
+}
+
+.chip--success {
+  color: rgb(var(--zn-color-success));
+  border-color: rgb(var(--zn-color-success));
+  background: rgba(var(--zn-color-success), .10);
+}
+
+.chip--neutral {
+  color: rgb(var(--zn-text));
+  border-color: rgb(var(--zn-border-color));
+  background: rgba(var(--zn-border-color), .10);
+}
+
+.chip--transparent {
+  color: rgb(var(--zn-text));
+  border-color: transparent;
+  background: transparent;
+}
+
+.chip--custom {
+  color: rgb(var(--zn-text));
+  border-color: hsl(from var(--chip-color-override, inherit) h s l / 0.6);
+  background-color: hsl(from var(--chip-color-override, inherit) h s l / 0.1);
+}
+
+.chip__action {
+  text-transform: unset;
+}
+
+.chip--small {
+  font-size: var(--zn-font-size-small);
+  padding: var(--zn-spacing-2x-small) var(--zn-spacing-x-small);
+  line-height: var(--zn-line-height-dense);
+}
+
+.chip--medium {
+  font-size: var(--zn-font-size-medium);
+  padding: var(--zn-spacing-2x-small) var(--zn-spacing-small);
+}
+
+.chip--large {
+  font-size: var(--zn-font-size-large);
+  padding: var(--zn-spacing-x-small) var(--zn-spacing-x-large);
+}

package/src/components/chip/chip.test.ts

@@ -0,0 +1,10 @@
+import '../../../dist/zn.min.js';
+import { expect, fixture, html } from '@open-wc/testing';
+
+describe('<zn-chip>', () => {
+  it('should render a component', async () => {
+    const el = await fixture(html` <zn-chip></zn-chip> `);
+
+    expect(el).to.exist;
+  });
+});

package/src/components/chip/index.ts

@@ -0,0 +1,12 @@
+import ZnChip from './chip.component';
+
+export * from './chip.component';
+export default ZnChip;
+
+ZnChip.define('zn-chip');
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'zn-chip': ZnChip;
+  }
+}