@kubex/zinc 0.0.2 → 1.0.0

package/src/internal/slot.ts

@@ -0,0 +1,110 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+
+/** A reactive controller that determines when slots exist. */
+export class HasSlotController implements ReactiveController {
+  host: ReactiveControllerHost & Element;
+  slotNames: string[] = [];
+
+  constructor(host: ReactiveControllerHost & Element, ...slotNames: string[]) {
+    (this.host = host).addController(this);
+    this.slotNames = slotNames;
+  }
+
+  private hasDefaultSlot() {
+    return [...this.host.childNodes].some(node => {
+      if (node.nodeType === node.TEXT_NODE && node.textContent!.trim() !== '') {
+        return true;
+      }
+
+      if (node.nodeType === node.ELEMENT_NODE) {
+        const el = node as HTMLElement;
+        const tagName = el.tagName.toLowerCase();
+
+        // Ignore visually hidden elements since they aren't rendered
+        if (tagName === 'zn-visually-hidden') {
+          return false;
+        }
+
+        // If it doesn't have a slot attribute, it's part of the default slot
+        if (!el.hasAttribute('slot')) {
+          return true;
+        }
+      }
+
+      return false;
+    });
+  }
+
+  private hasNamedSlot(name: string) {
+    return this.host.querySelector(`:scope > [slot="${name}"]`) !== null;
+  }
+
+  test(slotName: string) {
+    return slotName === '[default]' ? this.hasDefaultSlot() : this.hasNamedSlot(slotName);
+  }
+
+  hostConnected() {
+    this.host.shadowRoot!.addEventListener('slotchange', this.handleSlotChange);
+  }
+
+  hostDisconnected() {
+    this.host.shadowRoot!.removeEventListener('slotchange', this.handleSlotChange);
+  }
+
+  getSlot(slotName: string) {
+    return this.host.querySelector(`:scope > [slot="${slotName}"]`)!;
+  }
+
+  getSlots(slotName: string) {
+    return this.host.querySelectorAll(`:scope > [slot="${slotName}"]`) as NodeListOf<HTMLElement>;
+  }
+
+  private handleSlotChange = (event: Event) => {
+    const slot = event.target as HTMLSlotElement;
+
+    if ((this.slotNames.includes('[default]') && !slot.name) || (slot.name && this.slotNames.includes(slot.name))) {
+      this.host.requestUpdate();
+    }
+  };
+}
+
+/**
+ * Given a slot, this function iterates over all of its assigned element and text nodes and returns the concatenated
+ * HTML as a string. This is useful because we can't use slot.innerHTML as an alternative.
+ */
+export function getInnerHTML(slot: HTMLSlotElement): string {
+  const nodes = slot.assignedNodes({ flatten: true });
+  let html = '';
+
+  [...nodes].forEach(node => {
+    if (node.nodeType === Node.ELEMENT_NODE) {
+      html += (node as HTMLElement).outerHTML;
+    }
+
+    if (node.nodeType === Node.TEXT_NODE) {
+      html += node.textContent;
+    }
+  });
+
+  return html;
+}
+
+/**
+ * Given a slot, this function iterates over all of its assigned text nodes and returns the concatenated text as a
+ * string. This is useful because we can't use slot.textContent as an alternative.
+ */
+export function getTextContent(slot: HTMLSlotElement | undefined | null): string {
+  if (!slot) {
+    return '';
+  }
+  const nodes = slot.assignedNodes({ flatten: true });
+  let text = '';
+
+  [...nodes].forEach(node => {
+    if (node.nodeType === Node.TEXT_NODE) {
+      text += node.textContent;
+    }
+  });
+
+  return text;
+}

package/src/internal/storage.ts

