@xtia/jel 0.2.1 → 0.3.0

package/README.md

@@ -5,9 +5,12 @@ Jel is a thin layer over the DOM to simplify element structure creation, manipul
 
 See [demo/index.ts](https://github.com/tiadrop/jel-ts/blob/main/demo/index.ts) for example operation. Compare with [resulting page](https://aleta.codes/jel-ts-demo/).
 
-## `$` basic use:
+## `$` Basic Use:
 
 `$.[tagname](details)` produces an element of `<tagname>`. `details` can be content of various types or a descriptor object.
+```
+$ npm i @xtia/jel
+```
 
 ```ts
 import { $ } from "@xtia/jel";
@@ -44,4 +47,85 @@ body.append([
     )
 ])
 
+```
+
+## `DOMContent`
+
+Content can be string, Text, HTMLElement, JelEntity or arbitrarily nested array of content. Typing as DOMContent where possible enables flexibility.
+
+```ts
+function showDialogue(content: DOMContent) => {
+    const element = $.div({
+        classes: "dialogue",
+        content: [
+            content,
+            $.div({
+                classes: "buttons",
+                // content: [...]
+            })
+        ]
+    });
+    // ...
+}
+
+interface Job {
+    name: string;
+    completionMessage: DOMContent;
+}
+
+showDialogue("Hello, world");
+showDialogue(["Hello, ", $.i("world")]);
+showDialogue([
+    $.h2(`${job.name} Complete`),
+    $.p(job.completionMessage),
+]);
+```
+
+## `ElementClassDescriptor`
+
+Element classes can be specified as string, `{ [className]: boolean }` and arbitrarily nested array thereof.
+
+```ts
+function renderFancyButton(
+    caption: DOMContent,
+    onClick: () => void,
+    classes: ElementClassDefinition = []
+) {
+    return $.button({
+        content: caption,
+        classes: ["fancy-button", classes],
+        // ...
+    });
+}
+
+function showDialogue(content: DOMContent, danger: boolean = false) {
+    const element = $.div({
+        // ...
+        classes: "dialogue",
+        content: [
+            content, 
+            renderFancyButton("OK", close, ["ok-button", { danger }]),
+        ]
+    });
+    // ...
+}
+```
+
+## Jel-Wrapped Elements
+
+Jel wraps its elements in an interface for common operations plus an `append()` method that accepts `DOMContent`.
+
+For other operations the element is accessible via `ent.element`:
+
+```ts
+const button = $.button();
+const rect = button.element.getBoundingClientRect();
+```
+
+## Shorthand
+
+If you need an element with just a class, id and/or content you can use `tag#id.classes` notation, ie `$("div#someId.class1.class2", content?)`.
+
+```ts
+showDialogue(["Hello ", $("span.green", "world")]);
 ```

package/index.d.ts

@@ -1,4 +1,4 @@
-export type ElementClassSpec = string | Record<string, boolean> | ElementClassSpec[];
+export type ElementClassDescriptor = string | Record<string, boolean> | ElementClassDescriptor[];
 export type DOMContent = number | null | string | Element | JelEntity<object, any> | Text | DOMContent[];
 export type DomEntity<T extends HTMLElement> = JelEntity<ElementAPI<T>, HTMLElementEventMap>;
 type JelConstructor<Spec, API, EventDataMap> = (spec?: Partial<Spec & CommonOptions<EventDataMap>>) => JelEntity<API, EventDataMap>;
@@ -11,17 +11,18 @@ type JelEntity<API, EventDataMap> = API & {
     on<E extends keyof EventDataMap>(eventId: E, handler: (this: JelEntity<API, EventDataMap>, data: EventDataMap[E]) => void): void;
     readonly [componentDataSymbol]: JelComponentData;
 };
-type Styles = Partial<{
-    [key in keyof CSSStyleDeclaration]: string | number;
-}> & Record<`--${string}`, string | number>;
+type StylesDescriptor = Partial<{
+    [key in keyof CSSStyleDeclaration]: CSSValue;
+}>;
 interface ElementDescriptor {
-    classes?: ElementClassSpec;
+    classes?: ElementClassDescriptor;
     content?: DOMContent;
     attribs?: Record<string, string | number | boolean>;
     on?: Partial<{
         [E in keyof HTMLElementEventMap]: (event: HTMLElementEventMap[E]) => void;
     }>;
-    style?: Styles;
+    style?: StylesDescriptor;
+    cssVariables?: Record<string, CSSValue>;
 }
 type DomHelper = ((<T extends keyof HTMLElementTagNameMap>(tagName: T, descriptor: ElementDescriptor) => DomEntity<HTMLElementTagNameMap[T]>) & (<T extends keyof HTMLElementTagNameMap>(selector: `${T}#${string}`, content?: DOMContent) => DomEntity<HTMLElementTagNameMap[T]>) & (<T extends keyof HTMLElementTagNameMap>(selector: `${T}.${string}`, content?: DOMContent) => DomEntity<HTMLElementTagNameMap[T]>) & (<T extends keyof HTMLElementTagNameMap>(selector: T, content?: DOMContent) => DomEntity<HTMLElementTagNameMap[T]>) & (<T extends HTMLElement>(element: T) => DomEntity<T>) & {
     [T in keyof HTMLElementTagNameMap]: (descriptor: ElementDescriptor) => DomEntity<HTMLElementTagNameMap[T]>;
@@ -31,6 +32,7 @@ type DomHelper = ((<T extends keyof HTMLElementTagNameMap>(tagName: T, descripto
 type JelComponentData = {
     dom: DOMContent;
 };
+type CSSValue = string | number;
 type ElementAPI<T extends HTMLElement> = {
     readonly element: T;
     content: DOMContent;
@@ -38,12 +40,16 @@ type ElementAPI<T extends HTMLElement> = {
     attribs: {
         [key: string]: string | null;
     };
-    style: CSSStyleDeclaration;
+    style: StylesDescriptor & ((styles: StylesDescriptor) => void);
     innerHTML: string;
+    setCSSVariable(table: Record<string, CSSValue>): void;
+    setCSSVariable(variableName: string, value: CSSValue): void;
     qsa(selector: string): DomEntity<any>[];
     append(...content: DOMContent[]): void;
     remove(): void;
-};
+} & (T extends HTMLInputElement ? {
+    value: string;
+} : {});
 type OptionalKeys<T> = {
     [K in keyof T]-?: {} extends Pick<T, K> ? K : never;
 }[keyof T];

package/index.js

@@ -13,6 +13,22 @@ var __assign = (this && this.__assign) || function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.$ = void 0;
 exports.definePart = definePart;
+var elementProxy = {
+    get: function (style, prop) {
+        return style[prop];
+    },
+    set: function (style, prop, value) {
+        style[prop] = value;
+        return true;
+    },
+    apply: function (style, _, _a) {
+        var styles = _a[0];
+        Object.entries(styles).forEach(function (_a) {
+            var prop = _a[0], val = _a[1];
+            return style[prop] = val;
+        });
+    },
+};
 function createElement(tag, descriptor) {
     if (descriptor === void 0) { descriptor = {}; }
     if (isContent(descriptor))
@@ -42,17 +58,18 @@ function createElement(tag, descriptor) {
             ent.element.setAttribute(k, v === true ? k : v);
         });
     }
-    if (descriptor.content)
+    if (descriptor.content !== undefined)
         recursiveAppend(ent.element, descriptor.content);
     if (descriptor.style) {
         Object.entries(descriptor.style).forEach(function (_a) {
             var prop = _a[0], val = _a[1];
-            if (/\-/.test(prop)) {
-                ent.element.style.setProperty(prop, val.toString());
-            }
-            else {
-                ent.element.style[prop] = val;
-            }
+            ent.element.style[prop] = val;
+        });
+    }
+    if (descriptor.cssVariables) {
+        Object.entries(descriptor.cssVariables).forEach(function (_a) {
+            var prop = _a[0], val = _a[1];
+            ent.element.style.setProperty("--" + prop, val);
         });
     }
     if (descriptor.on) {
@@ -156,6 +173,16 @@ function getWrappedElement(element) {
             _a.remove = function () {
                 element.remove();
             },
+            _a.setCSSVariable = function (variableNameOrTable, value) {
+                if (typeof variableNameOrTable == "object") {
+                    Object.entries(variableNameOrTable).forEach(function (_a) {
+                        var k = _a[0], v = _a[1];
+                        element.style.setProperty("--" + k, v);
+                    });
+                    return;
+                }
+                element.style.setProperty("--" + variableNameOrTable, value);
+            },
             _a.classes = element.classList,
             _a.qsa = function (selector) {
                 return [].slice.call(element.querySelectorAll(selector)).map(function (el) { return getWrappedElement(el); });
@@ -186,7 +213,17 @@ function getWrappedElement(element) {
                 enumerable: false,
                 configurable: true
             }),
-            _a.style = element.style,
+            Object.defineProperty(_a, "value", {
+                get: function () {
+                    return element.value;
+                },
+                set: function (v) {
+                    element.value = v;
+                },
+                enumerable: false,
+                configurable: true
+            }),
+            _a.style = new Proxy(element.style, elementProxy),
             _a);
         elementWrapCache.set(element, domEntity_1);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xtia/jel",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "repository": {
     "url": "https://github.com/tiadrop/jel-ts",
     "type": "github"