@duskmoon-dev/el-base

Core utilities and base classes for DuskMoon custom elements.

Installation

bun add @duskmoon-dev/el-base

Usage

BaseElement

The BaseElement class provides a foundation for creating custom elements with:

• Shadow DOM setup with adoptedStyleSheets
• Reactive properties with attribute reflection
• Batched updates using microtask queue
• Style injection utilities
• Event emission helpers

import { BaseElement, css } from '@duskmoon-dev/el-base';

const styles = css`
  :host {
    display: block;
  }
  .greeting {
    color: var(--dm-primary);
  }
`;

class MyGreeting extends BaseElement {
  static properties = {
    name: { type: String, reflect: true, default: 'World' },
  };

  declare name: string;

  constructor() {
    super();
    this.attachStyles(styles);
  }

  render() {
    return `<div class="greeting">Hello, ${this.name}!</div>`;
  }
}

customElements.define('my-greeting', MyGreeting);

CSS Utilities

css Template Tag

Creates a CSSStyleSheet from a template literal:

import { css } from '@duskmoon-dev/el-base';

const styles = css`
  :host {
    display: inline-flex;
  }
  button {
    padding: 0.5rem 1rem;
  }
`;

combineStyles

Combines multiple stylesheets:

import { combineStyles } from '@duskmoon-dev/el-base';

const combinedStyles = combineStyles(baseStyles, themeStyles, componentStyles);

cssVars

Creates CSS custom property declarations:

import { cssVars } from '@duskmoon-dev/el-base';

const vars = cssVars({
  'dm-primary': '#3b82f6',
  'dm-spacing': '1rem',
});
// Returns: '--dm-primary: #3b82f6; --dm-spacing: 1rem;'

Default Theme

The package includes default CSS custom properties for theming. Import the theme stylesheet:

import { defaultTheme, resetStyles } from '@duskmoon-dev/el-base';

// Apply to shadow root
this.shadowRoot.adoptedStyleSheets = [resetStyles, defaultTheme, componentStyles];

Color Tokens

Gray Scale

Typography

Spacing

Border Radius

Shadows

Transitions

API

BaseElement

Property Definitions

Define reactive properties with automatic attribute reflection:

static properties = {
  // Simple string property
  label: { type: String },

  // Boolean with attribute reflection
  disabled: { type: Boolean, reflect: true },

  // Number with default value
  count: { type: Number, default: 0 },

  // Custom attribute name (kebab-case)
  maxItems: { type: Number, attribute: 'max-items' },

  // Object/Array (not reflected to attributes)
  data: { type: Object },
  items: { type: Array, default: [] },
};

Property definition options:

Lifecycle

class MyElement extends BaseElement {
  // Called when element is added to DOM
  connectedCallback() {
    super.connectedCallback();
    // Setup code
  }

  // Called when element is removed from DOM
  disconnectedCallback() {
    super.disconnectedCallback();
    // Cleanup code
  }

  // Called when properties change (batched)
  update() {
    // Re-render or update DOM
    this.shadowRoot.innerHTML = this.render();
  }

  // Return HTML string for Shadow DOM content
  render() {
    return `<div>Content</div>`;
  }
}

TypeScript Types

import type {
  PropertyDefinition,
  PropertyDefinitions,
  Size,
  Variant,
  ValidationState,
  BaseElementProps,
  SizableProps,
  VariantProps,
  FormElementProps,
  ValidatableProps,
  ValueChangeEventDetail,
} from '@duskmoon-dev/el-base';

Creating Custom Elements

Full example of a custom element:

import { BaseElement, css, defaultTheme, resetStyles } from '@duskmoon-dev/el-base';

const styles = css`
  :host {
    display: inline-block;
  }

  .counter {
    display: flex;
    align-items: center;
    gap: var(--dm-spacing-sm);
  }

  button {
    padding: var(--dm-spacing-xs) var(--dm-spacing-sm);
    border-radius: var(--dm-radius-sm);
    background: var(--dm-primary);
    color: white;
    border: none;
    cursor: pointer;
    transition: opacity var(--dm-transition-fast);
  }

  button:hover {
    opacity: 0.9;
  }

  .value {
    min-width: 2rem;
    text-align: center;
    font-weight: var(--dm-font-weight-medium);
  }
`;

export class MyCounter extends BaseElement {
  static properties = {
    value: { type: Number, reflect: true, default: 0 },
    min: { type: Number, default: 0 },
    max: { type: Number, default: 100 },
  };

  declare value: number;
  declare min: number;
  declare max: number;

  constructor() {
    super();
    this.attachStyles(resetStyles, defaultTheme, styles);
  }

  connectedCallback() {
    super.connectedCallback();
    this.shadowRoot?.addEventListener('click', this.handleClick.bind(this));
  }

  private handleClick(e: Event) {
    const target = e.target as HTMLElement;
    if (target.matches('[data-action="decrement"]')) {
      this.decrement();
    } else if (target.matches('[data-action="increment"]')) {
      this.increment();
    }
  }

  private decrement() {
    if (this.value > this.min) {
      this.value--;
      this.emit('change', { value: this.value });
    }
  }

  private increment() {
    if (this.value < this.max) {
      this.value++;
      this.emit('change', { value: this.value });
    }
  }

  render() {
    return `
      <div class="counter">
        <button data-action="decrement" ${this.value <= this.min ? 'disabled' : ''}>-</button>
        <span class="value">${this.value}</span>
        <button data-action="increment" ${this.value >= this.max ? 'disabled' : ''}>+</button>
      </div>
    `;
  }
}

export function register() {
  if (!customElements.get('my-counter')) {
    customElements.define('my-counter', MyCounter);
  }
}

License

MIT