@aquera/nile-elements 0.0.1-beta.1

package/rollup.config.js

@@ -0,0 +1,86 @@
+import { readdirSync } from 'fs';
+import summary from 'rollup-plugin-summary';
+import { terser } from 'rollup-plugin-terser';
+import resolve from '@rollup/plugin-node-resolve';
+import replace from '@rollup/plugin-replace';
+import typescript from '@rollup/plugin-typescript';
+import { getBabelOutputPlugin } from '@rollup/plugin-babel';
+import glob from 'glob';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const { LERNA_PACKAGE_NAME } = process.env;
+const PACKAGE_ROOT_PATH = process.cwd();
+
+import styles from 'rollup-plugin-styles';
+
+export default {
+  input: Object.fromEntries(
+    glob.sync('src/**/*.ts').map(file => [
+      // This remove `src/` as well as the file extension from each file, so e.g.
+      // src/nested/foo.js becomes nested/foo
+      path.relative(
+        'src',
+        file.slice(0, file.length - path.extname(file).length)
+      ),
+      // This expands the relative paths to absolute paths, so e.g.
+      // src/nested/foo becomes /project/src/nested/foo.js
+      fileURLToPath(new URL(file, import.meta.url)),
+    ])
+  ),
+  external: ['tslib', 'lit', /^lit\/.*/],
+  output: [
+    {
+      // Modern JS bundles (no JS compilation, ES module output)
+      format: 'es',
+      chunkFileNames: '[name]-[hash].esm.js',
+      entryFileNames: '[name].esm.js',
+      dir: 'dist',
+      sourcemap: false,
+    },
+    {
+      // Legacy JS bundles (ES5 compilation and SystemJS module output)
+      format: 'esm',
+      chunkFileNames: '[name]-[hash].cjs.js',
+      entryFileNames: '[name].cjs.js',
+      dir: 'dist',
+      sourcemap: true,
+      plugins: [
+        getBabelOutputPlugin({
+          compact: true,
+          presets: [
+            [
+              '@babel/preset-env',
+              {
+                modules: 'systemjs',
+              },
+            ],
+          ],
+        }),
+      ],
+    },
+  ],
+  onwarn(warning) {
+    if (warning.code !== 'THIS_IS_UNDEFINED') {
+      console.error(`(!) ${warning.message}`);
+    }
+  },
+  plugins: [
+    typescript(),
+    replace({ 'Reflect.decorate': 'undefined' }),
+    resolve(),
+    terser({
+      ecma: 2017,
+      module: true,
+      warnings: true,
+      mangle: {
+        properties: {
+          regex: /^__/,
+        },
+      },
+    }),
+    styles(),
+    summary(),
+  ],
+  preserveEntrySignatures: false,
+};

package/src/index.ts

@@ -0,0 +1,17 @@
+export { NileButton } from './nile-button';
+export { NileHeading } from './nile-heading';
+export { NileIcon } from './nile-icon';
+export { NileInput } from './nile-input';
+export { NileSidebar } from './nile-sidebar';
+export { NileMenu } from './nile-menu';
+export { NileBadge } from './nile-badge';
+export { NileDrawer } from './nile-drawer';
+export { NileCheckbox } from './nile-checkbox';
+export { NileRadio } from './nile-radio';
+export { NileRadioGroup } from './nile-radio-group';
+export { NilePopup } from './nile-popup';
+export { NileTooltip } from './nile-tooltip';
+export { NileSlideToggle } from './nile-slide-toggle';
+export { NileLoader } from './nile-loader';
+export { NileProgressBar } from './nile-progress-bar';
+export { NileSpinner } from './nile-spinner';

package/src/internal/animate.ts

