p-elements-core 2.1.0-rc8 → 2.1.0

package/typings/decorators/property.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Supported property type constructors for reactive properties.
+ * These constructors are used to convert attribute values to the correct JavaScript type.
+ *
+ * @typedef {StringConstructor | NumberConstructor | BooleanConstructor | ObjectConstructor | ArrayConstructor} PropertyType
+ */
+type PropertyType = StringConstructor | NumberConstructor | BooleanConstructor | ObjectConstructor | ArrayConstructor;
+/**
+ * Legacy string-based property types (deprecated).
+ * Maintained for backward compatibility. Use PropertyType constructors instead.
+ *
+ * @typedef {('string' | 'number' | 'boolean' | 'object' | 'array')} oldPropertyType
+ * @deprecated Use PropertyType constructors (String, Number, Boolean, Object, Array) instead
+ */
+type oldPropertyType = "string" | "number" | "boolean" | "object" | "array";
+/**
+ * Configuration options for the @property decorator.
+ * Defines how a property should sync with HTML attributes and trigger updates.
+ *
+ * @interface PropertyOptions
+ *
+ * @example
+ * ```typescript
+ * @property({ type: String, reflect: true })
+ * name = 'default';
+ *
+ * @property({ type: Number, attribute: 'data-count' })
+ * count = 0;
+ *
+ * @property({ type: Boolean })
+ * active = false;
+ * ```
+ */
+export interface PropertyOptions {
+    /**
+     * The type constructor for converting attribute values to property values.
+     * Use String, Number, Boolean, Object, or Array.
+     * @type {PropertyType | oldPropertyType}
+     */
+    type?: PropertyType | oldPropertyType;
+    /**
+     * The HTML attribute name to sync with, or false to disable attribute syncing.
+     * - `true` (default): Use kebab-case version of property name
+     * - `string`: Use specific attribute name
+     * - `false`: No attribute syncing
+     * @type {string | boolean}
+     */
+    attribute?: string | boolean;
+    /**
+     * Whether to reflect property changes back to the HTML attribute.
+     * When true, setting the property will update the attribute.
+     * @type {boolean}
+     * @default false
+     */
+    reflect?: boolean;
+    readonly?: boolean;
+    /**
+     * Custom converter for complex attribute/property transformations.
+     * @type {AttributeConverter<any>}
+     */
+    converter?: AttributeConverter<any>;
+}
+/**
+ * PropertyOptions extended with the property name.
+ * Used internally to track registered properties.
+ *
+ * @typedef {PropertyOptions & { name: string }} PropertyOptionsWithName
+ */
+export type PropertyOptionsWithName = PropertyOptions & {
+    name: string;
+};
+/**
+ * Checks if an element is currently updating its attributes from property setters.
+ * Used to prevent circular updates during property reflection.
+ *
+ * @param {HTMLElement} element - The element to check
+ * @returns {boolean} True if the element is currently setting attributes
+ *
+ * @example
+ * ```typescript
+ * if (!isSettingAttribute(this)) {
+ *   // Safe to update property from attribute
+ * }
+ * ```
+ */
+export declare function isSettingAttribute(element: HTMLElement): boolean;
+/**
+ * Process any pending update callbacks for an element.
+ * Should be called when the element connects to the DOM to trigger
+ * deferred lifecycle callbacks.
+ *
+ * @param {any} element - The element with pending updates
+ * @returns {void}
+ *
+ * @example
+ * ```typescript
+ * connectedCallback() {
+ *   processPendingUpdates(this);
+ * }
+ * ```
+ */
+export declare function processPendingUpdates(element: any): void;
+/**
+ * Interface for custom attribute conversion functions.
+ *
+ * @interface AttributeConverter
+ * @template T The type of the property value
+ * @description Provides custom conversion logic between HTML attribute strings
+ * and JavaScript property values for complex data types or custom formatting.
+ */
+export interface AttributeConverter<T> {
+    /**
+     * Converts an HTML attribute string value to a JavaScript property value.
+     *
+     * @param {string | null} value - The attribute value to convert
+     * @returns {T} The converted JavaScript value
+     * @optional
+     *
+     * @example
+     * ```typescript
+     * fromAttribute: (value: string | null) => {
+     *   return value ? JSON.parse(value) : null;
+     * }
+     * ```
+     */
+    fromAttribute?(value: string | null): T;
+    /**
+     * Converts a JavaScript property value to an HTML attribute string.
+     *
+     * @param {T} value - The JavaScript value to convert
+     * @returns {string} The converted attribute string
+     * @optional
+     *
+     * @example
+     * ```typescript
+     * toAttribute: (value: object) => {
+     *   return JSON.stringify(value);
+     * }
+     * ```
+     */
+    toAttribute?(value: T): string;
+}
+/**
+ * Class field decorator that creates a reactive property with automatic attribute syncing.
+ *
+ * Features:
+ * - Automatic type conversion between attributes and properties
+ * - Optional property → attribute reflection
+ * - Custom converters for complex types
+ * - Automatic observedAttributes registration
+ * - Deferred updates for disconnected elements
+ * - Lifecycle integration (updated, shouldUpdate, renderNow)
+ *
+ * @decorator
+ * @param {PropertyOptions} [options={}] - Configuration options for the property
+ * @returns {(target: any, propertyKey: string) => void} The decorator function
+ *
+ * @example
+ * Basic usage with different types:
+ * ```typescript
+ * class MyElement extends BaseComponent {
+ *   @property({ type: String })
+ *   name = 'default';
+ *
+ *   @property({ type: Number })
+ *   count = 0;
+ *
+ *   @property({ type: Boolean })
+ *   active = false;
+ * }
+ * ```
+ *
+ * @example
+ * With reflection (property changes update attribute):
+ * ```typescript
+ * class MyElement extends BaseComponent {
+ *   @property({ type: String, reflect: true })
+ *   status = 'pending';
+ *
+ *   updateStatus() {
+ *     this.status = 'complete'; // Also updates status="complete" attribute
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * Custom attribute name and converter:
+ * ```typescript
+ * class MyElement extends BaseComponent {
+ *   @property({
+ *     type: Object,
+ *     attribute: 'data-config',
+ *     converter: {
+ *       fromAttribute: (value) => value ? JSON.parse(value) : {},
+ *       toAttribute: (value) => JSON.stringify(value)
+ *     }
+ *   })
+ *   config = {};
+ * }
+ * ```
+ *
+ * @example
+ * Property without attribute syncing:
+ * ```typescript
+ * class MyElement extends BaseComponent {
+ *   @property({ attribute: false })
+ *   internalState = null; // No attribute created or observed
+ * }
+ * ```
+ */
+export declare function property(options?: PropertyOptions): (target: any, propertyKey: string) => void;
+export {};
+//# sourceMappingURL=property.d.ts.map

