@liquefy/cascade.ui 1.0.0 → 2.0.0

package/src/Overlay.js

@@ -1,85 +1,95 @@
-import { Component, withoutRecording } from "@liquefy/cascade.component";
-
-/**
- * Overlay - the other half of overlay.js's port (see OverlayFrame.js).
- * Builds nothing at its own position; its whole job is to hand its
- * single child to the nearest enclosing OverlayFrame (found via
- * `this.inherit("overlayFrame")`) whenever `this.showing` is true, and
- * take it back whenever it's false (or this component stops being shown
- * altogether - see onHide()).
- *
- * Deliberately named `showing`, not flow's own `isVisible` - flow's
- * `isVisible` is a much more general, base-Component concept (computed
- * from the render tree itself - whether a component is actually being
- * rendered at all at its own position right now, propagated down from
- * the root via renderParent - see flow.core's own reactiveRender()) that
- * cascade's direct-render model has no equivalent for yet. `showing` here
- * is Overlay's own, narrower concept: set this to true/false directly
- * (or via the properties bag - `overlay(content, {showing: true})`) to
- * control it, not flow's generic `.show(value)` helper (which just
- * conditionally includes a component in a build() result at all -
- * ported separately, unchanged, onto Component itself).
- */
-export function overlay(...parameters) {
-  return new Overlay(...parameters);
-}
-
-export class Overlay extends Component {
-  setProperties({ children, showing }) {
-    if (children && children.length > 1) {
-      throw new Error("Overlay accepts at most a single child.");
-    }
-    this.overlayChild = children && children.length > 0 ? children[0] : null;
-    this.showing = !!showing;
-  }
-
-  initialUnobservables() {
-    return { visibleOnFrame: null, shownChild: null };
-  }
-
-  // Build-only (like PortalContents - see Portal.js): a build only runs
-  // while something is showing this component, so building is where the
-  // content is handed to the frame - again whenever showing changes.
-  // Builds nothing where it stands.
-  build() {
-    this.update();
-    return null;
-  }
-
-  // Shown again (see Component.onShow()): an up-to-date build doesn't
-  // rerun, so hand the content over here. Read without recording - this
-  // runs inside whoever is rendering.
-  onShow() {
-    withoutRecording(() => this.update());
-  }
-
-  // No longer shown - its page switched away from, say: take the content
-  // back, whatever `showing` says.
-  onHide() {
-    const u = this.unobservable;
-    if (u.visibleOnFrame) {
-      u.visibleOnFrame.hideOverlay(this);
-      u.visibleOnFrame = null;
-    }
-  }
-
-  update() {
-    const u = this.unobservable;
-    if (this.showing) {
-      const overlayFrame = this.inherit("overlayFrame");
-      if (overlayFrame && u.visibleOnFrame !== overlayFrame) {
-        if (u.visibleOnFrame) u.visibleOnFrame.hideOverlay(this);
-        u.visibleOnFrame = overlayFrame;
-        u.shownChild = this.overlayChild;
-        overlayFrame.showOverlay(this, this.overlayChild);
-      } else if (overlayFrame && u.shownChild !== this.overlayChild) {
-        // Shown already, with other content: a modal window becoming full
-        // screen, say - hand the frame the new content.
-        u.shownChild = this.overlayChild;
-        overlayFrame.showOverlay(this, this.overlayChild);
-      }
-    } else {
-      this.onHide();
-    }
-  }
-}
+import { Component, withoutRecording } from "@liquefy/cascade.component";
+
+/**
+ * Overlay - the other half of overlay.js's port (see OverlayFrame.js).
+ * Builds nothing at its own position; its whole job is to hand its
+ * single child to the nearest enclosing OverlayFrame (found via
+ * `this.inherit("overlayFrame")`) whenever `this.showing` is true, and
+ * take it back whenever it's false (or this component stops being shown
+ * altogether - see onHide()).
+ *
+ * Deliberately named `showing`, not flow's own `isVisible`: whether a
+ * component is shown at all is cascade's onShow()/onHide() (see
+ * Component), which Overlay uses itself - an Overlay that stops being
+ * shown takes its content back. `showing` is Overlay's own, narrower
+ * concept: set it to true/false directly (or via the properties bag -
+ * `overlay(content, {showing: true})`) to control it, not the generic
+ * `.showIf(value)` helper (which just conditionally includes a component
+ * in a build() result at all).
+ *
+ * One overlay per frame: shown on a frame already showing another
+ * Overlay's content, this one evicts it (see OverlayFrame's class doc).
+ */
+export function overlay(...parameters) {
+  return new Overlay(...parameters);
+}
+
+export class Overlay extends Component {
+  setProperties({ children, showing }) {
+    if (children && children.length > 1) {
+      throw new Error("Overlay accepts at most a single child.");
+    }
+    this.overlayChild = children && children.length > 0 ? children[0] : null;
+    this.showing = !!showing;
+  }
+
+  initialUnobservables() {
+    return { visibleOnFrame: null, shownChild: null, shownContext: null };
+  }
+
+  // Build-only (like PortalSource - see cascade.dom's Portal.js): a build only runs
+  // while something is showing this component, so building is where the
+  // content is handed to the frame - again whenever showing changes.
+  // Builds nothing where it stands.
+  build() {
+    this.update();
+    return null;
+  }
+
+  // Shown again (see Component.onShow()): an up-to-date build doesn't
+  // rerun, so hand the content over here. Read without recording - this
+  // runs inside whoever is rendering.
+  onShow() {
+    withoutRecording(() => this.update());
+  }
+
+  // No longer shown - its page switched away from, say: take the content
+  // back, whatever `showing` says.
+  onHide() {
+    const u = this.unobservable;
+    if (u.visibleOnFrame) {
+      u.visibleOnFrame.hideOverlay(this);
+      u.visibleOnFrame = null;
+    }
+  }
+
+  update() {
+    const u = this.unobservable;
+    if (this.showing) {
+      const overlayFrame = this.inherit("overlayFrame");
+      if (!overlayFrame && !u.warnedMissing) {
+        u.warnedMissing = true;
+        console.warn("overlay(): no overlayFrame() around it - what it shows isn't shown.");
+      }
+      // What its content is shown with: the context this Overlay passes on
+      // - so a dialog inherits from where it's opened (see OverlayFrame).
+      const context = u.childContext;
+      if (overlayFrame && u.visibleOnFrame !== overlayFrame) {
+        if (u.visibleOnFrame) u.visibleOnFrame.hideOverlay(this);
+        u.visibleOnFrame = overlayFrame;
+        u.shownChild = this.overlayChild;
+        u.shownContext = context;
+        overlayFrame.showOverlay(this, this.overlayChild, context);
+      } else if (overlayFrame && (u.shownChild !== this.overlayChild || u.shownContext !== context)) {
+        // Shown already, with other content: a modal window becoming full
+        // screen, say - hand the frame the new content. Or placed
+        // elsewhere: the content follows.
+        u.shownChild = this.overlayChild;
+        u.shownContext = context;
+        overlayFrame.showOverlay(this, this.overlayChild, context);
+      }
+    } else {
+      this.onHide();
+    }
+  }
+}