@@ -0,0 +1,67 @@
+/**
+ * Animates an element using keyframes. Returns a promise that resolves after the animation completes or gets canceled.
+ */
+export function animateTo(el: HTMLElement, keyframes: Keyframe[], options?: KeyframeAnimationOptions) {
+  return new Promise(resolve => {
+    if (options?.duration === Infinity) {
+      throw new Error('Promise-based animations must be finite.');
+    }
+
+    const animation = el.animate(keyframes, {
+      ...options,
+      duration: prefersReducedMotion() ? 0 : options!.duration
+    });
+
+    animation.addEventListener('cancel', resolve, { once: true });
+    animation.addEventListener('finish', resolve, { once: true });
+  });
+}
+
+/** Parses a CSS duration and returns the number of milliseconds. */
+export function parseDuration(delay: number | string) {
+  delay = delay.toString().toLowerCase();
+
+  if (delay.indexOf('ms') > -1) {
+    return parseFloat(delay);
+  }
+
+  if (delay.indexOf('s') > -1) {
+    return parseFloat(delay) * 1000;
+  }
+
+  return parseFloat(delay);
+}
+
+/** Tells if the user has enabled the "reduced motion" setting in their browser or OS. */
+export function prefersReducedMotion() {
+  const query = window.matchMedia('(prefers-reduced-motion: reduce)');
+  return query.matches;
+}
+
+/**
+ * Stops all active animations on the target element. Returns a promise that resolves after all animations are canceled.
+ */
+export function stopAnimations(el: HTMLElement) {
+  return Promise.all(
+    el.getAnimations().map(animation => {
+      return new Promise(resolve => {
+        const handleAnimationEvent = requestAnimationFrame(resolve);
+
+        animation.addEventListener('cancel', () => handleAnimationEvent, { once: true });
+        animation.addEventListener('finish', () => handleAnimationEvent, { once: true });
+        animation.cancel();
+      });
+    })
+  );
+}
+
+/**
+ * We can't animate `height: auto`, but we can calculate the height and shim keyframes by replacing it with the
+ * element's scrollHeight before the animation.
+ */
+export function shimKeyframesHeightAuto(keyframes: Keyframe[], calculatedHeight: number) {
+  return keyframes.map(keyframe => ({
+    ...keyframe,
+    height: keyframe.height === 'auto' ? `${calculatedHeight}px` : keyframe.height
+  }));
+}

package/src/internal/default-value.ts

@@ -0,0 +1,49 @@
+// @defaultValue decorator
+//
+// Runs when the corresponding attribute of the observed property changes, e.g. after calling Element.setAttribute or after updating
+// the observed property.
+//
+// The decorator checks whether the value of the attribute is different from the value of the property and in that case
+// it saves the new value.
+//
+//
+// Usage:
+//
+//  @property({ type: Boolean, reflect: true }) checked = false;
+//
+//  @defaultValue('checked') defaultChecked = false;
+//
+
+import { defaultConverter } from 'lit';
+import type { ReactiveElement } from 'lit';
+
+export const defaultValue =
+  (propertyName = 'value') =>
+  (proto: ReactiveElement, key: string) => {
+    const ctor = proto.constructor as typeof ReactiveElement;
+
+    const attributeChangedCallback = ctor.prototype.attributeChangedCallback;
+    ctor.prototype.attributeChangedCallback = function (
+      this: ReactiveElement & { [name: string]: unknown },
+      name,
+      old,
+      value
+    ) {
+      const options = ctor.getPropertyOptions(propertyName);
+      const attributeName = typeof options.attribute === 'string' ? options.attribute : propertyName;
+
+      if (name === attributeName) {
+        const converter = options.converter || defaultConverter;
+        const fromAttribute =
+          typeof converter === 'function' ? converter : converter?.fromAttribute ?? defaultConverter.fromAttribute;
+
+        const newValue: unknown = fromAttribute!(value, options.type);
+
+        if (this[propertyName] !== newValue) {
+          this[key] = newValue;
+        }
+      }
+
+      attributeChangedCallback.call(this, name, old, value);
+    };
+  };

package/src/internal/event.ts

@@ -0,0 +1,13 @@
+/** Waits for a specific event to be emitted from an element. Ignores events that bubble up from child elements. */
+export function waitForEvent(el: HTMLElement, eventName: string) {
+  return new Promise<void>(resolve => {
+    function done(event: Event) {
+      if (event.target === el) {
+        el.removeEventListener(eventName, done);
+        resolve();
+      }
+    }
+
+    el.addEventListener(eventName, done);
+  });
+}