@@ -0,0 +1,70 @@
+export class Store {
+  public storage: Storage;
+  public prefix: string;
+  public ttl: number;
+
+  constructor(storage: Storage, prefix: string, ttl: number = 0) {
+    this.storage = storage;
+    this.prefix = prefix;
+    this.ttl = ttl * 1000;
+    //TODO: Improve this to run once per prefix
+    this.cleanup();
+  }
+
+  public get(key: string): null | string {
+    if (!key || key.length < 1) {
+      return null;
+    }
+
+    return this.stripTtl(this.storage.getItem(this.prefix + key));
+  }
+
+  public stripTtl(value: string | null): null | string {
+    if (value === null) {
+      return null;
+    }
+    const parts = value.split(",");
+    if (parts.length === 1) {
+      return parts[0];
+    }
+    const i = parts.shift()
+    const ttl = i ? parseInt(i) : 0;
+    if (ttl > 0 && ttl < Date.now()) {
+      return null;
+    }
+    return parts.join(",") || '';
+  }
+
+  public setWithTTL(key: string, value: string, ttl: number): void {
+    if (!key || key.length < 1) {
+      return;
+    }
+    ttl = ttl > 0 ? Date.now() + (ttl * 1000) : 0;
+    this.storage.setItem(this.prefix + key, ttl + "," + value);
+  }
+
+  public set(key: string, value: string): void {
+    this.setWithTTL(key, value, this.ttl);
+  }
+
+  public remove(key: string): void {
+    this.storage.removeItem(this.prefix + key);
+  }
+
+  public cleanup() {
+    for (let i = 0; i < this.storage.length; i++) {
+      const key = this.storage.key(i);
+      if (key === null) {
+        continue;
+      }
+
+      if (key.startsWith(this.prefix)) {
+        const value = this.stripTtl(this.storage.getItem(key));
+        if (value === null) // Check for TTLed values
+        {
+          this.storage.removeItem(key);
+        }
+      }
+    }
+  }
+}

package/src/internal/tabbable.ts

