@thi.ng/rdom-components 0.5.39 → 0.6.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-03-27T19:05:49Z
+- **Last updated**: 2023-04-08T11:09:50Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,18 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [0.6.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/rdom-components@0.6.0) (2023-04-08)
+
+#### 🚀 Features
+
+- add staticDropdownAlt(), add docs ([0f1b922](https://github.com/thi-ng/umbrella/commit/0f1b922))
+
+#### 🩹 Bug fixes
+
+- update dropdown args & attrib handling ([f2bd62b](https://github.com/thi-ng/umbrella/commit/f2bd62b))
+  - update static/dynamicDropdown()
+  - allow user attribs to supply onchange handler
+
 ## [0.5.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/rdom-components@0.5.0) (2022-07-12)
 
 #### 🚀 Features

package/README.md

@@ -61,7 +61,7 @@ For Node.js REPL:
 const rdomComponents = await import("@thi.ng/rdom-components");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.21 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 1.28 KB
 
 ## Dependencies
 
@@ -87,6 +87,7 @@ A selection:
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/color-themes.png" width="240"/>        | Probabilistic color theme generator                                         | [Demo](https://demo.thi.ng/umbrella/color-themes/)        | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/color-themes)        |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/dominant-colors.png" width="240"/>     | Color palette generation via dominant color extraction from uploaded images | [Demo](https://demo.thi.ng/umbrella/dominant-colors/)     | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/dominant-colors)     |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/parse-playground.png" width="240"/>    | Parser grammar livecoding editor/playground & codegen                       | [Demo](https://demo.thi.ng/umbrella/parse-playground/)    | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/parse-playground)    |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/trace-bitmap.jpg" width="240"/>        | Multi-layer vectorization & dithering of bitmap images                      | [Demo](https://demo.thi.ng/umbrella/trace-bitmap/)        | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/trace-bitmap)        |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/webgl-channel-mixer.jpg" width="240"/> | rdom & WebGL-based image channel editor                                     | [Demo](https://demo.thi.ng/umbrella/webgl-channel-mixer/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/webgl-channel-mixer) |
 
 ## API

package/dropdown.d.ts

@@ -1,11 +1,67 @@
 import type { Fn } from "@thi.ng/api";
 import { type SelectAttribs } from "@thi.ng/hiccup-html/forms";
-import type { ISubscribable, Subscription } from "@thi.ng/rstream";
+import type { ISubscribable, ISubscription } from "@thi.ng/rstream";
 export interface DropdownOpts<T> {
     attribs: Partial<SelectAttribs>;
     label: Fn<T, string>;
     value: Fn<T, string>;
 }
-export declare const dynamicDropdown: <T = string, S extends string = string>(items: ISubscribable<T[]>, sel: Subscription<S, S>, opts?: Partial<DropdownOpts<T>> | undefined) => import("@thi.ng/rdom").IComponent<T[]>;
-export declare const staticDropdown: <T = string, S extends string = string>(items: T[], sel: Subscription<S, S>, opts?: Partial<DropdownOpts<T>> | undefined) => [string, import("@thi.ng/api").Nullable<Partial<SelectAttribs>>, ...any[]];
+/**
+ * Dropdown `<select>` component with dynamically defined list of items (via
+ * subscription) and reactive updates using additionally provided `sel`
+ * subscription.
+ *
+ * @remarks
+ * Only single selections are supported. Each generated `<option>` element will
+ * have its own child subscription to update its `selected` attribute based on
+ * current value of `sel`.
+ *
+ * See {@link staticDropdown} or {@link staticDropdownAlt} for use cases where
+ * the items themselves are statically defined.
+ *
+ * @param items
+ * @param sel
+ * @param opts
+ */
+export declare const dynamicDropdown: <T = string, S extends string = string>(items: ISubscribable<T[]>, sel: ISubscription<S, S>, opts?: Partial<DropdownOpts<T>> | undefined) => import("@thi.ng/rdom").IComponent<T[]>;
+/**
+ * Dropdown `<select>` component with statically defined list of items, but
+ * reactive updates using provided `sel` subscription.
+ *
+ * @remarks
+ * Only single selections are supported. Each generated `<option>` element will
+ * have its own child subscription to update its `selected` attribute based on
+ * current value of `sel`.
+ *
+ * See {@link staticDropdownAlt} for alternative approach or
+ * {@link dynamicDropdown} for use cases where the items themselves are
+ * dynamically changeable.
+ *
+ * @param items
+ * @param sel
+ * @param opts
+ * @returns
+ */
+export declare const staticDropdown: <T = string, S extends string = string>(items: T[], sel: ISubscription<S, S>, opts?: Partial<DropdownOpts<T>> | undefined) => [string, import("@thi.ng/api").Nullable<Partial<SelectAttribs>>, ...any[]];
+/**
+ * Similar to {@link staticDropdown}, but using only a single subscription for
+ * the entire dropdown.
+ *
+ * @remarks
+ * **IMPORTANT:** This component is replacing its entire `<select>` element (and
+ * all its children) with each value change of `sel`. The component will only be
+ * fully mounted when `sel` produces a non-null value. In other words, `sel`
+ * **MUST** be pre-initialized for the component to show up (e.g. using
+ * rstream's
+ * [`reactive`](https://docs.thi.ng/umbrella/rstream/functions/reactive.html)
+ * with a seed value).
+ *
+ * Internally uses thi.ng/rdom
+ * [`$replace()`](https://docs.thi.ng/umbrella/rdom/functions/_replace.html).
+ *
+ * @param items
+ * @param sel
+ * @param opts
+ */
+export declare const staticDropdownAlt: <T = string, S extends string = string>(items: T[], sel: ISubscription<S, S>, opts?: Partial<DropdownOpts<T>> | undefined) => import("@thi.ng/rdom").IComponent<[string, import("@thi.ng/api").Nullable<Partial<SelectAttribs>>, ...any[]]>;
 //# sourceMappingURL=dropdown.d.ts.map

package/dropdown.js

@@ -1,23 +1,94 @@
 import { option, select } from "@thi.ng/hiccup-html/forms";
 import { $input } from "@thi.ng/rdom/event";
+import { __nextID } from "@thi.ng/rdom/idgen";
 import { $list } from "@thi.ng/rdom/list";
+import { $replace } from "@thi.ng/rdom/replace";
+/**
+ * Dropdown `<select>` component with dynamically defined list of items (via
+ * subscription) and reactive updates using additionally provided `sel`
+ * subscription.
+ *
+ * @remarks
+ * Only single selections are supported. Each generated `<option>` element will
+ * have its own child subscription to update its `selected` attribute based on
+ * current value of `sel`.
+ *
+ * See {@link staticDropdown} or {@link staticDropdownAlt} for use cases where
+ * the items themselves are statically defined.
+ *
+ * @param items
+ * @param sel
+ * @param opts
+ */
 export const dynamicDropdown = (items, sel, opts) => {
     opts = {
         value: String,
         label: String,
         ...opts,
     };
-    return $list(items, "select", { ...opts.attribs, onchange: $input(sel) }, $option(sel, opts));
+    return $list(items, "select", { onchange: $input(sel), ...opts.attribs }, $option(sel, opts));
 };
+/**
+ * Dropdown `<select>` component with statically defined list of items, but
+ * reactive updates using provided `sel` subscription.
+ *
+ * @remarks
+ * Only single selections are supported. Each generated `<option>` element will
+ * have its own child subscription to update its `selected` attribute based on
+ * current value of `sel`.
+ *
+ * See {@link staticDropdownAlt} for alternative approach or
+ * {@link dynamicDropdown} for use cases where the items themselves are
+ * dynamically changeable.
+ *
+ * @param items
+ * @param sel
+ * @param opts
+ * @returns
+ */
 export const staticDropdown = (items, sel, opts) => {
     opts = {
         value: String,
         label: String,
         ...opts,
     };
-    return select({ ...opts.attribs, onchange: $input(sel) }, ...items.map($option(sel, opts)));
+    return select({ onchange: $input(sel), ...opts.attribs }, ...items.map($option(sel, opts)));
+};
+/**
+ * Similar to {@link staticDropdown}, but using only a single subscription for
+ * the entire dropdown.
+ *
+ * @remarks
+ * **IMPORTANT:** This component is replacing its entire `<select>` element (and
+ * all its children) with each value change of `sel`. The component will only be
+ * fully mounted when `sel` produces a non-null value. In other words, `sel`
+ * **MUST** be pre-initialized for the component to show up (e.g. using
+ * rstream's
+ * [`reactive`](https://docs.thi.ng/umbrella/rstream/functions/reactive.html)
+ * with a seed value).
+ *
+ * Internally uses thi.ng/rdom
+ * [`$replace()`](https://docs.thi.ng/umbrella/rdom/functions/_replace.html).
+ *
+ * @param items
+ * @param sel
+ * @param opts
+ */
+export const staticDropdownAlt = (items, sel, opts) => {
+    opts = {
+        value: String,
+        label: String,
+        ...opts,
+    };
+    return $replace(sel.map((id) => select({ onchange: $input(sel), ...opts.attribs }, ...items.map((x) => {
+        const value = opts.value(x);
+        return option({ value, selected: value === id }, opts.label(x));
+    })), { id: __nextID("dropdown") }));
 };
 const $option = (sel, { label, value }) => (x) => {
     let v = value(x);
-    return option({ value: v, selected: sel.map((x) => v === x) }, label(x));
+    return option({
+        value: v,
+        selected: sel.map((x) => v === x, { id: __nextID("opt") }),
+    }, label(x));
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/rdom-components",
-  "version": "0.5.39",
+  "version": "0.6.0",
   "description": "Collection of unstyled, customizable components for @thi.ng/rdom",
   "type": "module",
   "module": "./index.js",
@@ -34,21 +34,21 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.7.5",
-    "@thi.ng/associative": "^6.2.33",
-    "@thi.ng/hiccup-html": "^2.2.12",
-    "@thi.ng/rdom": "^0.10.18",
-    "@thi.ng/rstream": "^7.2.46",
-    "@thi.ng/strings": "^3.4.3",
-    "@thi.ng/transducers": "^8.4.1"
+    "@thi.ng/api": "^8.7.6",
+    "@thi.ng/associative": "^6.2.34",
+    "@thi.ng/hiccup-html": "^2.2.13",
+    "@thi.ng/rdom": "^0.11.0",
+    "@thi.ng/rstream": "^8.0.0",
+    "@thi.ng/strings": "^3.4.4",
+    "@thi.ng/transducers": "^8.4.2"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.34.4",
-    "@thi.ng/testament": "^0.3.14",
+    "@thi.ng/testament": "^0.3.15",
     "rimraf": "^4.4.1",
     "tools": "^0.0.1",
     "typedoc": "^0.23.28",
-    "typescript": "^5.0.2"
+    "typescript": "^5.0.4"
   },
   "keywords": [
     "browser",
@@ -105,5 +105,5 @@
     "status": "alpha",
     "year": 2020
   },
-  "gitHead": "83b15b34326d480cbca0472b20390d4d3bbb792a\n"
+  "gitHead": "abcedd9e4e06a4b631f363610eec572f79b571c1\n"
 }