package/src/internal/form.ts

@@ -0,0 +1,408 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+import type { NileFormControl } from '../internal/nile-element';
+import type { NileButton } from '../nile-button';
+
+//
+// We store a WeakMap of forms + controls so we can keep references to all Nile controls within a given form. As
+// elements connect and disconnect to/from the DOM, their containing form is used as the key and the form control is
+// added and removed from the form's set, respectively.
+//
+export const formCollections: WeakMap<HTMLFormElement, Set<NileFormControl>> = new WeakMap();
+
+//
+// We store a WeakMap of reportValidity() overloads so we can override it when form controls connect to the DOM and
+// restore the original behavior when they disconnect.
+//
+const reportValidityOverloads: WeakMap<HTMLFormElement, () => boolean> = new WeakMap();
+
+//
+// We store a Set of controls that users have interacted with. This allows us to determine the interaction state
+// without littering the DOM with additional data attributes.
+//
+const userInteractedControls: WeakSet<NileFormControl> = new WeakSet();
+
+//
+// We store a WeakMap of interactions for each form control so we can track when all conditions are met for validation.
+//
+const interactions = new WeakMap<NileFormControl, string[]>();
+
+export interface FormControlControllerOptions {
+  /** A function that returns the form containing the form control. */
+  form: (input: NileFormControl) => HTMLFormElement | null;
+  /** A function that returns the form control's name, which will be submitted with the form data. */
+  name: (input: NileFormControl) => string;
+  /** A function that returns the form control's current value. */
+  value: (input: NileFormControl) => unknown | unknown[];
+  /** A function that returns the form control's default value. */
+  defaultValue: (input: NileFormControl) => unknown | unknown[];
+  /** A function that returns the form control's current disabled state. If disabled, the value won't be submitted. */
+  disabled: (input: NileFormControl) => boolean;
+  /**
+   * A function that maps to the form control's reportValidity() function. When the control is invalid, this will
+   * prevent submission and trigger the browser's constraint violation warning.
+   */
+  reportValidity: (input: NileFormControl) => boolean;
+  /** A function that sets the form control's value */
+  setValue: (input: NileFormControl, value: unknown) => void;
+  /**
+   * An array of event names to listen to. When all events in the list are emitted, the control will receive validity
+   * states such as user-valid and user-invalid.user interacted validity states. */
+  assumeInteractionOn: string[];
+}
+
+/** A reactive controller to allow form controls to participate in form submission, validation, etc. */
+export class FormControlController implements ReactiveController {
+  host: NileFormControl & ReactiveControllerHost;
+  form?: HTMLFormElement | null;
+  options: FormControlControllerOptions;
+
+  constructor(host: ReactiveControllerHost & NileFormControl, options?: Partial<FormControlControllerOptions>) {
+    (this.host = host).addController(this);
+    this.options = {
+      form: input => {
+        // If there's a form attribute, use it to find the target form by id
+        if (input.hasAttribute('form') && input.getAttribute('form') !== '') {
+          const root = input.getRootNode() as Document | ShadowRoot;
+          const formId = input.getAttribute('form');
+
+          if (formId) {
+            return root.getElementById(formId) as HTMLFormElement;
+          }
+        }
+
+        return input.closest('form');
+      },
+      name: input => input.name,
+      value: input => input.value,
+      defaultValue: input => input.defaultValue,
+      disabled: input => input.disabled ?? false,
+      reportValidity: input => (typeof input.reportValidity === 'function' ? input.reportValidity() : true),
+      setValue: (input, value: string) => (input.value = value),
+      assumeInteractionOn: ['sl-input'],
+      ...options
+    };
+    this.handleFormData = this.handleFormData.bind(this);
+    this.handleFormSubmit = this.handleFormSubmit.bind(this);
+    this.handleFormReset = this.handleFormReset.bind(this);
+    this.reportFormValidity = this.reportFormValidity.bind(this);
+    this.handleInteraction = this.handleInteraction.bind(this);
+  }
+
+  hostConnected() {
+    const form = this.options.form(this.host);
+
+    if (form) {
+      this.attachForm(form);
+    }
+
+    // Listen for interactions
+    interactions.set(this.host, []);
+    this.options.assumeInteractionOn.forEach(event => {
+      this.host.addEventListener(event, this.handleInteraction);
+    });
+  }
+
+  hostDisconnected() {
+    this.detachForm();
+
+    // Clean up interactions
+    interactions.delete(this.host);
+    this.options.assumeInteractionOn.forEach(event => {
+      this.host.removeEventListener(event, this.handleInteraction);
+    });
+  }
+
+  hostUpdated() {
+    const form = this.options.form(this.host);
+
+    // Detach if the form no longer exists
+    if (!form) {
+      this.detachForm();
+    }
+
+    // If the form has changed, reattach it
+    if (form && this.form !== form) {
+      this.detachForm();
+      this.attachForm(form);
+    }
+
+    if (this.host.hasUpdated) {
+      this.setValidity(this.host.validity.valid);
+    }
+  }
+
+  private attachForm(form?: HTMLFormElement) {
+    if (form) {
+      this.form = form;
+
+      // Add this element to the form's collection
+      if (formCollections.has(this.form)) {
+        formCollections.get(this.form)!.add(this.host);
+      } else {
+        formCollections.set(this.form, new Set<NileFormControl>([this.host]));
+      }
+
+      this.form.addEventListener('formdata', this.handleFormData);
+      this.form.addEventListener('submit', this.handleFormSubmit);
+      this.form.addEventListener('reset', this.handleFormReset);
+
+      // Overload the form's reportValidity() method so it looks at nile form controls
+      if (!reportValidityOverloads.has(this.form)) {
+        reportValidityOverloads.set(this.form, this.form.reportValidity);
+        this.form.reportValidity = () => this.reportFormValidity();
+      }
+    } else {
+      this.form = undefined;
+    }
+  }
+
+  private detachForm() {
+    if (this.form) {
+      // Remove this element from the form's collection
+      formCollections.get(this.form)?.delete(this.host);
+
+      this.form.removeEventListener('formdata', this.handleFormData);
+      this.form.removeEventListener('submit', this.handleFormSubmit);
+      this.form.removeEventListener('reset', this.handleFormReset);
+
+      // Remove the overload and restore the original method
+      if (reportValidityOverloads.has(this.form)) {
+        this.form.reportValidity = reportValidityOverloads.get(this.form)!;
+        reportValidityOverloads.delete(this.form);
+      }
+    }
+
+    this.form = undefined;
+  }
+
+  private handleFormData(event: FormDataEvent) {
+    const disabled = this.options.disabled(this.host);
+    const name = this.options.name(this.host);
+    const value = this.options.value(this.host);
+
+    // For buttons, we only submit the value if they were the submitter. This is currently done in doAction() by
+    // injecting the name/value on a temporary button, so we can just skip them here.
+    const isButton = this.host.tagName.toLowerCase() === 'sl-button';
+
+    if (!disabled && !isButton && typeof name === 'string' && name.length > 0 && typeof value !== 'undefined') {
+      if (Array.isArray(value)) {
+        (value as unknown[]).forEach(val => {
+          event.formData.append(name, (val as string | number | boolean).toString());
+        });
+      } else {
+        event.formData.append(name, (value as string | number | boolean).toString());
+      }
+    }
+  }
+
+  private handleFormSubmit(event: Event) {
+    const disabled = this.options.disabled(this.host);
+    const reportValidity = this.options.reportValidity;
+
+    // Update the interacted state for all controls when the form is submitted
+    if (this.form && !this.form.noValidate) {
+      formCollections.get(this.form)?.forEach(control => {
+        this.setUserInteracted(control, true);
+      });
+    }
+
+    if (this.form && !this.form.noValidate && !disabled && !reportValidity(this.host)) {
+      event.preventDefault();
+      event.stopImmediatePropagation();
+    }
+  }
+
+  private handleFormReset() {
+    this.options.setValue(this.host, this.options.defaultValue(this.host));
+    this.setUserInteracted(this.host, false);
+    interactions.set(this.host, []);
+  }
+
+  private handleInteraction(event: Event) {
+    const emittedEvents = interactions.get(this.host)!;
+
+    if (!emittedEvents.includes(event.type)) {
+      emittedEvents.push(event.type);
+    }
+
+    // Mark it as user-interacted as soon as all associated events have been emitted
+    if (emittedEvents.length === this.options.assumeInteractionOn.length) {
+      this.setUserInteracted(this.host, true);
+    }
+  }
+
+  private reportFormValidity() {
+    //
+    // Nile form controls work hard to act like regular form controls. They support the Constraint Validation API
+    // and its associated methods such as setCustomValidity() and reportValidity(). However, the HTMLFormElement also
+    // has a reportValidity() method that will trigger validation on all child controls. Since we're not yet using
+    // ElementInternals, we need to overload this method so it looks for any element with the reportValidity() method.
+    //
+    // We preserve the original method in a WeakMap, but we don't call it from the overload because that would trigger
+    // validations in an unexpected order. When the element disconnects, we revert to the original behavior. This won't
+    // be necessary once we can use ElementInternals.
+    //
+    // Note that we're also honoring the form's novalidate attribute.
+    //
+    if (this.form && !this.form.noValidate) {
+      // This seems sloppy, but checking all elements will cover native inputs, Nile inputs, and other custom
+      // elements that support the constraint validation API.
+      const elements = this.form.querySelectorAll<HTMLInputElement>('*');
+
+      for (const element of elements) {
+        if (typeof element.reportValidity === 'function') {
+          if (!element.reportValidity()) {
+            return false;
+          }
+        }
+      }
+    }
+
+    return true;
+  }
+
+  private setUserInteracted(el: NileFormControl, hasInteracted: boolean) {
+    if (hasInteracted) {
+      userInteractedControls.add(el);
+    } else {
+      userInteractedControls.delete(el);
+    }
+
+    el.requestUpdate();
+  }
+
+  private doAction(type: 'submit' | 'reset', submitter?: HTMLInputElement | NileButton) {
+    if (this.form) {
+      const button = document.createElement('button');
+      button.type = type;
+      button.style.position = 'absolute';
+      button.style.width = '0';
+      button.style.height = '0';
+      button.style.clipPath = 'inset(50%)';
+      button.style.overflow = 'hidden';
+      button.style.whiteSpace = 'nowrap';
+
+      // Pass name, value, and form attributes through to the temporary button
+      if (submitter) {
+        button.name = submitter.name;
+        button.value = submitter.value;
+
+        ['formaction', 'formenctype', 'formmethod', 'formnovalidate', 'formtarget'].forEach(attr => {
+          if (submitter.hasAttribute(attr)) {
+            button.setAttribute(attr, submitter.getAttribute(attr)!);
+          }
+        });
+      }
+
+      this.form.append(button);
+      button.click();
+      button.remove();
+    }
+  }
+
+  /** Returns the associated `<form>` element, if one exists. */
+  getForm() {
+    return this.form ?? null;
+  }
+
+  /** Resets the form, restoring all the control to their default value */
+  reset(submitter?: HTMLInputElement | NileButton) {
+    this.doAction('reset', submitter);
+  }
+
+  /** Submits the form, triggering validation and form data injection. */
+  submit(submitter?: HTMLInputElement | NileButton) {
+    // Calling form.submit() bypasses the submit event and constraint validation. To prevent this, we can inject a
+    // native submit button into the form, "click" it, then remove it to simulate a standard form submission.
+    this.doAction('submit', submitter);
+  }
+
+  /**
+   * Synchronously sets the form control's validity. Call this when you know the future validity but need to update
+   * the host element immediately, i.e. before Lit updates the component in the next update.
+   */
+  setValidity(isValid: boolean) {
+    const host = this.host;
+    const hasInteracted = Boolean(userInteractedControls.has(host));
+    const required = Boolean(host.required);
+
+    //
+    // We're mapping the following "states" to data attributes. In the future, we can use ElementInternals.states to
+    // create a similar mapping, but instead of [data-invalid] it will look like :--invalid.
+    //
+    //
+    host.toggleAttribute('data-required', required);
+    host.toggleAttribute('data-optional', !required);
+    host.toggleAttribute('data-invalid', !isValid);
+    host.toggleAttribute('data-valid', isValid);
+    host.toggleAttribute('data-user-invalid', !isValid && hasInteracted);
+    host.toggleAttribute('data-user-valid', isValid && hasInteracted);
+  }
+
+  /**
+   * Updates the form control's validity based on the current value of `host.validity.valid`. Call this when anything
+   * that affects constraint validation changes so the component receives the correct validity states.
+   */
+  updateValidity() {
+    const host = this.host;
+    this.setValidity(host.validity.valid);
+  }
+
+  /**
+   * Dispatches a non-bubbling, cancelable custom event of type `sl-invalid`.
+   * If the `sl-invalid` event will be cancelled then the original `invalid`
+   * event (which may have been passed as argument) will also be cancelled.
+   * If no original `invalid` event has been passed then the `sl-invalid`
+   * event will be cancelled before being dispatched.
+   */
+  emitInvalidEvent(originalInvalidEvent?: Event) {
+    const slInvalidEvent = new CustomEvent<Record<PropertyKey, never>>('sl-invalid', {
+      bubbles: false,
+      composed: false,
+      cancelable: true,
+      detail: {}
+    });
+
+    if (!originalInvalidEvent) {
+      slInvalidEvent.preventDefault();
+    }
+
+    if (!this.host.dispatchEvent(slInvalidEvent)) {
+      originalInvalidEvent?.preventDefault();
+    }
+  }
+}
+
+/*
+ * Predefined common validity states.
+ * All of them are read-only.
+ */
+
+// A validity state object that represents `valid`
+export const validValidityState: ValidityState = Object.freeze({
+  badInput: false,
+  customError: false,
+  patternMismatch: false,
+  rangeOverflow: false,
+  rangeUnderflow: false,
+  stepMismatch: false,
+  tooLong: false,
+  tooShort: false,
+  typeMismatch: false,
+  valid: true,
+  valueMissing: false
+});
+
+// A validity state object that represents `value missing`
+export const valueMissingValidityState: ValidityState = Object.freeze({
+  ...validValidityState,
+  valid: false,
+  valueMissing: true
+});
+
+// A validity state object that represents a custom error
+export const customErrorValidityState: ValidityState = Object.freeze({
+  ...validValidityState,
+  valid: false,
+  customError: true
+});

package/src/internal/nile-element.ts

@@ -0,0 +1,47 @@
+import { LitElement } from 'lit';
+
+export default class NileElement extends LitElement {
+
+  /** Emits a custom event with more convenient defaults. */
+  emit(name: string, detail?: any) {
+    const event = new CustomEvent(name, {
+      bubbles: true,
+      cancelable: false,
+      composed: true,
+      detail
+    });
+
+    this.dispatchEvent(event);
+  }
+}
+
+
+export interface NileFormControl extends NileElement {
+  // Form attributes
+  name: string;
+  value: unknown;
+  disabled?: boolean;
+  defaultValue?: unknown;
+  defaultChecked?: boolean;
+  form?: string;
+
+  // Constraint validation attributes
+  pattern?: string;
+  min?: number | string | Date;
+  max?: number | string | Date;
+  step?: number | 'any';
+  required?: boolean;
+  minlength?: number;
+  maxlength?: number;
+
+  // Form validation properties
+  readonly validity: ValidityState;
+  readonly validationMessage: string;
+
+  // Form validation methods
+  checkValidity: () => boolean;
+  getForm: () => HTMLFormElement | null;
+  reportValidity: () => boolean;
+  setCustomValidity: (message: string) => void;
+}
+