@context-action/lit-ui 0.0.0-stage → 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1636 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+// \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+let lit = require("lit");
+let lit_decorators_js = require("lit/decorators.js");
+let _lit_context = require("@lit/context");
+let react = require("react");
+react = __toESM(react, 1);
+let _context_action_lit = require("@context-action/lit");
+// \0@oxc-project+runtime@0.155.0/helpers/esm/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+// src/form-associated-element.ts
+/**
+* @fileoverview Abstract Form-Associated Custom Element (FACE) base class extending LitElement.
+* Provides ElementInternals integration, standard constraint validation, form value management,
+* and robust form reset lifecycle hooks across browser and headless (JSDOM/SSR) environments.
+*
+* @implements view-layer
+* @implements web-component-primitive
+* @memberof core-concepts
+*/
+/**
+* Synthesizes an immutable ValidityState object from a set of ValidityStateFlags.
+* Used as a high-fidelity fallback when ElementInternals.validity is unavailable in the environment.
+*/
+function createSyntheticValidityState(flags) {
+	const badInput = !!flags.badInput;
+	const customError = !!flags.customError;
+	const patternMismatch = !!flags.patternMismatch;
+	const rangeOverflow = !!flags.rangeOverflow;
+	const rangeUnderflow = !!flags.rangeUnderflow;
+	const stepMismatch = !!flags.stepMismatch;
+	const tooLong = !!flags.tooLong;
+	const tooShort = !!flags.tooShort;
+	const typeMismatch = !!flags.typeMismatch;
+	const valueMissing = !!flags.valueMissing;
+	return {
+		badInput,
+		customError,
+		patternMismatch,
+		rangeOverflow,
+		rangeUnderflow,
+		stepMismatch,
+		tooLong,
+		tooShort,
+		typeMismatch,
+		valid: !(badInput || customError || patternMismatch || rangeOverflow || rangeUnderflow || stepMismatch || tooLong || tooShort || typeMismatch || valueMissing),
+		valueMissing
+	};
+}
+/**
+* Abstract Form-Associated Custom Element (FACE) base class extending LitElement.
+*
+* Provides:
+* - Native form participation via `ElementInternals` and `static formAssociated = true`
+* - Defensive fallbacks for server-side rendering (SSR) and headless test environments (JSDOM)
+* - Complete Form value management (`setFormValue`, `getFormValue`, `formValue`)
+* - Constraint validation APIs (`setValidity`, `validity`, `validationMessage`, `checkValidity`, `reportValidity`, `setCustomValidity`)
+* - Lifecycle callbacks (`formResetCallback`, `formDisabledCallback`, `formStateRestoreCallback`, `formAssociatedCallback`)
+* - Standard overridable hooks (`onFormReset`, `onFormDisabled`, `onFormStateRestore`, `onFormAssociated`)
+* - Automatic form reset event synchronization and leak-free unbinding on disconnect
+*/
+var FormAssociatedLitElement = class extends lit.LitElement {
+	static {
+		this.formAssociated = true;
+	}
+	#formValue;
+	#formState;
+	#validityFlags;
+	#validationMessage;
+	#customError;
+	#isResetting;
+	#associatedForm;
+	constructor() {
+		super();
+		this.name = "";
+		this.type = "custom-field";
+		this.disabled = false;
+		this.required = false;
+		this.#formValue = null;
+		this.#formState = null;
+		this.#validityFlags = {};
+		this.#validationMessage = "";
+		this.#customError = false;
+		this.#isResetting = false;
+		this.#associatedForm = null;
+		this.#handleFormReset = (event) => {
+			if (this.#isResetting || event.defaultPrevented) return;
+			queueMicrotask(() => {
+				if (this.#isResetting || event.defaultPrevented) return;
+				this.formResetCallback();
+			});
+		};
+		if (typeof this.attachInternals === "function") try {
+			this.internals = this.attachInternals();
+		} catch {}
+	}
+	/**
+	* The associated HTMLFormElement, if any.
+	* Resolves first via ElementInternals.form, then checks the 'form' attribute by ID,
+	* and finally falls back to the closest ancestor <form>.
+	*/
+	get form() {
+		if (this.internals && "form" in this.internals && this.internals.form !== void 0) return this.internals.form;
+		const formAttr = this.getAttribute("form");
+		if (formAttr && this.ownerDocument) {
+			const el = this.ownerDocument.getElementById(formAttr);
+			if (el instanceof HTMLFormElement) return el;
+		}
+		return this.closest("form");
+	}
+	/**
+	* Sets the element's form submission value and optional state restoration value.
+	*
+	* @param value The value to submit with the form: string, File, FormData, or null (clears submission).
+	* @param state Optional state object used for session restoration / autocomplete.
+	*/
+	setFormValue(value, state) {
+		this.#formValue = value;
+		this.#formState = state;
+		if (this.internals && typeof this.internals.setFormValue === "function") try {
+			this.internals.setFormValue(value, state);
+		} catch {}
+	}
+	/**
+	* Returns the current form submission value.
+	*/
+	getFormValue() {
+		return this.#formValue;
+	}
+	/**
+	* Getter alias for getFormValue() for uniform property access.
+	*/
+	get formValue() {
+		return this.#formValue;
+	}
+	/**
+	* Returns the current state restoration object.
+	*/
+	get formState() {
+		return this.#formState;
+	}
+	/**
+	* Sets the validity flags, validation error message, and optional anchor element.
+	*
+	* @param flags A map of ValidityStateFlags indicating constraint violations.
+	* @param message A human-readable validation error message (required if any flag is true).
+	* @param anchor An optional HTMLElement inside the element's ShadowRoot used to anchor browser tooltips.
+	*/
+	setValidity(flags = {}, message, anchor) {
+		this.#validityFlags = { ...flags };
+		this.#validationMessage = message ?? "";
+		this.#customError = !!flags.customError;
+		if (this.internals && typeof this.internals.setValidity === "function") try {
+			this.internals.setValidity(flags, message, anchor);
+		} catch {}
+	}
+	/**
+	* Returns the current ValidityState object representing constraint validation status.
+	*/
+	get validity() {
+		if (this.internals && "validity" in this.internals && this.internals.validity) return this.internals.validity;
+		return createSyntheticValidityState({
+			...this.#validityFlags,
+			customError: this.#validityFlags.customError || this.#customError
+		});
+	}
+	/**
+	* Returns the current validation error message, or an empty string if valid.
+	*/
+	get validationMessage() {
+		if (this.internals && "validationMessage" in this.internals && typeof this.internals.validationMessage === "string") return this.internals.validationMessage;
+		return this.validity.valid ? "" : this.#validationMessage;
+	}
+	/**
+	* Returns true if the element participates in constraint validation and is not disabled.
+	*/
+	get willValidate() {
+		if (this.internals && "willValidate" in this.internals && typeof this.internals.willValidate === "boolean") return this.internals.willValidate;
+		return !this.disabled;
+	}
+	/**
+	* Checks whether the element satisfies all validation constraints.
+	* If invalid, fires a cancelable 'invalid' event on the element and returns false.
+	* If valid (or validation is disabled), returns true.
+	*/
+	checkValidity() {
+		if (this.internals && typeof this.internals.checkValidity === "function") try {
+			return this.internals.checkValidity();
+		} catch {}
+		if (!this.willValidate) return true;
+		if (!this.validity.valid) {
+			const event = new Event("invalid", {
+				bubbles: false,
+				cancelable: true
+			});
+			this.dispatchEvent(event);
+			return false;
+		}
+		return true;
+	}
+	/**
+	* Checks validity, reports errors to the user (e.g. browser popup), and returns validity status.
+	*/
+	reportValidity() {
+		if (this.internals && typeof this.internals.reportValidity === "function") try {
+			return this.internals.reportValidity();
+		} catch {}
+		return this.checkValidity();
+	}
+	/**
+	* Sets a custom validation error message. If message is non-empty, sets customError to true.
+	* If message is empty, clears custom validity errors.
+	*/
+	setCustomValidity(message) {
+		if (message) this.setValidity({ customError: true }, message);
+		else this.setValidity({});
+	}
+	/**
+	* Native FACE callback invoked by the browser engine when the associated form is reset.
+	* Dispatches to the overridable onFormReset() hook.
+	*/
+	formResetCallback() {
+		if (this.#isResetting) return;
+		this.#isResetting = true;
+		try {
+			this.onFormReset();
+		} finally {
+			queueMicrotask(() => {
+				this.#isResetting = false;
+			});
+		}
+	}
+	/**
+	* Overridable lifecycle hook called when the associated form is reset.
+	* Subclasses should restore default values, re-evaluate validation, and request updates.
+	*/
+	onFormReset() {}
+	/**
+	* Native FACE callback invoked when the element or parent fieldset is disabled/enabled.
+	*/
+	formDisabledCallback(disabled) {
+		this.disabled = disabled;
+		this.onFormDisabled(disabled);
+		this.requestUpdate();
+	}
+	/**
+	* Overridable lifecycle hook called when the disabled state changes.
+	*/
+	onFormDisabled(_disabled) {}
+	/**
+	* Native FACE callback invoked when the browser restores form state (history navigation / autofill).
+	*/
+	formStateRestoreCallback(state, mode) {
+		this.#formState = state;
+		this.onFormStateRestore(state, mode);
+	}
+	/**
+	* Overridable lifecycle hook called when the browser restores form state.
+	*/
+	onFormStateRestore(_state, _mode) {}
+	/**
+	* Native FACE callback invoked when the element is associated or disassociated with a form.
+	*/
+	formAssociatedCallback(form) {
+		this.#syncFormListener(form);
+		this.onFormAssociated(form);
+	}
+	/**
+	* Overridable lifecycle hook called when the element's form association changes.
+	*/
+	onFormAssociated(_form) {}
+	#handleFormReset;
+	#syncFormListener(newForm) {
+		if (this.#associatedForm === newForm) return;
+		if (this.#associatedForm) this.#associatedForm.removeEventListener("reset", this.#handleFormReset);
+		this.#associatedForm = newForm;
+		if (this.#associatedForm) this.#associatedForm.addEventListener("reset", this.#handleFormReset);
+	}
+	connectedCallback() {
+		super.connectedCallback();
+		this.#syncFormListener(this.form);
+	}
+	disconnectedCallback() {
+		this.#syncFormListener(null);
+		super.disconnectedCallback();
+	}
+};
+__decorate([(0, lit_decorators_js.property)({
+	type: String,
+	reflect: true
+})], FormAssociatedLitElement.prototype, "name", void 0);
+__decorate([(0, lit_decorators_js.property)({
+	type: String,
+	reflect: true
+})], FormAssociatedLitElement.prototype, "type", void 0);
+__decorate([(0, lit_decorators_js.property)({
+	type: Boolean,
+	reflect: true
+})], FormAssociatedLitElement.prototype, "disabled", void 0);
+__decorate([(0, lit_decorators_js.property)({
+	type: Boolean,
+	reflect: true
+})], FormAssociatedLitElement.prototype, "required", void 0);
+// src/context.ts
+/**
+* @fileoverview W3C Context Protocol (@lit/context) tokens and dependency injection utilities
+* for Context-Action stores, action registers, and dispatchers across Shadow DOM boundaries.
+*
+* @implements context-protocol
+* @implements dependency-injection
+* @implements store-integration-pattern
+* @implements action-pipeline-system
+* @memberof core-concepts
+*/
+/**
+* Standard W3C Context token for an ActionRegister.
+* Uses Symbol.for to ensure singleton identity across independent bundle chunks and micro-frontends.
+*
+* @implements action-pipeline-system
+* @memberof api-terms
+*/
+const actionRegisterContext = (0, _lit_context.createContext)(Symbol.for("context-action.register"));
+/**
+* Standard W3C Context token for an ActionDispatcher function.
+* Uses Symbol.for to ensure singleton identity across independent bundle chunks.
+*
+* @implements action-pipeline-system
+* @memberof api-terms
+*/
+const actionDispatcherContext = (0, _lit_context.createContext)(Symbol.for("context-action.dispatcher"));
+/**
+* Factory function creating a strongly-typed W3C Context token for a named Context-Action store.
+*
+* Distinct store names yield isolated contexts. Identical store names across different
+* modules or micro-frontend bundles share the same underlying global Symbol.
+*
+* @template T State type managed by the store.
+* @param name Unique name of the store domain (e.g. 'cart', 'auth', 'theme').
+* @returns A Context token for the named ReadableStore.
+*
+* @example
+* ```typescript
+* export const cartStoreContext = createStoreContext<CartState>('cart');
+* ```
+*
+* @implements store-integration-pattern
+* @memberof api-terms
+*/
+function createStoreContext(name) {
+	if (!name || typeof name !== "string") throw new TypeError("createStoreContext: \"name\" must be a non-empty string.");
+	return (0, _lit_context.createContext)(Symbol.for(`context-action.store.${name}`));
+}
+/**
+* Factory function creating a strongly-typed ActionRegister context token for a specific action map.
+*
+* @template A Action payload map.
+* @param name Optional domain qualifier. Defaults to the root action register.
+* @returns A typed Context token for ActionRegister<A>.
+*/
+function createActionRegisterContext(name = "default") {
+	return (0, _lit_context.createContext)(Symbol.for(`context-action.register.${name}`));
+}
+/**
+* Factory function creating a strongly-typed ActionDispatcher context token for a specific action map.
+*
+* @template A Action payload map.
+* @param name Optional domain qualifier. Defaults to the root action dispatcher.
+* @returns A typed Context token for ActionDispatcher<A>.
+*/
+function createActionDispatcherContext(name = "default") {
+	return (0, _lit_context.createContext)(Symbol.for(`context-action.dispatcher.${name}`));
+}
+/**
+* Imperatively attaches an ActionRegister ContextProvider to a host element.
+*
+* @template A Action payload map.
+* @param host The hosting LitElement or ReactiveElement.
+* @param register The ActionRegister instance to provide.
+* @param context Optional custom context token (defaults to actionRegisterContext).
+* @returns The initialized ContextProvider instance.
+*/
+function provideActionRegister(host, register, context = actionRegisterContext) {
+	return new _lit_context.ContextProvider(host, {
+		context,
+		initialValue: register
+	});
+}
+/**
+* Imperatively attaches an ActionDispatcher ContextProvider to a host element.
+*
+* @template A Action payload map.
+* @param host The hosting LitElement or ReactiveElement.
+* @param dispatcher The ActionDispatcher function to provide.
+* @param context Optional custom context token (defaults to actionDispatcherContext).
+* @returns The initialized ContextProvider instance.
+*/
+function provideActionDispatcher(host, dispatcher, context = actionDispatcherContext) {
+	return new _lit_context.ContextProvider(host, {
+		context,
+		initialValue: dispatcher
+	});
+}
+/**
+* Imperatively attaches a ReadableStore ContextProvider to a host element.
+*
+* @template T Store state type.
+* @param host The hosting LitElement or ReactiveElement.
+* @param context The store Context token created via `createStoreContext`.
+* @param store The ReadableStore instance to provide.
+* @returns The initialized ContextProvider instance.
+*/
+function provideStore(host, context, store) {
+	return new _lit_context.ContextProvider(host, {
+		context,
+		initialValue: store
+	});
+}
+/**
+* ReactiveController that consumes a Context-Action ReadableStore from the W3C Context
+* hierarchy across Shadow DOM boundaries, subscribes to state updates, and triggers host re-renders.
+*
+* Key guarantees:
+* 1. Attaches to host via `host.addController(this)`.
+* 2. Uses `@lit/context` ContextConsumer to dynamically resolve store instances across Shadow DOM boundaries.
+* 3. Supports selective projections with memoization (`equalityFn`).
+* 4. Ensures ZERO memory leaks: completely terminates store subscription when `hostDisconnected()` runs.
+* 5. Re-evaluates store state and resubscribes on `hostConnected()`.
+*
+* @template T Source store state type.
+* @template Selected Derived slice type.
+*
+* @implements store-integration-pattern
+* @implements reactive-state-management
+* @memberof core-concepts
+*/
+var ContextStoreController = class {
+	#host;
+	#selector;
+	#equalityFn;
+	#currentStore = void 0;
+	#unsubscribeStore = null;
+	#selectedValue = void 0;
+	#isResolved = false;
+	constructor(host, options) {
+		if (!host || typeof host.addController !== "function") throw new TypeError("ContextStoreController requires a valid host implementing ReactiveControllerHost and HTMLElement.");
+		if (!options?.context) throw new TypeError("ContextStoreController requires a valid Context token.");
+		this.#host = host;
+		this.#selector = options.selector ?? ((s) => s);
+		this.#equalityFn = options.equalityFn ?? Object.is;
+		new _lit_context.ContextConsumer(host, {
+			context: options.context,
+			callback: (store) => this.#handleStoreResolved(store),
+			subscribe: true
+		});
+		host.addController(this);
+	}
+	/** Current projected state derived from the injected store, or undefined if not yet provided. */
+	get value() {
+		return this.#selectedValue;
+	}
+	/** The resolved ReadableStore instance currently bound to this controller. */
+	get store() {
+		return this.#currentStore;
+	}
+	/** Indicates whether the context request has been satisfied by an ancestor provider. */
+	get isResolved() {
+		return this.#isResolved;
+	}
+	#extractRawValue(store) {
+		if (typeof store.getValue === "function") return store.getValue();
+		if (typeof store.getSnapshot === "function") return store.getSnapshot();
+		throw new TypeError("ContextStoreController: Provided store must implement getValue() or getSnapshot().");
+	}
+	#handleStoreResolved(nextStore) {
+		if (this.#currentStore === nextStore && this.#isResolved) return;
+		this.#cleanupStoreSubscription();
+		this.#currentStore = nextStore;
+		if (!nextStore) {
+			this.#isResolved = false;
+			this.#selectedValue = void 0;
+			this.#host.requestUpdate();
+			return;
+		}
+		this.#isResolved = true;
+		this.#syncStateAndSubscribe();
+		this.#host.requestUpdate();
+	}
+	#syncStateAndSubscribe() {
+		if (!this.#currentStore) return;
+		const raw = this.#extractRawValue(this.#currentStore);
+		this.#selectedValue = this.#selector(raw);
+		this.#unsubscribeStore = this.#currentStore.subscribe(() => {
+			if (!this.#currentStore) return;
+			const nextRaw = this.#extractRawValue(this.#currentStore);
+			const nextSelected = this.#selector(nextRaw);
+			if (!this.#equalityFn(this.#selectedValue, nextSelected)) {
+				this.#selectedValue = nextSelected;
+				this.#host.requestUpdate();
+			}
+		});
+	}
+	#cleanupStoreSubscription() {
+		if (this.#unsubscribeStore) {
+			this.#unsubscribeStore();
+			this.#unsubscribeStore = null;
+		}
+	}
+	hostConnected() {
+		if (this.#currentStore && !this.#unsubscribeStore) {
+			this.#syncStateAndSubscribe();
+			this.#host.requestUpdate();
+		}
+	}
+	hostDisconnected() {
+		this.#cleanupStoreSubscription();
+	}
+};
+/**
+* ReactiveController that consumes an ActionRegister from the W3C Context hierarchy
+* across Shadow DOM boundaries and exposes typed dispatch methods.
+*
+* @template A Action payload map.
+*
+* @implements action-pipeline-system
+* @implements action-controller
+* @memberof core-concepts
+*/
+var ContextActionController = class {
+	#host;
+	#register = void 0;
+	#isPending = false;
+	#lastError = void 0;
+	constructor(host, options) {
+		if (!host || typeof host.addController !== "function") throw new TypeError("ContextActionController requires a valid host implementing ReactiveControllerHost and HTMLElement.");
+		this.#host = host;
+		const ctx = options?.context ?? actionRegisterContext;
+		new _lit_context.ContextConsumer(host, {
+			context: ctx,
+			callback: (reg) => {
+				this.#register = reg;
+				this.#host.requestUpdate();
+			},
+			subscribe: true
+		});
+		host.addController(this);
+	}
+	/** The resolved ActionRegister instance, or undefined if no provider is present. */
+	get register() {
+		return this.#register;
+	}
+	/** Whether an action dispatch is currently in progress. */
+	get isPending() {
+		return this.#isPending;
+	}
+	/** The last error thrown during an action dispatch, if any. */
+	get lastError() {
+		return this.#lastError;
+	}
+	/**
+	* Dispatches an action through the context-injected ActionRegister pipeline.
+	*
+	* @template K Action name.
+	* @param action Name of the registered action.
+	* @param args Action payload arguments.
+	*/
+	async dispatch(action, ...args) {
+		if (!this.#register) throw new Error(`ContextActionController: Cannot dispatch "${String(action)}". No ActionRegister found in context hierarchy.`);
+		this.#isPending = true;
+		this.#lastError = void 0;
+		this.#host.requestUpdate();
+		try {
+			await this.#register.dispatch(action, ...args);
+		} catch (err) {
+			const errorObj = err instanceof Error ? err : new Error(String(err));
+			this.#lastError = errorObj;
+			throw errorObj;
+		} finally {
+			this.#isPending = false;
+			this.#host.requestUpdate();
+		}
+	}
+	/**
+	* Dispatches an action and returns the pipeline execution result.
+	*
+	* @template K Action name.
+	* @template R Expected return value.
+	* @param action Name of the registered action.
+	* @param args Action payload arguments.
+	* @returns Pipeline result promise.
+	*/
+	async dispatchWithResult(action, ...args) {
+		if (!this.#register) throw new Error(`ContextActionController: Cannot dispatch "${String(action)}". No ActionRegister found in context hierarchy.`);
+		this.#isPending = true;
+		this.#lastError = void 0;
+		this.#host.requestUpdate();
+		try {
+			if (typeof this.#register.dispatchWithResult === "function") return await this.#register.dispatchWithResult(action, ...args);
+			return await this.#register.dispatch(action, ...args);
+		} catch (err) {
+			const errorObj = err instanceof Error ? err : new Error(String(err));
+			this.#lastError = errorObj;
+			throw errorObj;
+		} finally {
+			this.#isPending = false;
+			this.#host.requestUpdate();
+		}
+	}
+	hostConnected() {}
+	hostDisconnected() {}
+};
+// src/facade.ts
+function findPropertyDescriptor(target, key) {
+	let current = target;
+	while (current) {
+		const descriptor = Object.getOwnPropertyDescriptor(current, key);
+		if (descriptor) return descriptor;
+		current = Object.getPrototypeOf(current);
+	}
+}
+/**
+* Creates a reusable host-agnostic handle factory that exposes only the specified
+* properties and methods from a Custom Element, hiding raw `HTMLElement` APIs.
+* Can be used directly with Vanilla DOM, Lit, or
+* `createLitElementBridge({ createHandle })`.
+*
+* Methods are bound to the current element and cached per element, so repeated
+* reads return the same function identity until the element or the underlying
+* method changes. The cache is keyed weakly and never retains a detached element.
+*
+* @example
+* ```ts
+* const TimelineElement = createLitElementBridge<TimelineProps, TimelineElement, TimelineHandle>({
+*   tagName: 'st-timeline',
+*   properties: ['input', 'set'],
+*   createHandle: createElementFacade(['focusItem', 'scrollTo', 'commitSelection']),
+* });
+* ```
+*/
+function createElementFacade(keys) {
+	const uniqueKeys = Array.from(new Set(keys));
+	return (getElement) => {
+		const requireElement = () => {
+			const element = getElement();
+			if (!element) throw new Error("Custom element handle is not mounted");
+			return element;
+		};
+		const boundMethods = /* @__PURE__ */ new WeakMap();
+		const facade = {};
+		for (const key of uniqueKeys) Object.defineProperty(facade, key, {
+			configurable: false,
+			enumerable: true,
+			get() {
+				const element = requireElement();
+				const value = Reflect.get(element, key, element);
+				if (typeof value !== "function") return value;
+				let cache = boundMethods.get(element);
+				if (!cache) {
+					cache = /* @__PURE__ */ new Map();
+					boundMethods.set(element, cache);
+				}
+				const cached = cache.get(key);
+				if (cached && cached.source === value) return cached.bound;
+				const bound = value.bind(element);
+				cache.set(key, {
+					source: value,
+					bound
+				});
+				return bound;
+			},
+			set(nextValue) {
+				const element = requireElement();
+				const descriptor = findPropertyDescriptor(element, key);
+				if (descriptor && !descriptor.set && !descriptor.writable) throw new TypeError(`Cannot assign to read-only property '${String(key)}'`);
+				if (!Reflect.set(element, key, nextValue, element)) throw new TypeError(`Cannot assign to read-only property '${String(key)}'`);
+			}
+		});
+		return Object.freeze(facade);
+	};
+}
+// src/react-bridge.ts
+/**
+* @fileoverview React 18/19 bridge helper for consuming Lit Custom Elements.
+* Provides direct property assignment to bypass attribute stringification,
+* stable custom event listener mapping with deterministic cleanup, and
+* OOP Facade handle forwarding via `createHandle`.
+*
+* @implements view-layer
+* @implements web-component-primitive
+* @memberof core-concepts
+*/
+const useIsomorphicLayoutEffect = typeof window === "undefined" ? react.useEffect : react.useLayoutEffect;
+function isEventHandler(value) {
+	return typeof value === "function" || typeof value === "object" && value !== null && typeof value.handleEvent === "function";
+}
+/**
+* Creates a type-safe React bridge component for consuming any Lit Custom Element
+* with seamless property synchronization, custom event listeners, and ref forwarding.
+*
+* Solves standard React ↔ Web Component pain points:
+* 1. Direct Property Assignment: Directly assigns objects, arrays, and stores to the DOM
+*    instance without stringifying to `"[object Object]"` in React 18/19.
+* 2. Property Removal: Clears keys removed from `properties` on later renders.
+* 3. Stable Custom Events: Attaches one listener per event and reads the latest
+*    handler, so ordinary re-renders never re-register listeners.
+* 4. Ref Forwarding: Forwards an OOP Facade handle (`createHandle`) or the raw
+*    Custom Element instance when no factory is provided.
+*/
+function createLitElementBridge(tagOrOptions, maybeConfig) {
+	const { tagName, properties = [], events = {}, createHandle } = typeof tagOrOptions === "string" ? {
+		tagName: tagOrOptions,
+		...maybeConfig
+	} : tagOrOptions;
+	const propertyKeys = Array.from(properties);
+	const propertyKeySet = new Set(propertyKeys);
+	const eventEntries = Object.entries(events);
+	const Bridge = react.forwardRef(function LitCustomElementBridge(props, forwardedRef) {
+		const elementRef = react.useRef(null);
+		const [element, setElement] = react.useState(null);
+		const appliedPropertiesRef = react.useRef(/* @__PURE__ */ new Set());
+		const appliedElementRef = react.useRef(null);
+		const eventBindingsRef = react.useRef([]);
+		const handleRef = react.useCallback((node) => {
+			elementRef.current = node;
+			setElement(node);
+		}, []);
+		react.useImperativeHandle(forwardedRef, () => {
+			if (createHandle) return createHandle(() => elementRef.current);
+			return elementRef.current;
+		}, [createHandle]);
+		useIsomorphicLayoutEffect(() => {
+			if (!element) return;
+			if (appliedElementRef.current !== element) {
+				appliedElementRef.current = element;
+				appliedPropertiesRef.current = /* @__PURE__ */ new Set();
+			}
+			const host = element;
+			const propsRecord = props;
+			const appliedProperties = appliedPropertiesRef.current;
+			for (const propKey of propertyKeys) if (propKey in propsRecord) {
+				appliedProperties.add(propKey);
+				try {
+					host[propKey] = propsRecord[propKey];
+				} catch {}
+			} else if (appliedProperties.has(propKey)) try {
+				host[propKey] = void 0;
+			} catch {} finally {
+				appliedProperties.delete(propKey);
+			}
+		}, [
+			element,
+			props,
+			propertyKeys
+		]);
+		react.useEffect(() => {
+			if (!element) return;
+			const previousBindings = eventBindingsRef.current;
+			const nextBindings = [];
+			const propsRecord = props;
+			for (let index = 0; index < eventEntries.length; index++) {
+				const [propHandlerName, customEventName] = eventEntries[index];
+				const handler = propsRecord[propHandlerName];
+				const previous = previousBindings[index];
+				if (previous && previous.element === element && previous.eventName === customEventName && previous.handler === handler) {
+					nextBindings.push(previous);
+					continue;
+				}
+				if (previous?.listener) previous.element.removeEventListener(previous.eventName, previous.listener);
+				if (isEventHandler(handler)) {
+					const listener = (event) => {
+						if (typeof handler === "function") handler(event);
+						else handler.handleEvent(event);
+					};
+					element.addEventListener(customEventName, listener);
+					nextBindings.push({
+						element,
+						eventName: customEventName,
+						handler,
+						listener
+					});
+				} else nextBindings.push({
+					element,
+					eventName: customEventName,
+					handler
+				});
+			}
+			for (let index = eventEntries.length; index < previousBindings.length; index++) {
+				const stale = previousBindings[index];
+				if (stale.listener) stale.element.removeEventListener(stale.eventName, stale.listener);
+			}
+			eventBindingsRef.current = nextBindings;
+		});
+		react.useEffect(() => {
+			return () => {
+				for (const binding of eventBindingsRef.current) if (binding.listener) binding.element.removeEventListener(binding.eventName, binding.listener);
+				eventBindingsRef.current = [];
+			};
+		}, []);
+		const domProps = { ref: handleRef };
+		for (const [key, value] of Object.entries(props)) if (key === "children") domProps[key] = value;
+		else if (key === "className") domProps.class = value;
+		else if (key === "htmlFor") domProps.for = value;
+		else if (!propertyKeySet.has(key) && !(key in events)) domProps[key] = value;
+		return react.createElement(tagName, domProps);
+	});
+	Bridge.displayName = `LitBridge(${tagName})`;
+	return Bridge;
+}
+// src/define-once.ts
+/**
+* @fileoverview Idempotent custom element registration for the reference
+* components. ESM and CJS builds can both be loaded in one process, so an
+* unconditional `customElements.define()` would throw on the second load.
+*
+* @implements web-component-primitive
+* @memberof core-concepts
+*/
+function defineCustomElement(tagName, elementConstructor) {
+	if (typeof customElements === "undefined") return;
+	if (customElements.get(tagName)) return;
+	customElements.define(tagName, elementConstructor);
+}
+// src/components/quantity-stepper.ts
+/**
+* @fileoverview Reference implementation of <lit-quantity-stepper> custom element.
+* Extends FormAssociatedLitElement for full native <form> and FormData participation,
+* constraint validation, form reset lifecycle, and Shadow DOM encapsulation.
+*
+* @implements view-layer
+* @implements web-component-primitive
+* @memberof core-concepts
+*/
+/**
+* Reference Form-Associated Custom Element providing a numerical stepper control.
+*
+* Features:
+* - Native <form> submission and `new FormData()` integration via `ElementInternals`.
+* - HTML5 constraint validation (`rangeUnderflow`, `rangeOverflow`, `stepMismatch`, `badInput`).
+* - Form reset lifecycle restoration via `onFormReset()`.
+* - Disabled and readonly state propagation.
+* - Increment / Decrement methods with step precision and boundary clamping.
+* - Standard CustomEvent dispatching (`change`, `input`, `quantity-change`) with `{ bubbles: true, composed: true }`.
+* - Fully encapsulated Shadow DOM styling with `::part(button)` and `::part(input)` styling hooks.
+*/
+var LitQuantityStepper = class extends FormAssociatedLitElement {
+	constructor(..._args) {
+		super(..._args);
+		this.value = 1;
+		this.min = 1;
+		this.max = 99;
+		this.step = 1;
+		this.readonly = false;
+		this.focused = false;
+		this.#initialValue = 1;
+		this.#handleInput = (e) => {
+			e.stopPropagation();
+			const target = e.target;
+			const parsed = parseFloat(target.value);
+			this.value = Number.isNaN(parsed) ? target.value : parsed;
+			this.#syncFormState();
+			this.#emitEvents("input");
+		};
+		this.#handleChange = (e) => {
+			e.stopPropagation();
+			const target = e.target;
+			const parsed = parseFloat(target.value);
+			this.value = Number.isNaN(parsed) ? target.value : parsed;
+			this.#syncFormState();
+			this.#emitEvents("change");
+		};
+	}
+	static {
+		this.styles = lit.css`
+    :host {
+      display: inline-flex;
+      vertical-align: middle;
+      font-family: var(
+        --stepper-font-family,
+        system-ui,
+        -apple-system,
+        BlinkMacSystemFont,
+        'Segoe UI',
+        Roboto,
+        sans-serif
+      );
+      --_border-color: var(--stepper-border-color, #cbd5e1);
+      --_focus-border-color: var(--stepper-focus-border-color, #3b82f6);
+      --_invalid-border-color: var(--stepper-invalid-border-color, #ef4444);
+      --_bg: var(--stepper-bg, #ffffff);
+      --_btn-bg: var(--stepper-button-bg, #f8fafc);
+      --_btn-hover-bg: var(--stepper-button-hover-bg, #e2e8f0);
+      --_btn-active-bg: var(--stepper-button-active-bg, #cbd5e1);
+      --_btn-color: var(--stepper-button-color, #334155);
+      --_radius: var(--stepper-radius, 8px);
+      --_font-size: var(--stepper-font-size, 14px);
+      --_height: var(--stepper-height, 36px);
+    }
+
+    :host([disabled]) {
+      opacity: 0.5;
+      pointer-events: none;
+      cursor: not-allowed;
+    }
+
+    :host([hidden]) {
+      display: none !important;
+    }
+
+    .stepper {
+      display: inline-flex;
+      align-items: stretch;
+      height: var(--_height);
+      background: var(--_bg);
+      border: 1px solid var(--_border-color);
+      border-radius: var(--_radius);
+      overflow: hidden;
+      transition: border-color 0.15s ease, box-shadow 0.15s ease;
+      box-sizing: border-box;
+    }
+
+    .stepper.focused {
+      border-color: var(--_focus-border-color);
+      box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.2);
+    }
+
+    :host(:invalid) .stepper,
+    .stepper.invalid {
+      border-color: var(--_invalid-border-color);
+    }
+
+    :host(:invalid) .stepper.focused,
+    .stepper.invalid.focused {
+      box-shadow: 0 0 0 3px rgba(239, 68, 68, 0.2);
+    }
+
+    button {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      width: var(--_height);
+      padding: 0;
+      margin: 0;
+      border: none;
+      background: var(--_btn-bg);
+      color: var(--_btn-color);
+      font-size: calc(var(--_font-size) + 2px);
+      font-weight: 600;
+      cursor: pointer;
+      user-select: none;
+      transition: background-color 0.15s ease, color 0.15s ease;
+      box-sizing: border-box;
+    }
+
+    button:hover:not(:disabled) {
+      background: var(--_btn-hover-bg);
+    }
+
+    button:active:not(:disabled) {
+      background: var(--_btn-active-bg);
+    }
+
+    button:disabled {
+      cursor: not-allowed;
+      opacity: 0.4;
+    }
+
+    .btn-decrement {
+      border-right: 1px solid var(--_border-color);
+    }
+
+    .btn-increment {
+      border-left: 1px solid var(--_border-color);
+    }
+
+    input {
+      width: 48px;
+      padding: 0 6px;
+      margin: 0;
+      border: none;
+      background: transparent;
+      text-align: center;
+      font-size: var(--_font-size);
+      font-weight: 600;
+      color: var(--stepper-text-color, #0f172a);
+      font-family: inherit;
+      box-sizing: border-box;
+      -moz-appearance: textfield;
+    }
+
+    input::-webkit-outer-spin-button,
+    input::-webkit-inner-spin-button {
+      -webkit-appearance: none;
+      margin: 0;
+    }
+
+    input:focus {
+      outline: none;
+    }
+  `;
+	}
+	#initialValue;
+	connectedCallback() {
+		super.connectedCallback();
+		this.#initialValue = this.defaultValue ?? this.value;
+		this.#syncFormState();
+	}
+	updated(changedProperties) {
+		super.updated(changedProperties);
+		if (changedProperties.has("defaultValue") && this.defaultValue !== void 0) this.#initialValue = this.defaultValue;
+		if (changedProperties.has("value") || changedProperties.has("min") || changedProperties.has("max") || changedProperties.has("step") || changedProperties.has("disabled")) this.#syncFormState();
+	}
+	/**
+	* Evaluates step alignment using floating-point safe division.
+	*/
+	#checkStepMismatch(val, min, step) {
+		if (step <= 0 || Number.isNaN(val)) return false;
+		const quotient = (val - min) / step;
+		return Math.abs(quotient - Math.round(quotient)) > 1e-7;
+	}
+	/**
+	* Formats a value for form submission and HTML input display,
+	* preventing scientific notation drift.
+	*/
+	#formatValue(val) {
+		if (typeof val === "number") {
+			if (Number.isNaN(val)) return "NaN";
+			if (Math.abs(val) < 1e-9) return "0";
+			const str = String(val);
+			if (str.includes("e-")) return val.toFixed(10).replace(/\.?0+$/, "");
+			return str;
+		}
+		return String(val ?? "");
+	}
+	/**
+	* Derives decimal precision from numbers to avoid IEEE 754 precision drift.
+	*/
+	#getPrecision(...numbers) {
+		let maxDecimals = 0;
+		for (const n of numbers) {
+			if (!Number.isFinite(n)) continue;
+			const str = n.toString();
+			const dot = str.indexOf(".");
+			if (dot !== -1) maxDecimals = Math.max(maxDecimals, str.length - dot - 1);
+		}
+		return Math.min(12, maxDecimals);
+	}
+	/**
+	* Synchronizes internal value with ElementInternals form value and constraint validation.
+	*/
+	#syncFormState() {
+		this.setFormValue(this.#formatValue(this.value));
+		const flags = {};
+		let message = "";
+		const rawVal = this.value;
+		const isBlank = typeof rawVal === "string" && rawVal.trim() === "";
+		const num = isBlank ? NaN : Number(this.value);
+		if (isBlank || Number.isNaN(num)) {
+			flags.badInput = true;
+			message = "Please enter a valid number.";
+		} else if (num < this.min) {
+			flags.rangeUnderflow = true;
+			message = `Value must be greater than or equal to ${this.min}.`;
+		} else if (num > this.max) {
+			flags.rangeOverflow = true;
+			message = `Value must be less than or equal to ${this.max}.`;
+		} else if (this.#checkStepMismatch(num, this.min, this.step)) {
+			flags.stepMismatch = true;
+			message = `Value must be an increment of ${this.step} from ${this.min}.`;
+		}
+		const anchor = this.inputEl ?? this.renderRoot?.querySelector("input");
+		this.setValidity(flags, message, anchor);
+	}
+	/**
+	* Emits input, change, and quantity-change CustomEvents across Shadow DOM boundaries.
+	*/
+	#emitEvents(triggerType) {
+		const detail = { value: this.value };
+		if (triggerType === "input" || triggerType === "both") this.dispatchEvent(new CustomEvent("input", {
+			bubbles: true,
+			composed: true,
+			detail
+		}));
+		if (triggerType === "change" || triggerType === "both") {
+			this.dispatchEvent(new CustomEvent("change", {
+				bubbles: true,
+				composed: true,
+				detail
+			}));
+			this.dispatchEvent(new CustomEvent("quantity-change", {
+				bubbles: true,
+				composed: true,
+				detail
+			}));
+		}
+	}
+	/**
+	* Increments the current value by the configured step.
+	* If at or above max, or if disabled/readonly, this operation is a no-op.
+	*/
+	increment() {
+		if (this.disabled || this.readonly) return;
+		const current = Number(this.value);
+		if (Number.isNaN(current)) return;
+		const precision = this.#getPrecision(this.step, current, this.max);
+		const next = Number((current + this.step).toFixed(precision));
+		if (next > this.max + 1e-9) return;
+		const clamped = Math.abs(next - this.max) < 1e-9 ? this.max : Math.min(next, this.max);
+		this.value = Math.abs(clamped) < 1e-9 ? 0 : clamped;
+		this.#syncFormState();
+		this.requestUpdate();
+		this.#emitEvents("both");
+	}
+	/**
+	* Decrements the current value by the configured step.
+	* If at or below min, or if disabled/readonly, this operation is a no-op.
+	*/
+	decrement() {
+		if (this.disabled || this.readonly) return;
+		const current = Number(this.value);
+		if (Number.isNaN(current)) return;
+		const precision = this.#getPrecision(this.step, current, this.min);
+		const next = Number((current - this.step).toFixed(precision));
+		if (next < this.min - 1e-9) return;
+		const clamped = Math.abs(next - this.min) < 1e-9 ? this.min : Math.max(next, this.min);
+		this.value = Math.abs(clamped) < 1e-9 ? 0 : clamped;
+		this.#syncFormState();
+		this.requestUpdate();
+		this.#emitEvents("both");
+	}
+	/**
+	* Sets the value imperatively with optional event dispatching.
+	*
+	* @param val New numerical value.
+	* @param options.dispatchEvents If true, emits `input` and `change` events.
+	*/
+	setValue(val, options) {
+		const num = typeof val === "number" ? val : Number(val);
+		this.value = num;
+		this.#syncFormState();
+		this.requestUpdate();
+		if (options?.dispatchEvents) this.#emitEvents("both");
+	}
+	/**
+	* Handles user input from the internal number input field.
+	*/
+	#handleInput;
+	/**
+	* Handles commit / change from the internal number input field.
+	*/
+	#handleChange;
+	/**
+	* Invoked by FormAssociatedLitElement when the parent form executes a reset.
+	* Restores initial value, clears validation, and synchronizes form value.
+	*/
+	onFormReset() {
+		this.value = this.defaultValue ?? this.#initialValue;
+		this.#syncFormState();
+		this.requestUpdate();
+	}
+	render() {
+		const isInvalid = !this.validity.valid;
+		const current = Number(this.value);
+		const isDecDisabled = this.disabled || this.readonly || Number.isNaN(current) || current <= this.min + 1e-9;
+		const isIncDisabled = this.disabled || this.readonly || Number.isNaN(current) || current >= this.max - 1e-9;
+		return lit.html`
+      <div
+        class="stepper ${this.focused ? "focused" : ""} ${isInvalid ? "invalid" : ""}"
+        role="group"
+        aria-label=${this.getAttribute("aria-label") || "Quantity Stepper"}
+      >
+        <button
+          type="button"
+          part="button button-decrement"
+          class="btn-decrement"
+          ?disabled=${isDecDisabled}
+          @click=${this.decrement}
+          tabindex="-1"
+          aria-label="Decrease quantity"
+        >−</button>
+        <input
+          type="number"
+          part="input"
+          .value=${this.#formatValue(this.value)}
+          min=${this.min}
+          max=${this.max}
+          step=${this.step}
+          ?disabled=${this.disabled}
+          ?readonly=${this.readonly}
+          @input=${this.#handleInput}
+          @change=${this.#handleChange}
+          @focus=${() => {
+			this.focused = true;
+		}}
+          @blur=${() => {
+			this.focused = false;
+		}}
+          aria-label="Quantity"
+        />
+        <button
+          type="button"
+          part="button button-increment"
+          class="btn-increment"
+          ?disabled=${isIncDisabled}
+          @click=${this.increment}
+          tabindex="-1"
+          aria-label="Increase quantity"
+        >+</button>
+      </div>
+    `;
+	}
+};
+__decorate([(0, lit_decorators_js.property)({ type: Number })], LitQuantityStepper.prototype, "value", void 0);
+__decorate([(0, lit_decorators_js.property)({ type: Number })], LitQuantityStepper.prototype, "min", void 0);
+__decorate([(0, lit_decorators_js.property)({ type: Number })], LitQuantityStepper.prototype, "max", void 0);
+__decorate([(0, lit_decorators_js.property)({ type: Number })], LitQuantityStepper.prototype, "step", void 0);
+__decorate([(0, lit_decorators_js.property)({
+	type: Boolean,
+	reflect: true
+})], LitQuantityStepper.prototype, "readonly", void 0);
+__decorate([(0, lit_decorators_js.property)({
+	type: Number,
+	attribute: "default-value"
+})], LitQuantityStepper.prototype, "defaultValue", void 0);
+__decorate([(0, lit_decorators_js.state)()], LitQuantityStepper.prototype, "focused", void 0);
+__decorate([(0, lit_decorators_js.query)("input")], LitQuantityStepper.prototype, "inputEl", void 0);
+defineCustomElement("lit-quantity-stepper", LitQuantityStepper);
+// src/components/cart-badge.ts
+/**
+* @fileoverview Reference implementation of <lit-cart-badge> custom element.
+* Demonstrates dual-mode store subscription (direct property vs W3C Context Protocol),
+* selective projection for total count, coalesced pending state tracking,
+* and zero-memory-leak unmounting.
+*
+* @implements view-layer
+* @implements store-integration-pattern
+* @implements action-pipeline-system
+* @memberof core-concepts
+*/
+/**
+* Standard W3C Context token for the shopping cart domain store.
+* Uses Symbol.for to guarantee singleton identity across independent bundle chunks.
+*/
+const cartStoreContext = createStoreContext("cart");
+/**
+* Default projection selector that extracts total quantity from diverse cart store state structures:
+* - Primitive numbers (e.g. `5`)
+* - State objects with `totalCount`, `count`, or `total` numerical fields
+* - State objects with `items` arrays containing quantity numbers or objects (`{ quantity: n }`)
+*/
+function defaultCartCountSelector(state) {
+	if (typeof state === "number") return Number.isFinite(state) ? Math.max(0, Math.floor(state)) : 0;
+	if (state && typeof state === "object") {
+		const obj = state;
+		if (typeof obj.totalCount === "number" && Number.isFinite(obj.totalCount)) return Math.max(0, Math.floor(obj.totalCount));
+		if (typeof obj.count === "number" && Number.isFinite(obj.count)) return Math.max(0, Math.floor(obj.count));
+		if (typeof obj.total === "number" && Number.isFinite(obj.total)) return Math.max(0, Math.floor(obj.total));
+		if (Array.isArray(obj.items)) return obj.items.reduce((sum, item) => {
+			const qty = typeof item === "number" ? item : typeof item?.quantity === "number" ? item.quantity : 1;
+			return sum + (Number.isFinite(qty) ? Math.max(0, qty) : 0);
+		}, 0);
+	}
+	return 0;
+}
+/**
+* Reference Custom Element for displaying a dynamic shopping cart badge.
+*
+* Supports two consumption paradigms:
+* 1. Direct property assignment: `.store=${cartStore}` and `.register=${actionRegister}`.
+* 2. W3C Context Protocol: automatically injects `cartStoreContext` and `actionRegisterContext`
+*    from ancestor providers across Shadow DOM boundaries.
+*/
+var LitCartBadge = class extends lit.LitElement {
+	static {
+		this.styles = lit.css`
+    :host {
+      display: inline-flex;
+      vertical-align: middle;
+      font-family: var(
+        --cart-badge-font-family,
+        system-ui,
+        -apple-system,
+        BlinkMacSystemFont,
+        'Segoe UI',
+        Roboto,
+        sans-serif
+      );
+      --_bg: var(--cart-badge-bg, #2563eb);
+      --_color: var(--cart-badge-color, #ffffff);
+      --_hover-bg: var(--cart-badge-hover-bg, #1d4ed8);
+      --_active-bg: var(--cart-badge-active-bg, #1e40af);
+      --_radius: var(--cart-badge-radius, 9999px);
+      --_font-size: var(--cart-badge-font-size, 0.875rem);
+      --_font-weight: var(--cart-badge-font-weight, 600);
+      --_padding: var(--cart-badge-padding, 4px 10px);
+      --_pulse-scale: var(--cart-badge-pulse-scale, 1.2);
+    }
+
+    :host([variant='secondary']) {
+      --_bg: var(--cart-badge-bg, #475569);
+      --_hover-bg: var(--cart-badge-hover-bg, #334155);
+      --_active-bg: var(--cart-badge-active-bg, #1e293b);
+    }
+
+    :host([variant='accent']) {
+      --_bg: var(--cart-badge-bg, #7c3aed);
+      --_hover-bg: var(--cart-badge-hover-bg, #6d28d9);
+      --_active-bg: var(--cart-badge-active-bg, #5b21b6);
+    }
+
+    :host([variant='danger']) {
+      --_bg: var(--cart-badge-bg, #dc2626);
+      --_hover-bg: var(--cart-badge-hover-bg, #b91c1c);
+      --_active-bg: var(--cart-badge-active-bg, #991b1b);
+    }
+
+    :host([hidden]) {
+      display: none !important;
+    }
+
+    :host([hide-zero][count-zero]) {
+      display: none !important;
+    }
+
+    :host([disabled]) {
+      opacity: 0.6;
+      pointer-events: none;
+      cursor: not-allowed;
+    }
+
+    .badge {
+      display: inline-flex;
+      align-items: center;
+      gap: 6px;
+      padding: var(--_padding);
+      background-color: var(--_bg);
+      color: var(--_color);
+      border-radius: var(--_radius);
+      font-size: var(--_font-size);
+      font-weight: var(--_font-weight);
+      border: none;
+      cursor: pointer;
+      user-select: none;
+      outline: none;
+      transition: background-color 0.15s ease, transform 0.15s ease;
+      box-sizing: border-box;
+      line-height: 1;
+    }
+
+    .badge:hover:not(:disabled) {
+      background-color: var(--_hover-bg);
+    }
+
+    .badge:active:not(:disabled) {
+      background-color: var(--_active-bg);
+    }
+
+    .badge:focus-visible {
+      box-shadow: 0 0 0 3px rgba(37, 99, 235, 0.35);
+    }
+
+    .badge:disabled {
+      cursor: not-allowed;
+      opacity: 0.6;
+    }
+
+    .count {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      min-width: 1.25em;
+      font-variant-numeric: tabular-nums;
+    }
+
+    .pulse {
+      animation: cart-badge-pulse 300ms cubic-bezier(0.4, 0, 0.2, 1);
+    }
+
+    @keyframes cart-badge-pulse {
+      0% {
+        transform: scale(1);
+      }
+      50% {
+        transform: scale(var(--_pulse-scale));
+      }
+      100% {
+        transform: scale(1);
+      }
+    }
+
+    .spinner {
+      display: inline-block;
+      width: 12px;
+      height: 12px;
+      border: 2px solid currentColor;
+      border-top-color: transparent;
+      border-radius: 50%;
+      animation: cart-badge-spin 0.8s linear infinite;
+      box-sizing: border-box;
+    }
+
+    @keyframes cart-badge-spin {
+      to {
+        transform: rotate(360deg);
+      }
+    }
+  `;
+	}
+	#contextStoreController;
+	#contextActionController;
+	#directStoreController;
+	#directActionController;
+	#previousCount;
+	constructor() {
+		super();
+		this.value = void 0;
+		this.maxCount = 99;
+		this.hideZero = false;
+		this.label = "Cart";
+		this.disabled = false;
+		this.variant = "primary";
+		this.isPulsing = false;
+		this.#directStoreController = null;
+		this.#directActionController = null;
+		this.#handleClick = async () => {
+			if (this.disabled || this.isPending) return;
+			this.dispatchEvent(new CustomEvent("cart-badge-click", {
+				bubbles: true,
+				composed: true,
+				detail: {
+					count: this.count,
+					isPending: this.isPending
+				}
+			}));
+			if (this.actionName) try {
+				if (this.#directActionController) await this.#directActionController.dispatch(this.actionName, this.actionPayload);
+				else if (this.#contextActionController.register) await this.#contextActionController.dispatch(this.actionName, this.actionPayload);
+			} catch (error) {
+				this.dispatchEvent(new CustomEvent("cart-action-error", {
+					bubbles: true,
+					composed: true,
+					detail: { error }
+				}));
+			}
+		};
+		this.#contextStoreController = new ContextStoreController(this, {
+			context: cartStoreContext,
+			selector: (state) => this.selector ? this.selector(state) : defaultCartCountSelector(state),
+			equalityFn: (a, b) => this.equalityFn ? this.equalityFn(a, b) : Object.is(a, b)
+		});
+		this.#contextActionController = new ContextActionController(this, { context: actionRegisterContext });
+	}
+	willUpdate(changedProperties) {
+		super.willUpdate(changedProperties);
+		if (changedProperties.has("store") || changedProperties.has("selector") || changedProperties.has("equalityFn")) {
+			if (this.#directStoreController) {
+				this.#directStoreController.dispose();
+				this.#directStoreController = null;
+			}
+			if (this.store) this.#directStoreController = new _context_action_lit.StoreController(this, this.store, {
+				selector: (state) => this.selector ? this.selector(state) : defaultCartCountSelector(state),
+				equalityFn: this.equalityFn ?? Object.is
+			});
+		}
+		if (changedProperties.has("register")) {
+			if (this.register) this.#directActionController = new _context_action_lit.ActionController(this, this.register);
+			else this.#directActionController = null;
+		}
+		const currentCount = this.count;
+		if (this.#previousCount !== void 0 && currentCount > this.#previousCount) this.isPulsing = true;
+		this.#previousCount = currentCount;
+	}
+	/**
+	* Derives the current total count from direct override, direct store, or context store.
+	*/
+	get count() {
+		if (this.value !== void 0) return this.value;
+		if (this.#directStoreController) return this.#directStoreController.value;
+		if (this.store) {
+			const raw = typeof this.store.getValue === "function" ? this.store.getValue() : typeof this.store.getSnapshot === "function" ? this.store.getSnapshot() : void 0;
+			return this.selector ? this.selector(raw) : defaultCartCountSelector(raw);
+		}
+		if (this.#contextStoreController.isResolved && this.#contextStoreController.value !== void 0) return this.#contextStoreController.value;
+		return 0;
+	}
+	set count(val) {
+		const oldVal = this.count;
+		if (val === void 0 || val === null) this.value = void 0;
+		else this.value = Number.isFinite(val) ? Math.max(0, Math.floor(val)) : 0;
+		this.requestUpdate("count", oldVal);
+	}
+	/**
+	* Indicates whether an action dispatch is currently in flight.
+	*/
+	get isPending() {
+		if (this.#directActionController) return this.#directActionController.isPending;
+		return this.#contextActionController.isPending;
+	}
+	updated(changedProperties) {
+		super.updated(changedProperties);
+		const currentCount = this.count;
+		this.toggleAttribute("has-items", currentCount > 0);
+		this.toggleAttribute("count-zero", currentCount === 0);
+	}
+	#handleClick;
+	render() {
+		const current = this.count;
+		if (this.hideZero && current <= 0) return lit.nothing;
+		const pending = this.isPending;
+		const displayCount = current > this.maxCount ? `${this.maxCount}+` : String(current);
+		return lit.html`
+      <button
+        type="button"
+        part="button badge"
+        class="badge ${this.isPulsing ? "pulse" : ""}"
+        ?disabled=${this.disabled || pending}
+        @click=${this.#handleClick}
+        @animationend=${() => {
+			this.isPulsing = false;
+		}}
+        aria-label=${this.getAttribute("aria-label") || `${this.label}: ${displayCount} items`}
+      >
+        <slot name="icon">
+          <span part="icon" class="icon" aria-hidden="true">🛒</span>
+        </slot>
+        <span part="label" class="label"><slot>${this.label}</slot></span>
+        <span part="count" class="count">${displayCount}</span>
+        ${pending ? lit.html`<span
+              part="spinner"
+              class="spinner"
+              aria-label="Loading"
+            ></span>` : lit.nothing}
+      </button>
+    `;
+	}
+};
+__decorate([(0, lit_decorators_js.property)({ attribute: false })], LitCartBadge.prototype, "store", void 0);
+__decorate([(0, lit_decorators_js.property)({ attribute: false })], LitCartBadge.prototype, "register", void 0);
+__decorate([(0, lit_decorators_js.property)({ attribute: false })], LitCartBadge.prototype, "selector", void 0);
+__decorate([(0, lit_decorators_js.property)({ attribute: false })], LitCartBadge.prototype, "equalityFn", void 0);
+__decorate([(0, lit_decorators_js.property)({ attribute: false })], LitCartBadge.prototype, "storeContext", void 0);
+__decorate([(0, lit_decorators_js.property)({ attribute: false })], LitCartBadge.prototype, "actionContext", void 0);
+__decorate([(0, lit_decorators_js.property)({ type: Number })], LitCartBadge.prototype, "value", void 0);
+__decorate([(0, lit_decorators_js.property)({
+	type: Number,
+	attribute: "max-count"
+})], LitCartBadge.prototype, "maxCount", void 0);
+__decorate([(0, lit_decorators_js.property)({
+	type: Boolean,
+	reflect: true,
+	attribute: "hide-zero"
+})], LitCartBadge.prototype, "hideZero", void 0);
+__decorate([(0, lit_decorators_js.property)({ type: String })], LitCartBadge.prototype, "label", void 0);
+__decorate([(0, lit_decorators_js.property)({
+	type: String,
+	attribute: "action-name"
+})], LitCartBadge.prototype, "actionName", void 0);
+__decorate([(0, lit_decorators_js.property)({ attribute: false })], LitCartBadge.prototype, "actionPayload", void 0);
+__decorate([(0, lit_decorators_js.property)({
+	type: Boolean,
+	reflect: true
+})], LitCartBadge.prototype, "disabled", void 0);
+__decorate([(0, lit_decorators_js.property)({
+	type: String,
+	reflect: true
+})], LitCartBadge.prototype, "variant", void 0);
+__decorate([(0, lit_decorators_js.state)()], LitCartBadge.prototype, "isPulsing", void 0);
+defineCustomElement("lit-cart-badge", LitCartBadge);
+exports.ContextActionController = ContextActionController;
+Object.defineProperty(exports, "ContextConsumer", {
+	enumerable: true,
+	get: function() {
+		return _lit_context.ContextConsumer;
+	}
+});
+Object.defineProperty(exports, "ContextProvider", {
+	enumerable: true,
+	get: function() {
+		return _lit_context.ContextProvider;
+	}
+});
+exports.ContextStoreController = ContextStoreController;
+Object.defineProperty(exports, "ControllerScope", {
+	enumerable: true,
+	get: function() {
+		return _context_action_lit.ControllerScope;
+	}
+});
+exports.FormAssociatedLitElement = FormAssociatedLitElement;
+exports.LitCartBadge = LitCartBadge;
+exports.LitQuantityStepper = LitQuantityStepper;
+exports.actionDispatcherContext = actionDispatcherContext;
+exports.actionRegisterContext = actionRegisterContext;
+exports.cartStoreContext = cartStoreContext;
+exports.createActionDispatcherContext = createActionDispatcherContext;
+exports.createActionRegisterContext = createActionRegisterContext;
+Object.defineProperty(exports, "createContext", {
+	enumerable: true,
+	get: function() {
+		return _lit_context.createContext;
+	}
+});
+exports.createCustomElementBridge = createLitElementBridge;
+exports.createElementFacade = createElementFacade;
+exports.createLitBridge = createLitElementBridge;
+exports.createLitElementBridge = createLitElementBridge;
+exports.createStoreContext = createStoreContext;
+exports.defaultCartCountSelector = defaultCartCountSelector;
+exports.provideActionDispatcher = provideActionDispatcher;
+exports.provideActionRegister = provideActionRegister;
+exports.provideStore = provideStore;
+
+//# sourceMappingURL=index.cjs.map