solid-ctrl-flow 2.1.1 → 2.2.0

package/dist/index.d.ts

@@ -9,14 +9,31 @@ import { splitProps } from 'solid-js';
 /** Like a {@link Match} but gets the value from the closest {@link On} ancestor */
 export declare function Case(props: ParentProps<{
     value: unknown;
-}>): JSX.Element;
+}>): JSX;
 
 /**
- * Creates a slot that allows you to show a component outside of its parent.
+ * Eventually wraps its content into a template if a certain condition is met.
+ * If you set {@link Standard.recycled} to `true`, the content will be memoized in the beginning and will be recycled even if the wrapper changes.
+ * You can't use memoization 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.recycled} is not 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 {@link Keyed.keyed} is active and {@link Standard.recycled} isn't, 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"];
+
+/**
+ * Friendlier version of the {@link Portal}.
  * It works with arbitrary nesting.
+ * The components communicate only if they're part of the same {@link Extractor}.
+ * It is uncommon for an {@link Extractor} to be defined inside a component.
  * Example:
  * ```tsx
- * const e = createExtractor();
+ * const e = new Extractor();
  * return <>
  *  <e.Joint>
  *      <div id="something">
@@ -24,51 +41,33 @@ export declare function Case(props: ParentProps<{
  *      </div>
  *      <div id="something-else">
  *          <e.Source>
- *              This text will be shown instead of `e.Dest`.
- *              If there weren't to be any `e.Joint` ancestor, then this text would have stayed here
+ *              This text will be shown instead of `e.Dest`
  *          </e.Source>
  *      </div>
  *  </e.Joint>
  * </>
  * ```
- * @param name Name to give to the context of the extractor
  */
-export declare function createExtractor(name?: string): {
-    /** Shows the content of the closest {@link Source} child of the closest {@link Joint} ancestor of this component */
-    Dest: () => JSX.Element;
-    /** Puts its content inside of a {@link Dest} if it is available; There is no need to include this component on the DOM tree */
-    Source: (props: Slot & {
-        order?: number | undefined;
-    } & {
-        children?: JSX.Element;
-    } & {
-        sameContext?: boolean | undefined;
-    }) => JSX.Element;
-    /** Allows {@link Dest} and {@link Source} childrens to communicate with each other  */
+export declare class Extractor {
+    constructor(name?: string);
+    readonly ctx: Context<State | undefined>;
     Joint: (props: {
-        children?: JSX.Element;
-    }) => JSX.Element;
+        children?: JSX;
+    }) => JSX;
+    Dest: () => JSX;
+    Source: (props: Info) => JSX;
     /**
-     * Gets an {@link Accessor} that tells if the context in which THIS getter has been executed has been extracted (Is inside of a {@link Dest})
-     * @returns Returns `null` if there is no parent {@link Joint}, the number of {@link Dest}s in which this component is being displayed otherwise (Usually 1)
+     * Returns the number of destinations available for the current {@link Extractor}.
+     * It's a getter that returns a function that will be bound to the {@link Owner} in which the getter was called.
+     * If the current {@link Owner} is NOT under a {@link Joint}, it will return `undefined`
      */
