@htmlplus/element 1.0.0 → 1.1.0

package/bundlers/rollup.d.ts

@@ -1,5 +1,5 @@
-import { Plugin } from '../types';
-export declare const rollup: (...plugins: Array<Plugin>) => {
+import { TransformerPlugin } from '../transformer/index.js';
+export declare const htmlplus: (...plugins: Array<TransformerPlugin>) => {
     name: string;
     buildStart(): Promise<void>;
     load(id: any): Promise<string | undefined>;

package/bundlers/rollup.js

@@ -1,6 +1,6 @@
-import { compiler } from '../compiler/index.js';
-export const rollup = (...plugins) => {
-    const { start, run, finish } = compiler(...plugins);
+import { transformer } from '../transformer/index.js';
+export const htmlplus = (...plugins) => {
+    const { start, run, finish } = transformer(...plugins);
     return {
         name: 'htmlplus',
         async buildStart() {
@@ -9,8 +9,8 @@ export const rollup = (...plugins) => {
         async load(id) {
             if (!id.endsWith('.tsx'))
                 return;
-            const { isInvalid, script } = await run(id);
-            if (isInvalid)
+            const { script, skipped } = await run(id);
+            if (skipped)
                 return;
             return script;
         },

package/bundlers/vite.d.ts

@@ -1,5 +1,5 @@
-import { Plugin } from '../types';
-export declare const vite: (...plugins: Array<Plugin>) => {
+import { TransformerPlugin } from '../transformer/index.js';
+export declare const htmlplus: (...plugins: Array<TransformerPlugin>) => {
     name: string;
     buildStart(): Promise<void>;
     load(id: any): Promise<string | undefined>;

package/bundlers/vite.js

@@ -1,7 +1,7 @@
 import path from 'path';
-import { compiler } from '../compiler/index.js';
-export const vite = (...plugins) => {
-    const { start, run, finish } = compiler(...plugins);
+import { transformer } from '../transformer/index.js';
+export const htmlplus = (...plugins) => {
+    const { start, run, finish } = transformer(...plugins);
     return {
         name: 'htmlplus',
         async buildStart() {
@@ -10,8 +10,8 @@ export const vite = (...plugins) => {
         async load(id) {
             if (!id.endsWith('.tsx'))
                 return;
-            let { isInvalid, script, stylePath } = await run(id);
-            if (isInvalid)
+            let { script, skipped, stylePath } = await run(id);
+            if (skipped)
                 return;
             if (script && stylePath) {
                 script = script.replace(path.basename(stylePath), `${path.basename(stylePath)}?inline`);

package/client/decorators/bind.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Used to bind a method of a class to the current context,
+ * making it easier to reference `this` within the method.
+ */
 export declare function Bind(): (target: Object, propertyKey: PropertyKey, descriptor: PropertyDescriptor) => {
     configurable: boolean;
     get(): any;

package/client/decorators/bind.js

@@ -1,4 +1,8 @@
 import { defineProperty } from '../utils/index.js';
+/**
+ * Used to bind a method of a class to the current context,
+ * making it easier to reference `this` within the method.
+ */
 export function Bind() {
     return function (target, propertyKey, descriptor) {
         return {

package/client/decorators/direction.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Indicates whether the [Direction](https://mdn.io/css-direction)
+ * of the element is `Right-To-Left` or `Left-To-Right`.
+ */
+export declare function Direction(): (target: import("../../types/index.js").PlusElement, propertyKey: PropertyKey) => void;

package/client/decorators/direction.js

@@ -0,0 +1,8 @@
+import { direction, toDecorator } from '../utils/index.js';
+/**
+ * Indicates whether the [Direction](https://mdn.io/css-direction)
+ * of the element is `Right-To-Left` or `Left-To-Right`.
+ */
+export function Direction() {
+    return toDecorator(direction);
+}

package/client/decorators/element.d.ts

@@ -1,2 +1,7 @@
 import { PlusElement } from '../../types';
+/**
+ * The class marked with this decorator is considered a
+ * [Custom Element](https://mdn.io/using-custom-elements),
+ * and its name, in kebab-case, serves as the element name.
+ */
 export declare function Element(): (constructor: PlusElement) => void;

package/client/decorators/element.js

@@ -1,6 +1,11 @@
 import { camelCase, kebabCase } from 'change-case';
 import * as CONSTANTS from '../../constants/index.js';
-import { call, getConfig, getMembers, getNamespace, getTag, isServer, request, toProperty } from '../utils/index.js';
+import { call, getConfig, getMembers, getTag, isServer, request, toProperty } from '../utils/index.js';
+/**
+ * The class marked with this decorator is considered a
+ * [Custom Element](https://mdn.io/using-custom-elements),
+ * and its name, in kebab-case, serves as the element name.
+ */
 export function Element() {
     return function (constructor) {
         if (isServer())
@@ -46,7 +51,7 @@ export function Element() {
             connectedCallback() {
                 const instance = this[CONSTANTS.API_INSTANCE];
                 // TODO: experimental for global config
-                Object.assign(instance, getConfig(getNamespace(instance), 'component', getTag(instance), 'property'));
+                Object.assign(instance, getConfig('element', getTag(instance), 'property'));
                 const connect = () => {
                     instance[CONSTANTS.API_CONNECTED] = true;
                     call(instance, CONSTANTS.LIFECYCLE_CONNECTED);

package/client/decorators/event.d.ts

@@ -1,21 +1,35 @@
 import { PlusElement } from '../../types';
+/**
+ * A function type that generates a `CustomEvent`.
+ */
 export type EventEmitter<T = any> = (data?: T) => CustomEvent<T>;
+/**
+ * An object that configures
+ * [options](https://developer.mozilla.org/docs/Web/API/Event/EventEvent#options)
+ * for the event dispatcher.
+ */
 export interface EventOptions {
     /**
-     * A string custom event name to override the default.
-     */
-    name?: string;
-    /**
-     * A Boolean indicating whether the event bubbles up through the DOM or not. default is `false`.
+     * A boolean value indicating whether the event bubbles.
+     * The default is `false`.
      */
     bubbles?: boolean;
     /**
-     * A Boolean indicating whether the event is cancelable. default is `false`.
+     * A boolean value indicating whether the event can be cancelled.
+     * The default is `false`.
      */
     cancelable?: boolean;
     /**
-     * A Boolean value indicating whether or not the event can bubble across the boundary between the shadow DOM and the regular DOM. The default is false.
+     * A boolean value indicating whether the event will trigger listeners outside of a shadow root
+     * (see [Event.composed](https://mdn.io/event-composed) for more details).
+     * The default is `false`.
      */
     composed?: boolean;
 }
+/**
+ * Provides the capability to dispatch a [CustomEvent](https://mdn.io/custom-event)
+ * from an element.
+ *
+ * @param options An object that configures options for the event dispatcher.
+ */
 export declare function Event<T = any>(options?: EventOptions): (target: PlusElement, propertyKey: PropertyKey) => void;

package/client/decorators/event.js

@@ -1,5 +1,11 @@
 import { kebabCase, pascalCase } from 'change-case';
 import { defineProperty, getFramework, host } from '../utils/index.js';
+/**
+ * Provides the capability to dispatch a [CustomEvent](https://mdn.io/custom-event)
+ * from an element.
+ *
+ * @param options An object that configures options for the event dispatcher.
+ */
 export function Event(options = {}) {
     return function (target, propertyKey) {
         defineProperty(target, propertyKey, {
@@ -9,14 +15,13 @@ export function Event(options = {}) {
                     const element = host(this);
                     const framework = getFramework(element);
                     (_a = options.bubbles) !== null && _a !== void 0 ? _a : (options.bubbles = false);
-                    let name = options.name || String(propertyKey);
+                    let name = String(propertyKey);
                     switch (framework) {
                         case 'qwik':
                         case 'solid':
                             name = pascalCase(name).toLowerCase();
                             break;
                         case 'preact':
-                        case 'react':
                             name = pascalCase(name);
                             break;
                         default:

package/client/decorators/host.d.ts

@@ -1,2 +1,4 @@
-import { PlusElement } from '../../types';
-export declare function Host(): (target: PlusElement, propertyKey: PropertyKey) => void;
+/**
+ * Indicates the host of the element.
+ */
+export declare function Host(): (target: import("../../types/index.js").PlusElement, propertyKey: PropertyKey) => void;

package/client/decorators/host.js

@@ -1,10 +1,7 @@
-import { defineProperty, host } from '../utils/index.js';
+import { host, toDecorator } from '../utils/index.js';
+/**
+ * Indicates the host of the element.
+ */
 export function Host() {
-    return function (target, propertyKey) {
-        defineProperty(target, propertyKey, {
-            get() {
-                return host(this);
-            }
-        });
-    };
+    return toDecorator(host);
 }

package/client/decorators/index.d.ts

@@ -1,11 +1,14 @@
 export * from './bind.js';
+export * from './direction.js';
 export * from './element.js';
 export * from './event.js';
 export * from './host.js';
+export * from './isRTL.js';
 export * from './listen.js';
 export * from './method.js';
 export * from './property.js';
 export * from './query.js';
 export * from './queryAll.js';
+export * from './slots.js';
 export * from './state.js';
 export * from './watch.js';

package/client/decorators/index.js

@@ -1,11 +1,14 @@
 export * from './bind.js';
+export * from './direction.js';
 export * from './element.js';
 export * from './event.js';
 export * from './host.js';
+export * from './isRTL.js';
 export * from './listen.js';
 export * from './method.js';
 export * from './property.js';
 export * from './query.js';
 export * from './queryAll.js';
+export * from './slots.js';
 export * from './state.js';
 export * from './watch.js';

package/client/decorators/isRTL.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Indicates whether the direction of the element is `Right-To-Left` or not.
+ */
+export declare function IsRTL(): (target: import("../../types/index.js").PlusElement, propertyKey: PropertyKey) => void;

package/client/decorators/isRTL.js

@@ -0,0 +1,7 @@
+import { isRTL, toDecorator } from '../utils/index.js';
+/**
+ * Indicates whether the direction of the element is `Right-To-Left` or not.
+ */
+export function IsRTL() {
+    return toDecorator(isRTL);
+}

package/client/decorators/listen.d.ts

@@ -1,20 +1,50 @@
 import { PlusElement } from '../../types';
+/**
+ * An object that configures
+ * [options](https://developer.mozilla.org/docs/Web/API/EventTarget/addEventListener#options)
+ * for the event listener.
+ */
 export interface ListenOptions {
+    /**
+     * A boolean value indicating that events of this type will be dispatched to the registered
+     * `listener` before being dispatched to any `EventTarget` beneath it in the DOM tree.
+     * If not specified, defaults to `false`.
+     */
     capture?: boolean;
+    /**
+     * A boolean value indicating that the `listener` should be invoked at most once after being added.
+     * If `true`, the `listener` would be automatically removed when invoked.
+     * If not specified, defaults to `false`.
+     */
     once?: boolean;
+    /**
+     * A boolean value that, if `true`,
+     * indicates that the function specified by `listener` will never call
+     * [preventDefault()](https://developer.mozilla.org/en-US/docs/Web/API/Event/preventDefault).
+     * If a passive listener does call `preventDefault()`,
+     * the user agent will do nothing other than generate a console warning.
+     */
     passive?: boolean;
+    /**
+     * An [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal).
+     * The listener will be removed when the given `AbortSignal` object's
+     * [abort()](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort) method is called.
+     * If not specified, no `AbortSignal` is associated with the listener.
+     */
     signal?: AbortSignal;
+    /**
+     * The target element, defaults to `host`.
+     */
     target?: 'host' | 'body' | 'document' | 'window';
 }
 /**
- * The default options.
- */
-export declare const ListenOptionsDefault: ListenOptions;
-/**
- * Will be called whenever the specified event is delivered to the target.
- * [More](https://mdn.io/addEventListener).
- * @param type A case-sensitive string representing the [event type](https://mdn.io/events) to listen for.
- * @param options An object that specifies characteristics about the event listener.
+ * Will be called whenever the specified event is delivered to the target
+ * [More](https://mdn.io/add-event-listener).
+ *
+ * @param type A case-sensitive string representing the [Event Type](https://mdn.io/events) to listen for.
+ * @param options An object that configures
+ * [options](https://developer.mozilla.org/docs/Web/API/EventTarget/addEventListener#options)
+ * for the event listener.
  */
 export declare function Listen(type: string, options?: ListenOptions): (target: PlusElement, propertyKey: PropertyKey, descriptor: PropertyDescriptor) => {
     configurable: boolean;

package/client/decorators/listen.js

@@ -2,22 +2,19 @@ import * as CONSTANTS from '../../constants/index.js';
 import { appendToMethod, host, on, off } from '../utils/index.js';
 import { Bind } from './bind.js';
 /**
- * The default options.
- */
-export const ListenOptionsDefault = {
-    target: 'host'
-};
-/**
- * Will be called whenever the specified event is delivered to the target.
- * [More](https://mdn.io/addEventListener).
- * @param type A case-sensitive string representing the [event type](https://mdn.io/events) to listen for.
- * @param options An object that specifies characteristics about the event listener.
+ * Will be called whenever the specified event is delivered to the target
+ * [More](https://mdn.io/add-event-listener).
+ *
+ * @param type A case-sensitive string representing the [Event Type](https://mdn.io/events) to listen for.
+ * @param options An object that configures
+ * [options](https://developer.mozilla.org/docs/Web/API/EventTarget/addEventListener#options)
+ * for the event listener.
  */
 export function Listen(type, options) {
     return function (target, propertyKey, descriptor) {
-        options = Object.assign({}, ListenOptionsDefault, options);
+        options = Object.assign({ target: 'host' }, options);
         const element = (instance) => {
-            switch (options === null || options === void 0 ? void 0 : options.target) {
+            switch (options.target) {
                 case 'body':
                     return window.document.body;
                 case 'document':

package/client/decorators/method.d.ts

@@ -1,2 +1,6 @@
 import { PlusElement } from '../../types';
+/**
+ * Provides a way to encapsulate functionality within an element
+ * and invoke it as needed, both internally and externally.
+ */
 export declare function Method(): (target: PlusElement, propertyKey: PropertyKey) => void;

package/client/decorators/method.js

@@ -1,5 +1,9 @@
 import * as CONSTANTS from '../../constants/index.js';
 import { appendToMethod, defineProperty, host } from '../utils/index.js';
+/**
+ * Provides a way to encapsulate functionality within an element
+ * and invoke it as needed, both internally and externally.
+ */
 export function Method() {
     return function (target, propertyKey) {
         appendToMethod(target, CONSTANTS.LIFECYCLE_CONNECTED, function () {

package/client/decorators/property.d.ts

@@ -1,12 +1,19 @@
 import { PlusElement } from '../../types';
+/**
+ * The configuration for property decorator.
+ */
 export interface PropertyOptions {
     /**
      * Whether property value is reflected back to the associated attribute. default is `false`.
      */
     reflect?: boolean;
     /**
-     * TODO
+     * Do not set the value to this property. This value is automatically set during transpiling.
      */
     type?: number;
 }
+/**
+ * Creates a reactive property, reflecting a corresponding attribute value,
+ * and updates the element when the property is set.
+ */
 export declare function Property(options?: PropertyOptions): (target: PlusElement, propertyKey: PropertyKey) => void;

package/client/decorators/property.js

@@ -1,5 +1,9 @@
 import * as CONSTANTS from '../../constants/index.js';
 import { addMember, appendToMethod, defineProperty, host, request, toProperty, updateAttribute } from '../utils/index.js';
+/**
+ * Creates a reactive property, reflecting a corresponding attribute value,
+ * and updates the element when the property is set.
+ */
 export function Property(options) {
     return function (target, propertyKey) {
         const name = String(propertyKey);

package/client/decorators/query.d.ts

@@ -1,2 +1,9 @@
-import { PlusElement } from '../../types';
-export declare function Query(selectors: string): (target: PlusElement, propertyKey: PropertyKey) => void;
+/**
+ * Selects the first element in the shadow dom that matches a specified CSS selector.
+ *
+ * @param selectors A string containing one or more selectors to match.
+ * This string must be a valid CSS selector string; if it isn't, a `SyntaxError` exception is thrown. See
+ * [Locating DOM elements using selectors](https://developer.mozilla.org/en-US/docs/Web/API/Document_object_model/Locating_DOM_elements_using_selectors)
+ * for more about selectors and how to manage them.
+ */
+export declare function Query(selectors: string): (target: import("../../types/index.js").PlusElement, propertyKey: PropertyKey) => void;

package/client/decorators/query.js

@@ -1,11 +1,12 @@
-import { defineProperty, shadowRoot } from '../utils/index.js';
+import { query, toDecorator } from '../utils/index.js';
+/**
+ * Selects the first element in the shadow dom that matches a specified CSS selector.
+ *
+ * @param selectors A string containing one or more selectors to match.
+ * This string must be a valid CSS selector string; if it isn't, a `SyntaxError` exception is thrown. See
+ * [Locating DOM elements using selectors](https://developer.mozilla.org/en-US/docs/Web/API/Document_object_model/Locating_DOM_elements_using_selectors)
+ * for more about selectors and how to manage them.
+ */
 export function Query(selectors) {
-    return function (target, propertyKey) {
-        defineProperty(target, propertyKey, {
-            get() {
-                var _a;
-                return (_a = shadowRoot(this)) === null || _a === void 0 ? void 0 : _a.querySelector(selectors);
-            }
-        });
-    };
+    return toDecorator(query, selectors);
 }

package/client/decorators/queryAll.d.ts

@@ -1,2 +1,12 @@
-import { PlusElement } from '../../types';
-export declare function QueryAll(selectors: string): (target: PlusElement, propertyKey: PropertyKey) => void;
+/**
+ * Selects all elements in the shadow dom that match a specified CSS selector.
+ *
+ * @param selectors A string containing one or more selectors to match against.
+ * This string must be a valid
+ * [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors)
+ * string; if it's not, a `SyntaxError` exception is thrown. See
+ * [Locating DOM elements using selectors](https://developer.mozilla.org/en-US/docs/Web/API/Document_object_model/Locating_DOM_elements_using_selectors)
+ * for more information about using selectors to identify elements.
+ * Multiple selectors may be specified by separating them using commas.
+ */
+export declare function QueryAll(selectors: string): (target: import("../../types/index.js").PlusElement, propertyKey: PropertyKey) => void;

package/client/decorators/queryAll.js

@@ -1,11 +1,15 @@
-import { defineProperty, shadowRoot } from '../utils/index.js';
+import { queryAll, toDecorator } from '../utils/index.js';
+/**
+ * Selects all elements in the shadow dom that match a specified CSS selector.
+ *
+ * @param selectors A string containing one or more selectors to match against.
+ * This string must be a valid
+ * [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors)
+ * string; if it's not, a `SyntaxError` exception is thrown. See
+ * [Locating DOM elements using selectors](https://developer.mozilla.org/en-US/docs/Web/API/Document_object_model/Locating_DOM_elements_using_selectors)
+ * for more information about using selectors to identify elements.
+ * Multiple selectors may be specified by separating them using commas.
+ */
 export function QueryAll(selectors) {
-    return function (target, propertyKey) {
-        defineProperty(target, propertyKey, {
-            get() {
-                var _a;
-                return (_a = shadowRoot(this)) === null || _a === void 0 ? void 0 : _a.querySelectorAll(selectors);
-            }
-        });
-    };
+    return toDecorator(queryAll, selectors);
 }

package/client/decorators/slots.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Returns the slots name.
+ */
+export declare function Slots(): (target: import("../../types/index.js").PlusElement, propertyKey: PropertyKey) => void;

package/client/decorators/slots.js

@@ -0,0 +1,7 @@
+import { slots, toDecorator } from '../utils/index.js';
+/**
+ * Returns the slots name.
+ */
+export function Slots() {
+    return toDecorator(slots);
+}

package/client/decorators/state.d.ts

@@ -1,2 +1,6 @@
 import { PlusElement } from '../../types';
+/**
+ * Applying this decorator to any `class property` will trigger the
+ * element to re-render upon the desired property changes.
+ */
 export declare function State(): (target: PlusElement, propertyKey: PropertyKey) => void;

package/client/decorators/state.js

@@ -1,4 +1,8 @@
 import { defineProperty, request } from '../utils/index.js';
+/**
+ * Applying this decorator to any `class property` will trigger the
+ * element to re-render upon the desired property changes.
+ */
 export function State() {
     return function (target, propertyKey) {
         const name = String(propertyKey);

package/client/decorators/watch.d.ts

@@ -1,9 +1,10 @@
 import { PlusElement } from '../../types';
 /**
- * Monitors `@Property` and `@State` to catch changes.
- * The decorated method will be invoked after any
- * changes with the `key`, `newValue`, and `oldValue` as parameters.
- * If the arguments aren't defined, all of the `@Property` and `@State` are considered.
+ * Monitors `@Property` and `@State` to detect changes.
+ * The decorated method will be called after any changes,
+ * with the `key`, `newValue`, and `oldValue` as parameters.
+ * If the `key` is not defined, all `@Property` and `@State` are considered.
+ *
  * @param keys Collection of `@Property` and `@State` names.
  * @param immediate Triggers the callback immediately after initialization.
  */

package/client/decorators/watch.js

@@ -1,10 +1,11 @@
 import * as CONSTANTS from '../../constants/index.js';
 import { appendToMethod } from '../utils/index.js';
 /**
- * Monitors `@Property` and `@State` to catch changes.
- * The decorated method will be invoked after any
- * changes with the `key`, `newValue`, and `oldValue` as parameters.
- * If the arguments aren't defined, all of the `@Property` and `@State` are considered.
+ * Monitors `@Property` and `@State` to detect changes.
+ * The decorated method will be called after any changes,
+ * with the `key`, `newValue`, and `oldValue` as parameters.
+ * If the `key` is not defined, all `@Property` and `@State` are considered.
+ *
  * @param keys Collection of `@Property` and `@State` names.
  * @param immediate Triggers the callback immediately after initialization.
  */

package/client/index.d.ts

@@ -1,4 +1,2 @@
 export * from './decorators/index.js';
-export * from './helpers/index.js';
-export * from './services/index.js';
-export { getConfig, setConfig } from './utils/config.js';
+export { classes, direction, getConfig, host, isCSSColor, isRTL, query, queryAll, on, off, slots, styles, toUnit, setConfig, type Config, type ConfigOptions } from './utils/index.js';

package/client/index.js

@@ -1,4 +1,2 @@
 export * from './decorators/index.js';
-export * from './helpers/index.js';
-export * from './services/index.js';
-export { getConfig, setConfig } from './utils/config.js';
+export { classes, direction, getConfig, host, isCSSColor, isRTL, query, queryAll, on, off, slots, styles, toUnit, setConfig } from './utils/index.js';

package/client/utils/classes.d.ts

@@ -1 +1,4 @@
+/**
+ * TODO
+ */
 export declare const classes: (input: any, smart?: boolean) => string;