@mmstack/primitives 21.0.23 → 21.0.24

package/fesm2022/mmstack-primitives.mjs

@@ -600,7 +600,30 @@ const mapArray = indexArray;
  * @param mapFn The mapping function. Receives the item and its index as a Signal.
  * @param options Optional configuration:
  *  - `onDestroy`: A callback invoked when a mapped item is removed from the array.
+ *  - `key`: A custom key extractor for identity matching (e.g. `(item) => item.id`)
+ *    when item references change but conceptual identity is preserved.
  * @returns A `Signal<U[]>` containing the mapped array.
+ *
+ * @example
+ * ```ts
+ * const users = signal([
+ *   { id: 1, name: 'Alice' },
+ *   { id: 2, name: 'Bob' },
+ * ]);
+ *
+ * const rows = keyArray(
+ *   users,
+ *   (user, index) => ({
+ *     label: computed(() => `#${index()} ${user.name}`),
+ *     id: user.id,
+ *   }),
+ *   { key: (u) => u.id },
+ * );
+ *
+ * // Reordering users() rebuilds index signals only — `rows` entries
+ * // are matched by id and reused, not re-created.
+ * users.set([users()[1], users()[0]]);
+ * ```
  */
 function keyArray(source, mapFn, options = {}) {
     const sourceSignal = isSignal(source) ? source : computed(source);
@@ -757,15 +780,69 @@ function mapObject(source, mapFn, options = {}) {
     }).asReadonly();
 }
 
-/** Project with optional equality. Pure & sync. */
+/**
+ * Synchronous projection of a signal value with optional `CreateSignalOptions`
+ * (custom `equal`, `debugName`, etc.). Equivalent to `map` plus the ability to
+ * pass signal options through to the underlying `computed()`.
+ *
+ * @example
+ * ```ts
+ * const user = piped({ id: 1, name: 'Alice' });
+ * const name = user.pipe(select((u) => u.name));
+ * name(); // 'Alice'
+ * ```
+ */
 const select = (projector, opt) => (src) => computed(() => projector(src()), opt);
-/** Combine with another signal using a projector. */
+/**
+ * Combine the piped signal with another `Signal` using a projector. The result
+ * recomputes whenever either source changes.
+ *
+ * @example
+ * ```ts
+ * const price = piped(10);
+ * const quantity = signal(3);
+ * const total = price.pipe(combineWith(quantity, (p, q) => p * q));
+ * total(); // 30
+ * ```
+ */
 const combineWith = (other, project, opt) => (src) => computed(() => project(src(), other()), opt);
-/** Only re-emit when equal(prev, next) is false. */
+/**
+ * Suppress emissions while consecutive values are considered equal. The
+ * comparator defaults to `Object.is`; pass a custom one for structural or
+ * key-based equality (e.g. compare by `id` only).
+ *
+ * @example
+ * ```ts
+ * const user = piped({ id: 1, lastSeen: Date.now() });
+ * const byId = user.pipe(distinct((a, b) => a.id === b.id));
+ * // byId only re-emits when `id` changes, not on every `lastSeen` update
+ * ```
+ */
 const distinct = (equal = Object.is) => (src) => computed(() => src(), { equal });
-/** map to new value */
+/**
+ * Pure synchronous transform from input to output. Equivalent to a `computed()`
+ * that reads the source and returns `fn(value)`.
+ *
+ * @example
+ * ```ts
+ * const count = piped(2);
+ * const doubled = count.pipe(map((n) => n * 2));
+ * doubled(); // 4
+ * ```
+ */
 const map = (fn) => (src) => computed(() => fn(src()));
-/** filter values, keeping the last value if it was ever available, if first value is filtered will return undefined */
+/**
+ * Keep only values that pass the predicate. The result holds the last passing
+ * value across emissions; before any value passes, the result is `undefined` —
+ * see {@link filterWith} when you need a non-`undefined` seed.
+ *
+ * @example
+ * ```ts
+ * const event = piped<MouseEvent | null>(null);
+ * const clicks = event.pipe(filter((e): e is MouseEvent => e?.type === 'click'));
+ * clicks(); // undefined until a click happens, then the last MouseEvent
+ * ```
+ */
 const filter = (predicate) => (src) => linkedSignal({
     source: src,
     computation: (next, prev) => {
@@ -774,7 +851,19 @@ const filter = (predicate) => (src) => linkedSignal({
         return prev?.source;
     },
 });
-/** tap into the value */
+/**
+ * Run a side effect on every emission without altering the signal value. Wraps
+ * Angular's `effect()`, so it must run in an injection context or receive an
+ * explicit `injector`. Use for logging / analytics — not for setting other
+ * signals (that's what regular `effect()` is for).
+ *
+ * @example
+ * ```ts
+ * const count = piped(0);
+ * count.pipe(tap((n) => console.log('count:', n)));
+ * count.set(1); // logs 'count: 1'
+ * ```
+ */
 const tap = (fn, injector) => (src) => {
     effect(() => fn(src()), {
         injector,
@@ -782,24 +871,66 @@ const tap = (fn, injector) => (src) => {
     return src;
 };
 /**
- * Like {@link filter}, but emits `initial` until a value passes the predicate
- * for the first time. Avoids the `T | undefined` return type.
+ * Like {@link filter}, but emits `initial` until a value first passes the
+ * predicate. Eliminates the `T | undefined` return type at the cost of an
+ * explicit seed value.
+ *
+ * @example
+ * ```ts
+ * const event = piped<MouseEvent | null>(null);
+ * const lastClick = event.pipe(filterWith((e) => e?.type === 'click', null));
+ * lastClick(); // null until the first click, then the most recent click event
+ * ```
  */
 const filterWith = (predicate, initial) => (src) => linkedSignal({
     source: src,
     computation: (next, prev) => predicate(next) ? next : (prev?.value ?? initial),
 });
-/** Emits `initial` first, then mirrors source. */
+/**
+ * Emit `initial` on the first read, then mirror the source on every subsequent
+ * read. Useful for giving a pipeline a sensible seed value before the source
+ * is ready (e.g. loading state).
+ *
+ * @example
+ * ```ts
+ * const data = piped<User | null>(null);
+ * const view = data.pipe(startWith<User | null, 'loading'>('loading'));
+ * view(); // 'loading' on first read, then User | null afterward
+ * ```
+ */
 const startWith = (initial) => (src) => linkedSignal({
     source: src,
     computation: (next, prev) => (prev === undefined ? initial : next),
 });
-/** Emits `[prev, curr]` pairs. The first emission has prev = undefined. */
+/**
+ * Emit `[prev, curr]` tuples so consumers can react to transitions instead of
+ * raw values. On the first emission `prev` is `undefined`.
+ *
+ * @example
+ * ```ts
+ * const count = piped(0);
+ * const delta = count.pipe(pairwise(), map(([prev, curr]) => curr - (prev ?? 0)));
+ * count.set(5);
+ * delta(); // 5
+ * ```
+ */
 const pairwise = () => (src) => linkedSignal({
     source: src,
     computation: (next, prev) => [prev?.source, next],
 });
-/** Reduce-like accumulator across emissions. */
+/**
+ * Reduce-like accumulator that folds each emission into a running result.
+ * Behaves like `Array.prototype.reduce` but applied over time, with the
+ * accumulator persisted across emissions.
+ *
+ * @example
+ * ```ts
+ * const delta = piped(0);
+ * const total = delta.pipe(scan((acc, n) => acc + n, 0));
+ * delta.set(5); // total() === 5
+ * delta.set(3); // total() === 8
+ * ```
+ */
 const scan = (reducer, seed) => (src) => linkedSignal({
     source: src,
     computation: (next, prev) => reducer(prev?.value ?? seed, next),
@@ -968,6 +1099,15 @@ const EVENTS = [
  * Battery Status API. Returns `null` until the underlying `getBattery()`
  * promise resolves, or permanently when the API is unsupported (Firefox /
  * Safari at the time of writing). SSR-safe.
+ *
+ * @example
+ * ```ts
+ * const battery = batteryStatus();
+ * effect(() => {
+ *   const b = battery();
+ *   if (b) console.log(`${Math.round(b.level * 100)}% • charging: ${b.charging}`);
+ * });
+ * ```
  */
 function batteryStatus(debugName = 'batteryStatus') {
     if (isPlatformServer(inject(PLATFORM_ID)) ||
@@ -1250,6 +1390,15 @@ function unwrap$1(target) {
  * Defaults `target` to the current `ElementRef` so it can be used inline in a
  * component's `class` field. SSR-safe — returns a constant `false` signal on
  * the server.
+ *
+ * @example
+ * ```ts
+ * @Component({ ... })
+ * class MenuComponent {
+ *   // Defaults to the host element — flips true when focus is inside.
+ *   readonly hasFocus = focusWithin();
+ * }
+ * ```
  */
 function focusWithin(target = inject(ElementRef)) {
     if (isPlatformServer(inject(PLATFORM_ID))) {
@@ -1352,6 +1501,14 @@ const serverDate$1 = new Date();
  * activity) resets the timer and flips the signal back to `false`.
  *
  * SSR-safe — always `false` with a frozen `since` date on the server.
+ *
+ * @example
+ * ```ts
+ * const isAway = idle({ ms: 30_000 });
+ * effect(() => {
+ *   if (isAway()) console.log('idle since', isAway.since());
+ * });
+ * ```
  */
 function idle(opt) {
     if (isPlatformServer(inject(PLATFORM_ID))) {
@@ -1715,6 +1872,14 @@ const serverDate = new Date();
  *
  * @param debugName Optional debug name for the signal.
  * @returns A `NetworkStatusSignal` instance.
+ *
+ * @example
+ * ```ts
+ * const online = networkStatus();
+ * effect(() => {
+ *   if (!online()) console.log('offline since', online.since());
+ * });
+ * ```
  */
 function networkStatus(debugName = 'networkStatus') {
     if (isPlatformServer(inject(PLATFORM_ID))) {
@@ -1754,6 +1919,15 @@ const SSR_FALLBACK = {
  *
  * SSR-safe — returns a constant `portrait-primary / 0°` signal on the server
  * and in environments without `screen.orientation` support.
+ *
+ * @example
+ * ```ts
+ * const screenOrientation = orientation();
+ * effect(() => {
+ *   const { type, angle } = screenOrientation();
+ *   console.log(`${type} at ${angle}°`);
+ * });
+ * ```
  */
 function orientation(debugName = 'orientation') {
     if (isPlatformServer(inject(PLATFORM_ID)) ||
@@ -2033,6 +2207,27 @@ function sensor(type, options) {
             throw new Error(`Unknown sensor type: ${type}`);
     }
 }
+/**
+ * Bulk sensor factory — creates several sensor signals at once and returns
+ * them keyed by sensor type. Convenient when a single consumer needs to react
+ * to multiple browser signals; for a single sensor prefer {@link sensor}
+ * directly.
+ *
+ * @typeParam TType The union of sensor keys being requested.
+ * @param track Array of sensor type keys to create.
+ * @param opt Optional per-sensor options keyed by sensor type.
+ * @returns A record `{ [key]: <SensorReturnType> }` for each requested key.
+ *
+ * @example
+ * ```ts
+ * const { windowSize, networkStatus } = sensors(
+ *   ['windowSize', 'networkStatus'],
+ *   { windowSize: { throttle: 200 } },
+ * );
+ *
+ * effect(() => console.log(windowSize(), networkStatus()));
+ * ```
+ */
 function sensors(track, opt) {
     return track.reduce((result, key) => {
         result[key] = sensor(key, opt?.[key]);