@duskmoon-dev/el-base 0.6.0

package/README.md

@@ -0,0 +1,368 @@
+# @duskmoon-dev/el-base
+
+Core utilities and base classes for DuskMoon custom elements.
+
+## Installation
+
+```bash
+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
+
+```typescript
+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:
+
+```typescript
+import { css } from '@duskmoon-dev/el-base';
+
+const styles = css`
+  :host {
+    display: inline-flex;
+  }
+  button {
+    padding: 0.5rem 1rem;
+  }
+`;
+```
+
+#### `combineStyles`
+
+Combines multiple stylesheets:
+
+```typescript
+import { combineStyles } from '@duskmoon-dev/el-base';
+
+const combinedStyles = combineStyles(baseStyles, themeStyles, componentStyles);
+```
+
+#### `cssVars`
+
+Creates CSS custom property declarations:
+
+```typescript
+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:
+
+```typescript
+import { defaultTheme, resetStyles } from '@duskmoon-dev/el-base';
+
+// Apply to shadow root
+this.shadowRoot.adoptedStyleSheets = [resetStyles, defaultTheme, componentStyles];
+```
+
+#### Color Tokens
+
+| Variable         | Description            |
+| ---------------- | ---------------------- |
+| `--dm-primary`   | Primary brand color    |
+| `--dm-secondary` | Secondary color        |
+| `--dm-success`   | Success/positive color |
+| `--dm-warning`   | Warning color          |
+| `--dm-error`     | Error/danger color     |
+| `--dm-info`      | Information color      |
+
+#### Gray Scale
+
+| Variable                                | Description   |
+| --------------------------------------- | ------------- |
+| `--dm-gray-50`                          | Lightest gray |
+| `--dm-gray-100` through `--dm-gray-800` | Gray scale    |
+| `--dm-gray-900`                         | Darkest gray  |
+
+#### Typography
+
+| Variable                                                                                                   | Description      |
+| ---------------------------------------------------------------------------------------------------------- | ---------------- |
+| `--dm-font-family`                                                                                         | Base font family |
+| `--dm-font-size-xs` through `--dm-font-size-2xl`                                                           | Font sizes       |
+| `--dm-font-weight-normal`, `--dm-font-weight-medium`, `--dm-font-weight-semibold`, `--dm-font-weight-bold` | Font weights     |
+| `--dm-line-height-tight`, `--dm-line-height-normal`, `--dm-line-height-relaxed`                            | Line heights     |
+
+#### Spacing
+
+| Variable          | Description           |
+| ----------------- | --------------------- |
+| `--dm-spacing-xs` | Extra small (0.25rem) |
+| `--dm-spacing-sm` | Small (0.5rem)        |
+| `--dm-spacing-md` | Medium (1rem)         |
+| `--dm-spacing-lg` | Large (1.5rem)        |
+| `--dm-spacing-xl` | Extra large (2rem)    |
+
+#### Border Radius
+
+| Variable           | Description      |
+| ------------------ | ---------------- |
+| `--dm-radius-sm`   | Small radius     |
+| `--dm-radius-md`   | Medium radius    |
+| `--dm-radius-lg`   | Large radius     |
+| `--dm-radius-full` | Full/pill radius |
+
+#### Shadows
+
+| Variable         | Description   |
+| ---------------- | ------------- |
+| `--dm-shadow-sm` | Small shadow  |
+| `--dm-shadow-md` | Medium shadow |
+| `--dm-shadow-lg` | Large shadow  |
+
+#### Transitions
+
+| Variable                 | Description               |
+| ------------------------ | ------------------------- |
+| `--dm-transition-fast`   | Fast transition (150ms)   |
+| `--dm-transition-normal` | Normal transition (200ms) |
+| `--dm-transition-slow`   | Slow transition (300ms)   |
+
+## API
+
+### BaseElement
+
+| Method                 | Description                                      |
+| ---------------------- | ------------------------------------------------ |
+| `attachStyles(styles)` | Attach one or more stylesheets to Shadow DOM     |
+| `render()`             | Override to return HTML content string           |
+| `update()`             | Called when reactive properties change (batched) |
+| `emit(name, detail?)`  | Emit a CustomEvent from the element              |
+| `query(selector)`      | Query single element in Shadow DOM               |
+| `queryAll(selector)`   | Query all matching elements in Shadow DOM        |
+
+### Property Definitions
+
+Define reactive properties with automatic attribute reflection:
+
+```typescript
+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:
+
+| Option      | Type       | Description                                                        |
+| ----------- | ---------- | ------------------------------------------------------------------ |
+| `type`      | `Function` | Type constructor: `String`, `Number`, `Boolean`, `Object`, `Array` |
+| `reflect`   | `boolean`  | Whether to reflect property to attribute                           |
+| `attribute` | `string`   | Custom attribute name (defaults to lowercase property name)        |
+| `default`   | `any`      | Default value for the property                                     |
+
+### Lifecycle
+
+```typescript
+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
+
+```typescript
+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:
+
+```typescript
+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