solid-ctrl-flow 1.0.39 → 1.0.40

package/dist/index.d.ts

@@ -3,7 +3,6 @@ import { Context } from 'solid-js';
 import { EffectFunction } from 'solid-js';
 import { JSX } from 'solid-js';
 import { MemoOptions } from 'solid-js';
-import { Ref } from 'solid-js';
 import { Resource } from 'solid-js';
 import { Setter } from 'solid-js';
 import { Signal } from 'solid-js';
@@ -133,6 +132,18 @@ export declare function createReactiveResource<R>(f: EffectFunction<R | undefine
 /** Built-in {@link ReactiveContext} which allows you to display different things in debug mode */
 export declare const debug: ReactiveContext<boolean>;
 
+/**
+ * Eventually wraps its content into a template if a certain condition is met.
+ * The content is memoized in the beginning and will be recycled even if the wrapper changes.
+ * You can avoid the memoization trought {@link Standard.unrecycled}, this is needed if you want to use a context provider on your template.
+ * If {@link Keyed.keyed} is active, the template will be executed each time the content of {@link Standard.when} changes.
+ * If {@link Standard.unrecycled} is active, the content will be executed each time it is mounted (Each time {@link Standard.when} goes from a falsish value to a truish one and vice versa).
+ * If both {@link Keyed.keyed} and {@link Standard.unrecycled} are active, the content will be executed each time {@link Standard.when} changes
+ */
+export declare function Enfold<T>(props: Keyed<T>): JSX.Element;
+
+export declare function Enfold<T>(props: Unkeyed<T>): JSX.Element;
+
 /** Handy type alias */
 declare type Equals = MemoOptions<unknown>["equals"];
 
@@ -143,6 +154,12 @@ declare type Info = {
     children: JSX.Element;
 };
 
+/** Parameters to pass to a keyed {@link Enfold} */
+declare type Keyed<T> = Standard<T> & {
+    keyed: true;
+    template: Template<NonNullable<T>>;
+};
+
 /**
  * Memoizes some of the properties of {@link obj}.
  * If {@link keys} is not provided, memoizes everything that get returned by {@link Object.keys} when provided with {@link obj}.
@@ -158,11 +175,11 @@ export declare function memoProps<T, K extends readonly (keyof T)[]>(obj: T, key
 /**
  * Like a {@link For}, but instead of putting an element after another it nests them.
  * The component will try to recycle the layers when the source array changes (Once again, like the {@link For}).
- * Due to the recyling, the layers will be created indipendently, thus their {@link Owner}s won't be nested in their parents' ones.
+ * Due to the recyling, the layers will be created indipendently, thus their {@link Owner}s won't be nested in their parents' ones, this makes the component unsuitable to wrap the content with context providers.
  * Example:
  * ```tsx
  * return <>
- * 	<Nest each={[ 1, 2, 3 ]} template={(x, y) => <>({x}, {y()}, -{x})</>}>
+ * 	<Nest each={[ 1, 2, 3 ]} template={(c, x) => <>({x}, {c()}, -{x})</>}>
  * 		content
  * 	</Nest>
  * </>
@@ -170,8 +187,8 @@ export declare function memoProps<T, K extends readonly (keyof T)[]>(obj: T, key
  * Will output "(1, (2, (3, content, -3), -2), -1)"
  */
 export declare function Nest<T>(props: {
-    each: T[];
-    template: (x: T, c: Accessor<JSX.Element>, i: Accessor<number>) => JSX.Element;
+    each: readonly T[] | undefined;
+    template: (c: Accessor<JSX.Element>, x: T, i: Accessor<number>) => JSX.Element;
     children: JSX.Element;
 }): JSX.Element;
 
@@ -214,15 +231,6 @@ export declare abstract class ReactiveContext<T> extends BASE_CTOR<T> {
     static create<T>(defaultValue: T, name?: string): ReactiveContext<T>;
 }
 
-/**
- * Executes a {@link Ref}.
- * Throws a {@link ReferenceError} if {@link ref} its not a function at runtime (Which should never be the case thanks to the solid compiler)
- * @param ref The function to execute
- * @param value The value to pass to the function
- * @returns The same value of {@link value}
- */
-export declare function refCall<T, U extends T = T>(ref: Ref<T> | undefined, value: U): U;
-
 /**
  * Executes {@link f} with the provided value for the specified {@link Context}.
  * You can pass `undefined` to {@link value} in order to get back the default value for {@link ctx}.
@@ -244,6 +252,16 @@ export declare function runWithContext<T, R>(ctx: Context<T>, value: T | undefin
  */
 export declare function splitAndMemoProps<T extends Record<any, any>, K extends readonly (keyof T)[]>(obj: T, keys: K, equals?: Equals): [Pick<T, Extract<K, readonly (keyof T)[]>[number]>, Omit<T, K[number]>];
 
+/** Standard parameters to pass to an {@link Enfold} */
+declare type Standard<T> = {
+    when: T;
+    children: JSX.Element;
+    unrecycled?: boolean;
+};
+
+/** Type of an element wrapping call-back which accepts an additional parameter */
+declare type Template<T> = (c: Accessor<JSX.Element>, x: T) => JSX.Element;
+
 /**
  * Creates a full-fledged solid {@link Setter} from a normal one
  * @param get The getter of the {@link Signal}; It's needed when a function gets passed to the new setter
@@ -258,6 +276,12 @@ export declare function toSetter<T>(get: Accessor<T>, set: (x: T) => void): Sett
  */
 export declare function toSignal<T, K extends keyof T>(obj: Accessor<T>, k: Accessor<K>): Signal<T[K]>;
 
+/** Parameters to pass to an unkeyed {@link Enfold} */
+declare type Unkeyed<T> = Standard<T> & {
+    keyed?: false;
+    template: Template<Accessor<NonNullable<T>>>;
+};
+
 /**
  * Executes {@link f} untracking it.
  * Due to the fact that the function is passed as input, it does not untrack its changes (It's intentional)
@@ -269,11 +293,25 @@ export declare function toSignal<T, K extends keyof T>(obj: Accessor<T>, k: Acce
 export declare function untrackCall<F extends (...args: any[]) => unknown>(this: ThisParameterType<F>, f: F, ...args: Parameters<F>): ReturnType<F>;
 
 /**
- * Calls an {@link Accessor} maintaining its reactivity
+ * Calls an {@link Accessor} maintaining its reactivity at 1 level
  * @param f The {@link Accessor} to the value to emulate
  * @returns A {@link Proxy} that copies the functionalities of the result of {@link f} calling it for each interaction, thus maintaining reactivity
  */
-export declare const unwrap: <T>(f: Accessor<T>) => T;
+export declare const unwrap: <T extends object>(f: Accessor<T>) => T;
+
+/**
+ * Calls {@link f} maintaining its reactivity at 2 levels.
+ * Unlike the normal {@link unwrap}, this maintains reactivity on the elements of the array too, which means that it can be destructured
+ * ```ts
+ * const first = unwrap(f);         // The value of "first" is reactive but CANNOT be destructured
+ * const [ getFirst ] = first;      // The value of "getFirst" is NOT reactive, it's the first element of the CURRENT signal returned by "f"
+ *
+ * const second = unwrapSignal(f);  // The value of "second" is reactive and CAN be destructured
+ * const [ getSecond ] = second;    // The value of "getSecond" IS reactive, it's a function that calls "f", gets the first element and calls that too
+ * ```
+ * @param f An {@link Accessor} to a {@link Signal}
+ */
+export declare function unwrapSignal<T>(f: Accessor<Signal<T>>): Signal<T>;
 
 /** Like a {@link Match} but gets the value from the closest {@link Case} ancestor */
 export declare function When(props: {

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { useContext, createMemo, createComponent, createContext, createRoot, getOwner, Match, mergeProps, onCleanup, For, Show, untrack, splitProps, createEffect, on, createResource, mapArray, createSignal, onMount, createRenderEffect } from "solid-js";
+import { useContext, createMemo, createComponent, createContext, createRoot, getOwner, Match, mergeProps, splitProps, createEffect, on, createResource, untrack, Show, onCleanup, For, mapArray, createSignal, onMount, createRenderEffect } from "solid-js";
 import { createMutable } from "solid-js/store";
 const BASE_CTOR = Function;
 class ReactiveContext extends BASE_CTOR {
@@ -78,6 +78,58 @@ function When(props) {
     }
   }, other));
 }
