@runopencode/rx-stencil 0.4.0 → 0.4.1

package/README.md

@@ -1,5 +1,7 @@
 # @runopencode/rx-stencil
 
+[![npm version](https://badge.fury.io/js/@runopencode%2Frx-stencil.svg)](https://badge.fury.io/js/@runopencode%2Frx-stencil)
+
 This is a small utility library which provides a set of useful functions for working
 with [Stencil](https://stenciljs.com) components in conjunction with [RxJS](https://rxjs.dev). RxJS is not, in general,
 well integrated with Stencil, nor core concepts of Stencil in regard to reactivity. However, certain problems can be

package/docs/components.md

@@ -0,0 +1,69 @@
+# Components
+
+## rx-async
+
+`rx-async` is a simple component which accepts an observable as a property and renders the result of the observable. It
+is similar to the `async` pipe in Angular. It is useful when you want to render the result of an observable in a
+template. 
+
+**Of course, it will work only if the observable emits a scalar value.**
+
+Component has only one property, `value`, which accepts:
+
+- `null` or `undefined` - in this case, component will render nothing.
+- `Observable` - in this case, component will render every value emitted by the observable.
+- `Promise` - in this case, component will render the value resolved by the promise.
+
+### Usage example
+
+Setting value in server-side rendered application:
+
+```html
+<rx-async></rx-async>
+
+<script type="text/javascript">
+    let counter$ = new Subject();
+    
+    setInterval(() => {
+        counter$.next(Math.random());
+    }, 1000);
+    
+    document.querySelector('rx-async').value = counter$;
+    
+</script>
+```
+
+Or, per example, in a StencilJS component:
+
+```typescript jsx
+import {
+    Component,
+    ComponentInterface,
+    Host,
+    h,
+} from '@stencil/core';
+import { Subject } from 'rxjs';
+
+@Component({
+    tag: 'app-counter',
+    shadow: true,
+})
+class AppCounter implements ComponentInterface {
+    
+    private readonly counter$: Subject<number> = new Subject();
+    
+    public connectedCallback(): void {
+        setInterval((): void => {
+            this.counter$.next(Math.random());
+        }, 1000);
+    }
+    
+    public render(): any {
+         return (
+             <Host>
+                 <rx-async value={this.counter$}/>
+             </Host>
+         );
+    }
+}
+```

package/docs/creation-operators.md

@@ -0,0 +1,79 @@
+# Creation operators
+
+These are operators which create observables with common, predefined behaviour. Read more about creation operators in
+official RxJS documentation: https://rxjs.dev/guide/operators.
+
+## mutationObservable()
+
+Mutation observable is just a simple wrapper
+around [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) which emits collection of
+MutationRecord as changes in DOM subtree occur. This function is part of library as utility as some of the library
+operators use it internally.
+
+Function signature is: `mutationObservable(target: Node, options?: MutationObserverInit): Observable<MutationRecord[]>`
+
+Details of this operator are not documented as behaviour is fully described in official documentation of
+MutationObserver and its `MutationObserver.observe()`
+method: https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver/observe.
+
+## propertyObservable()
+
+Common use case for Stencil components is to observe changes of component properties decorated with either `@Prop()`
+or `@State()` decorator. In order to react on those changes prior to rendering, it is required to create a method and
+decorate it with `@Watch()` decorator, as described
+here: https://stenciljs.com/docs/reactive-data#the-watch-decorator-watch.
+
+Instead of that, you may use `propertyObservable()` operator which will create an observable which will emit new value
+as soon as property changes. This operator can be used for watching changes of both `@Prop()` and `@State()` decorated
+properties, as well as any other property of the component.
+
+Function signature is: `propertyObservable<T = any>(cmp: ComponentInterface, property: string): Observable<T>`
+
+There are many use cases where this operator can be used, however, a simple example where we are calculating, so called,
+computed property is given in example below:
+
+```typescript jsx
+import { Component, ComponentInterface, Prop } from '@stencil/core';
+import { combineLatest, map } from 'rxjs';
+import { propertyObservable, untilDisconnected, scheduleRender } from '@runopencode/rx-stencil';
+
+@Component({
+    tag: 'my-component',
+})
+class MyComponent implements ComponentInterface {
+
+    @Prop()
+    public first: number = 0;
+
+    @Prop()
+    public second: number = 0;
+
+    private sum: number = 0;
+
+    public connectedCallback(): void {
+        combineLatest([
+            propertyObservable(this, 'first'),
+            propertyObservable(this, 'second'),
+        ]).pipe(
+            untilDisconnected(this),
+            map(([first, second]) => first + second),
+            scheduleRender(this),
+        ).subscribe(sum => this.sum = sum);
+    }
+
+    public render(): any {
+        return <div>{this.sum}</div>;
+    }
+}
+```
+
+## renderObservable()
+
+This operator is used to create an observable which will emit new value after `render()` function of the component is
+called. Note that this operator will emmit value on next micro-task (that is, after `Promise.resolve()`) to ensure that
+resulting DOM is updated and in stable state.
+
+This function is part of library as utility as some of the library operators use it internally.
+
+Function signature is: `renderObservable(cmp: ComponentInterface): Observable<void>`
+

package/docs/pipeable-operators.md

@@ -0,0 +1,36 @@
+# Pipeable operators
+
+Pipeable operators are functions which allows you to compose observables in a declarative way. They are used in
+conjunction with `pipe()` function from RxJS. Read more about pipeable operators in official RxJS
+documentation: https://rxjs.dev/guide/operators.
+
+## scheduleRender()
+
+Operator which taps into observable and schedules rendering of component as soon as observable emits new value. By
+default, rendering ill be requested on next micro-task (i.e. after `Promise.resolve()`), but you can disable this
+behaviour by passing `false` as second parameter.
+
+Function signature
+is: `scheduleRender<T = unknown>(cmp: ComponentInterface, nextTick: boolean = true): MonoTypeOperatorFunction<T>`
+
+## toProperty()
+
+Operator which taps into observable and sets value of component property as soon as observable emits new value.
+
+Function signature is: `toProperty<T = any>(cmp: ComponentInterface, property: string): MonoTypeOperatorFunction<T>`
+
+## untilDisconnected()
+
+Operator which taps into observable and unsubscribes from it as soon as component is disconnected from DOM. Operator
+will try to monitor execution of the `disconnectedCallback()` method of the component in order to emmit event. However,
+if method is not defined on the component, mutation observable will be used on parent node of the component in order to
+detect when component is removed from DOM.
+
+Monitoring of `disconnectCallback()` is much more reliable and performant, so it is recommended to define this method on
+component if you are using this operator, because with mutation observer it is not possible to reliably detect when
+component is re-attached to DOM.
+
+Function signature is: `untilDisconnected<T = unknown>(cmp: ComponentInterface): MonoTypeOperatorFunction<T>`
+
+Common use case for this operator is to use it as a cleanup operator for observables which are created
+in `connectedCallback()` method of the component.

package/docs/query-selector-all-decorator.md

@@ -0,0 +1,154 @@
+# @QuerySelectorAll()
+
+`@QuerySelectorAll()` is a property decorator which can be used to query for a collection of elements in the component's
+template. It is inspired by the `@ViewChildren()` and `@ContentChildren()` decorators in Angular. It accepts a CSS
+selector as an argument which will be used to query for the elements. In Stencil, you can reference to a DOM
+element in the component (see: https://stenciljs.com/docs/templating-jsx#getting-a-reference-to-a-dom-element for more
+details), however, getting collection of elements is a bit tricky. Using this decorator, you can achieve that with ease,
+and you are able to apply declarative style of programming when working with DOM elements.
+
+`@QuerySelectorAll()` decorator accepts two arguments:
+
+- `selector`, string, required - CSS selector which will be used to query for the elements. It can be any valid CSS
+  selector. Search will start from the component element, or shadow root if component is using shadow DOM and parameter
+  `options.shadowRoot` is set to `true`.
+- `options`, `QuerySelectorAllOptions`, optional, default `undefined` which means that default options will be used.
+  This is an object with following properties:
+    - `shadowRoot`, boolean, optional, default `false` - if set to `true`, search will start from shadow root of the
+      component, instead of the component element itself. If component does not use shadow DOM, exception will be
+      thrown.
+    - `mutationObserver`, boolean, optional, default `false` - if set to `true`, decorator will use MutationObserver to
+      observe changes in the DOM subtree of the component. This is more reliable approach, but it is also more
+      expensive. It should be used when you are querying for elements which are projected into the component through
+      `<slot>` element, or if subtree of the component is changed by some other means, not via Stencil's reactivity. By
+      default, decorator will monitor execution of the `render()` function of the component and will query for the
+      elements after each execution.
+
+`@QuerySelectorAll()` decorator must be used on any property of the component, and type of the property is `Observable`
+from `rxjs` library. Observable will be used to emit reference to collection of queried elements, or empty collection,
+if elements could not be found. Note that you should not set initial value for the property, decorator will do that for
+you. Example:
+
+```typescript
+class MyCmp {
+    @QuerySelectorAll('div')
+    private elements$: Observable<HTMLElement[]>;
+}
+```
+
+After each execution of the `render()` function of the component (or mutation of DOM subtree), decorator will query for
+the elements and emit their reference. This value will be emitted only if collection differs from the previous one.
+Emission is executed on next micro-task (i.e. after `Promise.resolve()`).
+
+A fair warning: in theory, you are able to create infinite loop without noticing because value is emitted on next
+micro-task, main browser thread will not be blocked.
+
+## Example
+
+Similar to example given for `@QuerySelectorAll()` decorator, we are trying to build a search list, however, filters
+will be projected through `<slot>` element. Only thing that we know is that filters will be either `<input>` or
+`<select>`elements and their `name` attribute should be used as the name of query parameter in search URL. Such flexible
+search component is fairly simple to write using RxJS and `@QuerySelectorAll()` decorator.
+
+```typescript jsx
+import { Component, ComponentInterface, State } from '@stencil/core';
+import {
+    combineLatest,
+    debounceTime,
+    distinctUntilChanged,
+    fromEvent,
+    map,
+    merge,
+    Observable, queue,
+    startWith,
+    switchMap,
+} from 'rxjs';
+import { fromFetch } from 'rxjs/internal/observable/dom/fetch';
+import { untilDisconnected } from '@runopencode/rx-stencil';
+
+@Component({
+    tag: 'app-search',
+    shadow: true,
+})
+class AppSearch implements ComponentInterface {
+
+    @QuerySelector('input, select')
+    private readonly fields$: Observable<HTMLInputElement[] | HTMLSelectElement[]>;
+
+    @State()
+    private result: string[] = [];
+
+    public connectedCallback(): void {
+        this.fields$.pipe(
+            // When inputs/selects are ready, we can start listening for `input` and `change` events.
+            switchMap((fields: HTMLInputElement[] | HTMLSelectElement[]): Observable<string> => {
+                // This is tricky part, we need to convert every field into observable which will emit
+                // tuple of field name and its value. Since we are going to use `combineLatest()` operator,
+                // we need to start with initial value for all, we will use `startWith()` operator for that.
+                let observables: Observable<[string, string]>[] = fields.map((input: HTMLInputElement | HTMLSelectElement): Observable<string> => {
+                    return merge(
+                        fromEvent(input, 'input'),
+                        fromEvent(input, 'change'),
+                    ).pipe(
+                        startWith(),
+                        map((): string => [input.name, input.value.trim()]),
+                    );
+                });
+
+                // Now we can combine all observables into one. Note that because of `startWith()` operator,
+                // `combineLatest()` will emit initial value immediately. If you want to avoid that, you can
+                // use `skip(1)` operator.
+                return combineLatest(observables);
+            }),
+            // debounce input events to avoid sending too many requests
+            // and filter out same search terms sent in a row      
+            debounceTime(300),
+            // convert array of tuples into query string
+            map((values: [string, string][]): string => {
+                let queryParams: string[] = [];
+                
+                for (let [name, value] of values) {
+                    queryParams.push(`${name}=${value}`);
+                }
+                
+                return queryParams.join('&');
+            }),
+            // skip successive same query params
+            distinctUntilChanged(),
+            // send search request
+            switchMap((query: string): Observable<string[]> => {
+                return fromFetch(`https://api.example.com/search?${query}`).pipe(
+                        switchMap((response: Response): Observable<string[]> => response.json()),
+                );
+            }),
+            // unsubscribe when component is disconnected
+            untilDisconnected(this),
+        ).subscribe((result: string[]): void => {
+            this.result = result;
+        });
+    }
+
+    public render(): any {
+        return (
+            <Host>
+                <slot />
+                {this.result.map((item): any => <div>{item}</div>)}
+            </Host>
+        );
+    }
+}
+```
+
+With this component, you can use any number of `<input>` and `<select>` elements as filters, and they will be queried by
+the component.
+
+```html
+<app-search>
+    <input type="search" name="term" />
+    <select name="category">
+        <option value="1">Category 1</option>
+        <option value="2">Category 2</option>
+        <option value="3">Category 3</option>
+    </select>
+</app-search>
+```

package/docs/query-selector-decorator.md

@@ -0,0 +1,116 @@
+# @QuerySelector()
+
+`@QuerySelector()` is a property decorator which can be used to query for a specific element in the component's
+template. It is inspired by the `@ViewChild()` and `@ContentChild()` decorators in Angular. It accepts a CSS selector as
+an argument which will be used to query for the element. This is alternative approach to the getting reference to a DOM
+element in the component (see: https://stenciljs.com/docs/templating-jsx#getting-a-reference-to-a-dom-element for more
+details). Using this decorator, you are able to apply declarative style of programming when working with DOM elements.
+
+`@QuerySelector()` decorator accepts two arguments:
+
+- `selector`, string, required - CSS selector which will be used to query for the element. It can be any valid CSS
+  selector. Search will start from the component element, or shadow root if component is using shadow DOM and parameter
+  `options.shadowRoot` is set to `true`.
+- `options`, `QuerySelectorOptions`, optional, default `undefined` which means that default options will be used. This
+  is an object with following properties:
+    - `shadowRoot`, boolean, optional, default `false` - if set to `true`, search will start from shadow root of the
+      component, instead of the component element itself. If component does not use shadow DOM, exception will be
+      thrown.
+    - `mutationObserver`, boolean, optional, default `false` - if set to `true`, decorator will use MutationObserver to
+      observe changes in the DOM subtree of the component. This is more reliable approach, but it is also more
+      expensive. It should be used when you are querying for element which is projected into the component through
+      `<slot>` element, or if subtree of the component is changed by some other means, not via Stencil's reactivity. By
+      default, decorator will monitor execution of the `render()` function of the component and will query for the
+      element after each execution.
+
+`@QuerySelector()` decorator must be used on any property of the component, and type of the property is `Observable`
+from `rxjs` library. Observable will be used to emit reference to queried element, or `null` if element does not exist.
+Note that you should not set initial value for the property, decorator will do that for you. Example:
+
+```typescript
+class MyCmp {
+    @QuerySelector('div')
+    private element$: Observable<HTMLElement | null>;
+}
+```
+
+After each execution of the `render()` function of the component (or mutation of DOM subtree), decorator will query for 
+the element and emit its reference, if it can be found, or `null`. This value will be emitted only if it is different 
+from the previous one and on next micro-task (i.e. after `Promise.resolve()`).
+
+A fair warning: in theory, you are able to create infinite loop without noticing because value is emitted on next
+micro-task, main browser thread will not be blocked.
+
+## Example
+
+Let's say that your component has a template which consist of an input field for search and a list of results. You want
+for user to be able to type term in the input field and to see results in the list. However, you would like to debounce
+search as well as not to send same search term twice. Imperative approach would require a lot of code for this task,
+however, with RxJS this can be done in a very elegant way.
+
+```typescript jsx
+import {
+    Component,
+    ComponentInterface,
+    State,
+    h,
+} from '@stencil/core';
+import {
+    debounceTime,
+    distinctUntilChanged,
+    from,
+    fromEvent,
+    map,
+    Observable,
+    switchMap,
+} from 'rxjs';
+import { fromFetch } from 'rxjs/internal/observable/dom/fetch';
+import { untilDisconnected } from '@runopencode/rx-stencil';
+
+@Component({
+    tag: 'app-search',
+    shadow: true,
+})
+class AppSearch implements ComponentInterface {
+
+    @QuerySelector('input[type="search"]', true)
+    private readonly input$: Observable<HTMLInputElement>;
+
+    @State()
+    private result: string[] = [];
+
+    public connectedCallback(): void {
+        this.input$.pipe(
+            // when input is ready, we can start listening for `input` events
+            switchMap((input: HTMLInputElement): Observable<string> => {
+                return fromEvent(input, 'input').pipe(
+                        map((): string => input.value.trim()),
+                );
+            }),
+            // debounce input events to avoid sending too many requests
+            // and filter out same search terms sent in a row      
+            debounceTime(300),
+            distinctUntilChanged(),
+            // send search request
+            switchMap((term: string): Observable<string[]> => {
+                return fromFetch(`https://api.example.com/search?term=${term}`).pipe(
+                        switchMap((response: Response): Observable<string[]> => response.json()),
+                );
+            }),
+            // unsubscribe when component is disconnected
+            untilDisconnected(this),
+        ).subscribe((result: string[]): void => {
+            this.result = result;
+        });
+    }
+
+    public render(): any {
+        return (
+            <Host>
+                <input type='search' />
+                {this.result.map((item): any => <div>{item}</div>)}
+            </Host>
+        );
+    }
+}
+```

package/docs/subscribers.md

@@ -0,0 +1,49 @@
+# Subscribers
+
+These are functions which can be used as subscribers to observables for common tasks in order to decrease boilerplate
+code and improve developer experience.
+
+## setProperty()
+
+Function which can be used as subscriber to observable in order to set value of component property as soon as observable
+emits new value. Common use case would be to use it in conjunction with `propertyObservable()` operator and set a value
+of "computed" property of the component.
+
+Function signature is: `setProperty<T = any>(cmp: ComponentInterface, property: string): Subscriber<T>`
+
+Improved example from [propertyObservable()](creation-operators.md#propertyobservable) operator documentation:
+
+```typescript jsx
+import { Component, ComponentInterface, Prop, State } from '@stencil/core';
+import { combineLatest, map } from 'rxjs';
+import { propertyObservable, untilDisconnected, setProperty } from '@runopencode/rx-stencil';
+
+@Component({
+    tag: 'my-component',
+})
+class MyComponent implements ComponentInterface {
+
+    @Prop()
+    public first: number = 0;
+
+    @Prop()
+    public second: number = 0;
+
+    @State()
+    private sum: number = 0;
+
+    public connectedCallback(): void {
+        combineLatest([
+            propertyObservable(this, 'first'),
+            propertyObservable(this, 'second'),
+        ]).pipe(
+            untilDisconnected(this),
+            map(([first, second]) => first + second),
+        ).subscribe(setProperty(this, 'sum'));
+    }
+
+    public render(): any {
+        return <div>{this.sum}</div>;
+    }
+}
+```

package/package.json

@@ -1,7 +1,12 @@
 {
     "name": "@runopencode/rx-stencil",
-    "version": "0.4.0",
+    "version": "0.4.1",
     "description": "ReactiveX (RxJS) utilities for Stencil",
+    "keywords": [
+        "stencil",
+        "stenciljs",
+        "rxjs"
+    ],
     "main": "dist/index.cjs.js",
     "module": "dist/index.js",
     "es2015": "dist/esm/index.mjs",
@@ -16,7 +21,8 @@
     },
     "files": [
         "dist/",
-        "loader/"
+        "loader/",
+        "docs/"
     ],
     "scripts": {
         "build": "stencil build --docs",