@qualcomm-ui/angular-core 1.0.1 → 1.0.3

package/machine/index.d.ts

@@ -1,14 +1,214 @@
-export * from "./api-context.directive";
-export * from "./api-context.service";
-export * from "./bindable-id-collection";
-export * from "./bindable-id";
-export * from "./bindable";
-export type * from "./machine.types";
-export * from "./merge-props";
-export * from "./q-bind.directive";
-export * from "./normalize-props";
-export * from "./refs";
-export * from "./track";
-export * from "./use-machine";
-export * from "./use-track-bindings";
-//# sourceMappingURL=index.d.ts.map
+import * as i0 from '@angular/core';
+import { Signal, InjectOptions, InjectionToken, Provider, ElementRef, Renderer2, OnDestroy, Injector } from '@angular/core';
+import * as _qualcomm_ui_utils_machine from '@qualcomm-ui/utils/machine';
+import { Dict as Dict$1, BindableIdCollection, BindableId, EventDetails, BindableParams, Bindable, MachineSchema, MachineConfig, Machine } from '@qualcomm-ui/utils/machine';
+
+/**
+ * Manages the API context for a service.
+ *
+ * Provides a way to initialize and access an API signal, ensuring that it is only
+ * set once. Attempting to reinitialize or access an uninitialized API will result
+ * in errors.
+ *
+ * @template T - The type of the data returned by the API.
+ */
+declare abstract class BaseApiContextService<T> {
+    readonly initialized: i0.WritableSignal<boolean>;
+    get context(): Signal<T>;
+    private _context;
+    init(computedApi: Signal<T>): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<BaseApiContextService<any>, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<BaseApiContextService<any>>;
+}
+type UseContextOpts<Optional extends boolean = false> = InjectOptions & {
+    /**
+     * Use optional injection, and return `null` if the requested token is not found.
+     */
+    optional?: Optional;
+};
+type ApiContext<T> = [
+    InjectionToken<() => T>,
+    <Optional extends boolean = false>(opts?: UseContextOpts<Optional>) => Optional extends true ? (() => T) | null : () => T,
+    () => Provider[]
+];
+declare function createApiContext<T, K extends typeof BaseApiContextService<T> = typeof BaseApiContextService<T>>(name: string, service: K, initialValue?: T): ApiContext<T>;
+
+/**
+ * Base directive for creating context-aware directives that render content
+ * only when an API context is available.
+ *
+ * This abstract class provides the core functionality to:
+ * 1. Check if a required API context service is available
+ * 2. Render the associated template only when the API instance is accessible
+ * 3. Provide the API instance to the template as a typed value
+ */
+declare abstract class ApiContextDirective<T extends object> {
+    private readonly templateRef;
+    private readonly viewContainerRef;
+    private readonly injector;
+    protected constructor(contextService: BaseApiContextService<T>, contextName: string);
+    static ɵfac: i0.ɵɵFactoryDeclaration<ApiContextDirective<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<ApiContextDirective<any>, never, never, {}, {}, never, never, true, never>;
+}
+
+declare function bindableIdCollection<T extends Dict$1>(): BindableIdCollection<any, any>;
+
+declare function bindableId(initialValue: string | undefined): BindableId<string | undefined>;
+
+declare function bindable<T, ChangeEvent extends EventDetails | void | null>(props: () => BindableParams<T, ChangeEvent>): Bindable<T, ChangeEvent>;
+declare namespace bindable {
+    var cleanup: (fn: VoidFunction) => void;
+    var ref: <T>(defaultValue: T) => {
+        get: () => T;
+        set: (next: T) => void;
+    };
+}
+
+type StyleObject = Record<string, string | number>;
+type Dict = Record<string, any>;
+declare const normalizeProps: _qualcomm_ui_utils_machine.PropNormalizer<_qualcomm_ui_utils_machine.JSX.CSSProperties>;
+
+interface TrackBindingsConfig {
+    debug?: boolean | undefined;
+    /**
+     * If true, the default prop spreader for this part will not be initialized.
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Override the ElementRef target for the property spreader function.
+     */
+    elementRef?: ElementRef | (() => ElementRef);
+    /**
+     * Prop getter for additional props to spread onto the host element.
+     */
+    extraBindings?: (() => Dict) | Signal<Dict>;
+}
+type InitTrackerFn = ((opts?: TrackBindingsConfig) => void) & {
+    /**
+     * Add additional props to spread onto the host element.
+     */
+    extendWith: (computedProps: () => Dict) => void;
+    setDisabled: (disabled: boolean) => void;
+};
+/**
+ * Creates a reactive property binding system that dynamically applies computed
+ * properties to a host element. This function sets up an effect that watches for
+ * changes in the provided property getter and efficiently updates the DOM element
+ * accordingly.
+ *
+ * @param propGetter - A function that returns a dictionary of properties to bind to the element.
+ *   Supports attributes, CSS classes, styles, event listeners, and DOM properties.
+ *
+ * @returns An initialization function that starts the reactive binding process
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   selector: 'my-component',
+ *   template: '<div>Content</div>'
+ * })
+ * export class MyComponent {
+ *   protected readonly isExpanded = signal(false)
+ *
+ *   private readonly trackBindings = useTrackBindings(() => ({
+ *     class: 'active component',
+ *     'aria-expanded': this.isExpanded(),
+ *   }))
+ *
+ *   ngOnInit() {
+ *     // Start the reactive binding
+ *     this.trackBindings()
+ *   }
+ * }
+ * ```
+ */
+declare function useTrackBindings(propGetter: () => Dict): InitTrackerFn;
+declare function applyBindings(el: HTMLElement, props: Dict, renderer: Renderer2): void;
+
+/**
+ * @deprecated, migrate to the useTrackBindingsInitOptions
+ */
+interface MachineInitOptions extends TrackBindingsConfig {
+    disabled?: never;
+}
+
+interface Props {
+    [key: string]: any;
+}
+/**
+ * Construct the real resulting type so callers keep strong typing.
+ */
+type MergeProps<T extends readonly Props[]> = T extends readonly [
+    infer First extends Props,
+    ...infer Rest extends readonly Props[]
+] ? First & MergeProps<Rest> : {};
+/**
+ * Angular-friendly version of `mergeProps`.
+ *
+ * - Handlers (`on*`) are composed with `callAll`.
+ * - `class` / `className` values are merged via `clsx`.
+ * - `style` strings or objects are merged and normalised.
+ */
+declare function mergeProps<T extends readonly Props[]>(...sources: T): MergeProps<T>;
+
+interface NgBindOptions {
+    /**
+     * This list of properties will not be spread onto the target element.
+     */
+    omittedProps?: string[];
+}
+/**
+ * A directive similar to Vue's `v-bind` that spreads an object's properties onto
+ * the host element. For the best performance, use a stable reference to a signal
+ * instead of an object literal in the template. Converts callbacks from `on*`
+ * syntax to their corresponding Angular event callbacks. Does not account for
+ * input/output properties due to Angular limitations.
+ *
+ * @example
+ * <!-- bad: new object every time -->
+ * <div [q-bind]="{class: 'a', onClick: click}"></div>
+ *
+ * <!-- good: stable reference -->
+ * <div [q-bind]="buttonProps"></div>
+ */
+declare class QBindDirective implements OnDestroy {
+    readonly bind: i0.InputSignal<Dict | undefined>;
+    readonly bindOptions: i0.InputSignal<NgBindOptions>;
+    private readonly elementRef;
+    private readonly renderer;
+    private readonly injector;
+    private readonly listeners;
+    private prev;
+    readonly omittedProps: i0.Signal<Set<string>>;
+    constructor();
+    ngOnDestroy(): void;
+    private removeClass;
+    private addClass;
+    private removeStyle;
+    private addStyle;
+    private addEventListener;
+    private handleAttrs;
+    static ɵfac: i0.ɵɵFactoryDeclaration<QBindDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<QBindDirective, "[q-bind]", never, { "bind": { "alias": "q-bind"; "required": true; "isSignal": true; }; "bindOptions": { "alias": "q-bind-options"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+declare function createRefs<T>(refs: T): {
+    get<K extends keyof T>(key: K): T[K];
+    set<K extends keyof T>(key: K, value: T[K]): void;
+};
+
+declare function useTrack(injector: Injector): (deps: any[], _effect: VoidFunction) => void;
+
+interface MachineOpts {
+    /**
+     * If true, enable debug logging.
+     *
+     * @default false
+     */
+    debug?: boolean | undefined;
+}
+declare function useMachine<T extends MachineSchema>(config: MachineConfig<T>, userProps: (Partial<T["props"]> | Signal<Partial<T["props"]>>) | undefined, injector: Injector, opts?: MachineOpts): Machine<T>;
+
+export { ApiContextDirective, BaseApiContextService, QBindDirective, applyBindings, bindable, bindableId, bindableIdCollection, createApiContext, createRefs, mergeProps, normalizeProps, useMachine, useTrack, useTrackBindings };
+export type { ApiContext, Dict, MachineInitOptions, MachineOpts, MergeProps, NgBindOptions, StyleObject, TrackBindingsConfig, UseContextOpts };
+//# sourceMappingURL=index.d.ts.map

package/machine/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/machine/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAA;AACvC,cAAc,uBAAuB,CAAA;AACrC,cAAc,0BAA0B,CAAA;AACxC,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,mBAAmB,iBAAiB,CAAA;AACpC,cAAc,eAAe,CAAA;AAC7B,cAAc,oBAAoB,CAAA;AAClC,cAAc,mBAAmB,CAAA;AACjC,cAAc,QAAQ,CAAA;AACtB,cAAc,SAAS,CAAA;AACvB,cAAc,eAAe,CAAA;AAC7B,cAAc,sBAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sources":["../../src/machine/api-context.service.ts","../../src/machine/api-context.directive.ts","../../src/machine/bindable-id-collection.ts","../../src/machine/bindable-id.ts","../../src/machine/bindable.ts","../../src/machine/normalize-props.ts","../../src/machine/use-track-bindings.ts","../../src/machine/machine.types.ts","../../src/machine/merge-props.ts","../../src/machine/q-bind.directive.ts","../../src/machine/refs.ts","../../src/machine/track.ts","../../src/machine/use-machine.ts"],"sourcesContent":[null,null,null,null,null,null,null,null,null,null,null,null,null],"names":[],"mappings":";;;;;AAaA;;;;;;;;AAQG;AACH;;AAIE;;;;;AAeD;AAEK;AACJ;;AAEG;;;AAIC;;;AAKJ;;AAGF;;AC5CA;;;;;;;;AAQG;AACH;AAEE;AACA;AACA;;;;AA6BD;;ACjDD;;ACAA;;ACKA;;;AA2CgB;;;;;;ACtBV;AAEA;AAEN;;;ACfE;AAEA;;AAEG;AACH;AAEA;;AAEG;;AAGH;;AAEG;;AAEJ;AAED;AACE;;AAEG;;AAEH;;AAGF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BG;AACH;AAgMA;;AC3QA;;AAEG;AACG;;AAEL;;ACJD;AACE;AACD;AAgCD;;AAEG;AACG;;AAEJ;;AAKF;;;;;;AAMG;AACH;;;AClCE;;AAEG;AACH;AACD;AAED;;;;;;;;;;;;;AAaG;AACH;;;AAQE;AACA;AACA;AACA;;;;AAoBA;AAKA;AAWA;AASA;AAWA;AAOA;AAYA;;;AA6ED;;ACzMD;;;AAcC;;ACPD;;;ACmCE;;;;AAIG;AACH;AACD;AAED;;;"}