+function memoProps(obj, keys = Object.keys(obj), equals = false) {
+  const out = {};
+  for (const elm of keys)
+    Object.defineProperty(out, elm, {
+      enumerable: true,
+      get: createMemo(() => obj[elm], void 0, {
+        equals
+      })
+    });
+  return out;
+}
+function splitAndMemoProps(obj, keys, equals) {
+  const out = splitProps(obj, keys);
+  out[0] = memoProps(out[0], keys, equals);
+  return out;
+}
+function createReactiveResource(f) {
+  var refetch;
+  const memo = createMemo(f);
+  createEffect(on(memo, () => refetch?.()));
+  const [get] = [, {
+    refetch
+  }] = createResource(memo);
+  return get;
+}
+function untrackCall(f, ...args) {
+  return untrack(() => f.apply(this, args));
+}
+const unwrap = (f) => new Proxy(f, HANDLER);
+const HANDLER = new Proxy({}, {
+  get(cache, k) {
+    return cache[k] ??= (t, ...args) => {
+      return Reflect[k](t(), ...args);
+    };
+  }
+});
+function Enfold(props) {
+  const f = () => props.children;
+  const children = unwrap(createMemo(() => props.unrecycled ? f : createMemo(f)));
+  return createComponent(Show, {
+    get keyed() {
+      return props.keyed;
+    },
+    get when() {
+      return props.when;
+    },
+    get fallback() {
+      return children();
+    },
+    children: (x) => createMemo(() => untrackCall(props.template, children, x))
+  });
+}
 function createExtractor(name = "extractor") {
   const ctx2 = createContext(void 0, {
     name
@@ -151,47 +203,11 @@ function Joint(props) {
     }
   });
 }