@@ -0,0 +1,198 @@
+// Cached compute style calls. This is specifically for browsers that dont support `checkVisibility()`.
+// computedStyle calls are "live" so they only need to be retrieved once for an element.
+const computedStyleMap = new WeakMap<Element, CSSStyleDeclaration>();
+
+function getCachedComputedStyle(el: HTMLElement): CSSStyleDeclaration {
+  let computedStyle: undefined | CSSStyleDeclaration = computedStyleMap.get(el);
+
+  if (!computedStyle) {
+    computedStyle = window.getComputedStyle(el, null);
+    computedStyleMap.set(el, computedStyle);
+  }
+
+  return computedStyle;
+}
+
+function isVisible(el: HTMLElement): boolean {
+  // This is the fastest check, but isn't supported in Safari.
+  if (typeof el.checkVisibility === 'function') {
+    // Opacity is focusable, visibility is not.
+    return el.checkVisibility({ checkOpacity: false, checkVisibilityCSS: true });
+  }
+
+  // Fallback "polyfill" for "checkVisibility"
+  const computedStyle = getCachedComputedStyle(el);
+
+  return computedStyle.visibility !== 'hidden' && computedStyle.display !== 'none';
+}
+
+// While this behavior isn't standard in Safari / Chrome yet, I think it's the most reasonable
+// way of handling tabbable overflow areas. Browser sniffing seems gross, and it's the most
+// accessible way of handling overflow areas. [Konnor]
+function isOverflowingAndTabbable(el: HTMLElement): boolean {
+  const computedStyle = getCachedComputedStyle(el);
+
+  const { overflowY, overflowX } = computedStyle;
+
+  if (overflowY === 'scroll' || overflowX === 'scroll') {
+    return true;
+  }
+
+  if (overflowY !== 'auto' || overflowX !== 'auto') {
+    return false;
+  }
+
+  // Always overflow === "auto" by this point
+  const isOverflowingY = el.scrollHeight > el.clientHeight;
+
+  if (isOverflowingY && overflowY === 'auto') {
+    return true;
+  }
+
+  const isOverflowingX = el.scrollWidth > el.clientWidth;
+
+  if (isOverflowingX && overflowX === 'auto') {
+    return true;
+  }
+
+  return false;
+}
+
+/** Determines if the specified element is tabbable using heuristics inspired by https://github.com/focus-trap/tabbable */
+function isTabbable(el: HTMLElement) {
+  const tag = el.tagName.toLowerCase();
+
+  const tabindex = Number(el.getAttribute('tabindex'));
+  const hasTabindex = el.hasAttribute('tabindex');
+
+  // elements with a tabindex attribute that is either NaN or <= -1 are not tabbable
+  if (hasTabindex && (isNaN(tabindex) || tabindex <= -1)) {
+    return false;
+  }
+
+  // Elements with a disabled attribute are not tabbable
+  if (el.hasAttribute('disabled')) {
+    return false;
+  }
+
+  // If any parents have "inert", we aren't "tabbable"
+  if (el.closest('[inert]')) {
+    return false;
+  }
+
+  // Radios without a checked attribute are not tabbable
+  if (tag === 'input' && el.getAttribute('type') === 'radio' && !el.hasAttribute('checked')) {
+    return false;
+  }
+
+  if (!isVisible(el)) {
+    return false;
+  }
+
+  // Audio and video elements with the controls attribute are tabbable
+  if ((tag === 'audio' || tag === 'video') && el.hasAttribute('controls')) {
+    return true;
+  }
+
+  // Elements with a tabindex other than -1 are tabbable
+  if (el.hasAttribute('tabindex')) {
+    return true;
+  }
+
+  // Elements with a contenteditable attribute are tabbable
+  if (el.hasAttribute('contenteditable') && el.getAttribute('contenteditable') !== 'false') {
+    return true;
+  }
+
+  // At this point, the following elements are considered tabbable
+  const isNativelyTabbable = [
+    'button',
+    'input',
+    'select',
+    'textarea',
+    'a',
+    'audio',
+    'video',
+    'summary',
+    'iframe'
+  ].includes(tag);
+
+  if (isNativelyTabbable) {
+    return true;
+  }
+
+  // We save the overflow checks for last, because they're the most expensive
+  return isOverflowingAndTabbable(el);
+}
+
+/**
+ * Returns the first and last bounding elements that are tabbable. This is more performant than checking every single
+ * element because it short-circuits after finding the first and last ones.
+ */
+export function getTabbableBoundary(root: HTMLElement | ShadowRoot) {
+  const tabbableElements = getTabbableElements(root);
+
+  // Find the first and last tabbable elements
+  const start = tabbableElements[0] ?? null;
+  const end = tabbableElements[tabbableElements.length - 1] ?? null;
+
+  return { start, end };
+}
+
+/**
+ * This looks funky. Basically a slot's children will always be picked up *if* they're within the `root` element.
+ * However, there is an edge case when, if the `root` is wrapped by another shadow DOM, it won't grab the children.
+ * This fixes that fun edge case.
+ */
+function getSlottedChildrenOutsideRootElement(slotElement: HTMLSlotElement, root: HTMLElement | ShadowRoot) {
+  return (slotElement.getRootNode({ composed: true }) as ShadowRoot | null)?.host !== root;
+}
+
+export function getTabbableElements(root: HTMLElement | ShadowRoot) {
+  const walkedEls = new WeakMap();
+  const tabbableElements: HTMLElement[] = [];
+
+  function walk(el: HTMLElement | ShadowRoot) {
+    if (el instanceof Element) {
+      // if the element has "inert" we can just no-op it.
+      if (el.hasAttribute('inert') || el.closest('[inert]')) {
+        return;
+      }
+
+      if (walkedEls.has(el)) {
+        return;
+      }
+      walkedEls.set(el, true);
+
+      if (!tabbableElements.includes(el) && isTabbable(el)) {
+        tabbableElements.push(el);
+      }
+
+      if (el instanceof HTMLSlotElement && getSlottedChildrenOutsideRootElement(el, root)) {
+        el.assignedElements({ flatten: true }).forEach((assignedEl: HTMLElement) => {
+          walk(assignedEl);
+        });
+      }
+
+      if (el.shadowRoot !== null && el.shadowRoot.mode === 'open') {
+        walk(el.shadowRoot);
+      }
+    }
+
+    for (const e of el.children) {
+      walk(e as HTMLElement);
+    }
+  }
+
+  // Collect all elements including the root
+  walk(root);
+
+  // Is this worth having? Most sorts will always add increased overhead. And positive tabindexes shouldn't really be used.
+  // So is it worth being right? Or fast?
+  return tabbableElements.sort((a, b) => {
+    // Make sure we sort by tabindex.
+    const aTabindex = Number(a.getAttribute('tabindex')) || 0;
+    const bTabindex = Number(b.getAttribute('tabindex')) || 0;
+    return bTabindex - aTabindex;
+  });
+}

package/src/internal/theme.ts

