@uistate/aliases 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ajdin Imsirovic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,348 @@
+# @uistate/aliases
+
+**Ergonomic DOM aliases that stay close to the metal.**
+
+Thin, transparent wrappers for verbose DOM APIs. Zero abstraction penalty. You're still writing vanilla JavaScript—just faster.
+
+## Philosophy
+
+Every function is a one-line wrapper with 1:1 mapping to platform primitives. No magic, no lock-in, no framework churn. Just ergonomics.
+
+## Installation
+
+```bash
+npm install @uistate/aliases
+```
+
+## Usage
+
+```javascript
+// Import what you need
+import { $, mk, on, find } from '@uistate/aliases';
+
+// Or import everything
+import * as dom from '@uistate/aliases';
+```
+
+## Full Example
+
+```javascript
+import { $, mk, on, find } from '@uistate/aliases';
+
+const list = $('list');
+const add = $('add');
+let counter = 1;
+
+on(add, 'click', () => {
+  const li = mk('li');
+  li.innerHTML = `Item ${counter++} <button class="remove">Remove</button>`;
+  list.append(li);
+});
+
+on(list, 'click', (e) => {
+  const btn = find(e.target, 'button.remove');
+  if (!btn) return;
+  const li = find(btn, 'li');
+  alert(`Removing ${li.textContent.replace(' Remove', '')}`);
+  li.remove();
+});
+```
+
+**Character Count Comparison:**
+- Original: 449 characters
+- Aliased: 329 characters  
+- **Savings: ~27% reduction**
+
+## API Reference
+
+### Selection
+
+#### `$(id)`
+Get element by ID.
+```javascript
+const el = $('myId');
+// document.getElementById('myId')
+```
+
+#### `qs(selector, context?)`
+Query selector (single element).
+```javascript
+const btn = qs('.button');
+const nested = qs('.child', parent);
+// document.querySelector('.button')
+```
+
+#### `qsa(selector, context?)`
+Query selector all.
+```javascript
+const items = qsa('.item');
+// document.querySelectorAll('.item')
+```
+
+#### `find(element, selector)`
+Find closest ancestor matching selector.
+```javascript
+const li = find(button, 'li');
+// button.closest('li')
+```
+
+### Creation
+
+#### `mk(tag)`
+Create element.
+```javascript
+const div = mk('div');
+// document.createElement('div')
+```
+
+#### `txt(content)`
+Create text node.
+```javascript
+const text = txt('Hello');
+// document.createTextNode('Hello')
+```
+
+#### `frag()`
+Create document fragment.
+```javascript
+const fragment = frag();
+// document.createDocumentFragment()
+```
+
+### Events
+
+#### `on(element, event, callback, options?)`
+Add event listener.
+```javascript
+on(button, 'click', handleClick);
+on(input, 'change', handleChange, { passive: true });
+// element.addEventListener(event, callback, options)
+```
+
+#### `off(element, event, callback, options?)`
+Remove event listener.
+```javascript
+off(button, 'click', handleClick);
+// element.removeEventListener(event, callback, options)
+```
+
+#### `once(element, event, callback)`
+Add one-time event listener.
+```javascript
+once(button, 'click', handleClick);
+// element.addEventListener(event, callback, { once: true })
+```
+
+#### `emit(element, event, detail?)`
+Dispatch custom event.
+```javascript
+emit(element, 'custom', { data: 'value' });
+// element.dispatchEvent(new CustomEvent(event, { detail }))
+```
+
+### Manipulation
+
+#### `append(parent, ...children)`
+Append children to parent.
+```javascript
+append(list, item1, item2);
+// parent.append(...children)
+```
+
+#### `prepend(parent, ...children)`
+Prepend children to parent.
+```javascript
+prepend(list, item);
+// parent.prepend(...children)
+```
+
+#### `before(reference, ...nodes)`
+Insert nodes before reference.
+```javascript
+before(item, newItem);
+// reference.before(...nodes)
+```
+
+#### `after(reference, ...nodes)`
+Insert nodes after reference.
+```javascript
+after(item, newItem);
+// reference.after(...nodes)
+```
+
+#### `replace(old, ...nodes)`
+Replace element with nodes.
+```javascript
+replace(oldItem, newItem);
+// old.replaceWith(...nodes)
+```
+
+#### `remove(element)`
+Remove element from DOM.
+```javascript
+remove(item);
+// element.remove()
+```
+
+### Attributes
+
+#### `attr(element, name, value?)`
+Get/set/remove attribute.
+```javascript
+const href = attr(link, 'href');           // Get
+attr(link, 'href', '/path');               // Set
+attr(link, 'disabled', null);              // Remove
+```
+
+#### `data(element, key, value?)`
+Get/set dataset attribute.
+```javascript
+const id = data(element, 'id');            // Get
+data(element, 'id', '123');                // Set
+```
+
+### Classes
+
+#### `cls(element, ...classes)`
+Add classes.
+```javascript
+cls(element, 'active', 'highlight');
+// element.classList.add(...classes)
+```
+
+#### `uncls(element, ...classes)`
+Remove classes.
+```javascript
+uncls(element, 'active', 'highlight');
+// element.classList.remove(...classes)
+```
+
+#### `toggle(element, class, force?)`
+Toggle class.
+```javascript
+toggle(element, 'active');
+toggle(element, 'visible', true);
+// element.classList.toggle(class, force)
+```
+
+#### `has(element, class)`
+Check if element has class.
+```javascript
+if (has(element, 'active')) { }
+// element.classList.contains(class)
+```
+
+### Styles
+
+#### `css(element, property, value?)`
+Get/set styles.
+```javascript
+const color = css(element, 'color');                    // Get
+css(element, 'color', 'red');                           // Set
+css(element, { color: 'red', fontSize: '16px' });       // Set multiple
+```
+
+### Traversal
+
+#### `parent(element)`
+Get parent element.
+```javascript
+const p = parent(element);
+// element.parentElement
+```
+
+#### `children(element)`
+Get child elements as array.
+```javascript
+const kids = children(element);
+// Array.from(element.children)
+```
+
+#### `siblings(element)`
+Get sibling elements.
+```javascript
+const sibs = siblings(element);
+```
+
+#### `next(element)`
+Get next sibling element.
+```javascript
+const nextEl = next(element);
+// element.nextElementSibling
+```
+
+#### `prev(element)`
+Get previous sibling element.
+```javascript
+const prevEl = prev(element);
+// element.previousElementSibling
+```
+
+### Utilities
+
+#### `ready(callback)`
+Execute callback when DOM is ready.
+```javascript
+ready(() => {
+  console.log('DOM ready');
+});
+```
+
+#### `clone(element, deep?)`
+Clone element.
+```javascript
+const copy = clone(element);
+const deepCopy = clone(element, true);
+// element.cloneNode(deep)
+```
+
+#### `empty(element)`
+Remove all children.
+```javascript
+empty(element);
+// element.innerHTML = ''
+```
+
+## Bundle Size
+
+~2-3kb minified + gzipped. Tree-shakeable—import only what you use.
+
+## TypeScript
+
+Full TypeScript definitions included.
+
+```typescript
+import { $, mk, on } from '@uistate/aliases';
+
+const button = $('myButton'); // HTMLElement | null
+const div = mk('div');        // HTMLDivElement
+```
+
+## Why @uistate/aliases?
+
+### ✅ What We Alias
+- Verbose global functions: `document.getElementById` → `$`
+- Repetitive API calls: `document.createElement` → `mk`
+- Long method names: `addEventListener` → `on`
+
+### ❌ What We Don't Alias
+- Property access: `e.target`, `el.textContent` (stay vanilla)
+- Native methods: `remove()`, `replace()` (unless they're verbose)
+- Standard operations: String/Array methods (use platform APIs)
+
+### Philosophy
+Close to the metal, ergonomic by design. These aliases are:
+- **Transparent**: 1:1 mapping to platform APIs
+- **Educational**: Learn vanilla JS through usage
+- **Optional**: No lock-in, adopt incrementally
+- **Timeless**: Won't break when frameworks change
+
+## Ecosystem
+
+Part of the **uistate** family:
+- `@uistate/core` - State management
+- `@uistate/aliases` - DOM ergonomics (this package)
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,93 @@
+// ============================================
+// @uistate/aliases - TypeScript Definitions
+// ============================================
+
+// --- SELECTION ---
+export function $(id: string): HTMLElement | null;
+export function qs<E extends Element = Element>(sel: string, ctx?: Document | Element): E | null;
+export function qsa<E extends Element = Element>(sel: string, ctx?: Document | Element): NodeListOf<E>;
+export function find<E extends Element = Element>(el: Element, sel: string): E | null;
+
+// --- CREATION ---
+export function mk<K extends keyof HTMLElementTagNameMap>(tag: K): HTMLElementTagNameMap[K];
+export function mk(tag: string): HTMLElement;
+export function txt(content: string): Text;
+export function frag(): DocumentFragment;
+
+// --- EVENTS ---
+export function on<K extends keyof HTMLElementEventMap>(
+  el: Element | Document | Window,
+  ev: K,
+  cb: (this: Element, ev: HTMLElementEventMap[K]) => any,
+  opts?: boolean | AddEventListenerOptions
+): void;
+export function on(
+  el: Element | Document | Window,
+  ev: string,
+  cb: EventListenerOrEventListenerObject,
+  opts?: boolean | AddEventListenerOptions
+): void;
+
+export function off<K extends keyof HTMLElementEventMap>(
+  el: Element | Document | Window,
+  ev: K,
+  cb: (this: Element, ev: HTMLElementEventMap[K]) => any,
+  opts?: boolean | EventListenerOptions
+): void;
+export function off(
+  el: Element | Document | Window,
+  ev: string,
+  cb: EventListenerOrEventListenerObject,
+  opts?: boolean | EventListenerOptions
+): void;
+
+export function once<K extends keyof HTMLElementEventMap>(
+  el: Element | Document | Window,
+  ev: K,
+  cb: (this: Element, ev: HTMLElementEventMap[K]) => any
+): void;
+export function once(
+  el: Element | Document | Window,
+  ev: string,
+  cb: EventListenerOrEventListenerObject
+): void;
+
+export function emit(el: Element, ev: string, detail?: any): void;
+
+// --- MANIPULATION ---
+export function append(parent: Element, ...children: (Node | string)[]): void;
+export function prepend(parent: Element, ...children: (Node | string)[]): void;
+export function before(ref: Element, ...nodes: (Node | string)[]): void;
+export function after(ref: Element, ...nodes: (Node | string)[]): void;
+export function replace(old: Element, ...nodes: (Node | string)[]): void;
+export function remove(el: Element): void;
+
+// --- ATTRIBUTES ---
+export function attr(el: Element, name: string): string | null;
+export function attr(el: Element, name: string, value: string | null): void;
+
+export function data(el: HTMLElement, key: string): string | undefined;
+export function data(el: HTMLElement, key: string, value: string): void;
+
+// --- CLASSES ---
+export function cls(el: Element, ...classes: string[]): void;
+export function uncls(el: Element, ...classes: string[]): void;
+export function toggle(el: Element, cls: string, force?: boolean): boolean;
+export function has(el: Element, cls: string): boolean;
+
+// --- STYLES ---
+export function css(el: HTMLElement, prop: string): string;
+export function css(el: HTMLElement, prop: string, value: string): void;
+export function css(el: HTMLElement, prop: Partial<CSSStyleDeclaration>): void;
+
+// --- TRAVERSAL ---
+export function parent(el: Element): HTMLElement | null;
+export function children(el: Element): Element[];
+export function siblings(el: Element): Element[];
+export function next(el: Element): Element | null;
+export function prev(el: Element): Element | null;
+
+// --- UTILITIES ---
+export function ready(cb: () => void): void;
+export function clone<T extends Node>(el: T, deep?: boolean): T;
+export function empty(el: Element): void;

package/index.js

@@ -0,0 +1,73 @@
+// ============================================
+// @uistate/aliases - Ergonomic DOM Aliases
+// ============================================
+
+// --- SELECTION ---
+export const $ = (id) => document.getElementById(id);
+export const qs = (sel, ctx = document) => ctx.querySelector(sel);
+export const qsa = (sel, ctx = document) => ctx.querySelectorAll(sel);
+export const find = (el, sel) => el.closest(sel);
+
+// --- CREATION ---
+export const mk = (tag) => document.createElement(tag);
+export const txt = (content) => document.createTextNode(content);
+export const frag = () => document.createDocumentFragment();
+
+// --- EVENTS ---
+export const on = (el, ev, cb, opts) => el.addEventListener(ev, cb, opts);
+export const off = (el, ev, cb, opts) => el.removeEventListener(ev, cb, opts);
+export const once = (el, ev, cb) => el.addEventListener(ev, cb, { once: true });
+export const emit = (el, ev, detail) => el.dispatchEvent(new CustomEvent(ev, { detail }));
+
+// --- MANIPULATION ---
+export const append = (parent, ...children) => parent.append(...children);
+export const prepend = (parent, ...children) => parent.prepend(...children);
+export const before = (ref, ...nodes) => ref.before(...nodes);
+export const after = (ref, ...nodes) => ref.after(...nodes);
+export const replace = (old, ...nodes) => old.replaceWith(...nodes);
+export const remove = (el) => el.remove();
+
+// --- ATTRIBUTES ---
+export const attr = (el, name, value) => {
+  if (value === undefined) return el.getAttribute(name);
+  if (value === null) el.removeAttribute(name);
+  else el.setAttribute(name, value);
+};
+
+export const data = (el, key, value) => {
+  if (value === undefined) return el.dataset[key];
+  el.dataset[key] = value;
+};
+
+// --- CLASSES ---
+export const cls = (el, ...classes) => el.classList.add(...classes);
+export const uncls = (el, ...classes) => el.classList.remove(...classes);
+export const toggle = (el, cls, force) => el.classList.toggle(cls, force);
+export const has = (el, cls) => el.classList.contains(cls);
+
+// --- STYLES ---
+export const css = (el, prop, value) => {
+  if (typeof prop === 'object') {
+    Object.assign(el.style, prop);
+  } else if (value === undefined) {
+    return getComputedStyle(el)[prop];
+  } else {
+    el.style[prop] = value;
+  }
+};
+
+// --- TRAVERSAL ---
+export const parent = (el) => el.parentElement;
+export const children = (el) => Array.from(el.children);
+export const siblings = (el) => children(parent(el)).filter(child => child !== el);
+export const next = (el) => el.nextElementSibling;
+export const prev = (el) => el.previousElementSibling;
+
+// --- UTILITIES ---
+export const ready = (cb) => {
+  if (document.readyState !== 'loading') cb();
+  else document.addEventListener('DOMContentLoaded', cb);
+};
+
+export const clone = (el, deep = true) => el.cloneNode(deep);
+export const empty = (el) => { el.innerHTML = ''; };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@uistate/aliases",
+  "version": "1.0.0",
+  "description": "Ergonomic single-character and short-name DOM aliases for vanilla JavaScript - thin wrappers that stay close to the metal with zero abstraction penalty",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "type": "module",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "dom",
+    "dom-aliases",
+    "vanilla-js",
+    "ergonomic",
+    "lightweight",
+    "zero-dependency",
+    "framework-free",
+    "dom-utilities",
+    "shorthand",
+    "close-to-metal",
+    "uistate"
+  ],
+  "author": "Ajdin Imsirovic",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ImsirovicAjdin/uistate-aliases"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "types": "./index.d.ts"
+    }
+  }
+}