-function untrackCall(f, ...args) {
-  return untrack(() => f.apply(this, args));
-}
-function refCall(ref, value) {
-  if (!ref)
-    return value;
-  if (typeof ref !== "function")
-    throw new ReferenceError('Il parametro "ref" deve essere stato compilato in una funzione a runtime');
-  ref(value);
-  return value;
-}
-function memoProps(obj, keys = Object.keys(obj), equals = false) {
-  const out = {};
-  for (const elm of keys)
-    Object.defineProperty(out, elm, {
-      enumerable: true,
-      get: createMemo(() => obj[elm], void 0, {
-        equals
-      })
-    });
-  return out;
-}
-function splitAndMemoProps(obj, keys, equals) {
-  const out = splitProps(obj, keys);
-  out[0] = memoProps(out[0], keys, equals);
-  return out;
-}
-function createReactiveResource(f) {
-  var refetch;
-  const memo = createMemo(f);
-  createEffect(on(memo, () => refetch?.()));
-  const [get] = [, {
-    refetch
-  }] = createResource(memo);
-  return get;
-}
 function Nest(props) {
   const memo = memoProps(props, ["template", "children"]);
   const content = mapArray(() => props.each, (x, i) => {
     const [get, set] = createSignal();
-    const out = memo.template(x, get, i);
+    const out = createMemo(() => untrackCall(memo.template, get, x, i));
     return (x2) => {
       onMount(() => set(() => x2));
       onCleanup(() => set(void 0));
@@ -223,17 +239,13 @@ function toSignal(obj, k) {
 function coalesceSignal([get, set], f) {
   return [() => get() ?? set(f), set];
 }
-const unwrap = (f) => new Proxy(f, HANDLER);
-const HANDLER = new Proxy({}, {
-  get(cache, k) {
-    return cache[k] ??= (t, ...args) => {
-      return Reflect[k](t(), ...args);
-    };
-  }
-});
+function unwrapSignal(f) {
+  return [() => f()[0](), (x) => f()[1](x)];
+}
 const debug = ReactiveContext.create(false, "debug-scope");
 export {
   Case,
+  Enfold,
   Nest,
   ReactiveContext,
   When,
@@ -244,11 +256,11 @@ export {
   createReactiveResource,
   debug,
   memoProps,
-  refCall,
   runWithContext,
   splitAndMemoProps,
   toSetter,
   toSignal,
   untrackCall,
-  unwrap
+  unwrap,
+  unwrapSignal
 };

package/dist/index.umd.js

@@ -80,6 +80,58 @@
       }
     }, other));
   }
+  function memoProps(obj, keys = Object.keys(obj), equals = false) {
+    const out = {};
+    for (const elm of keys)
+      Object.defineProperty(out, elm, {
+        enumerable: true,
+        get: solidJs.createMemo(() => obj[elm], void 0, {
+          equals
+        })
+      });
+    return out;
+  }
+  function splitAndMemoProps(obj, keys, equals) {
+    const out = solidJs.splitProps(obj, keys);
+    out[0] = memoProps(out[0], keys, equals);
+    return out;
+  }
+  function createReactiveResource(f) {
+    var refetch;
+    const memo = solidJs.createMemo(f);
+    solidJs.createEffect(solidJs.on(memo, () => refetch?.()));
+    const [get] = [, {
+      refetch
+    }] = solidJs.createResource(memo);
+    return get;
+  }
+  function untrackCall(f, ...args) {
+    return solidJs.untrack(() => f.apply(this, args));
+  }
+  const unwrap = (f) => new Proxy(f, HANDLER);
+  const HANDLER = new Proxy({}, {
+    get(cache, k) {
+      return cache[k] ??= (t, ...args) => {
+        return Reflect[k](t(), ...args);
+      };
+    }
+  });
+  function Enfold(props) {
+    const f = () => props.children;
+    const children = unwrap(solidJs.createMemo(() => props.unrecycled ? f : solidJs.createMemo(f)));
+    return solidJs.createComponent(solidJs.Show, {
+      get keyed() {
+        return props.keyed;
+      },
+      get when() {
+        return props.when;
+      },
+      get fallback() {
+        return children();
+      },
+      children: (x) => solidJs.createMemo(() => untrackCall(props.template, children, x))
+    });
+  }
   function createExtractor(name = "extractor") {
     const ctx2 = solidJs.createContext(void 0, {
       name
@@ -153,47 +205,11 @@
       }
     });
   }