-    readonly extracting: () => number | null;
-};
-
-/**
- * Eventually wraps its content into a template if a certain condition is met.
- * If you set {@link Standard.recycled} to `true`, the content will be memoized in the beginning and will be recycled even if the wrapper changes.
- * You can't use memoization 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.recycled} is not 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 {@link Keyed.keyed} is active and {@link Standard.recycled} isn't, 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;
+    get getDestCount(): (() => number) | undefined;
+}
 
-/** Handy type alias */
-declare type Equals = MemoOptions<unknown>["equals"];
+/** Informations about a single {@link Source} */
+declare type Info = ParentProps<{
+    order?: number;
+}>;
 
 /** Parameters to pass to a keyed {@link Enfold} */
 declare type Keyed<T> = Standard<T> & {
@@ -115,7 +114,35 @@ export declare function memoProps<T, K extends readonly (keyof T)[]>(obj: T, key
 export declare function On<T>(props: ParentProps<{
     value: T;
     onCompare?(a: unknown, b: T): boolean;
-}>): JSX.Element;
+}>): JSX;
+
+/**
+ * Ordered linked list that allows for:
+ * - O(n) Iteration
+ * - O(n) Insertion
+ * - O(1) Removal (With a node reference)
+ */
+export declare class OrderedLinkedList<T> {
+    next?: OrderedLinkedListNode<T>;
+    /** Yields all the elements PAST the current */
+    [Symbol.iterator](): Generator<T>;
+    /**
+     * Adds a node to the list in order
+     * @param node The node to add
+     * @param comp The comparison function to use
+     * @returns The same value as {@link node}
+     */
+    add(node: OrderedLinkedListNode<T>, comp: (a: T, b: T) => number): OrderedLinkedListNode<T>;
+}
+
+/** Node for the {@link OrderedLinkedList} */
+export declare class OrderedLinkedListNode<T> extends OrderedLinkedList<T> {
+    value: T;
+    constructor(value: T);
+    prev?: OrderedLinkedList<T>;
+    /** Removes the current node from the list */
+    remove(): void;
+}
 
 /**
  * Executes {@link f} with the provided value for the specified {@link Context}.
@@ -133,43 +160,6 @@ export declare function SameContext(props: ParentProps<{
     owner: Owner;
 }>): JSX.Element;
 
-/** Element which tracks its index in its containing array */
-export declare interface Slot {
-    slot?: number;
-}
-
-/** Utility of {@link Slot}s */
-export declare namespace Slot {
-    /**
-     * Pushes an element into a slotted list
-     * @param list The list in which to add the element
-     * @param v The element to add to {@link list}
-     * @returns The index of the new element
-     */
-    const push: <T extends Slot>(list: T[], v: T) => number;
-    /**
-     * Exactly like {@link removeSlotAt}, but it gets the index from {@link v}
-     * @param list The list from which to remove the element
-     * @param v The element to remove from {@link list}
-     * @returns The removed element
-     */
-    const remove: <T extends Slot>(list: T[], v: T) => T | undefined;
-    /**
-     * Removes an element from a slotted list.
-     * The function returns `undefined` ONLY if the index is out of range (A {@link Slot} can't be `undefined`)
-     * @param list The list from which to remove the element
-     * @param i The index at which to remove the element
-     * @returns The removed element
-     */
-    export function removeAt<T extends Slot>(list: T[], i: number): T | undefined;
-    /**
-     * Restores the indexes of a slotted list.
-     * This function is useful after a sort, filter, or any other operation that changes the order of the elements in the list without taking care of {@link Slot}s
-     * @param list The list to restore
-     */
-    export function restore(list: Slot[]): void;
-}
-
 /**
  * Executes {@link splitProps} and memoizes every returned object but the last one using {@link memoProps}
  * @param obj Object to split and partially memoize
@@ -183,6 +173,14 @@ declare type Standard<T> = ParentProps<{
     recycled?: boolean;
 }>;
 
+/** Type of the data stored in the {@link Context} created by each {@link Extractor} */
+declare interface State {
+    readonly sources: OrderedLinkedList<Info>;
+    readonly extracting: number;
+    shift(k: number): void;
+    force(): void;
+}
+
 /** Type of an element wrapping call-back which accepts an additional parameter */
 declare type Template<T> = (c: Accessor<JSX.Element>, x: T) => JSX.Element;
 

package/dist/index.mjs

@@ -1,5 +1,4 @@
-import { createMemo, splitProps, untrack, createRoot, getOwner, createComponent, Show, createContext, useContext, onCleanup, For, createSelector, equalFn, Match } from "solid-js";
-import { createMutable } from "solid-js/store";
+import { createMemo, splitProps, untrack, createRoot, getOwner, createComponent, Show, createContext, useContext, onCleanup, For, createRenderEffect, on, createSignal, createSelector, equalFn, Match } from "solid-js";
 function memoProps(obj, keys = Reflect.ownKeys(obj), equals = false) {
   const out = {};
   for (const elm of keys)
@@ -49,117 +48,134 @@ function Enfold(props) {
     children: (x) => createMemo(() => untrackCall(props.template, children, x))
   });
 }