@@ -0,0 +1,54 @@
+import type {ReactiveController, ReactiveControllerHost} from "lit";
+
+/**
+ * ThemeController is a reactive controller that listens for theme changes
+ * and updates the theme property on the host element.
+ *
+ * if you want to reflect the theme attribute to the host element, you can use
+ * the following code:
+ *
+ * ```ts
+ * import { ThemeController } from "@zinc/internal/theme";
+ *
+ * export default class MyElement extends HTMLElement {
+ *    @property({ reflect: true }) t = '';
+ *    ...
+ *  ```
+ */
+export class ThemeController implements ReactiveController {
+  host: ReactiveControllerHost & HTMLElement;
+
+  t: string = '';
+
+  constructor(host: ReactiveControllerHost & HTMLElement) {
+    this.host = host;
+    this.host.addController(this);
+  }
+
+  hostConnected() {
+    this.getDefaultTheme();
+    this.host.setAttribute('t', this.t);
+    window.addEventListener('theme-change', this.handleThemeEventUpdate.bind(this));
+  }
+
+  hostDisconnected() {
+    window.removeEventListener('theme-change', this.handleThemeEventUpdate.bind(this));
+  }
+
+  handleThemeEventUpdate = (e: CustomEvent & { theme: string }) => {
+    if (e && e.detail) {
+      this.t = e.detail as string;
+      this.host.setAttribute('t', this.t);
+      return;
+    }
+
+    this.getDefaultTheme();
+  }
+
+  getDefaultTheme = () => {
+    this.t = document.documentElement.getAttribute('t')
+      || window.document.documentElement.getAttribute('t')
+      || window.document.body.getAttribute('t')
+      || 'light';
+  }
+}

package/src/internal/watch.ts

@@ -0,0 +1,63 @@
+import type {LitElement} from "lit";
+
+type UpdateHandler = (prev?: unknown, next?: unknown) => void;
+
+type NonUndefined<T> = T extends undefined ? never : T;
+
+type UpdateHandlerFunctionKeys<T extends object> = {
+  [K in keyof T]-?: NonUndefined<T[K]> extends UpdateHandler ? K : never;
+}[keyof T];
+
+interface WatchOptions {
+  /**
+   * If true, will only start watching after the initial update/render
+   */
+  waitUntilFirstUpdate?: boolean;
+}
+
+/**
+ * Runs when observed properties change, e.g. @property or @state, but before the component updates. To wait for an
+ * update to complete after a change occurs, use `await this.updateComplete` in the handler. To start watching after the
+ * initial update, set `{ waitUntilFirstUpdate: true }` or `this.hasUpdated` in the handler.
+ *
+ * Usage:
+ *
+ * ```ts
+ * @watch('propName')
+ * handlePropChanges(oldValue, newValue) {...}
+ * ```
+ *
+ * @param propertyName
+ * @param options
+ */
+export function watch(propertyName: string | string[], options?: WatchOptions) {
+  const resolvedOptions: Required<WatchOptions> = {
+    waitUntilFirstUpdate: false,
+    ...options,
+  };
+
+  return <ElemClass extends LitElement>(proto: ElemClass, decoratedFnName: UpdateHandlerFunctionKeys<ElemClass>) => {
+    // @ts-expect-error update is a protected property
+    const {update} = proto;
+    const watchedProperties = Array.isArray(propertyName) ? propertyName : [propertyName];
+
+    // @ts-expect-error update is a protected property
+    proto.update = function (this: ElemClass, changedProps: Map<keyof ElemClass, ElemClass[keyof ElemClass]>) {
+      watchedProperties.forEach(property => {
+        const key = property as keyof ElemClass;
+        if (changedProps.has(key)) {
+          const oldValue = changedProps.get(key);
+          const newValue = this[key];
+
+          if (oldValue !== newValue) {
+            if (!resolvedOptions.waitUntilFirstUpdate || this.hasUpdated) {
+              (this[decoratedFnName] as unknown as UpdateHandler)(oldValue, newValue)
+            }
+          }
+        }
+      });
+
+      update.call(this, changedProps);
+    }
+  }
+}

package/src/internal/zinc-element.ts

