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

package/dist/index.d.cts

@@ -0,0 +1,644 @@
+import { LitElement, PropertyValues, ReactiveController, ReactiveControllerHost, nothing } from "lit";
+import { Context, Context as Context$1, ContextConsumer, ContextProvider, createContext } from "@lit/context";
+import { ActionDispatcher, ActionNames, ActionPayloadMap, ActionRegister, DispatchArgs } from "@context-action/core";
+import { ControllerScope, ControllerScopeOptions, EqualityFn, ReadableStore, Selector } from "@context-action/lit";
+import * as React from "react";
+/**
+ * Standard form validity flags as defined in the HTML Living Standard.
+ */
+interface ValidityStateFlags {
+  badInput?: boolean;
+  customError?: boolean;
+  patternMismatch?: boolean;
+  rangeOverflow?: boolean;
+  rangeUnderflow?: boolean;
+  stepMismatch?: boolean;
+  tooLong?: boolean;
+  tooShort?: boolean;
+  typeMismatch?: boolean;
+  valueMissing?: boolean;
+}
+/**
+ * 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
+ */
+export declare class FormAssociatedLitElement extends LitElement {
+  #private;
+  /**
+   * Identifies this custom element as form-associated according to the HTML specification.
+   * Enables the browser engine to attach ElementInternals and include this element in form submission.
+   */
+  static readonly formAssociated = true;
+  /**
+   * The ElementInternals controller instance for this custom element.
+   * Undefined in environments where attachInternals is unsupported.
+   */
+  readonly internals?: ElementInternals;
+  name: string;
+  type: string;
+  disabled: boolean;
+  required: boolean;
+  constructor();
+  /**
+   * 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(): HTMLFormElement | null;
+  /**
+   * 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: File | string | FormData | null, state?: File | string | FormData | null): void;
+  /**
+   * Returns the current form submission value.
+   */
+  getFormValue(): File | string | FormData | null;
+  /**
+   * Getter alias for getFormValue() for uniform property access.
+   */
+  get formValue(): File | string | FormData | null;
+  /**
+   * Returns the current state restoration object.
+   */
+  get formState(): unknown;
+  /**
+   * 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?: ValidityStateFlags, message?: string, anchor?: HTMLElement): void;
+  /**
+   * Returns the current ValidityState object representing constraint validation status.
+   */
+  get validity(): ValidityState;
+  /**
+   * Returns the current validation error message, or an empty string if valid.
+   */
+  get validationMessage(): string;
+  /**
+   * Returns true if the element participates in constraint validation and is not disabled.
+   */
+  get willValidate(): boolean;
+  /**
+   * 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(): boolean;
+  /**
+   * Checks validity, reports errors to the user (e.g. browser popup), and returns validity status.
+   */
+  reportValidity(): boolean;
+  /**
+   * 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: string): void;
+  /**
+   * Native FACE callback invoked by the browser engine when the associated form is reset.
+   * Dispatches to the overridable onFormReset() hook.
+   */
+  formResetCallback(): void;
+  /**
+   * Overridable lifecycle hook called when the associated form is reset.
+   * Subclasses should restore default values, re-evaluate validation, and request updates.
+   */
+  protected onFormReset(): void;
+  /**
+   * Native FACE callback invoked when the element or parent fieldset is disabled/enabled.
+   */
+  formDisabledCallback(disabled: boolean): void;
+  /**
+   * Overridable lifecycle hook called when the disabled state changes.
+   */
+  protected onFormDisabled(_disabled: boolean): void;
+  /**
+   * Native FACE callback invoked when the browser restores form state (history navigation / autofill).
+   */
+  formStateRestoreCallback(state: unknown, mode: 'restore' | 'autocomplete'): void;
+  /**
+   * Overridable lifecycle hook called when the browser restores form state.
+   */
+  protected onFormStateRestore(_state: unknown, _mode: 'restore' | 'autocomplete'): void;
+  /**
+   * Native FACE callback invoked when the element is associated or disassociated with a form.
+   */
+  formAssociatedCallback(form: HTMLFormElement | null): void;
+  /**
+   * Overridable lifecycle hook called when the element's form association changes.
+   */
+  protected onFormAssociated(_form: HTMLFormElement | null): void;
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+}
+/**
+ * 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
+ */
+export declare const actionRegisterContext: Context<symbol, ActionRegister<any>>;
+/**
+ * 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
+ */
+export declare const actionDispatcherContext: Context<symbol, ActionDispatcher<any>>;
+/**
+ * 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
+ */
+export declare function createStoreContext<T = unknown>(name: string): Context<symbol, ReadableStore<T>>;
+/**
+ * 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>.
+ */
+export declare function createActionRegisterContext<A extends ActionPayloadMap = ActionPayloadMap>(name?: string): Context<symbol, ActionRegister<A>>;
+/**
+ * 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>.
+ */
+export declare function createActionDispatcherContext<A extends ActionPayloadMap = ActionPayloadMap>(name?: string): Context<symbol, ActionDispatcher<A>>;
+/**
+ * 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.
+ */
+export declare function provideActionRegister<A extends ActionPayloadMap = ActionPayloadMap>(host: HTMLElement & ReactiveControllerHost, register: ActionRegister<A>, context?: Context<unknown, ActionRegister<A>>): ContextProvider<Context<unknown, ActionRegister<A>>>;
+/**
+ * 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.
+ */
+export declare function provideActionDispatcher<A extends ActionPayloadMap = ActionPayloadMap>(host: HTMLElement & ReactiveControllerHost, dispatcher: ActionDispatcher<A>, context?: Context<unknown, ActionDispatcher<A>>): ContextProvider<Context<unknown, ActionDispatcher<A>>>;
+/**
+ * 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.
+ */
+export declare function provideStore<T>(host: HTMLElement & ReactiveControllerHost, context: Context<unknown, ReadableStore<T>>, store: ReadableStore<T>): ContextProvider<Context<unknown, ReadableStore<T>>>;
+/**
+ * Options for `ContextStoreController`.
+ *
+ * @template T Source store state type.
+ * @template Selected Projected output type.
+ */
+interface ContextStoreControllerOptions<T, Selected = T> {
+  /** The W3C Context token created via `createStoreContext`. */
+  context: Context<unknown, ReadableStore<T>>;
+  /** Optional projection selector to derive a slice of state. */
+  selector?: Selector<T, Selected>;
+  /** Optional equality comparator to prevent redundant rerenders. Defaults to Object.is. */
+  equalityFn?: EqualityFn<Selected>;
+}
+/**
+ * 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
+ */
+export declare class ContextStoreController<T = unknown, Selected = T> implements ReactiveController {
+  #private;
+  constructor(host: ReactiveControllerHost & HTMLElement, options: ContextStoreControllerOptions<T, Selected>);
+  /** Current projected state derived from the injected store, or undefined if not yet provided. */
+  get value(): Selected | undefined;
+  /** The resolved ReadableStore instance currently bound to this controller. */
+  get store(): ReadableStore<T> | undefined;
+  /** Indicates whether the context request has been satisfied by an ancestor provider. */
+  get isResolved(): boolean;
+  hostConnected(): void;
+  hostDisconnected(): void;
+}
+/**
+ * Options for `ContextActionController`.
+ *
+ * @template A Action payload map.
+ */
+interface ContextActionControllerOptions<A extends ActionPayloadMap = ActionPayloadMap> {
+  /** Optional custom context token (defaults to actionRegisterContext). */
+  context?: Context<unknown, ActionRegister<A>>;
+}
+/**
+ * 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
+ */
+export declare class ContextActionController<A extends ActionPayloadMap = ActionPayloadMap> implements ReactiveController {
+  #private;
+  constructor(host: ReactiveControllerHost & HTMLElement, options?: ContextActionControllerOptions<A>);
+  /** The resolved ActionRegister instance, or undefined if no provider is present. */
+  get register(): ActionRegister<A> | undefined;
+  /** Whether an action dispatch is currently in progress. */
+  get isPending(): boolean;
+  /** The last error thrown during an action dispatch, if any. */
+  get lastError(): Error | undefined;
+  /**
+   * 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.
+   */
+  dispatch<K extends ActionNames<A>>(action: K, ...args: DispatchArgs<A[K]>): Promise<void>;
+  /**
+   * 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.
+   */
+  dispatchWithResult<K extends ActionNames<A>, R = unknown>(action: K, ...args: DispatchArgs<A[K]>): Promise<R>;
+  hostConnected(): void;
+  hostDisconnected(): void;
+}
+/**
+ * @module facade
+ *
+ * Purpose:
+ *   Provides zero-dependency OOP Facade utilities (`PublicActionMethods`,
+ *   `ImperativeHandleFactory`, `createElementFacade`) that project a Custom
+ *   Element's public contract into an encapsulated handle without exposing raw
+ *   `HTMLElement` or `ShadowRoot` internals.
+ *
+ * Invariants:
+ *   - Pure TypeScript/ES2022 runtime with zero Lit or React dependencies,
+ *     usable in Vanilla DOM, Lit, or React bridges alike.
+ *   - `createElementFacade` returns a frozen object (`instanceof HTMLElement === false`),
+ *     binds methods lazily to the live element, and caches bound function
+ *     identities in a `WeakMap` so detached elements are never retained.
+ *   - Rejects writes to read-only properties with a `TypeError` and throws a
+ *     descriptive error when accessed while unmounted.
+ */
+/**
+ * Maps selected action keys from an ActionPayloadMap-compatible record into
+ * object-oriented method signatures while hiding internal action keys.
+ */
+type PublicActionMethods<Actions extends Record<string, any>, PublicKeys extends keyof Actions = keyof Actions, ReturnMap extends Partial<Record<PublicKeys, unknown>> = Record<never, never>> = { readonly [K in PublicKeys]: [Actions[K]] extends [void | undefined] ? () => K extends keyof ReturnMap ? Promise<ReturnMap[K]> : Promise<void> : (payload: Actions[K]) => K extends keyof ReturnMap ? Promise<ReturnMap[K]> : Promise<void>; };
+/**
+ * Host-agnostic factory function that creates an encapsulated OOP handle
+ * from a lazy custom element getter, hiding raw `HTMLElement` internals.
+ */
+type ImperativeHandleFactory<Element extends HTMLElement, Handle> = (getElement: () => Element | null) => Handle;
+/**
+ * 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']),
+ * });
+ * ```
+ */
+export declare function createElementFacade<Element extends HTMLElement, const Keys extends readonly (keyof Element)[]>(keys: Keys): ImperativeHandleFactory<Element, Pick<Element, Keys[number]>>;
+/**
+ * Configuration options for the Lit React Bridge.
+ * Controls direct property assignment, custom event mapping, and facade handles.
+ */
+interface LitBridgeConfig<Props extends Record<string, any>, Element extends HTMLElement = any, Handle = any> {
+  /**
+   * Property keys that should be assigned directly as DOM element properties
+   * rather than rendered as HTML attributes.
+   *
+   * This is critical for React 18 compatibility, which stringifies complex objects,
+   * arrays, functions, and class instances (such as Context-Action stores) to `"[object Object]"`.
+   *
+   * On a later render, a key previously assigned by the bridge and then omitted
+   * from props is reset to `undefined` so stale objects never remain on the
+   * element. Untouched element defaults are preserved, and read-only properties
+   * are left to the element adapter's interpretation.
+   */
+  properties?: readonly (keyof Props)[];
+  /**
+   * Map of React prop handler names to native DOM CustomEvent names.
+   *
+   * Listeners are reconciled by handler identity: a re-render with the same
+   * handler performs no DOM work, while a changed handler (or `undefined`)
+   * removes and re-attaches only that event.
+   *
+   * @example
+   * ```ts
+   * events: {
+   *   onQuantityChange: 'quantity-change',
+   *   onCartBadgeClick: 'cart-badge-click',
+   * }
+   * ```
+   */
+  events?: Record<string, string>;
+  /**
+   * Optional factory for `useImperativeHandle` that encapsulates the underlying
+   * `Element` and exposes only an object-oriented Facade handle to parent refs.
+   * When omitted, the raw `Element` instance is forwarded for backward compatibility.
+   *
+   * Use `createElementFacade(['focusItem', 'scrollTo'])` for a zero-dependency
+   * allow-list facade.
+   */
+  createHandle?: ImperativeHandleFactory<Element, Handle>;
+}
+/**
+ * Options object signature for createLitElementBridge, including the custom element tagName.
+ */
+interface LitBridgeOptions<Props extends Record<string, any>, Element extends HTMLElement = HTMLElement, Handle = Element> extends LitBridgeConfig<Props, Element, Handle> {
+  /**
+   * The registered custom element HTML tag name, e.g. 'lit-quantity-stepper'.
+   */
+  tagName: string;
+}
+/**
+ * Strongly typed React ForwardRefExoticComponent representing the bridged Custom Element.
+ */
+type LitElementComponent<Props extends Record<string, any>, Element extends HTMLElement = HTMLElement, Handle = Element> = React.ForwardRefExoticComponent<React.PropsWithoutRef<Props & Omit<React.HTMLAttributes<Element>, keyof Props>> & React.RefAttributes<Handle>>;
+/**
+ * Overload 1: Two-argument form `(tagName, config?)`.
+ *
+ * @example
+ * ```tsx
+ * const ReactStepper = createLitElementBridge<StepperProps, LitQuantityStepper>(
+ *   'lit-quantity-stepper',
+ *   {
+ *     properties: ['metadata', 'cartStore'],
+ *     events: { onQuantityChange: 'quantity-change' },
+ *   }
+ * );
+ * ```
+ */
+export declare function createLitElementBridge<Props extends Record<string, any> = Record<string, any>, Element extends HTMLElement = HTMLElement, Handle = Element>(tagName: string, config?: LitBridgeConfig<Props, Element, Handle>): LitElementComponent<Props, Element, Handle>;
+/**
+ * Overload 2: Single-argument options form `(options)`.
+ *
+ * @example
+ * ```tsx
+ * const ReactTimeline = createLitElementBridge<TimelineProps, TimelineElement, TimelineHandle>({
+ *   tagName: 'st-timeline',
+ *   properties: ['input', 'set'],
+ *   events: { onSelectionChange: 'selection-change' },
+ *   createHandle: createElementFacade(['focusItem', 'scrollTo', 'commitSelection']),
+ * });
+ * ```
+ */
+export declare function createLitElementBridge<Props extends Record<string, any> = Record<string, any>, Element extends HTMLElement = HTMLElement, Handle = Element>(options: LitBridgeOptions<Props, Element, Handle>): LitElementComponent<Props, Element, Handle>;
+/**
+ * Event detail payload dispatched by <lit-quantity-stepper> on change and input events.
+ */
+interface QuantityChangeEventDetail {
+  value: number;
+}
+/**
+ * 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.
+ */
+export declare class LitQuantityStepper extends FormAssociatedLitElement {
+  #private;
+  static styles: import("lit").CSSResult;
+  /**
+   * The current numerical value of the stepper.
+   */
+  value: number;
+  /**
+   * Minimum permissible value (inclusive).
+   */
+  min: number;
+  /**
+   * Maximum permissible value (inclusive).
+   */
+  max: number;
+  /**
+   * Step increment/decrement delta. Must be greater than 0.
+   */
+  step: number;
+  /**
+   * Whether the control prevents user modification while remaining form-submittable.
+   */
+  readonly: boolean;
+  /**
+   * Default value used to restore state when the enclosing form is reset.
+   */
+  defaultValue?: number;
+  private focused;
+  private inputEl?;
+  connectedCallback(): void;
+  updated(changedProperties: PropertyValues<this>): void;
+  /**
+   * Increments the current value by the configured step.
+   * If at or above max, or if disabled/readonly, this operation is a no-op.
+   */
+  increment(): void;
+  /**
+   * Decrements the current value by the configured step.
+   * If at or below min, or if disabled/readonly, this operation is a no-op.
+   */
+  decrement(): void;
+  /**
+   * 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: number, options?: {
+    dispatchEvents?: boolean;
+  }): void;
+  /**
+   * Invoked by FormAssociatedLitElement when the parent form executes a reset.
+   * Restores initial value, clears validation, and synchronizes form value.
+   */
+  protected onFormReset(): void;
+  render(): import("lit").TemplateResult<1>;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    'lit-quantity-stepper': LitQuantityStepper;
+  }
+}
+/**
+ * Standard W3C Context token for the shopping cart domain store.
+ * Uses Symbol.for to guarantee singleton identity across independent bundle chunks.
+ */
+export declare const cartStoreContext: Context$1<symbol, ReadableStore<any>>;
+/**
+ * Custom event detail emitted when the cart badge button is clicked.
+ */
+interface CartBadgeClickEventDetail {
+  count: number;
+  isPending: boolean;
+}
+/**
+ * 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 }`)
+ */
+export declare function defaultCartCountSelector(state: unknown): number;
+/**
+ * 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.
+ */
+export declare class LitCartBadge extends LitElement {
+  #private;
+  static styles: import("lit").CSSResult;
+  /**
+   * Explicit ReadableStore instance passed directly to this component.
+   * If provided, overrides context-based store resolution.
+   */
+  store?: ReadableStore<any>;
+  /**
+   * Explicit ActionRegister instance passed directly to this component.
+   * If provided, overrides context-based action register resolution.
+   */
+  register?: ActionRegister<any>;
+  /**
+   * Custom projection selector for deriving the total quantity from store state.
+   */
+  selector?: Selector<any, number>;
+  /**
+   * Custom equality comparator function used for selective projection memoization.
+   */
+  equalityFn?: EqualityFn<number>;
+  /**
+   * Optional custom W3C Context token for resolving a cart store from ancestor providers.
+   */
+  storeContext?: Context$1<unknown, ReadableStore<any>>;
+  /**
+   * Optional custom W3C Context token for resolving an ActionRegister from ancestor providers.
+   */
+  actionContext?: Context$1<unknown, ActionRegister<any>>;
+  /**
+   * Static numerical count override. If defined, overrides both store and context values.
+   */
+  value: number | undefined;
+  /**
+   * Maximum count displayed before truncating with a '+' suffix (e.g. 99 -> '99+').
+   */
+  maxCount: number;
+  /**
+   * When true, hides the badge completely when count is 0.
+   */
+  hideZero: boolean;
+  /**
+   * Label text rendered next to the count. Defaults to 'Cart'.
+   */
+  label: string;
+  /**
+   * Optional action name dispatched on click through the configured ActionRegister.
+   */
+  actionName?: string;
+  /**
+   * Optional payload passed when dispatching actionName.
+   */
+  actionPayload?: unknown;
+  /**
+   * Whether the badge button is disabled.
+   */
+  disabled: boolean;
+  /**
+   * Visual variant: 'primary' | 'secondary' | 'accent' | 'danger'
+   */
+  variant: 'primary' | 'secondary' | 'accent' | 'danger';
+  private isPulsing;
+  constructor();
+  willUpdate(changedProperties: PropertyValues<this>): void;
+  /**
+   * Derives the current total count from direct override, direct store, or context store.
+   */
+  get count(): number;
+  set count(val: number | undefined);
+  /**
+   * Indicates whether an action dispatch is currently in flight.
+   */
+  get isPending(): boolean;
+  updated(changedProperties: PropertyValues<this>): void;
+  render(): typeof nothing | import("lit").TemplateResult<1>;
+}
+declare global {
+  interface HTMLElementTagNameMap {
+    'lit-cart-badge': LitCartBadge;
+  }
+}
+export { type CartBadgeClickEventDetail, type Context, type ContextActionControllerOptions, ContextConsumer, ContextProvider, type ContextStoreControllerOptions, ControllerScope, type ControllerScopeOptions, type ImperativeHandleFactory, type LitBridgeConfig, type LitBridgeOptions, type LitElementComponent, type PublicActionMethods, type QuantityChangeEventDetail, type ValidityStateFlags, createContext, createLitElementBridge as createCustomElementBridge, createLitElementBridge as createLitBridge };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":["_0","Context"],"sources":["../src/form-associated-element.ts","../src/context.ts","../src/facade.ts","../src/react-bridge.ts","../src/components/quantity-stepper.ts","../src/components/cart-badge.ts"],"mappings":"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"}