-  function untrackCall(f, ...args) {
-    return solidJs.untrack(() => f.apply(this, args));
-  }
-  function refCall(ref, value) {
-    if (!ref)
-      return value;
-    if (typeof ref !== "function")
-      throw new ReferenceError('Il parametro "ref" deve essere stato compilato in una funzione a runtime');
-    ref(value);
-    return value;
-  }
-  function memoProps(obj, keys = Object.keys(obj), equals = false) {
-    const out = {};
-    for (const elm of keys)
-      Object.defineProperty(out, elm, {
-        enumerable: true,
-        get: solidJs.createMemo(() => obj[elm], void 0, {
-          equals
-        })
-      });
-    return out;
-  }
-  function splitAndMemoProps(obj, keys, equals) {
-    const out = solidJs.splitProps(obj, keys);
-    out[0] = memoProps(out[0], keys, equals);
-    return out;
-  }
-  function createReactiveResource(f) {
-    var refetch;
-    const memo = solidJs.createMemo(f);
-    solidJs.createEffect(solidJs.on(memo, () => refetch?.()));
-    const [get] = [, {
-      refetch
-    }] = solidJs.createResource(memo);
-    return get;
-  }
   function Nest(props) {
     const memo = memoProps(props, ["template", "children"]);
     const content = solidJs.mapArray(() => props.each, (x, i) => {
       const [get, set] = solidJs.createSignal();
-      const out = memo.template(x, get, i);
+      const out = solidJs.createMemo(() => untrackCall(memo.template, get, x, i));
       return (x2) => {
         solidJs.onMount(() => set(() => x2));
         solidJs.onCleanup(() => set(void 0));
@@ -225,16 +241,12 @@
   function coalesceSignal([get, set], f) {
     return [() => get() ?? set(f), set];
   }
-  const unwrap = (f) => new Proxy(f, HANDLER);
-  const HANDLER = new Proxy({}, {
-    get(cache, k) {
-      return cache[k] ??= (t, ...args) => {
-        return Reflect[k](t(), ...args);
-      };
-    }
-  });
+  function unwrapSignal(f) {
+    return [() => f()[0](), (x) => f()[1](x)];
+  }
   const debug = ReactiveContext.create(false, "debug-scope");
   exports2.Case = Case;
+  exports2.Enfold = Enfold;
   exports2.Nest = Nest;
   exports2.ReactiveContext = ReactiveContext;
   exports2.When = When;
@@ -245,12 +257,12 @@
   exports2.createReactiveResource = createReactiveResource;
   exports2.debug = debug;
   exports2.memoProps = memoProps;
-  exports2.refCall = refCall;
   exports2.runWithContext = runWithContext;
   exports2.splitAndMemoProps = splitAndMemoProps;
   exports2.toSetter = toSetter;
   exports2.toSignal = toSignal;
   exports2.untrackCall = untrackCall;
   exports2.unwrap = unwrap;
+  exports2.unwrapSignal = unwrapSignal;
   Object.defineProperty(exports2, Symbol.toStringTag, { value: "Module" });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-ctrl-flow",
-  "version": "1.0.39",
+  "version": "1.0.40",
   "description": "Control flow components for solid-js",
   "author": "AFatNiBBa",
   "license": "ISC",

package/readMe.md

@@ -34,12 +34,44 @@ return <>
 </>
 ```
 
+### `Enfold`
+Eventually wraps its content into a template if a certain condition is met.
+The following code
+```tsx
+const value = true;
+return <>
+  <Enfold when={value} template={c => <div style={{ background: "red" }}>{c()}</div>}>
+    content
+  </Enfold>
+</>
+```
+Is equivalent to this
+```tsx
+return <>
+  <div style={{ background: "red" }}>
+    content
+  </div>
+</>
+```
+And if `value` was falsish, it would have been equivalent to this
+```tsx
+return <>content</>
+```
+If you are wrapping the content with a context provider you need to set the `unrecycled` attribute to `true` to run again the whole content, otherwise the `Owner` of the content won't be child of the template one
+```tsx
+return <>
+  <Enfold unrecycled when={value} template={c => <ctx.Provider value={2} children={c()} />}>
+    {useContext(ctx)}
+  </Enfold>
+</>
+```
+
 ### `Nest`
 Like a `For`, but instead of putting an element after another it nests them.
 The following code
 ```tsx
 return <>
-  <Nest each={[ "red", "green", "blue" ]} template={(x, y) => <div style={{ background: x, padding: "1ch" }}>{y()}</div>}>
+  <Nest each={[ "red", "green", "blue" ]} template={(c, x) => <div style={{ background: x, padding: "1ch" }}>{c()}</div>}>
     content
   </Nest>
 </>
@@ -150,6 +182,9 @@ Functions that create bindings between `Signal`s
 > 
 > #### `coalesceSignal()`
 > Creates a non nullable `Signal` from a nullable one
+> 
+> #### `unwrapSignal()`
+> A `Signal`-specific version of `unwrap()` that allows the destructuring of its result
 
 ### `ReactiveContext.create()`
 Method that creates a reactive version of a solid `Context` with some additional built-in functionalities
@@ -164,7 +199,7 @@ const value = ctx();
 Creates a context scope that persists for the duration of a function
 
 ### `unwrap()`
-Calls an `Accessor` maintaining its reactivity
+Calls an `Accessor` maintaining its reactivity at 1 level
 
 ### `debug()`
 Allows you to define ui section that are only visible in debug or NOT in debug
@@ -180,12 +215,6 @@ return <>
 </>
 ```
 
-### `untrackCall()`
-Calls a function untracking what happens inside of it but not what gets passed as its argument
-
-### `refCall()`
-Executes a `Ref`
-
 ### `memoProps()`
 Creates a partial version of an object with memoized remaining properties
 
@@ -193,4 +222,7 @@ Creates a partial version of an object with memoized remaining properties
 Like `splitProps()` but memoizes the whole local part
 
 ### `createReactiveResource()`
-Like `createResource()` but the provided function will be reactive
+Like `createResource()` but the provided function will be reactive
+
+### `untrackCall()`
+Calls a function untracking what happens inside of it but not what gets passed as its argument