-var Slot;
-((Slot2) => {
-  Slot2.push = (list, v) => v.slot = list.push(v) - 1;
-  Slot2.remove = (list, v) => v.slot != null ? removeAt(list, v.slot) : v;
-  function removeAt(list, i) {
-    if (i >= list.length)
+class OrderedLinkedList {
+  next;
+  /** Yields all the elements PAST the current */
+  *[Symbol.iterator]() {
+    const { next } = this;
+    if (!next)
       return;
-    const last = list.pop();
-    if (i === list.length)
-      return last;
-    const out = list[i];
-    out.slot = void 0;
-    list[last.slot = i] = last;
-    return out;
+    yield next.value;
+    yield* next;
   }
-  Slot2.removeAt = removeAt;
-  function restore(list) {
-    for (var i = 0; i < list.length; i++)
-      list[i].slot = i;
+  /**
+   * Adds a node to the list in order
+   * @param node The node to add
+   * @param comp The comparison function to use
+   * @returns The same value as {@link node}
+   */
+  add(node, comp) {
+    const { next } = this;
+    if (next && comp(node.value, next.value) >= 0)
+      return next.add(node, comp);
+    this.next = node;
+    node.prev = this;
+    if (next)
+      (node.next = next).prev = node;
+    return node;
   }
-  Slot2.restore = restore;
-})(Slot || (Slot = {}));
-function createExtractor(name = "extractor") {
-  const ctx2 = createContext(void 0, {
-    name
-  });
-  return {
-    /** Shows the content of the closest {@link Source} child of the closest {@link Joint} ancestor of this component */
-    Dest: Dest.bind(ctx2),
-    /** Puts its content inside of a {@link Dest} if it is available; There is no need to include this component on the DOM tree */
-    Source: Source.bind(ctx2),
-    /** Allows {@link Dest} and {@link Source} childrens to communicate with each other  */
-    Joint: Joint.bind(ctx2),
-    /**
-     * Gets an {@link Accessor} that tells if the context in which THIS getter has been executed has been extracted (Is inside of a {@link Dest})
-     * @returns Returns `null` if there is no parent {@link Joint}, the number of {@link Dest}s in which this component is being displayed otherwise (Usually 1)
-     */
-    get extracting() {
-      const obj = useContext(ctx2);
-      return () => obj?.attached ?? null;
+}
+class OrderedLinkedListNode extends OrderedLinkedList {
+  constructor(value) {
+    super();
+    this.value = value;
+  }
+  prev;
+  /** Removes the current node from the list */
+  remove() {
+    const { prev, next } = this;
+    if (prev)
+      prev.next = next;
+    if (next)
+      next.prev = prev;
+    this.next = this.prev = void 0;
+  }
+}
+const COMPARATOR = (a, b) => (a.order ?? 0) - (b.order ?? 0);
+class Extractor {
+  constructor(name) {
+    this.ctx = createContext(void 0, {
+      name
+    });
+  }
+  ctx;
+  Joint = Joint.bind(this);
+  Dest = Dest.bind(this);
+  Source = Source.bind(this);
+  /**
+   * Returns the number of destinations available for the current {@link Extractor}.
+   * It's a getter that returns a function that will be bound to the {@link Owner} in which the getter was called.
+   * If the current {@link Owner} is NOT under a {@link Joint}, it will return `undefined`
+   */
+  get getDestCount() {
+    const state = useContext(this.ctx);
+    return state && (() => state.extracting);
+  }
+}
+function Joint(props) {
+  const state = createState();
+  return createComponent(this.ctx.Provider, {
+    value: state,
+    get children() {
+      return props.children;
     }
-  };
+  });
 }
 function Dest() {
-  const obj = useContext(this);
-  if (!obj)
-    return;
-  obj.attached++;
-  onCleanup(() => obj.attached--);
+  const state = useContext(this.ctx);
+  if (!state)
+    throw new Error("An extractor's destination must be inside one of its joints");
+  state.shift(1);
+  onCleanup(() => state.shift(-1));
   return createComponent(For, {
     get each() {
-      return obj.source.toSorted((a, b) => (a.order ?? 0) - (b.order ?? 0));
+      return [...state.sources];
     },
     children: (x) => createMemo(() => x.children)
   });
 }
 function Source(props) {
-  const obj = useContext(this);
-  if (!obj)
-    return createMemo(() => props.children);
-  const info = createInfo(props);
-  Slot.push(obj.source, info);
-  onCleanup(() => Slot.remove(obj.source, info));
-  return createComponent(Show, {
-    get when() {
-      return !obj.attached;
+  const state = useContext(this.ctx);
+  if (!state)
+    throw new Error("An extractor's source must be inside one of its joints");
+  const {
+    sources,
+    force
+  } = state;
+  const order = createMemo(() => props.order);
+  const info = {
+    get order() {
+      return order();
     },
     get children() {
-      return info.children;
+      return props.children;
     }
-  });
+  };
+  const node = new OrderedLinkedListNode(info);
+  createRenderEffect(on(order, () => {
+    onCleanup(() => node.remove());
+    sources.add(node, COMPARATOR);
+    force();
+  }));
+  return [];
 }
-function Joint(props) {
-  const {
-    Provider
-  } = this;
-  const obj = createMutable({
-    attached: 0,
-    source: []
+function createState() {
+  const [getExtracting, setExtracting] = createSignal(0, {
+    internal: true
   });
-  return createComponent(Provider, {
-    value: obj,
-    get children() {
-      return props.children;
-    }
+  const [getSources, setSources] = createSignal(new OrderedLinkedList(), {
+    internal: true,
+    equals: false
   });
-}
-function createInfo(props) {
-  const owner = getOwner(), memo = createMemo(() => props.order);
   return {
-    get order() {
-      return memo();
+    get sources() {
+      return getSources();
     },
-    get children() {
-      return createComponent(Show, {
-        get when() {
-          return props.sameContext;
-        },
-        get fallback() {
-          return props.children;
-        },
-        get children() {
-          return createComponent(SameContext, {
-            owner,
-            get children() {
-              return props.children;
-            }
-          });
-        }
-      });
-    }
+    get extracting() {
+      return getExtracting();
+    },
+    shift: (k) => setExtracting((v) => v + k),
+    force: () => setSources((s) => s)
   };
 }
 const ctx = createContext(void 0, {
@@ -195,10 +211,11 @@ function SameContext(props) {
 export {
   Case,
   Enfold,
+  Extractor,
   On,
+  OrderedLinkedList,
+  OrderedLinkedListNode,
   SameContext,
-  Slot,
-  createExtractor,
   memoProps,
   runWithContext,
   splitAndMemoProps,

package/dist/index.umd.js

@@ -1,6 +1,6 @@
 (function(global, factory) {
-  typeof exports === "object" && typeof module !== "undefined" ? factory(exports, require("solid-js"), require("solid-js/store")) : typeof define === "function" && define.amd ? define(["exports", "solid-js", "solid-js/store"], factory) : (global = typeof globalThis !== "undefined" ? globalThis : global || self, factory(global.solidCtrlFlow = {}, global.solidJs, global.solidJsStore));
-})(this, function(exports2, solidJs, store) {
+  typeof exports === "object" && typeof module !== "undefined" ? factory(exports, require("solid-js")) : typeof define === "function" && define.amd ? define(["exports", "solid-js"], factory) : (global = typeof globalThis !== "undefined" ? globalThis : global || self, factory(global.solidCtrlFlow = {}, global.solidJs));
+})(this, function(exports2, solidJs) {
   "use strict";
   function memoProps(obj, keys = Reflect.ownKeys(obj), equals = false) {
     const out = {};
@@ -51,117 +51,134 @@
       children: (x) => solidJs.createMemo(() => untrackCall(props.template, children, x))
     });
   }
-  exports2.Slot = void 0;
-  ((Slot2) => {
-    Slot2.push = (list, v) => v.slot = list.push(v) - 1;
-    Slot2.remove = (list, v) => v.slot != null ? removeAt(list, v.slot) : v;
-    function removeAt(list, i) {
-      if (i >= list.length)
+  class OrderedLinkedList {
+    next;
+    /** Yields all the elements PAST the current */
+    *[Symbol.iterator]() {
+      const { next } = this;
+      if (!next)
         return;
-      const last = list.pop();
-      if (i === list.length)
-        return last;
-      const out = list[i];
-      out.slot = void 0;
-      list[last.slot = i] = last;
-      return out;
+      yield next.value;
+      yield* next;
     }
-    Slot2.removeAt = removeAt;
-    function restore(list) {
-      for (var i = 0; i < list.length; i++)
-        list[i].slot = i;
+    /**
+     * Adds a node to the list in order
+     * @param node The node to add
+     * @param comp The comparison function to use
+     * @returns The same value as {@link node}
+     */
+    add(node, comp) {
+      const { next } = this;
+      if (next && comp(node.value, next.value) >= 0)
+        return next.add(node, comp);
+      this.next = node;
+      node.prev = this;
+      if (next)
+        (node.next = next).prev = node;
+      return node;
     }
-    Slot2.restore = restore;
-  })(exports2.Slot || (exports2.Slot = {}));
-  function createExtractor(name = "extractor") {
-    const ctx2 = solidJs.createContext(void 0, {
-      name
-    });
-    return {
-      /** Shows the content of the closest {@link Source} child of the closest {@link Joint} ancestor of this component */
-      Dest: Dest.bind(ctx2),
-      /** Puts its content inside of a {@link Dest} if it is available; There is no need to include this component on the DOM tree */
-      Source: Source.bind(ctx2),
-      /** Allows {@link Dest} and {@link Source} childrens to communicate with each other  */
-      Joint: Joint.bind(ctx2),
-      /**
-       * Gets an {@link Accessor} that tells if the context in which THIS getter has been executed has been extracted (Is inside of a {@link Dest})
-       * @returns Returns `null` if there is no parent {@link Joint}, the number of {@link Dest}s in which this component is being displayed otherwise (Usually 1)
-       */
-      get extracting() {
-        const obj = solidJs.useContext(ctx2);
-        return () => obj?.attached ?? null;
+  }
+  class OrderedLinkedListNode extends OrderedLinkedList {
+    constructor(value) {
+      super();
+      this.value = value;
+    }
+    prev;
+    /** Removes the current node from the list */
+    remove() {
+      const { prev, next } = this;
+      if (prev)
+        prev.next = next;
+      if (next)
+        next.prev = prev;
+      this.next = this.prev = void 0;
+    }
+  }
+  const COMPARATOR = (a, b) => (a.order ?? 0) - (b.order ?? 0);
+  class Extractor {
+    constructor(name) {
+      this.ctx = solidJs.createContext(void 0, {
+        name
+      });
+    }
+    ctx;
+    Joint = Joint.bind(this);
+    Dest = Dest.bind(this);
+    Source = Source.bind(this);
+    /**
+     * Returns the number of destinations available for the current {@link Extractor}.
+     * It's a getter that returns a function that will be bound to the {@link Owner} in which the getter was called.
+     * If the current {@link Owner} is NOT under a {@link Joint}, it will return `undefined`
+     */
+    get getDestCount() {
+      const state = solidJs.useContext(this.ctx);
+      return state && (() => state.extracting);
+    }
+  }
+  function Joint(props) {
+    const state = createState();
+    return solidJs.createComponent(this.ctx.Provider, {
+      value: state,
+      get children() {
+        return props.children;
       }
-    };
+    });
   }
   function Dest() {
-    const obj = solidJs.useContext(this);
-    if (!obj)
-      return;
-    obj.attached++;
-    solidJs.onCleanup(() => obj.attached--);
+    const state = solidJs.useContext(this.ctx);
+    if (!state)
+      throw new Error("An extractor's destination must be inside one of its joints");
+    state.shift(1);
+    solidJs.onCleanup(() => state.shift(-1));
     return solidJs.createComponent(solidJs.For, {
       get each() {
-        return obj.source.toSorted((a, b) => (a.order ?? 0) - (b.order ?? 0));
+        return [...state.sources];
       },
       children: (x) => solidJs.createMemo(() => x.children)
     });
   }
   function Source(props) {
-    const obj = solidJs.useContext(this);
-    if (!obj)
-      return solidJs.createMemo(() => props.children);
-    const info = createInfo(props);
-    exports2.Slot.push(obj.source, info);
-    solidJs.onCleanup(() => exports2.Slot.remove(obj.source, info));
-    return solidJs.createComponent(solidJs.Show, {
-      get when() {
-        return !obj.attached;
+    const state = solidJs.useContext(this.ctx);
+    if (!state)
+      throw new Error("An extractor's source must be inside one of its joints");
+    const {
+      sources,
+      force
+    } = state;
+    const order = solidJs.createMemo(() => props.order);
+    const info = {
+      get order() {
+        return order();
       },
       get children() {
-        return info.children;
+        return props.children;
       }
-    });
+    };
+    const node = new OrderedLinkedListNode(info);
+    solidJs.createRenderEffect(solidJs.on(order, () => {
+      solidJs.onCleanup(() => node.remove());
+      sources.add(node, COMPARATOR);
+      force();
+    }));
+    return [];
   }
-  function Joint(props) {
-    const {
-      Provider
-    } = this;
-    const obj = store.createMutable({
-      attached: 0,
-      source: []
+  function createState() {
+    const [getExtracting, setExtracting] = solidJs.createSignal(0, {
+      internal: true
     });
-    return solidJs.createComponent(Provider, {
-      value: obj,
-      get children() {
-        return props.children;
-      }
+    const [getSources, setSources] = solidJs.createSignal(new OrderedLinkedList(), {
+      internal: true,
+      equals: false
     });
-  }
-  function createInfo(props) {
-    const owner = solidJs.getOwner(), memo = solidJs.createMemo(() => props.order);
     return {
-      get order() {
-        return memo();
+      get sources() {
+        return getSources();
       },
-      get children() {
-        return solidJs.createComponent(solidJs.Show, {
-          get when() {
-            return props.sameContext;
-          },
-          get fallback() {
-            return props.children;
-          },
-          get children() {
-            return solidJs.createComponent(SameContext, {
-              owner,
-              get children() {
-                return props.children;
-              }
-            });
-          }
-        });
-      }
+      get extracting() {
+        return getExtracting();
+      },
+      shift: (k) => setExtracting((v) => v + k),
+      force: () => setSources((s) => s)
     };
   }
   const ctx = solidJs.createContext(void 0, {
@@ -196,9 +213,11 @@
   }
   exports2.Case = Case;
   exports2.Enfold = Enfold;
+  exports2.Extractor = Extractor;
   exports2.On = On;
+  exports2.OrderedLinkedList = OrderedLinkedList;
+  exports2.OrderedLinkedListNode = OrderedLinkedListNode;
   exports2.SameContext = SameContext;
-  exports2.createExtractor = createExtractor;
   exports2.memoProps = memoProps;
   exports2.runWithContext = runWithContext;
   exports2.splitAndMemoProps = splitAndMemoProps;

package/package.json

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

package/readMe.md

@@ -76,87 +76,76 @@ return <>
 </>
 ```
 
-### `createExtractor()`
-Creates a context for components that may need to be out of their parent in certain conditions.
-If you have this component
-```tsx
-const myCustomExtractor = createExtractor();
-
-function MyCustomComponent() {
-  return <>
-    1
-    <myCustomExtractor.Source>
-      2 {/* THIS WILL BE MOVED INSIDE THE "Dest" */}
-    </myCustomExtractor.Source>
-    3
-  </>
-}
-```
-If you use it normally it will output `4`, ***`1`***, ***`2`***, ***`3`***, `5`
+### `Extractor`
+Friendlier version of the `Portal`.
+Example:
 ```tsx
+const e = new Extractor();
 return <>
-  4
-  <MyCustomComponent />
-  5
-</>
-```
-But if you use it together with a `Dest` and a `Joint` it will output `6`, `7`, `8`, ***`2`***, `9`, `10`, `11`, ***`1`***, ***`3`***, `12`, `13`, `14`
-```tsx
-return <>
-  6
-  <myCustomExtractor.Joint>
-    7
-    <div>
-      8
-      <myCustomExtractor.Dest /> {/* THE CONTENT OF "Source" WILL BE MOVED HERE */}
-      9
+  <e.Joint>
+    <div id="something">
+      <e.Dest />
     </div>
-    10
-    <div>
-      11
-      <MyCustomComponent />
-      12
+    <div id="something-else">
+      <e.Source>
+        This text will be shown instead of `e.Dest`
+      </e.Source>
     </div>
-    13
-  </myCustomExtractor.Joint>
-  14
-</>
-```
-The `Joint` component is necessary for the `Source` and the `Dest` to communicate with each other.
-For example this will output `15`, `16`, `17`, `18`, `19`, ***`1`***, ***`2`***, ***`3`***, `20`, `21`
-```tsx
-return <>
-  15
-  <div>
-    16
-    <myCustomExtractor.Dest />
-    17
-  </div>
-  18
-  <div>
-    19
-    <MyCustomComponent />
-    20
-  </div>
-  21
+  </e.Joint>
 </>
 ```
-Notice that you can use a `Source` component without adding it to the DOM:
-```tsx
-<myCustomExtractor.Source>
-  {/* This doesn't get returned, but still gets shown if there is an available "Dest" */}
-  Something
-</myCustomExtractor.Source>
-return <>Something else</>
-```
-When something gets moved from a `Source` to a `Dest`, it will inherit contexts from its destination, UNLESS you use the `sameContext` attribute
+Both `Extractor.Source` and `Extractor.Dest` will throw if they're not inside a `Extractor.Joint`.
+<br />
+Componets from different `Extractor`s don't "talk" to each other and there can be more than one source and destinations:
 ```tsx
+const a = new Extractor(), b = new Extractor(), c = new Extractor()
+
+function ProofThatItWorksCrossComponent() {
+  return <>
+    0
+    {/* Sources will be sorted by the "order" attribute before being rendered inside a destination */}
+    {/* The value defaults to 0 and doesn't need to be an integer */}
+    <a.Source order={-1.1}>
+      1
+    </a.Source>
+    2
+  </>
+}
+
 return <>
-  <myCustomExtractor.Source sameContext>
-    ...
-  </myCustomExtractor.Source>
+  <a.Joint>
+    <a.Dest />
+    <b.Joint>
+      {/* No source */}
+      <b.Dest />
+      <c.Joint>
+        3
+        {/* Double destination */}
+        <a.Dest />
+        4
+        <a.Source>
+          5
+        </a.Source>
+        <c.Source>
+          {/* No destination */}
+          6
+        </c.Source>
+        <ProofThatItWorksCrossComponent />
+        <c.Joint>
+          {/* Inner scope for the "c" extractor */}
+          <c.Dest />
+          7
+          <c.Source>
+            8
+          </c.Source>
+          <c.Dest />
+        </c.Joint>
+      </c.Joint>
+    </b.Joint>
+  </a.Joint>
 </>
 ```
+The output of this code is ***1***, ***5***, 3, ***1***, ***5***, 4, 0, 2, ***8***, 7, ***8***
 
 ## Utility