@bquery/bquery 1.2.0 → 1.4.0

package/README.md

@@ -14,6 +14,7 @@
 [![Bundle Size](https://img.shields.io/bundlephobia/minzip/@bquery/bquery)](https://bundlephobia.com/package/@bquery/bquery)
 [![unpkg](https://img.shields.io/badge/unpkg-browse-blue?logo=unpkg)](https://unpkg.com/@bquery/bquery)
 [![CodeFactor](https://www.codefactor.io/repository/github/bquery/bquery/badge)](https://www.codefactor.io/repository/github/bquery/bquery)
+[![JsDelivr](https://data.jsdelivr.com/v1/package/npm/@bquery/bquery/badge)](https://www.jsdelivr.com/package/npm/@bquery/bquery)
 
 **The jQuery for the modern Web Platform.**
 
@@ -84,30 +85,33 @@ import { $, signal, component } from '@bquery/bquery';
 // Core only
 import { $, $$ } from '@bquery/bquery/core';
 
+// Core utilities (named exports, tree-shakeable)
+import { debounce, merge, uid, once, utils } from '@bquery/bquery/core';
+
 // À la carte (individual modules)
-import { signal, computed, effect } from '@bquery/bquery/reactive';
-import { component, html } from '@bquery/bquery/component';
-import { transition, spring } from '@bquery/bquery/motion';
+import { signal, computed, effect, linkedSignal, persistedSignal } from '@bquery/bquery/reactive';
+import { component, defineComponent, html } from '@bquery/bquery/component';
+import { transition, spring, animate, timeline } from '@bquery/bquery/motion';
 import { sanitize } from '@bquery/bquery/security';
 import { storage, cache } from '@bquery/bquery/platform';
 import { createRouter, navigate } from '@bquery/bquery/router';
-import { createStore } from '@bquery/bquery/store';
-import { mount } from '@bquery/bquery/view';
+import { createStore, defineStore } from '@bquery/bquery/store';
+import { mount, createTemplate } from '@bquery/bquery/view';
 ```
 
 ## Modules at a glance
 
-| Module        | Description                                    | Size (gzip) |
-| ------------- | ---------------------------------------------- | ----------- |
-| **Core**      | Selectors, DOM manipulation, events, utilities | ~7.7 KB     |
-| **Reactive**  | `signal`, `computed`, `effect`, `batch`        | ~1.2 KB     |
-| **Component** | Lightweight Web Components with props          | ~1.5 KB     |
-| **Motion**    | View transitions, FLIP animations, springs     | ~1.2 KB     |
-| **Security**  | HTML sanitizing, Trusted Types, CSP            | ~2.2 KB     |
-| **Platform**  | Storage, cache, notifications, buckets         | ~1.6 KB     |
-| **Router**    | SPA routing, navigation guards, history API    | ~2 KB       |
-| **Store**     | Signal-based state management, persistence     | ~1.5 KB     |
-| **View**      | Declarative DOM bindings, directives           | ~2.6 KB     |
+| Module        | Description                                        | Size (gzip) |
+| ------------- | -------------------------------------------------- | ----------- |
+| **Core**      | Selectors, DOM manipulation, events, utilities     | ~11.3 KB    |
+| **Reactive**  | `signal`, `computed`, `effect`, `batch`            | ~0.3 KB     |
+| **Component** | Lightweight Web Components with props              | ~1.9 KB     |
+| **Motion**    | View transitions, FLIP, timelines, scroll, springs | ~4.0 KB     |
+| **Security**  | HTML sanitizing, Trusted Types, CSP                | ~0.7 KB     |
+| **Platform**  | Storage, cache, notifications, buckets             | ~2.2 KB     |
+| **Router**    | SPA routing, navigation guards, history API        | ~2.2 KB     |
+| **Store**     | Signal-based state management, persistence         | ~0.3 KB     |
+| **View**      | Declarative DOM bindings, directives               | ~4.3 KB     |
 
 ## Quick examples
 
@@ -129,9 +133,20 @@ $('#list').delegate('click', '.item', (event, target) => {
 // Method chaining
 $('#box').addClass('active').css({ opacity: '0.8' }).attr('data-state', 'ready');
 
+// CSS getter (computed style)
+const color = $('#box').css('color'); // Returns computed style value
+
+// Selector matching
+if ($('#el').is('.active')) {
+  console.log('Element is active');
+}
+
 // DOM manipulation
-$('#content').wrap('<div class="wrapper"></div>');
-$('#wrapper').unwrap(); // Remove parent wrapper
+$('#content').wrap('div');
+$('#content').unwrap(); // Remove parent wrapper
+
+// Attribute helpers
+$('#dialog').toggleAttr('open');
 
 // Smooth scrolling
 $('#section').scrollTo({ behavior: 'smooth' });
@@ -142,12 +157,22 @@ const queryString = $('form').serializeString(); // Returns URL-encoded string
 
 // Collections
 $$('.items').addClass('highlight');
+$$('.items').append('<li class="item">New</li>');
+$$('.container').find('.item').addClass('found'); // Find descendants across collection
 ```
 
 ### Reactive – signals
 
 ```ts
-import { signal, computed, effect, batch, watch, readonly } from '@bquery/bquery/reactive';
+import {
+  signal,
+  computed,
+  effect,
+  batch,
+  watch,
+  readonly,
+  linkedSignal,
+} from '@bquery/bquery/reactive';
 
 const count = signal(0);
 const doubled = computed(() => count.value * 2);
@@ -169,12 +194,29 @@ batch(() => {
   count.value++;
   count.value++;
 });
+
+// Dispose signal (remove all subscribers)
+count.dispose();
+
+// Writable computed (linked signal)
+const first = signal('Ada');
+const last = signal('Lovelace');
+const fullName = linkedSignal(
+  () => `${first.value} ${last.value}`,
+  (next) => {
+    const [nextFirst, nextLast] = next.split(' ');
+    first.value = nextFirst ?? '';
+    last.value = nextLast ?? '';
+  }
+);
+
+fullName.value = 'Grace Hopper';
 ```
 
 ### Components – Web Components
 
 ```ts
-import { component, html } from '@bquery/bquery/component';
+import { component, defineComponent, html } from '@bquery/bquery/component';
 
 component('user-card', {
   props: {
@@ -199,18 +241,31 @@ component('user-card', {
     return html`<div>Hello ${props.username}</div>`;
   },
 });
+
+// Optional: create the class without auto-registration
+const UserCard = defineComponent('user-card', {
+  props: { username: { type: String, required: true } },
+  render: ({ props }) => html`<div>Hello ${props.username}</div>`,
+});
+customElements.define('user-card', UserCard);
 ```
 
 ### Motion – animations
 
 ```ts
-import { transition, spring } from '@bquery/bquery/motion';
+import { animate, keyframePresets, spring, transition } from '@bquery/bquery/motion';
 
 // View transitions (with fallback)
 await transition(() => {
   $('#content').text('Updated');
 });
 
+// Web Animations helper
+await animate(card, {
+  keyframes: keyframePresets.pop(),
+  options: { duration: 240, easing: 'ease-out' },
+});
+
 // Spring physics
 const x = spring(0, { stiffness: 120, damping: 14 });
 x.onChange((value) => {
@@ -221,6 +276,8 @@ await x.to(100);
 
 ### Security – sanitizing
 
+Internally modularized (sanitize core, Trusted Types, CSP helpers) — the public API remains unchanged. For legacy deep imports, `@bquery/bquery/security/sanitize` also re-exports `generateNonce()` and `isTrustedTypesSupported()`.
+
 ```ts
 import { sanitize, escapeHtml } from '@bquery/bquery/security';
 
@@ -236,6 +293,12 @@ const urlSafe = sanitize('<a href="java\u200Bscript:alert(1)">click</a>');
 // Automatic link security (adds rel="noopener noreferrer" to external/target="_blank" links)
 const secureLink = sanitize('<a href="https://external.com" target="_blank">Link</a>');
 
+// srcset validation (per-URL; entire attribute removed if any entry is unsafe)
+const safeSrcset = sanitize('<img srcset="safe.jpg 1x, javascript:alert(1) 2x">'); // <img>
+
+// Form action validation (blocks javascript: protocol)
+const safeForm = sanitize('<form action="javascript:alert(1)">...</form>');
+
 // Escape for text display
 const escaped = escapeHtml('<script>alert(1)</script>');
 ```
@@ -261,6 +324,8 @@ if (permission === 'granted') {
 
 ### Router – SPA navigation
 
+Internally, the router has been split into focused submodules (matching, navigation, state, links, utilities) with no public API changes.
+
 ```ts
 import { createRouter, navigate, currentRoute } from '@bquery/bquery/router';
 
@@ -297,8 +362,8 @@ effect(() => {
 ```ts
 import { createStore, createPersistedStore } from '@bquery/bquery/store';
 
-// Define a store
-const useCounter = createStore({
+// Create a store (returns the store instance directly)
+const counterStore = createStore({
   id: 'counter',
   state: () => ({ count: 0, name: 'Counter' }),
   getters: {
@@ -315,19 +380,46 @@ const useCounter = createStore({
 });
 
 // Use the store
-const counter = useCounter;
-counter.increment();
-console.log(counter.doubled); // Reactive getter
+counterStore.increment();
+console.log(counterStore.doubled); // Reactive getter
 
 // Persisted store (localStorage)
-const useSettings = createPersistedStore({
+const settingsStore = createPersistedStore({
   id: 'settings',
   state: () => ({ theme: 'dark', language: 'en' }),
 });
+
+// Factory-style store definition (Pinia-style)
+import { defineStore, mapGetters, watchStore } from '@bquery/bquery/store';
+
+const useCounter = defineStore('counter', {
+  state: () => ({ count: 0 }),
+  getters: {
+    doubled: (state) => state.count * 2,
+  },
+  actions: {
+    increment() {
+      this.count++;
+    },
+  },
+});
+
+const counter = useCounter();
+const getters = mapGetters(counter, ['doubled']);
+
+watchStore(
+  counter,
+  (state) => state.count,
+  (value) => {
+    console.log('Count changed:', value, getters.doubled);
+  }
+);
 ```
 
 ### View – declarative bindings
 
+Internally modularized into focused submodules; the public API remains unchanged.
+
 ```ts
 import { mount, createTemplate } from '@bquery/bquery/view';
 import { signal } from '@bquery/bquery/reactive';
@@ -422,6 +514,14 @@ bQuery.js
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
+## AI Agent Support
+
+This project provides dedicated context files for AI coding agents:
+
+- **[AGENT.md](AGENT.md)** — Architecture, module API reference, coding conventions, common tasks
+- **[llms.txt](llms.txt)** — Compact LLM-optimized project summary
+- **[.github/copilot-instructions.md](.github/copilot-instructions.md)** — GitHub Copilot context
+
 ## License
 
 MIT – See [LICENSE.md](LICENSE.md) for details.

package/dist/batch-x7b2eZST.js

@@ -0,0 +1,13 @@
+import { e as t, b } from "./core-BhpuvPhy.js";
+const e = (a) => {
+  b();
+  try {
+    a();
+  } finally {
+    t();
+  }
+};
+export {
+  e as b
+};
+//# sourceMappingURL=batch-x7b2eZST.js.map

package/dist/batch-x7b2eZST.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-x7b2eZST.js","sources":["../src/reactive/batch.ts"],"sourcesContent":["/**\n * Batched reactive updates.\n */\n\nimport { beginBatch, endBatch } from './internals';\n\n/**\n * Batches multiple signal updates into a single notification cycle.\n *\n * Updates made inside the batch function are deferred until the batch\n * completes, preventing intermediate re-renders and improving performance.\n *\n * @param fn - Function containing multiple signal updates\n */\nexport const batch = (fn: () => void): void => {\n  beginBatch();\n  try {\n    fn();\n  } finally {\n    endBatch();\n  }\n};\n"],"names":["batch","fn","beginBatch","endBatch"],"mappings":";AAcO,MAAMA,IAAQ,CAACC,MAAyB;AAC7C,EAAAC,EAAA;AACA,MAAI;AACF,IAAAD,EAAA;AAAA,EACF,UAAA;AACE,IAAAE,EAAA;AAAA,EACF;AACF;"}

package/dist/component/component.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Web Component factory and registry.
+ *
+ * @module bquery/component
+ */
+import type { ComponentDefinition } from './types';
+/**
+ * Creates a custom element class for a component definition.
+ *
+ * This is useful when you want to extend or register the class manually
+ * (e.g. with different tag names in tests or custom registries).
+ *
+ * @template TProps - Type of the component's props
+ * @param tagName - The custom element tag name (used for diagnostics)
+ * @param definition - The component configuration
+ */
+export declare const defineComponent: <TProps extends Record<string, unknown>>(tagName: string, definition: ComponentDefinition<TProps>) => typeof HTMLElement;
+/**
+ * Defines and registers a custom Web Component.
+ *
+ * This function creates a new custom element with the given tag name
+ * and configuration. The component uses Shadow DOM for encapsulation
+ * and automatically re-renders when observed attributes change.
+ *
+ * @template TProps - Type of the component's props
+ * @param tagName - The custom element tag name (must contain a hyphen)
+ * @param definition - The component configuration
+ *
+ * @example
+ * ```ts
+ * component('counter-button', {
+ *   props: {
+ *     start: { type: Number, default: 0 },
+ *   },
+ *   state: { count: 0 },
+ *   styles: `
+ *     button { padding: 0.5rem 1rem; }
+ *   `,
+ *   connected() {
+ *     // Use event delegation on shadow root so handler survives re-renders
+ *     const handleClick = (event: Event) => {
+ *       const target = event.target as HTMLElement | null;
+ *       if (target?.matches('button')) {
+ *         this.setState('count', (this.getState('count') as number) + 1);
+ *       }
+ *     };
+ *     this.shadowRoot?.addEventListener('click', handleClick);
+ *     // Store handler for cleanup
+ *     (this as any)._handleClick = handleClick;
+ *   },
+ *   disconnected() {
+ *     // Clean up event listener to prevent memory leaks
+ *     const handleClick = (this as any)._handleClick;
+ *     if (handleClick) {
+ *       this.shadowRoot?.removeEventListener('click', handleClick);
+ *     }
+ *   },
+ *   render({ props, state }) {
+ *     return html`
+ *       <button>
+ *         Count: ${state.count}
+ *       </button>
+ *     `;
+ *   },
+ * });
+ * ```
+ */
+export declare const component: <TProps extends Record<string, unknown>>(tagName: string, definition: ComponentDefinition<TProps>) => void;
+//# sourceMappingURL=component.d.ts.map

package/dist/component/component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../src/component/component.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAkB,MAAM,SAAS,CAAC;AAEnE;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpE,SAAS,MAAM,EACf,YAAY,mBAAmB,CAAC,MAAM,CAAC,KACtC,OAAO,WA4MT,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,eAAO,MAAM,SAAS,GAAI,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9D,SAAS,MAAM,EACf,YAAY,mBAAmB,CAAC,MAAM,CAAC,KACtC,IAMF,CAAC"}

package/dist/component/html.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Tagged template literal for creating HTML strings.
+ *
+ * This function handles interpolation of values into HTML templates,
+ * converting null/undefined to empty strings.
+ *
+ * @param strings - Template literal string parts
+ * @param values - Interpolated values
+ * @returns Combined HTML string
+ *
+ * @example
+ * ```ts
+ * const name = 'World';
+ * const greeting = html`<h1>Hello, ${name}!</h1>`;
+ * // Result: '<h1>Hello, World!</h1>'
+ * ```
+ */
+export declare const html: (strings: TemplateStringsArray, ...values: unknown[]) => string;
+/**
+ * Escapes HTML entities in interpolated values for XSS prevention.
+ * Use this when you need to safely embed user content in templates.
+ *
+ * @param strings - Template literal string parts
+ * @param values - Interpolated values to escape
+ * @returns Combined HTML string with escaped values
+ *
+ * @example
+ * ```ts
+ * const userInput = '<script>alert("xss")</script>';
+ * const safe = safeHtml`<div>${userInput}</div>`;
+ * // Result: '<div>&lt;script&gt;alert("xss")&lt;/script&gt;</div>'
+ * ```
+ */
+export declare const safeHtml: (strings: TemplateStringsArray, ...values: unknown[]) => string;
+//# sourceMappingURL=html.d.ts.map

package/dist/component/html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html.d.ts","sourceRoot":"","sources":["../../src/component/html.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,IAAI,GAAI,SAAS,oBAAoB,EAAE,GAAG,QAAQ,OAAO,EAAE,KAAG,MAE1E,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,QAAQ,GAAI,SAAS,oBAAoB,EAAE,GAAG,QAAQ,OAAO,EAAE,KAAG,MAgB9E,CAAC"}

package/dist/component/index.d.ts

@@ -34,130 +34,7 @@
  * });
  * ```
  */
-/**
- * Defines a single prop's type and configuration.
- *
- * @template T - The TypeScript type of the prop value
- *
- * @example
- * ```ts
- * const myProp: PropDefinition<number> = {
- *   type: Number,
- *   required: false,
- *   default: 0,
- * };
- * ```
- */
-export type PropDefinition<T = unknown> = {
-    /** Constructor or converter function for the prop type */
-    type: StringConstructor | NumberConstructor | BooleanConstructor | ObjectConstructor | ArrayConstructor | {
-        new (value: unknown): T;
-    } | ((value: unknown) => T);
-    /** Whether the prop must be provided */
-    required?: boolean;
-    /** Default value when prop is not provided */
-    default?: T;
-    /** Optional validator function to validate prop values */
-    validator?: (value: T) => boolean;
-};
-/**
- * Complete component definition including props, state, styles, and lifecycle.
- *
- * @template TProps - Type of the component's props
- */
-export type ComponentDefinition<TProps extends Record<string, unknown> = Record<string, unknown>> = {
-    /** Prop definitions with types and defaults */
-    props?: Record<keyof TProps, PropDefinition>;
-    /** Initial internal state */
-    state?: Record<string, unknown>;
-    /** CSS styles scoped to the component's shadow DOM */
-    styles?: string;
-    /** Lifecycle hook called before the component mounts (before first render) */
-    beforeMount?: () => void;
-    /** Lifecycle hook called when component is added to DOM */
-    connected?: () => void;
-    /** Lifecycle hook called when component is removed from DOM */
-    disconnected?: () => void;
-    /** Lifecycle hook called before an update render; return false to prevent */
-    beforeUpdate?: (props: TProps) => boolean | void;
-    /** Lifecycle hook called after reactive updates trigger a render */
-    updated?: () => void;
-    /** Error handler for errors during rendering or lifecycle */
-    onError?: (error: Error) => void;
-    /** Render function returning HTML string */
-    render: (context: {
-        props: TProps;
-        state: Record<string, unknown>;
-        emit: (event: string, detail?: unknown) => void;
-    }) => string;
-};
-/**
- * Tagged template literal for creating HTML strings.
- *
- * This function handles interpolation of values into HTML templates,
- * converting null/undefined to empty strings.
- *
- * @param strings - Template literal string parts
- * @param values - Interpolated values
- * @returns Combined HTML string
- *
- * @example
- * ```ts
- * const name = 'World';
- * const greeting = html`<h1>Hello, ${name}!</h1>`;
- * // Result: '<h1>Hello, World!</h1>'
- * ```
- */
-export declare const html: (strings: TemplateStringsArray, ...values: unknown[]) => string;
-/**
- * Escapes HTML entities in interpolated values for XSS prevention.
- * Use this when you need to safely embed user content in templates.
- *
- * @param strings - Template literal string parts
- * @param values - Interpolated values to escape
- * @returns Combined HTML string with escaped values
- *
- * @example
- * ```ts
- * const userInput = '<script>alert("xss")</script>';
- * const safe = safeHtml`<div>${userInput}</div>`;
- * // Result: '<div>&lt;script&gt;alert("xss")&lt;/script&gt;</div>'
- * ```
- */
-export declare const safeHtml: (strings: TemplateStringsArray, ...values: unknown[]) => string;
-/**
- * Defines and registers a custom Web Component.
- *
- * This function creates a new custom element with the given tag name
- * and configuration. The component uses Shadow DOM for encapsulation
- * and automatically re-renders when observed attributes change.
- *
- * @template TProps - Type of the component's props
- * @param tagName - The custom element tag name (must contain a hyphen)
- * @param definition - The component configuration
- *
- * @example
- * ```ts
- * component('counter-button', {
- *   props: {
- *     start: { type: Number, default: 0 },
- *   },
- *   state: { count: 0 },
- *   styles: `
- *     button { padding: 0.5rem 1rem; }
- *   `,
- *   connected() {
- *     console.log('Counter mounted');
- *   },
- *   render({ props, state, emit }) {
- *     return html`
- *       <button onclick="this.getRootNode().host.increment()">
- *         Count: ${state.count}
- *       </button>
- *     `;
- *   },
- * });
- * ```
- */
-export declare const component: <TProps extends Record<string, unknown>>(tagName: string, definition: ComponentDefinition<TProps>) => void;
+export { component, defineComponent } from './component';
+export { html, safeHtml } from './html';
+export type { ComponentDefinition, ComponentRenderContext, PropDefinition } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/component/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/component/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,GAAG,OAAO,IAAI;IACxC,0DAA0D;IAC1D,IAAI,EACA,iBAAiB,GACjB,iBAAiB,GACjB,kBAAkB,GAClB,iBAAiB,GACjB,gBAAgB,GAChB;QAAE,KAAK,KAAK,EAAE,OAAO,GAAG,CAAC,CAAA;KAAE,GAC3B,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,CAAC,CAAC;IAC5B,wCAAwC;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,CAAC,CAAC;IACZ,0DAA0D;IAC1D,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;CACnC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAC9F;IACE,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,MAAM,EAAE,cAAc,CAAC,CAAC;IAC7C,6BAA6B;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,6EAA6E;IAC7E,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,CAAC;IACjD,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,4CAA4C;IAC5C,MAAM,EAAE,CAAC,OAAO,EAAE;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC/B,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;KACjD,KAAK,MAAM,CAAC;CACd,CAAC;AAsDJ;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,IAAI,GAAI,SAAS,oBAAoB,EAAE,GAAG,QAAQ,OAAO,EAAE,KAAG,MAE1E,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,QAAQ,GAAI,SAAS,oBAAoB,EAAE,GAAG,QAAQ,OAAO,EAAE,KAAG,MAgB9E,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,SAAS,GAAI,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9D,SAAS,MAAM,EACf,YAAY,mBAAmB,CAAC,MAAM,CAAC,KACtC,IAwKF,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/component/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACxC,YAAY,EAAE,mBAAmB,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC"}

package/dist/component/props.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Prop coercion utilities.
+ *
+ * @module bquery/component
+ */
+import type { PropDefinition } from './types';
+/**
+ * Coerces a string attribute value into a typed prop value.
+ * Supports String, Number, Boolean, Object, Array, and custom converters.
+ *
+ * @internal
+ * @template T - The target type
+ * @param rawValue - The raw string value from the attribute
+ * @param config - The prop definition with type information
+ * @returns The coerced value of type T
+ */
+export declare const coercePropValue: <T>(rawValue: string, config: PropDefinition<T>) => T;
+//# sourceMappingURL=props.d.ts.map

package/dist/component/props.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"props.d.ts","sourceRoot":"","sources":["../../src/component/props.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,EAAE,UAAU,MAAM,EAAE,QAAQ,cAAc,CAAC,CAAC,CAAC,KAAG,CAiGhF,CAAC"}

package/dist/component/types.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Component types and render context definitions.
+ *
+ * @module bquery/component
+ */
+/**
+ * Defines a single prop's type and configuration.
+ *
+ * @template T - The TypeScript type of the prop value
+ *
+ * @example
+ * ```ts
+ * const myProp: PropDefinition<number> = {
+ *   type: Number,
+ *   required: false,
+ *   default: 0,
+ * };
+ * ```
+ */
+export type PropDefinition<T = unknown> = {
+    /** Constructor or converter function for the prop type */
+    type: StringConstructor | NumberConstructor | BooleanConstructor | ObjectConstructor | ArrayConstructor | {
+        new (value: unknown): T;
+    } | ((value: unknown) => T);
+    /** Whether the prop must be provided */
+    required?: boolean;
+    /** Default value when prop is not provided */
+    default?: T;
+    /** Optional validator function to validate prop values */
+    validator?: (value: T) => boolean;
+    /**
+     * Explicitly control whether to invoke `type` with `new` (constructor) or as a plain function.
+     * - `true`: Always use `new type(value)` (for class constructors, Date, etc.)
+     * - `false`: Always call `type(value)` (for converter functions)
+     * - `undefined` (default): Auto-detect based on heuristics with fallback
+     */
+    construct?: boolean;
+};
+/**
+ * Render context passed into a component render function.
+ */
+export type ComponentRenderContext<TProps extends Record<string, unknown>> = {
+    /** Typed props object populated from attributes */
+    props: TProps;
+    /** Internal mutable state object */
+    state: Record<string, unknown>;
+    /** Emit a custom event from the component */
+    emit: (event: string, detail?: unknown) => void;
+};
+/**
+ * Complete component definition including props, state, styles, and lifecycle.
+ *
+ * @template TProps - Type of the component's props
+ */
+export type ComponentDefinition<TProps extends Record<string, unknown> = Record<string, unknown>> = {
+    /** Prop definitions with types and defaults */
+    props?: Record<keyof TProps, PropDefinition>;
+    /** Initial internal state */
+    state?: Record<string, unknown>;
+    /** CSS styles scoped to the component's shadow DOM */
+    styles?: string;
+    /** Lifecycle hook called before the component mounts (before first render) */
+    beforeMount?: () => void;
+    /** Lifecycle hook called when component is added to DOM */
+    connected?: () => void;
+    /** Lifecycle hook called when component is removed from DOM */
+    disconnected?: () => void;
+    /** Lifecycle hook called before an update render; return false to prevent */
+    beforeUpdate?: (props: TProps) => boolean | void;
+    /** Lifecycle hook called after reactive updates trigger a render */
+    updated?: () => void;
+    /** Error handler for errors during rendering or lifecycle */
+    onError?: (error: Error) => void;
+    /** Render function returning HTML string */
+    render: (context: ComponentRenderContext<TProps>) => string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/component/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/component/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,GAAG,OAAO,IAAI;IACxC,0DAA0D;IAC1D,IAAI,EACA,iBAAiB,GACjB,iBAAiB,GACjB,kBAAkB,GAClB,iBAAiB,GACjB,gBAAgB,GAChB;QAAE,KAAK,KAAK,EAAE,OAAO,GAAG,CAAC,CAAA;KAAE,GAC3B,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,CAAC,CAAC;IAC5B,wCAAwC;IACxC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,CAAC,CAAC;IACZ,0DAA0D;IAC1D,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;IAClC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,sBAAsB,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IAC3E,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,6CAA6C;IAC7C,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CACjD,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAC9F;IACE,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,MAAM,EAAE,cAAc,CAAC,CAAC;IAC7C,6BAA6B;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,IAAI,CAAC;IACzB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,6EAA6E;IAC7E,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,CAAC;IACjD,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,4CAA4C;IAC5C,MAAM,EAAE,CAAC,OAAO,EAAE,sBAAsB,CAAC,MAAM,CAAC,KAAK,MAAM,CAAC;CAC7D,CAAC"}