package/typings/decorators/property.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"property.d.ts","sourceRoot":"","sources":["../../src/decorators/property.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,KAAK,YAAY,GACb,iBAAiB,GACjB,iBAAiB,GACjB,kBAAkB,GAClB,iBAAiB,GACjB,gBAAgB,CAAC;AAErB;;;;;;GAMG;AACH,KAAK,eAAe,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE5E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,IAAI,CAAC,EAAE,YAAY,GAAG,eAAe,CAAC;IAEtC;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAE7B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;OAGG;IACH,SAAS,CAAC,EAAE,kBAAkB,CAAC,GAAG,CAAC,CAAC;CACrC;AAED;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG,eAAe,GAAG;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAAC;AAoCvE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAEhE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI,CAiCxD;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,CAAC,CAAC;IAExC;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,CAAC,KAAK,EAAE,CAAC,GAAG,MAAM,CAAC;CAChC;AAiLD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,wBAAgB,QAAQ,CACtB,OAAO,GAAE,eAAoB,GAC5B,CAAC,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,MAAM,KAAK,IAAI,CAoN5C"}

package/typings/decorators/query.d.ts

@@ -0,0 +1,2 @@
+export declare const query: (selector: string, useShadowRoot?: boolean) => (target: Object, propertyKey: string) => void;
+//# sourceMappingURL=query.d.ts.map

package/typings/decorators/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/decorators/query.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,KAAK,GAAI,UAAU,MAAM,EAAE,uBAAoB,MAC1C,QAAQ,MAAM,EAAE,aAAa,MAAM,SAUpD,CAAC"}

package/typings/decorators/render-property-on-set.d.ts

@@ -0,0 +1,2 @@
+export declare const propertyRenderOnSet: (target: any, propertyKey: string) => void;
+//# sourceMappingURL=render-property-on-set.d.ts.map

package/typings/decorators/render-property-on-set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-property-on-set.d.ts","sourceRoot":"","sources":["../../src/decorators/render-property-on-set.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,mBAAmB,4CAAmB,CAAC"}