package/src/OverlayFrame.js

@@ -1,5 +1,5 @@
-import { Component, flush, frozen } from "@liquefy/cascade.component";
-import { div } from "@liquefy/cascade.dom";
+import { Component, flush, frozen, withoutRecording } from "@liquefy/cascade.component";
+import { div, elementBoundsProvider } from "@liquefy/cascade.dom";
 
 /**
  * OverlayFrame - ported from flow.ui/basic/src/overlay.js's own
@@ -12,13 +12,19 @@ import { div } from "@liquefy/cascade.dom";
  * Any component nested arbitrarily deep underneath an OverlayFrame -
  * through any mix of build() and hardcoded child references - can find
  * *this* one specifically via `this.inherit("overlayFrame")` (see
- * Component.inherit()): every OverlayFrame provides itself
- * (`this.overlayFrame = this`), so the walk always resolves to the
- * *nearest* one, never skipping past it to an outer frame. That's what
- * makes recursive modality work: a dialog opened from inside another
- * modal's own content finds *that* modal's own frame, not the page's
- * top-level one, so a third modal opened from inside it stacks correctly
- * on top of the second, not the first.
+ * Component.inherit()): every OverlayFrame provides itself as
+ * `overlayFrame`, so a lookup always finds the *nearest* one, never
+ * skipping past it to an outer frame. That's what makes recursive modality
+ * work: a dialog opened from inside another modal's own content finds
+ * *that* modal's own frame, not the page's top-level one, so a third modal
+ * opened from inside it stacks correctly on top of the second, not the
+ * first.
+ *
+ * The content an Overlay shows keeps the context of where the Overlay
+ * stands - so a dialog inherits what its page provides - with the frame it
+ * is shown in on top: the sub-frame showing it enters the tree with the
+ * Overlay's context (see Component.enteredContext()), and provides itself
+ * as `overlayFrame` on top of that.
  *
  * A frame's own real children are its static content plus, when
  * something is currently showing a modal on it, exactly one nested
@@ -27,22 +33,44 @@ import { div } from "@liquefy/cascade.dom";
  * doesn't block clicks through the parts of itself nothing is actually
  * using) - which is what lets an Overlay shown *inside* that sub-frame's
  * own content recurse the exact same way, arbitrarily deep.
+ *
+ * One overlay per frame: a frame shows the content of the Overlay that
+ * showed it last. An Overlay shown on a frame already showing another's
+ * content evicts it - the other keeps its `showing`, but isn't shown again
+ * until it's shown anew - and hiding the newer one leaves the frame empty,
+ * not the evicted one back. Overlays stack across frames (one opened from
+ * inside another's content, above), not side by side on one. This is by
+ * design, not an oversight - and may change only should a use case turn up
+ * that needs several overlays on one frame.
  */
 export function overlayFrame(...parameters) {
   return new OverlayFrame(...parameters);
 }
 
 export class OverlayFrame extends Component {
-  setProperties({ style, children, overlayContent }) {
+  setProperties({ style, children, overlayContent, originContext, isLayer }) {
     this.style = frozen(style || null);
     this.staticContent = frozen(children || []);
     // The alternative to showOverlay()/hideOverlay() below: an overlay
     // frame can be handed its modal content directly as a property
     // instead, for a frame that's dedicated to one specific modal rather
     // than a general, shared one any Overlay can find via inherit().
-    this.receivedOverlayContent = overlayContent || null;
-    // Provides itself for inherit("overlayFrame") - see Component.provide().
-    this.overlayFrame = this;
+    this.propertyContent = overlayContent || null;
+    // A sub-frame showing an Overlay's content: the context of where that
+    // Overlay stands - what the content inherits from (see build()).
+    this.originContext = originContext || null;
+    // One this frame opens itself, to show overlay content on (see build()).
+    this.isLayer = !!isLayer;
+  }
+
+  // Found by inherit("overlayFrame") from anywhere below - see
+  // Component.provide().
+  provide() {
+    return { overlayFrame: this };
+  }
+
+  enteredContext(given) {
+    return this.originContext || given;
   }
 
   // What some Overlay has currently assigned to this frame is *state* (see
@@ -54,8 +82,8 @@ export class OverlayFrame extends Component {
   // which is exactly where setState() in show/hideOverlay writes it back
   // to - the same writing, reused, not a fresh one spliced in ahead of a
   // reader that could never actually reach it (see their comment).
-  initializeState() {
-    return { assignedOverlayContent: null };
+  initialState() {
+    return { shownContent: null, shownContext: null };
   }
 
   initialUnobservables() {
@@ -63,16 +91,16 @@ export class OverlayFrame extends Component {
   }
 
   // Called by an Overlay component (via inherit("overlayFrame")) when it
-  // becomes visible - see Overlay.render(). `contentProvider` is the
+  // becomes visible - see Overlay.update(). `contentProvider` is the
   // Overlay itself, kept so a later hideOverlay() call from a *different*
   // Overlay (e.g. one that's since taken over) can't clear content it
-  // never actually assigned.
+  // never actually assigned - one overlay per frame (see the class doc).
   //
-  // Called from inside an Overlay's own render() - which is to say, from
+  // Called from inside an Overlay's own update - which is to say, from
   // *later* in this same pipeline than OverlayFrame's own build() (a
   // descendant calling back up to an ancestor). A plain write here could
   // never actually reach OverlayFrame's own already-registered dependency
-  // on `assignedOverlayContent`: "time as tree position" means a
+  // on `shownContent`: "time as tree position" means a
   // later-positioned write can never overtake an earlier-positioned
   // reader, by construction (see cascade.reactive's own
   // migrateOvertakenObserversFor) - this is exactly the motivating case
@@ -81,45 +109,55 @@ export class OverlayFrame extends Component {
   // frame, without flicker - see docs/plan-flagged-scheduling.md).
   // setState() (Component.js) makes the write land at the baseline
   // position (before everything), reusing the exact writing
-  // initializeState() above set up rather than splicing a new one in
+  // initialState() above set up rather than splicing a new one in
   // ahead of it that could never reach OverlayFrame's own reader either
   // way - it's also the only way a state property *may* be written from
   // inside a repeater at all - and flush() makes sure the resulting
   // rebuild happens within this same wave rather than waiting for the
   // next one.
-  showOverlay(contentProvider, overlayContent) {
+  //
+  // `context` is where the Overlay stands: the content is shown with it
+  // (see the class doc).
+  showOverlay(contentProvider, overlayContent, context) {
     this.unobservable.assigningContentProvider = contentProvider;
-    flush(() => this.setState({ assignedOverlayContent: overlayContent }));
-  }
-
-  hideOverlay(contentProvider) {
-    if (this.unobservable.assigningContentProvider === contentProvider) {
-      flush(() => this.setState({ assignedOverlayContent: null }));
+    const current = withoutRecording(() => [this.shownContent, this.shownContext]);
+    if (current[0] !== overlayContent || current[1] !== (context || null)) {
+      flush(() => this.setState({ shownContent: overlayContent, shownContext: context || null }));
     }
   }
 
-  // Replace this frame's own static content in place - used when the
-  // *same* modalSubFrame is reused for new overlay content (see build()
-  // below) rather than tearing the sub-frame down and recreating it,
-  // which would also retract and rebuild everything recursively nested
-  // inside it for no reason.
-  setStaticContent(staticContent) {
-    this.staticContent = frozen(staticContent instanceof Array ? staticContent : [staticContent]);
+  hideOverlay(contentProvider) {
+    const u = this.unobservable;
+    if (u.assigningContentProvider !== contentProvider) return;
+    u.assigningContentProvider = null;
+    flush(() => this.setState({ shownContent: null, shownContext: null }));
   }
 
   build() {
-    if (this.assignedOverlayContent && this.receivedOverlayContent) {
+    if (this.shownContent && this.propertyContent) {
       throw new Error("Cannot both assign overlay content via showOverlay() and set it as a property on the same overlay frame.");
     }
-    const overlayContent = this.assignedOverlayContent || this.receivedOverlayContent;
-
-    // const u = this.unobservable;
+    const overlayContent = this.shownContent || this.propertyContent;
 
-    const children = [...this.staticContent];
+    // A layer (a sub-frame showing what an overlay assigned - see below)
+    // shows its content on a measured element, covering the frame: what's
+    // shown there reads the frame's size with this.fromTarget() (see
+    // modalAssembly(), which goes full screen below a width).
+    const children = this.isLayer
+      ? this.staticContent.map((content) => elementBoundsProvider({
+        style: { position: "absolute", top: 0, left: 0, width: "100%", height: "100%", pointerEvents: "none" },
+        child: content,
+      }))
+      : [...this.staticContent];
 
     if (overlayContent) {
       children.push(new OverlayFrame(overlayContent, {
         key: "modalSubFrame",
+        isLayer: true,
+        // Content an Overlay assigned keeps the context of where it came
+        // from; content handed over as a property is this frame's creator's
+        // own, and is simply shown with this frame's.
+        originContext: this.shownContent ? this.shownContext : null,
         style: {
           position: "absolute", top: 0, left: 0, width: "100%", height: "100%",
           pointerEvents: "none",