@o.z/zui 0.4.3 → 0.4.6

package/dist/decorators/state.d.ts

@@ -1,10 +1,61 @@
+/**
+ * @fileoverview State decorator for reactive internal state management in ZUI components.
+ * Provides reactive state that triggers updates without reflecting to DOM attributes.
+ *
+ * @module state
+ */
+/**
+ * Configuration options for the @state decorator.
+ *
+ * @interface StateOptions
+ * @property {string} [callbackName] - Custom update callback method name
+ *
+ * @example
+ * @state({ callbackName: 'onHistoryChange' })
+ * accessor history: number[] = [];
+ */
 export interface StateOptions {
     callbackName?: string;
 }
 /**
- * Decorator for internal reactive state.
- * Triggers component updates but does NOT reflect to DOM attributes.
- * Useful for Objects, Arrays, or private data.
+ * Accessor decorator for internal reactive state that doesn't reflect to DOM attributes.
+ *
+ * Features:
+ * - Reactive state for objects and arrays
+ * - Automatic update callbacks on state changes
+ * - Deep reactivity with Proxy
+ * - No attribute reflection (unlike @property)
+ *
+ * @template T - Element type extending HTMLElement
+ * @template V - State value type
+ * @param {StateOptions} [options={}] - State configuration options
+ * @returns {ClassAccessorDecorator} An accessor decorator function
+ *
+ * @example
+ * ```typescript
+ * // Reactive array state
+ * @state()
+ * accessor items: string[] = [];
+ * // Calls itemsUpdate() on array mutations
+ *
+ * // Reactive object state
+ * @state()
+ * accessor user = { name: '', age: 0 };
+ * // Calls userUpdate() on property changes
+ *
+ * // With custom callback
+ * @state({ callbackName: 'onDataChange' })
+ * accessor data = {};
+ * // Calls onDataChange() instead of dataUpdate()
+ * ```
+ *
+ * @remarks
+ * - Best for complex objects, arrays, or private data
+ * - Uses Proxy for deep reactivity
+ * - Update callbacks receive (oldValue, newValue)
+ * - Changes are batched with queueMicrotask
+ *
+ * @see {@link makeReactive}
  */
 export declare const state: ({ callbackName }?: StateOptions) => <T extends HTMLElement, V>(accessor: {
     get: (this: T) => V;

package/dist/decorators/state.js

@@ -1,4 +1,4 @@
-import { makeReactive } from '../utilities.js';
+import { makeReactive } from '../utilities/makeReactive.js';
 
 function _type_of(obj){"@swc/helpers - typeof";return obj&&typeof Symbol!=="undefined"&&obj.constructor===Symbol?"symbol":typeof obj}var state=function(){var callbackName=(arguments.length>0&&arguments[0]!==void 0?arguments[0]:{}).callbackName;return function(accessor,context){var propName=context.name.toString();var updateMethodName=callbackName!==null&&callbackName!==void 0?callbackName:"".concat(propName,"Update");return {init:function init(initialValue){var zuiThis=this;var triggerUpdate=function(){queueMicrotask(function(){if(typeof zuiThis[updateMethodName]==="function"){zuiThis[updateMethodName](initialValue,initialValue);}});};var finalValue=initialValue;if(initialValue&&(typeof initialValue==="undefined"?"undefined":_type_of(initialValue))==="object"){finalValue=makeReactive(initialValue,triggerUpdate);}triggerUpdate();return finalValue},get:function get(){return accessor.get.call(this)},set:function set(newValue){var zuiThis=this;var triggerUpdate=function(){queueMicrotask(function(){if(typeof zuiThis[updateMethodName]==="function"){zuiThis[updateMethodName](newValue,newValue);}});};var finalValue=newValue;if(newValue&&(typeof newValue==="undefined"?"undefined":_type_of(newValue))==="object"){finalValue=makeReactive(newValue,triggerUpdate);}accessor.set.call(this,finalValue);triggerUpdate();}}}};
 

package/dist/decorators/types.d.ts

@@ -1,20 +1,128 @@
+/**
+ * @fileoverview Core TypeScript types and interfaces for ZUI framework.
+ * Defines type-safe event systems, update methods, and component interfaces.
+ *
+ * @module types
+ */
+/**
+ * Type guard for property update methods based on property type.
+ *
+ * @template T - Property type
+ * @example
+ * // For number properties:
+ * countUpdate(oldValue: number, newValue: number): void
+ *
+ * // For string properties:
+ * nameUpdate(oldValue: string, newValue: string): void
+ */
 export type PropertyUpdateMethod<T> = T extends number ? (oldValue: number, newValue: number) => void : T extends string ? (oldValue: string, newValue: string) => void : T extends boolean ? (oldValue: boolean, newValue: boolean) => void : (oldValue: T, newValue: T) => void;
+/**
+ * Mapped type that generates update method names from property names.
+ * Automatically appends 'Update' suffix to property names.
+ *
+ * @template T - Component instance type
+ * @example
+ * // If component has properties: count, name
+ * // UpdateMethods will include: countUpdate?, nameUpdate?
+ */
 export type UpdateMethods<T> = {
     [K in keyof T as `${string & K}Update`]?: K extends keyof T ? PropertyUpdateMethod<T[K]> : never;
 };
+/**
+ * Base interface for all ZUI components.
+ * Extends HTMLElement with optional lifecycle methods.
+ *
+ * @interface ZuiComponent
+ * @extends HTMLElement
+ */
 export interface ZuiComponent extends HTMLElement {
+    /** Called when element connects to DOM */
     connected?(): void;
+    /** Called when element disconnects from DOM */
     disconnected?(): void;
+    /** Called when observed attribute changes */
     attributeChanged?(attributeName: string, oldValue: string, newValue: string): void;
+    /** Index signature for dynamic properties */
     [key: string]: any;
 }
+/**
+ * Wrapper for custom event detail.
+ *
+ * @template T - Detail type
+ * @interface CustomEventDetail
+ * @property {T} value - The event payload
+ */
 export interface CustomEventDetail<T> {
     value: T;
 }
+/**
+ * Type-safe event emitter for dispatching custom events.
+ *
+ * @template T - Event detail type
+ * @class EventEmitter
+ *
+ * @example
+ * ```typescript
+ * const emitter = new EventEmitter<number>(element, 'count-changed');
+ * emitter.emit(42);
+ * ```
+ */
 export declare class EventEmitter<T> {
     private target;
     private eventName;
+    /**
+     * Creates an event emitter.
+     * @param target - The element that will dispatch events
+     * @param eventName - Name of the custom event (converted to kebab-case)
+     */
     constructor(target: HTMLElement, eventName: string);
+    /**
+     * Dispatches a custom event.
+     *
+     * @param {T} value - Event payload
+     * @param {Omit<CustomEventInit, 'detail'>} [options] - Additional event options
+     *
+     * @example
+     * ```typescript
+     * this.counterClick.emit({ count: 1 }, { bubbles: false });
+     * ```
+     *
+     * @remarks
+     * - Events bubble and composed are true by default
+     * - Detail is wrapped in { value: payload } structure
+     */
     emit(value: T, options?: Omit<CustomEventInit, 'detail'>): void;
 }
+/**
+ * Extracts the event detail type from an EventEmitter.
+ *
+ * @template T - EventEmitter type
+ */
 export type EventDetail<T> = T extends EventEmitter<infer U> ? U : never;
+/**
+ * Converts camelCase strings to kebab-case.
+ * Used for automatic event name generation.
+ *
+ * @template S - Input string type
+ */
+export type KebabCase<S extends string> = S extends `${infer T}${infer U}` ? U extends Uncapitalize<U> ? `${Uncapitalize<T>}${KebabCase<U>}` : `${Uncapitalize<T>}-${KebabCase<U>}` : S;
+/**
+ * Infers the CustomEvent detail type from an EventEmitter.
+ *
+ * @template T - EventEmitter type
+ */
+export type InferEventDetail<T> = T extends EventEmitter<infer U> ? CustomEventDetail<U> : never;
+/**
+ * Maps component event properties to their corresponding event types.
+ *
+ * @template T - Component type
+ *
+ * @example
+ * ```typescript
+ * // If component has: counterClick!: EventEmitter<{ count: number }>;
+ * // Then ZuiEventMap<Component> includes: 'counter-click': { value: { count: number } }
+ * ```
+ */
+export type ZuiEventMap<T> = {
+    [K in keyof T as T[K] extends EventEmitter<any> ? KebabCase<string & K> : never]: InferEventDetail<T[K]>;
+};

package/dist/dom.d.ts

@@ -2,9 +2,45 @@ import { Properties } from 'csstype';
 /**
  * Creates an HTML element with type-safe styles and children.
  *
- * @param tagName - The HTML tag name (e.g., 'div', 'span', 'a').
- * @param styles - An object of CSS styles in camelCase (e.g., { backgroundColor: 'red' }).
- * @param children - A number, a boolean, a string, a Node, or an array of them to append as children.
- * @returns The created HTML Element with the correct specific type.
+ * This utility provides a functional alternative to template literals or JSX,
+ * with full TypeScript support for CSS properties and element types.
+ *
+ * @template K - HTML tag name key from HTMLElementTagNameMap
+ * @param {K} tagName - The HTML tag name (e.g., 'div', 'span', 'a', 'button')
+ * @param {Properties<string | number>} [styles={}] - CSS styles in camelCase format
+ * @param {number | boolean | string | Node | (number | boolean | string | Node)[]} [children] - Child nodes or text content
+ * @returns {HTMLElementTagNameMap[K]} The created HTML element with proper type
+ *
+ * @throws {TypeError} If tagName is not a valid HTML element
+ *
+ * @example
+ * ```typescript
+ * // Create a styled div with text
+ * const div = createElement('div',
+ *   { backgroundColor: 'red', padding: '10px' },
+ *   'Hello World'
+ * );
+ *
+ * // Create nested elements
+ * const container = createElement('div', { display: 'flex' }, [
+ *   createElement('span', { color: 'blue' }, 'Item 1'),
+ *   createElement('span', { color: 'green' }, 'Item 2')
+ * ]);
+ *
+ * // Create form elements
+ * const input = createElement('input', {
+ *   type: 'text',
+ *   placeholder: 'Enter text...'
+ * });
+ * ```
+ *
+ * @remarks
+ * - Styles use the `csstype` package for full CSS property type checking
+ * - Children can be strings, numbers, booleans, Nodes, or arrays of these
+ * - Boolean and number children are converted to strings
+ * - Style properties with undefined/null values are ignored
+ *
+ * @see {@link https://www.npmjs.com/package/csstype} for CSS property types
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement}
  */
 export declare const createElement: <K extends keyof HTMLElementTagNameMap>(tagName: K, styles?: Properties<string | number>, children?: number | boolean | string | Node | (number | boolean | string | Node)[]) => HTMLElementTagNameMap[K];

package/dist/html.d.ts

@@ -1,20 +1,108 @@
+/**
+ * @fileoverview HTML template literal utilities for safe HTML string generation.
+ * Provides XSS protection through automatic escaping and type-safe HTML composition.
+ *
+ * @module html
+ */
 /**
  * A wrapper class to mark strings as "safe" (already sanitized or trusted).
+ *
+ * @class SafeHTML
+ * @property {string} value - The safe HTML string
+ *
+ * @example
+ * ```typescript
+ * const safe = new SafeHTML('<div>Trusted content</div>');
+ * console.log(safe.value); // '<div>Trusted content</div>'
+ * ```
+ *
+ * @remarks
+ * - Used internally by the `html` template tag
+ * - Signals that content doesn't need escaping
+ * - Should only be created from trusted sources
  */
 export declare class SafeHTML {
     readonly value: string;
+    /**
+     * Creates a SafeHTML instance.
+     * @param {string} value - HTML string that is already sanitized or trusted
+     */
     constructor(value: string);
+    /**
+     * Returns the safe HTML string.
+     * @returns {string} The HTML string
+     */
     toString(): string;
 }
 /**
  * A tagged template literal for safely generating HTML strings.
- * It automatically escapes values unless they are already valid `SafeHTML`.
- * * Usage:
- * const content = html`<div>${userInput}</div>`;
+ *
+ * Automatically escapes interpolated values to prevent XSS attacks,
+ * unless they are wrapped in `SafeHTML` or `unsafeHTML()`.
+ *
+ * @template T - Type of interpolated values
+ * @param {TemplateStringsArray} strings - Template string parts
+ * @param {...any[]} values - Interpolated values to insert
+ * @returns {SafeHTML} SafeHTML instance containing the generated HTML
+ *
+ * @throws {TypeError} If values cannot be converted to strings
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with escaping
+ * const userInput = '<script>alert("xss")</script>';
+ * const safeHtml = html`<div>${userInput}</div>`;
+ * // Result: '<div>&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;</div>'
+ *
+ * // With SafeHTML (no escaping)
+ * const trusted = unsafeHTML('<em>italic</em>');
+ * const html = html`<div>${trusted}</div>`;
+ * // Result: '<div><em>italic</em></div>'
+ *
+ * // With arrays
+ * const items = ['apple', 'banana', 'cherry'];
+ * const list = html`<ul>${items.map(item => html`<li>${item}</li>`)}</ul>`;
+ * ```
+ *
+ * @remarks
+ * - Always escapes strings unless they're SafeHTML instances
+ * - Handles arrays by recursively processing each item
+ * - Returns SafeHTML object for type safety
+ * - Follows the same pattern as lit-html or hyperHTML
+ *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates}
+ * @see {@link unsafeHTML} for escape hatch
  */
 export declare const html: (strings: TemplateStringsArray, ...values: any[]) => SafeHTML;
 /**
- * An escape hatch to treat a string as safe HTML.
- * WARNING: Only use this with trusted content.
+ * An escape hatch to treat a string as safe HTML without escaping.
+ *
+ * ⚠️ **WARNING**: Only use this with content you completely trust.
+ * Never use with user input, database content, or external data.
+ *
+ * @param {string} str - Trusted HTML string that doesn't need escaping
+ * @returns {SafeHTML} SafeHTML wrapper marking the string as safe
+ *
+ * @example
+ * ```typescript
+ * // ✅ Safe usage - hardcoded content
+ * const icon = unsafeHTML('<svg>...</svg>');
+ *
+ * // ❌ DANGEROUS - user input
+ * const userContent = getUserInput();
+ * const dangerous = unsafeHTML(userContent); // XSS vulnerability!
+ *
+ * // ✅ Safe pattern with sanitization
+ * const sanitized = sanitizeHTML(userInput);
+ * const safe = unsafeHTML(sanitized);
+ * ```
+ *
+ * @remarks
+ * - Consider using a proper HTML sanitizer like DOMPurify
+ * - Review usage of this function during security audits
+ * - Prefer `html` template tag for automatic escaping
+ *
+ * @see {@link https://github.com/cure53/DOMPurify} for HTML sanitization
+ * @see {@link html} for safe template literals
  */
 export declare const unsafeHTML: (str: string) => SafeHTML;

package/dist/index.cjs

@@ -2,9 +2,13 @@
 
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
-const utilities = require('./utilities.cjs');
+const utilities_delay = require('./utilities/delay.cjs');
+const utilities_isBrowser = require('./utilities/isBrowser.cjs');
+const utilities_makeReactive = require('./utilities/makeReactive.cjs');
+const utilities_toKebabCase = require('./utilities/toKebabCase.cjs');
 const decorators_defineElement = require('./decorators/defineElement.cjs');
 const decorators_event = require('./decorators/event.cjs');
+const decorators_mixin = require('./decorators/mixin.cjs');
 const decorators_property = require('./decorators/property.cjs');
 const decorators_refs = require('./decorators/refs.cjs');
 const decorators_state = require('./decorators/state.cjs');
@@ -12,14 +16,15 @@ const decorators_types = require('./decorators/types.cjs');
 const dom = require('./dom.cjs');
 const html = require('./html.cjs');
 
-function _assert_this_initialized(self){if(self===void 0){throw new ReferenceError("this hasn't been initialised - super() hasn't been called")}return self}function _call_super(_this,derived,args){derived=_get_prototype_of(derived);return _possible_constructor_return(_this,_is_native_reflect_construct()?Reflect.construct(derived,args||[],_get_prototype_of(_this).constructor):derived.apply(_this,args))}function _class_call_check(instance,Constructor){if(!(instance instanceof Constructor)){throw new TypeError("Cannot call a class as a function")}}function _defineProperties(target,props){for(var i=0;i<props.length;i++){var descriptor=props[i];descriptor.enumerable=descriptor.enumerable||false;descriptor.configurable=true;if("value"in descriptor)descriptor.writable=true;Object.defineProperty(target,descriptor.key,descriptor);}}function _create_class(Constructor,protoProps,staticProps){if(protoProps)_defineProperties(Constructor.prototype,protoProps);return Constructor}function _get(target,property,receiver){if(typeof Reflect!=="undefined"&&Reflect.get){_get=Reflect.get;}else {_get=function get(target,property,receiver){var base=_super_prop_base(target,property);if(!base)return;var desc=Object.getOwnPropertyDescriptor(base,property);if(desc.get){return desc.get.call(receiver||target)}return desc.value};}return _get(target,property,receiver||target)}function _get_prototype_of(o){_get_prototype_of=Object.setPrototypeOf?Object.getPrototypeOf:function getPrototypeOf(o){return o.__proto__||Object.getPrototypeOf(o)};return _get_prototype_of(o)}function _inherits(subClass,superClass){if(typeof superClass!=="function"&&superClass!==null){throw new TypeError("Super expression must either be null or a function")}subClass.prototype=Object.create(superClass&&superClass.prototype,{constructor:{value:subClass,writable:true,configurable:true}});if(superClass)_set_prototype_of(subClass,superClass);}function _possible_constructor_return(self,call){if(call&&(_type_of(call)==="object"||typeof call==="function")){return call}return _assert_this_initialized(self)}function _set_prototype_of(o,p){_set_prototype_of=Object.setPrototypeOf||function setPrototypeOf(o,p){o.__proto__=p;return o};return _set_prototype_of(o,p)}function _super_prop_base(object,property){while(!Object.prototype.hasOwnProperty.call(object,property)){object=_get_prototype_of(object);if(object===null)break}return object}function _type_of(obj){"@swc/helpers - typeof";return obj&&typeof Symbol!=="undefined"&&obj.constructor===Symbol?"symbol":typeof obj}function _is_native_reflect_construct(){try{var result=!Boolean.prototype.valueOf.call(Reflect.construct(Boolean,[],function(){}));}catch(_){}return (_is_native_reflect_construct=function(){return !!result})()}function Zui(Base){return /*#__PURE__*/function(Base){_inherits(ZuiElement,Base);function ZuiElement(){_class_call_check(this,ZuiElement);return _call_super(this,ZuiElement,arguments)}_create_class(ZuiElement,[{key:"addEventListener",value:function addEventListener(type,listener,options){_get(_get_prototype_of(ZuiElement.prototype),"addEventListener",this).call(this,type,listener,options);}}]);return ZuiElement}(Base)}
 
-exports.delay = utilities.delay;
-exports.isBrowser = utilities.isBrowser;
-exports.makeReactive = utilities.makeReactive;
-exports.toKebabCase = utilities.toKebabCase;
+
+exports.delay = utilities_delay.delay;
+exports.isBrowser = utilities_isBrowser.isBrowser;
+exports.makeReactive = utilities_makeReactive.makeReactive;
+exports.toKebabCase = utilities_toKebabCase.toKebabCase;
 exports.defineElement = decorators_defineElement.defineElement;
 exports.event = decorators_event.event;
+exports.Zui = decorators_mixin.Zui;
 exports.property = decorators_property.property;
 exports.ref = decorators_refs.ref;
 exports.state = decorators_state.state;
@@ -28,4 +33,3 @@ exports.createElement = dom.createElement;
 exports.SafeHTML = html.SafeHTML;
 exports.html = html.html;
 exports.unsafeHTML = html.unsafeHTML;
-exports.Zui = Zui;