package/typings/maquette/cache.d.ts

@@ -0,0 +1,10 @@
+import { CalculationCache } from "./interfaces";
+/**
+ * Creates a [[CalculationCache]] object, useful for caching [[VNode]] trees.
+ * In practice, caching of [[VNode]] trees is not needed, because achieving 60 frames per second is almost never a problem.
+ * For more information, see [[CalculationCache]].
+ *
+ * @param <Result> The type of the value that is cached.
+ */
+export declare let createCache: <Result>() => CalculationCache<Result>;
+//# sourceMappingURL=cache.d.ts.map

package/typings/maquette/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/maquette/cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;GAMG;AACH,eAAO,IAAI,WAAW,GAAI,MAAM,OAAM,gBAAgB,CAAC,MAAM,CAyB5D,CAAC"}

package/typings/maquette/dom.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Contains simple low-level utility functions to manipulate the real DOM.
+ */
+import { Projection, ProjectionOptions, VNode } from "./interfaces";
+export declare let applyDefaultProjectionOptions: (projectorOptions?: ProjectionOptions) => ProjectionOptions;
+export declare let dom: {
+    /**
+     * Creates a real DOM tree from `vnode`. The [[Projection]] object returned will contain the resulting DOM Node in
+     * its [[Projection.domNode|domNode]] property.
+     * This is a low-level method. Users will typically use a [[Projector]] instead.
+     * @param vnode - The root of the virtual DOM tree that was created using the [[h]] function. NOTE: [[VNode]]
+     * objects may only be rendered once.
+     * @param projectionOptions - Options to be used to create and update the projection.
+     * @returns The [[Projection]] which also contains the DOM Node that was created.
+     */
+    create: (vnode: VNode, projectionOptions?: ProjectionOptions) => Projection;
+    /**
+     * Appends a new child node to the DOM which is generated from a [[VNode]].
+     * This is a low-level method. Users will typically use a [[Projector]] instead.
+     * @param parentNode - The parent node for the new child node.
+     * @param vnode - The root of the virtual DOM tree that was created using the [[h]] function. NOTE: [[VNode]]
+     * objects may only be rendered once.
+     * @param projectionOptions - Options to be used to create and update the [[Projection]].
+     * @returns The [[Projection]] that was created.
+     */
+    append: (parentNode: Element, vnode: VNode, projectionOptions?: ProjectionOptions) => Projection;
+    /**
+     * Inserts a new DOM node which is generated from a [[VNode]].
+     * This is a low-level method. Users wil typically use a [[Projector]] instead.
+     * @param beforeNode - The node that the DOM Node is inserted before.
+     * @param vnode - The root of the virtual DOM tree that was created using the [[h]] function.
+     * NOTE: [[VNode]] objects may only be rendered once.
+     * @param projectionOptions - Options to be used to create and update the projection, see [[createProjector]].
+     * @returns The [[Projection]] that was created.
+     */
+    insertBefore: (beforeNode: Element, vnode: VNode, projectionOptions?: ProjectionOptions) => Projection;
+    /**
+     * Merges a new DOM node which is generated from a [[VNode]] with an existing DOM Node.
+     * This means that the virtual DOM and the real DOM will have one overlapping element.
+     * Therefore the selector for the root [[VNode]] will be ignored, but its properties and children will be applied to the Element provided.
+     * This is a low-level method. Users wil typically use a [[Projector]] instead.
+     * @param element - The existing element to adopt as the root of the new virtual DOM. Existing attributes and child nodes are preserved.
+     * @param vnode - The root of the virtual DOM tree that was created using the [[h]] function. NOTE: [[VNode]] objects
+     * may only be rendered once.
+     * @param projectionOptions - Options to be used to create and update the projection, see [[createProjector]].
+     * @returns The [[Projection]] that was created.
+     */
+    merge: (element: Element, vnode: VNode, projectionOptions?: ProjectionOptions) => Projection;
+    /**
+     * Replaces an existing DOM node with a node generated from a [[VNode]].
+     * This is a low-level method. Users will typically use a [[Projector]] instead.
+     * @param element - The node for the [[VNode]] to replace.
+     * @param vnode - The root of the virtual DOM tree that was created using the [[h]] function. NOTE: [[VNode]]
+     * objects may only be rendered once.
+     * @param projectionOptions - Options to be used to create and update the [[Projection]].
+     * @returns The [[Projection]] that was created.
+     */
+    replace: (element: Element, vnode: VNode, projectionOptions?: ProjectionOptions) => Projection;
+};
+//# sourceMappingURL=dom.d.ts.map