@@ -0,0 +1,113 @@
+import {LitElement} from "lit";
+import {property} from "lit/decorators.js";
+import {ThemeController} from "./theme";
+import type {
+  EventTypeDoesNotRequireDetail,
+  EventTypeRequiresDetail,
+  EventTypesWithoutRequiredDetail,
+  EventTypesWithRequiredDetail,
+  GetCustomEventType,
+  ValidEventTypeMap,
+  ZincEventInit
+} from "./event";
+
+export default class ZincElement extends LitElement {
+  @property() dir: string; // LTR or RTL direction
+  @property() lang: string; // Language
+  @property({reflect: true}) t: string; // Theme (light or dark)
+
+  static define(name: string, elementConstructor = this, options: ElementDefinitionOptions = {}) {
+    const currentRegisteredConstructor = customElements.get(name) as
+      | CustomElementConstructor
+      | typeof ZincElement;
+
+    if (!currentRegisteredConstructor) {
+      customElements.define(name, class extends elementConstructor {
+      } as unknown as CustomElementConstructor, options);
+      return;
+    }
+
+    let newVersion = ' (unknown version)';
+    let existingVersion = newVersion;
+
+    if ('version' in elementConstructor && elementConstructor.version && typeof elementConstructor.version === 'string') {
+      newVersion = ` v${elementConstructor.version}`;
+    }
+
+    if ('version' in currentRegisteredConstructor && currentRegisteredConstructor.version && typeof currentRegisteredConstructor.version === 'string') {
+      existingVersion = ` v${currentRegisteredConstructor.version}`;
+    }
+
+    // need to make sure we're not working with null or empty strings before doing version comparison
+    if (newVersion && existingVersion && newVersion === existingVersion) {
+      // if version match, we don't need to warn anyone, carry on.
+      return;
+    }
+
+    console.warn(
+      `Attempted to register <${name}>${newVersion} but it is already registered as <${name}>${existingVersion}.`
+    )
+  }
+
+  static dependencies: Record<string, typeof ZincElement> = {};
+
+  constructor() {
+    super();
+
+    // All Zinc components should have a theme controller  /
+    /* eslint-disable no-new */
+    new ThemeController(this);
+
+    // Make sure we have access to all dependencies and they are defined
+    Object.entries((this.constructor as typeof ZincElement).dependencies).forEach(([name, component]) => {
+      (this.constructor as typeof ZincElement).define(name, component);
+    });
+  }
+
+  emit<T extends string & keyof EventTypesWithoutRequiredDetail>(name: EventTypeDoesNotRequireDetail<T>, options?: ZincEventInit<T> | undefined): GetCustomEventType<T>;
+  emit<T extends string & keyof EventTypesWithRequiredDetail>(name: EventTypeRequiresDetail<T>, options?: ZincEventInit<T>): GetCustomEventType<T>;
+  emit<T extends string & keyof ValidEventTypeMap>(name: T, options?: ZincEventInit<T>): GetCustomEventType<T> {
+    const event = new CustomEvent(name, {
+      bubbles: true,
+      cancelable: true,
+      composed: true,
+      detail: {
+        element: this,
+      },
+      ...options
+    });
+
+    this.dispatchEvent(event);
+
+    return event as GetCustomEventType<T>;
+  }
+}
+
+export interface ZincFormControl extends ZincElement {
+  // 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;
+}

package/src/translations/en.ts

@@ -0,0 +1,30 @@
+import {registerTranslation, type Translation} from "../utilities/localize.js";
+
+const translation: Translation = {
+  $code: 'en',
+  $name: 'English',
+  $dir: 'ltr',
+
+  onChange: 'onChange',
+  showPassword: 'Show password',
+  hidePassword: 'Hide password',
+  clearEntry: 'Clear entry',
+  numOptionsSelected: num => {
+    if (num === 0) return 'No options selected';
+    if (num === 1) return '1 option selected';
+    return `${num} options selected`;
+  },
+  fileButtonText: 'Choose a file',
+  fileButtonTextMultiple: 'Choose files',
+  folderButtonText: 'Choose a folder',
+  fileDragDrop: 'Drop files here to upload',
+  folderDragDrop: 'Drop folder here to upload',
+  numFilesSelected: (num: number) => {
+    if (num === 0) return 'No files selected';
+    if (num === 1) return '1 file selected';
+    return `${num} files selected`;
+  }
+}
+
+registerTranslation(translation);
+export default translation;