@runopencode/rx-stencil 0.4.3 → 0.5.0

package/dist/types/components.d.ts

@@ -5,15 +5,38 @@
  * It contains typing information for all components that exist in this project.
  */
 import { HTMLStencilElement, JSXBase } from "./stencil-public-runtime";
-import { AsyncValue } from "./components/async/async";
-export { AsyncValue } from "./components/async/async";
+import { AsyncValue, ValueTransformFn } from "./components/async/async";
+export { AsyncValue, ValueTransformFn } from "./components/async/async";
 export namespace Components {
     interface RxAsync {
+        /**
+          * @default (value: unknown | null | undefined): any => value
+         */
+        "transform": ValueTransformFn;
         /**
           * @default null
          */
         "value": AsyncValue;
     }
+    interface TestPropertiesObservable {
+        "bar": string;
+        "baz": string;
+        "foo": string;
+    }
+    interface TestPropertyObservable {
+        "setValue": (value: string) => Promise<void>;
+    }
+    interface TestScheduleRender {
+        "increase": () => Promise<void>;
+    }
+    interface TestViewChildObservableShadowDom {
+        "clearLog": () => Promise<void>;
+        "getLog": () => Promise<string[]>;
+        /**
+          * @default 'all'
+         */
+        "which": 'even' | 'odd' | 'all';
+    }
 }
 declare global {
     interface HTMLRxAsyncElement extends Components.RxAsync, HTMLStencilElement {
@@ -22,19 +45,82 @@ declare global {
         prototype: HTMLRxAsyncElement;
         new (): HTMLRxAsyncElement;
     };
+    interface HTMLTestPropertiesObservableElement extends Components.TestPropertiesObservable, HTMLStencilElement {
+    }
+    var HTMLTestPropertiesObservableElement: {
+        prototype: HTMLTestPropertiesObservableElement;
+        new (): HTMLTestPropertiesObservableElement;
+    };
+    interface HTMLTestPropertyObservableElement extends Components.TestPropertyObservable, HTMLStencilElement {
+    }
+    var HTMLTestPropertyObservableElement: {
+        prototype: HTMLTestPropertyObservableElement;
+        new (): HTMLTestPropertyObservableElement;
+    };
+    interface HTMLTestScheduleRenderElement extends Components.TestScheduleRender, HTMLStencilElement {
+    }
+    var HTMLTestScheduleRenderElement: {
+        prototype: HTMLTestScheduleRenderElement;
+        new (): HTMLTestScheduleRenderElement;
+    };
+    interface HTMLTestViewChildObservableShadowDomElement extends Components.TestViewChildObservableShadowDom, HTMLStencilElement {
+    }
+    var HTMLTestViewChildObservableShadowDomElement: {
+        prototype: HTMLTestViewChildObservableShadowDomElement;
+        new (): HTMLTestViewChildObservableShadowDomElement;
+    };
     interface HTMLElementTagNameMap {
         "rx-async": HTMLRxAsyncElement;
+        "test-properties-observable": HTMLTestPropertiesObservableElement;
+        "test-property-observable": HTMLTestPropertyObservableElement;
+        "test-schedule-render": HTMLTestScheduleRenderElement;
+        "test-view-child-observable-shadow-dom": HTMLTestViewChildObservableShadowDomElement;
     }
 }
 declare namespace LocalJSX {
+    type OneOf<K extends string, PropT, AttrT = PropT> = { [P in K]: PropT } & { [P in `attr:${K}`]?: never } | { [P in `attr:${K}`]: AttrT } & { [P in K]?: never };
+
     interface RxAsync {
+        /**
+          * @default (value: unknown | null | undefined): any => value
+         */
+        "transform"?: ValueTransformFn;
         /**
           * @default null
          */
         "value"?: AsyncValue;
     }
+    interface TestPropertiesObservable {
+        "bar": string;
+        "baz": string;
+        "foo": string;
+    }
+    interface TestPropertyObservable {
+    }
+    interface TestScheduleRender {
+    }
+    interface TestViewChildObservableShadowDom {
+        /**
+          * @default 'all'
+         */
+        "which"?: 'even' | 'odd' | 'all';
+    }
+
+    interface TestPropertiesObservableAttributes {
+        "foo": string;
+        "bar": string;
+        "baz": string;
+    }
+    interface TestViewChildObservableShadowDomAttributes {
+        "which": 'even' | 'odd' | 'all';
+    }
+
     interface IntrinsicElements {
         "rx-async": RxAsync;
+        "test-properties-observable": Omit<TestPropertiesObservable, keyof TestPropertiesObservableAttributes> & { [K in keyof TestPropertiesObservable & keyof TestPropertiesObservableAttributes]?: TestPropertiesObservable[K] } & { [K in keyof TestPropertiesObservable & keyof TestPropertiesObservableAttributes as `attr:${K}`]?: TestPropertiesObservableAttributes[K] } & { [K in keyof TestPropertiesObservable & keyof TestPropertiesObservableAttributes as `prop:${K}`]?: TestPropertiesObservable[K] } & OneOf<"foo", TestPropertiesObservable["foo"], TestPropertiesObservableAttributes["foo"]> & OneOf<"bar", TestPropertiesObservable["bar"], TestPropertiesObservableAttributes["bar"]> & OneOf<"baz", TestPropertiesObservable["baz"], TestPropertiesObservableAttributes["baz"]>;
+        "test-property-observable": TestPropertyObservable;
+        "test-schedule-render": TestScheduleRender;
+        "test-view-child-observable-shadow-dom": Omit<TestViewChildObservableShadowDom, keyof TestViewChildObservableShadowDomAttributes> & { [K in keyof TestViewChildObservableShadowDom & keyof TestViewChildObservableShadowDomAttributes]?: TestViewChildObservableShadowDom[K] } & { [K in keyof TestViewChildObservableShadowDom & keyof TestViewChildObservableShadowDomAttributes as `attr:${K}`]?: TestViewChildObservableShadowDomAttributes[K] } & { [K in keyof TestViewChildObservableShadowDom & keyof TestViewChildObservableShadowDomAttributes as `prop:${K}`]?: TestViewChildObservableShadowDom[K] };
     }
 }
 export { LocalJSX as JSX };
@@ -42,6 +128,10 @@ declare module "@stencil/core" {
     export namespace JSX {
         interface IntrinsicElements {
             "rx-async": LocalJSX.IntrinsicElements["rx-async"] & JSXBase.HTMLAttributes<HTMLRxAsyncElement>;
+            "test-properties-observable": LocalJSX.IntrinsicElements["test-properties-observable"] & JSXBase.HTMLAttributes<HTMLTestPropertiesObservableElement>;
+            "test-property-observable": LocalJSX.IntrinsicElements["test-property-observable"] & JSXBase.HTMLAttributes<HTMLTestPropertyObservableElement>;
+            "test-schedule-render": LocalJSX.IntrinsicElements["test-schedule-render"] & JSXBase.HTMLAttributes<HTMLTestScheduleRenderElement>;
+            "test-view-child-observable-shadow-dom": LocalJSX.IntrinsicElements["test-view-child-observable-shadow-dom"] & JSXBase.HTMLAttributes<HTMLTestViewChildObservableShadowDomElement>;
         }
     }
 }

package/dist/types/rx/decorator/content-child.d.ts

@@ -0,0 +1,3 @@
+import { ViewChildOptions } from './view-child';
+export type ContentChildOptions = ViewChildOptions;
+export declare function ContentChild<E extends Element = Element>(selector: string, options?: ContentChildOptions): any;

package/dist/types/rx/decorator/content-children.d.ts

@@ -0,0 +1,3 @@
+import { ViewChildrenOptions } from './view-children';
+export type ContentChildrenOptions = ViewChildrenOptions;
+export declare function ContentChildren<E extends Element = Element>(selector: string, options?: ContentChildrenOptions): any;

package/dist/types/rx/decorator/index.d.ts

@@ -1,2 +1,6 @@
-export { QuerySelector, QuerySelectorOptions, } from './query-selector';
-export { QuerySelectorAll, QuerySelectorAllOptions, } from './query-selector-all';
+export * from './content-child';
+export * from './content-children';
+export * from './query-selector';
+export * from './query-selector-all';
+export * from './view-child';
+export * from './view-children';

package/dist/types/rx/decorator/query-selector-all.d.ts

@@ -1,22 +1,8 @@
-/**
- * Options for QuerySelectorAll decorator.
- */
-export type QuerySelectorAllOptions = {
-    /**
-     * If `true`, the elements will be searched in the shadow root. Default is `false`.
-     */
-    shadowRoot?: boolean;
-    /**
-     * If `true`, mutation observer instead of `renderObservable` from this package will
-     * be used to detect changes. Default is `false`.
-     */
-    mutationObserver?: boolean;
+import { ContentChildrenOptions } from './content-children';
+import { ViewChildrenOptions } from './view-children';
+export type QuerySelectorAllOptions = ViewChildrenOptions & {
+    target?: 'view';
+} | ContentChildrenOptions & {
+    target: 'content';
 };
-/**
- * Property decorator inspired by Angular's @ViewChild/@ContentChild.
- *
- * After each render, the decorated property will be set to the first element
- * matching the given selector. If no element is found, the property will be
- * set to null.
- */
-export declare function QuerySelectorAll<T extends HTMLElement = HTMLElement>(selector: string, options?: QuerySelectorAllOptions): any;
+export declare function QuerySelectorAll<E extends Element = Element>(selector: string, options?: QuerySelectorAllOptions): any;

package/dist/types/rx/decorator/query-selector.d.ts

@@ -1,30 +1,8 @@
-import { Observable } from 'rxjs';
-/**
- * Options for QuerySelector decorator.
- */
-export type QuerySelectorOptions = {
-    /**
-     * If `true`, the element will be searched in the shadow root. Default is `false`.
-     */
-    shadowRoot?: boolean;
-    /**
-     * If `true`, mutation observer instead of `renderObservable` from this package will
-     * be used to detect changes. Default is `false`.
-     */
-    mutationObserver?: boolean;
+import { ContentChildOptions } from './content-child';
+import { ViewChildOptions } from './view-child';
+export type QuerySelectorOptions = ViewChildOptions & {
+    target?: 'view';
+} | ContentChildOptions & {
+    target: 'content';
 };
-/**
- * Observe all sub nodes of the given node and notify
- * when any of them is removed and/or added.
- *
- * {@internal}
- */
-export declare function observeSubNodes(target: Node): Observable<void>;
-/**
- * Property decorator inspired by Angular's @ViewChild/@ContentChild.
- *
- * After each render, the decorated property will be set to the first element
- * matching the given selector. If no element is found, the property will be
- * set to null.
- */
-export declare function QuerySelector<T extends HTMLElement = HTMLElement>(selector: string, options?: QuerySelectorOptions): any;
+export declare function QuerySelector<E extends Element = Element>(selector: string, options?: QuerySelectorOptions): any;

package/dist/types/rx/decorator/view-child.d.ts

@@ -0,0 +1,27 @@
+import { ViewChildObservableOptions } from '../observable/view-child-observable';
+import { ElementFilterFn } from '../types';
+export type ViewChildOptions = {
+    /**
+     * If true, the property value will be cached and will not be updated when DOM changes.
+     *
+     * Default is false.
+     */
+    cached?: boolean;
+    /**
+     * If true, the property will be updated only when the element is present in the DOM.
+     *
+     * Default is false.
+     */
+    filter?: boolean | ElementFilterFn;
+    /**
+     * If true, property will be updated only when component is connected to the DOM. If false,
+     * property will be updated even if component is not connected to the DOM.
+     *
+     * This can be useful for cases where you want to move components in and out of the DOM, but
+     * you want to react only while component is connected to the DOM.
+     *
+     * Default is false.
+     */
+    whileConnected?: boolean;
+} & ViewChildObservableOptions;
+export declare function ViewChild<E extends Element = Element>(selector: string, options?: ViewChildOptions): any;

package/dist/types/rx/decorator/view-children.d.ts

@@ -0,0 +1,11 @@
+import { ElementsFilterFn } from '../types';
+import { ViewChildOptions } from './view-child';
+export type ViewChildrenOptions = Omit<ViewChildOptions, 'filter'> & {
+    /**
+     * If true, the property will be updated only when the elements are present in the DOM.
+     *
+     * Default is false.
+     */
+    filter?: boolean | ElementsFilterFn;
+};
+export declare function ViewChildren<E extends Element = Element>(selector: string, options?: ViewChildrenOptions): any;

package/dist/types/rx/index.d.ts

@@ -2,3 +2,4 @@ export * from './decorator';
 export * from './observable';
 export * from './operator';
 export * from './subscriber';
+export * from './types';

package/dist/types/rx/observable/connected-observable.d.ts

@@ -0,0 +1,9 @@
+import { ComponentInterface } from '../../stencil-public-runtime';
+import { Observable } from 'rxjs';
+/**
+ * Returns an observable that emits `true` when the component is connected to DOM,
+ * and `false` when it is disconnected from DOM.
+ *
+ * Uses hot observable pattern.
+ */
+export declare function connectedObservable(cmp: ComponentInterface): Observable<boolean>;

package/dist/types/rx/observable/content-child-observable.d.ts

@@ -0,0 +1,5 @@
+import { ComponentInterface } from '../../stencil-public-runtime';
+import { Observable } from 'rxjs';
+import { ViewChildObservableOptions } from './view-child-observable';
+export type ContentChildObservableOptions = ViewChildObservableOptions;
+export declare function contentChildObservable<E extends Element = Element>(cmp: ComponentInterface, selector: string, options?: ContentChildObservableOptions): Observable<E | null>;

package/dist/types/rx/observable/content-children-observable.d.ts

@@ -0,0 +1,5 @@
+import { ComponentInterface } from '../../stencil-public-runtime';
+import { Observable } from 'rxjs';
+import { ViewChildrenObservableOptions } from './view-children-observable';
+export type ContentChildrenObservableOptions = ViewChildrenObservableOptions;
+export declare function contentChildrenObservable<E extends Element = Element>(cmp: ComponentInterface, selector: string, options?: ContentChildrenObservableOptions): Observable<E[]>;

package/dist/types/rx/observable/from-event.d.ts

@@ -0,0 +1,26 @@
+import { ComponentInterface } from '../../stencil-public-runtime';
+import { Observable } from 'rxjs';
+export type EventHandlerOptions = {
+    capture?: boolean;
+    passive?: boolean;
+    once?: boolean;
+};
+/**
+ * Create an observable that emits events from a Stencil component.
+ *
+ * @param {ComponentInterface} cmp The Stencil component to listen for events on.
+ * @param {string} eventName The name of the event to listen for.
+ * @param {string} [delegate] An optional CSS selector to delegate the event to.
+ * @param {EventHandlerOptions} [options] An optional object that specifies event listener options.
+ * @returns {Observable<Event>} An observable that emits events of type T.
+ */
+export declare function fromEvent<T extends Event = Event>(cmp: ComponentInterface, eventName: string, delegate?: string, options?: EventHandlerOptions): Observable<T>;
+/**
+ * Create an observable that emits events from a Stencil component.
+ *
+ * @param {ComponentInterface} cmp The Stencil component to listen for events on.
+ * @param {string} eventName The name of the event to listen for.
+ * @param {EventHandlerOptions} [options] An optional object that specifies event listener options.
+ * @returns {Observable<Event>} An observable that emits events of type T.
+ */
+export declare function fromEvent<T extends Event = Event>(cmp: ComponentInterface, eventName: string, options?: EventHandlerOptions): Observable<T>;

package/dist/types/rx/observable/index.d.ts

@@ -1,4 +1,9 @@
-export { mutationObservable } from './mutation-observable';
-export { propertyObservable } from './property-observable';
-export { propertiesObservable } from './properties-observable';
-export { renderObservable } from './render-observable';
+export * from './content-child-observable';
+export * from './content-children-observable';
+export * from './from-event';
+export * from './mutation-observable';
+export * from './properties-observable';
+export * from './property-observable';
+export * from './render-observable';
+export * from './view-child-observable';
+export * from './view-children-observable';

package/dist/types/rx/observable/mutation-observable.d.ts

@@ -1,2 +1,8 @@
 import { Observable } from 'rxjs';
+/**
+ * Create mutation observer and return observable that emits mutation records when the target node is mutated.
+ *
+ * @param {Node} target The target node to observe for mutations.
+ * @param {MutationObserverInit} options The options for the mutation observer.
+ */
 export declare function mutationObservable(target: Node, options?: MutationObserverInit): Observable<MutationRecord[]>;

package/dist/types/rx/observable/properties-observable.d.ts

@@ -2,5 +2,10 @@ import { ComponentInterface } from '../../stencil-public-runtime';
 import { Observable } from 'rxjs';
 /**
  * Returns an observable that emits an array of values from the given properties.
+ *
+ * It always emits an array of values, even if only one property is specified. The order
+ * of the values in the emitted array corresponds to the order of the properties specified.
+ *
+ * Do note that `combineLatest()` operator is used to combine the observables.
  */
 export declare function propertiesObservable<T extends any[]>(cmp: ComponentInterface, ...properties: string[]): Observable<T>;

package/dist/types/rx/observable/property-observable.d.ts

@@ -3,4 +3,4 @@ import { Observable } from 'rxjs';
 /**
  * Returns an observable that emits property value when the component property value changes.
  */
-export declare function propertyObservable<T = any>(cmp: ComponentInterface, property: string): Observable<T>;
+export declare function propertyObservable<T = any>(cmp: ComponentInterface, property: string): Observable<T | undefined>;

package/dist/types/rx/observable/render-observable.d.ts

@@ -1,8 +1,13 @@
 import { ComponentInterface } from '../../stencil-public-runtime';
 import { Observable } from 'rxjs';
 /**
- * Returns an observable that emits when the component render()
+ * Returns an observable that emits when the component `render()`
  * function is called. Value will be emitted after the next
  * microtask (next tick).
+ *
+ * If component is already rendered, the observable will emit
+ * immediately.
+ *
+ * Uses hot observable pattern.
  */
 export declare function renderObservable(cmp: ComponentInterface): Observable<void>;

package/dist/types/rx/observable/view-child-observable.d.ts

@@ -0,0 +1,17 @@
+import { ComponentInterface } from '../../stencil-public-runtime';
+import { Observable } from 'rxjs';
+import { ElementComparatorFn } from '../types';
+export type ViewChildObservableOptions = {
+    /**
+     * If true, the observable will only emit when the element changes. If false, the observable will emit every time
+     * the component is rendered.
+     *
+     * You can also provide a custom comparator function to determine if the element has changed. The function should
+     * return true if the elements are equal, and false if they are not. If you set value to true, the default
+     * comparator function will be used, which compares the elements by reference.
+     *
+     * Default is true.
+     */
+    distinct?: ElementComparatorFn | boolean;
+};
+export declare function viewChildObservable<E extends Element = Element>(cmp: ComponentInterface, selector: string, options?: ViewChildObservableOptions): Observable<E | null>;

package/dist/types/rx/observable/view-children-observable.d.ts

@@ -0,0 +1,5 @@
+import { ComponentInterface } from '../../stencil-public-runtime';
+import { Observable } from 'rxjs';
+import { ViewChildObservableOptions } from './view-child-observable';
+export type ViewChildrenObservableOptions = ViewChildObservableOptions;
+export declare function viewChildrenObservable<E extends Element = Element>(cmp: ComponentInterface, selector: string, options?: ViewChildrenObservableOptions): Observable<E[]>;

package/dist/types/rx/operator/index.d.ts

@@ -1,3 +1,4 @@
-export { scheduleRender } from './schedule-render';
-export { toProperty } from './to-property';
-export { untilDisconnected } from './until-disconnected';
+export * from './schedule-render';
+export * from './to-property';
+export * from './until-disconnected';
+export * from './while-connected';

package/dist/types/rx/operator/to-property.d.ts

@@ -2,8 +2,6 @@ import { ComponentInterface } from '../../stencil-public-runtime';
 import { MonoTypeOperatorFunction } from 'rxjs';
 /**
  * Use this function to tap into a value stream and flush value to
- * component property. You may also use this function as subscription
- * function (function will detect that value is passed instead of
- * observable).
+ * component property.
  */
 export declare function toProperty<T = any>(cmp: ComponentInterface, property: string): MonoTypeOperatorFunction<T>;

package/dist/types/rx/operator/while-connected.d.ts

@@ -0,0 +1,22 @@
+import { ComponentInterface } from '../../stencil-public-runtime';
+import { MonoTypeOperatorFunction } from 'rxjs';
+export type WhileConnectedOptions = {
+    /**
+     * If true, the operator will re-emit the last value received from the source observable while component
+     * was disconnected, when the component is re-connected to DOM. This is useful for cases where the
+     * component may be disconnected and re-connected multiple times, and you want to ensure that the last
+     * emitted value is still available when the component is re-connected.
+     *
+     * Default is false.
+     */
+    reemit?: boolean;
+};
+/**
+ * Operator that emits values from the source observable only
+ * while the component is connected to DOM.
+ *
+ * This can be useful for cases where you want to move components in and out of the DOM,
+ * but still want to receive values from an observable while the component is connected
+ * and react to them.
+ */
+export declare function whileConnected<T = unknown>(cmp: ComponentInterface, options?: WhileConnectedOptions): MonoTypeOperatorFunction<T>;

package/dist/types/rx/subscriber/index.d.ts

@@ -1 +1 @@
-export { SetPropertyOptions, setProperty, } from './set-property';
+export * from './set-property';

package/dist/types/rx/subscriber/set-property.d.ts

@@ -13,4 +13,17 @@ export type SetPropertyOptions = {
      */
     nextTick?: boolean;
 };
+/**
+ * Set a property on a Stencil component and optionally schedule a render.
+ *
+ * This function returns a setter function that can be used to update the property value. Common use case
+ * is to set it as subscriber to an observable, so that the property is updated whenever the observable
+ * emits a new value.
+ *
+ * @param {ComponentInterface} cmp Component instance on which the property is to be set.
+ * @param {string} property Name of the property to be set on the component.
+ * @param {SetPropertyOptions} options Options to control the behavior of the property setter,
+ *                                     such as whether to schedule a render and whether to do
+ *                                     it on the next tick.
+ */
 export declare function setProperty<T = any>(cmp: ComponentInterface, property: string, options?: SetPropertyOptions): (value: T) => void;

package/dist/types/rx/types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A function that compares two elements and returns true if they are equal, and false if they are not.
+ */
+export type ElementComparatorFn<E extends Element = Element> = (previous: E | null, current: E | null) => boolean;
+/**
+ * A function that filters elements.
+ */
+export type ElementFilterFn<E extends Element = Element> = (element: E | null) => boolean;
+/**
+ * A function that filters collection of elements.
+ */
+export type ElementsFilterFn<E extends Element = Element> = (elements: E[]) => boolean;