package/typings/maquette/dom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../../src/maquette/dom.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAkBpE,eAAO,IAAI,6BAA6B,GACtC,mBAAmB,iBAAiB,KACnC,iBAEF,CAAC;AAEF,eAAO,IAAI,GAAG;IACZ;;;;;;;;OAQG;oBACa,KAAK,sBAAsB,iBAAiB,KAAG,UAAU;IAMzE;;;;;;;;OAQG;yBAEW,OAAO,SACZ,KAAK,sBACQ,iBAAiB,KACpC,UAAU;IAMb;;;;;;;;OAQG;+BAEW,OAAO,SACZ,KAAK,sBACQ,iBAAiB,KACpC,UAAU;IAMb;;;;;;;;;;OAUG;qBACc,OAAO,SAAS,KAAK,sBAAsB,iBAAiB,KAAG,UAAU;IAO1F;;;;;;;;OAQG;uBACgB,OAAO,SAAS,KAAK,sBAAsB,iBAAiB,KAAG,UAAU;CAM7F,CAAC"}

package/typings/maquette/h.d.ts

@@ -0,0 +1,35 @@
+import { VNode, VNodeChild, VNodeProperties } from "./interfaces";
+/**
+ * The `h` function is used to create a virtual DOM node.
+ * This function is largely inspired by the mercuryjs and mithril frameworks.
+ * The `h` stands for (virtual) hyperscript.
+ *
+ * @param selector    Contains the tagName, id and fixed css classnames in CSS selector format.
+ *                    It is formatted as follows: `tagname.cssclass1.cssclass2#id`.
+ * @param properties  An object literal containing properties that will be placed on the DOM node.
+ * @param children    Virtual DOM nodes and strings to add as child nodes.
+ *                    `children` may contain [[VNode]]s, `string`s, nested arrays, `null` and `undefined`.
+ *                    Nested arrays are flattened, `null` and `undefined` are removed.
+ *
+ * @returns           A VNode object, used to render a real DOM later.
+ *
+ * NOTE: There are {@link http://maquettejs.org/docs/rules.html two basic rules} you should be aware of when updating the virtual DOM.
+ */
+export declare function h(selector: string, properties?: VNodeProperties, children?: VNodeChild[] | null): VNode;
+/**
+ * The `h` function is used to create a virtual DOM node.
+ * This function is largely inspired by the mercuryjs and mithril frameworks.
+ * The `h` stands for (virtual) hyperscript.
+ *
+ * @param selector    Contains the tagName, id and fixed css classnames in CSS selector format.
+ *                    It is formatted as follows: `tagname.cssclass1.cssclass2#id`.
+ * @param children    Virtual DOM nodes and strings to add as child nodes.
+ *                    `children` may contain [[VNode]]s, `string`s, nested arrays, `null` and `undefined`.
+ *                    Nested arrays are flattened, `null` and `undefined` are removed.
+ *
+ * @returns           A VNode object, used to render a real DOM later.
+ *
+ * NOTE: There are {@link http://maquettejs.org/docs/rules.html two basic rules} you should be aware of when updating the virtual DOM.
+ */
+export declare function h(selector: string, children: VNodeChild[]): VNode;
+//# sourceMappingURL=h.d.ts.map

package/typings/maquette/h.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"h.d.ts","sourceRoot":"","sources":["../../src/maquette/h.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AA4BlE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,CAAC,CACf,QAAQ,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,eAAe,EAC5B,QAAQ,CAAC,EAAE,UAAU,EAAE,GAAG,IAAI,GAC7B,KAAK,CAAC;AACT;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,KAAK,CAAC"}

package/{src/maquette/index.ts → typings/maquette/index.d.ts}

@@ -1,4 +1,3 @@
-// Comment that is displayed in the API documentation for the maquette module:
 /**
  * Welcome to the API documentation of the **maquette** library.
  *
@@ -10,3 +9,4 @@ export { h } from "./h";
 export { createProjector } from "./projector";
 export { createCache } from "./cache";
 export { createMapping } from "./mapping";
+//# sourceMappingURL=index.d.ts.map

package/typings/maquette/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/maquette/index.ts"],"names":[],"mappings":"AACA;;;;GAIG;AACH,cAAc,cAAc,CAAC;AAC7B,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAC5B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC"}