@liquefy/cascade.ui 1.0.0

package/src/Overlay.js

@@ -0,0 +1,85 @@
+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();
+    }
+  }
+}

package/src/OverlayFrame.js

@@ -0,0 +1,137 @@
+import { Component, flush, frozen } from "@liquefy/cascade.component";
+import { div } from "@liquefy/cascade.dom";
+
+/**
+ * OverlayFrame - ported from flow.ui/basic/src/overlay.js's own
+ * OverlayFrame/Overlay pair, adapted to cascade's direct-render model
+ * (no separate build-then-mount pass, so no `ensure()`/creators-stack
+ * dance is needed to keep a modal's content correctly parented - see
+ * the comment on `overlayContent.overlayFrame` below for the one place
+ * that actually mattered and turned out to already be free here).
+ *
+ * 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.
+ *
+ * A frame's own real children are its static content plus, when
+ * something is currently showing a modal on it, exactly one nested
+ * `modalSubFrame` - itself just another OverlayFrame, absolutely
+ * positioned to cover this frame's own area (`pointerEvents: none` so it
+ * 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.
+ */
+export function overlayFrame(...parameters) {
+  return new OverlayFrame(...parameters);
+}
+
+export class OverlayFrame extends Component {
+  setProperties({ style, children, overlayContent }) {
+    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;
+  }
+
+  // What some Overlay has currently assigned to this frame is *state* (see
+  // cascade.component/README.md): established as nothing, then changed
+  // only through showOverlay()/hideOverlay() below - and, crucially, never
+  // reset by a rebuild, even though this frame is reconstructed (and
+  // reconciled by key) every time whoever builds it reruns. Declaring it
+  // here is also what positions it at the baseline (time 0, writer null),
+  // 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 };
+  }
+
+  initialUnobservables() {
+    return { assigningContentProvider: null };
+  }
+
+  // Called by an Overlay component (via inherit("overlayFrame")) when it
+  // becomes visible - see Overlay.render(). `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.
+  //
+  // Called from inside an Overlay's own render() - 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
+  // later-positioned write can never overtake an earlier-positioned
+  // reader, by construction (see cascade.reactive's own
+  // migrateOvertakenObserversFor) - this is exactly the motivating case
+  // flush()/accessInitialValues() were built for (a modal whose frame
+  // already rendered needing new content added back into it, in the same
+  // 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
+  // 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) {
+    this.unobservable.assigningContentProvider = contentProvider;
+    flush(() => this.setState({ assignedOverlayContent: overlayContent }));
+  }
+
+  hideOverlay(contentProvider) {
+    if (this.unobservable.assigningContentProvider === contentProvider) {
+      flush(() => this.setState({ assignedOverlayContent: 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]);
+  }
+
+  build() {
+    if (this.assignedOverlayContent && this.receivedOverlayContent) {
+      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 children = [...this.staticContent];
+
+    if (overlayContent) {
+      children.push(new OverlayFrame(overlayContent, {
+        key: "modalSubFrame",
+        style: {
+          position: "absolute", top: 0, left: 0, width: "100%", height: "100%",
+          pointerEvents: "none",
+        },
+      }));
+    }
+
+    // A stable key - this frame's own real element (and everything
+    // reconciled underneath it) must survive across rebuilds triggered
+    // by a modal opening/closing, not be torn down and recreated every
+    // single time (see the constructor's own docs on why a key is what
+    // makes build()-composed reconciliation possible at all).
+    return div({ class: "overlay-frame", key: "frame", style: { position: "relative", ...this.style }, children });
+  }
+}

package/src/Popover.js

@@ -0,0 +1,158 @@
+import { Component, frozen, callback } from "@liquefy/cascade.component";
+import { div } from "@liquefy/cascade.dom";
+import { overlay } from "./Overlay.js";
+import { zStack, wrapper, fitContainerStyle, zStackElementStyle } from "./Layout.js";
+
+/**
+ * Popover - ported from flow.ui/basic/src/popover.js: content shown next to
+ * something on the page (an information button, say), over everything
+ * else, closed by clicking anywhere outside it.
+ *
+ *  - anchor: what it points to - an element (typically what was clicked:
+ *    `event.currentTarget`), or a rectangle in viewport coordinates. An
+ *    element it follows: while it's shown, a resize of the window, or a
+ *    scroll, places it again, where the element now is - watched in the
+ *    frames after, for as long as it keeps moving, so whatever lays out
+ *    again on the same resize has done so, however late (a toolbar moving
+ *    the button it was opened from, say). A rectangle stays put.
+ *  - showing, close: whether it's shown, and what a click outside it calls.
+ *  - style, children: the popover's own content (usually a card or an
+ *    alert), and extra style for the box it's placed in.
+ *
+ * Flow measured the popover's own size to place it; here it's placed by
+ * which quarter of the window its anchor is in instead - below the anchor
+ * when that's in the upper half, above it otherwise, and aligned to the
+ * anchor's left or right edge, whichever is further from the window's
+ * edge - so it never needs measuring, and so never needs a second pass.
+ * Shown through overlay() - the nearest OverlayFrame shows it.
+ */
+export function popover(...parameters) {
+  return new Popover(...parameters);
+}
+
+const GAP = 6;
+
+export class Popover extends Component {
+  setProperties({ anchor, showing, close, style, children }) {
+    this.anchor = frozen(anchor || null);
+    this.showing = !!showing;
+    this.close = close || null;
+    this.style = frozen(style || null);
+    this.popoverChildren = frozen(children || []);
+  }
+
+  // `moved`: counts the frames after a resize or a scroll, while it's
+  // shown and anchored to an element - so it's built, and placed, again
+  // (see follow()).
+  initializeState() {
+    return { moved: 0 };
+  }
+
+  initialUnobservables() {
+    return { following: null };
+  }
+
+  // Where the anchor is now - or, for an element no longer in the page (a
+  // theme switch replacing the button, say), where it last was.
+  anchorRect() {
+    const anchor = this.anchor;
+    if (!anchor) return { left: 0, top: 0, right: 0, bottom: 0 };
+    if (typeof(anchor.getBoundingClientRect) !== "function") return anchor;
+    const u = this.unobservable;
+    if (anchor.isConnected || !u.lastAnchorRect) u.lastAnchorRect = anchor.getBoundingClientRect();
+    return u.lastAnchorRect;
+  }
+
+  // Following an element: while shown, on a resize or a scroll, place again
+  // - in the frames after, whenever the element has moved.
+  follow() {
+    const u = this.unobservable;
+    if (u.following) return;
+    const view = document.defaultView;
+    const later = view.requestAnimationFrame ? (action) => view.requestAnimationFrame(action) : (action) => setTimeout(action, 0);
+    // Watched frame by frame, until it has held still for a few: what moves
+    // it may lay out again later than the next frame - a bounds provider's
+    // ResizeObserver, say, which runs after animation frames.
+    const sameRect = (a, b) => a && b && a.left === b.left && a.top === b.top && a.right === b.right && a.bottom === b.bottom;
+    let watching = false;
+    let stillFrames = 0;
+    const watch = () => {
+      if (!u.following) { watching = false; return; }
+      const anchor = this.anchor;
+      const rect = anchor && anchor.isConnected && typeof(anchor.getBoundingClientRect) === "function" ? anchor.getBoundingClientRect() : null;
+      // Placed again if the element has moved - or the window has changed
+      // size: a placement from its right or bottom edge moves along with it.
+      const viewportChanged = u.placedViewport !== view.innerWidth + "x" + view.innerHeight;
+      if ((rect && !sameRect(rect, u.lastAnchorRect)) || viewportChanged) {
+        stillFrames = 0;
+        this.moved = this.moved + 1;
+      } else stillFrames++;
+      if (stillFrames < 3) later(watch);
+      else watching = false;
+    };
+    const moved = () => {
+      stillFrames = 0;
+      if (watching) return;
+      watching = true;
+      later(watch);
+    };
+    view.addEventListener("resize", moved);
+    document.addEventListener("scroll", moved, true);
+    u.following = () => {
+      view.removeEventListener("resize", moved);
+      document.removeEventListener("scroll", moved, true);
+    };
+  }
+
+  unfollow() {
+    const u = this.unobservable;
+    if (!u.following) return;
+    u.following();
+    u.following = null;
+  }
+
+  onHide() {
+    this.unfollow();
+  }
+
+  onDispose() {
+    super.onDispose();
+    this.unfollow();
+  }
+
+  placement() {
+    const anchor = this.anchorRect();
+    const view = document.defaultView;
+    const width = view ? view.innerWidth : 1024;
+    const height = view ? view.innerHeight : 768;
+    this.unobservable.placedViewport = width + "x" + height;
+    const placement = {};
+    if ((anchor.top + anchor.bottom) / 2 < height / 2) placement.top = anchor.bottom + GAP + "px";
+    else placement.bottom = height - anchor.top + GAP + "px";
+    if ((anchor.left + anchor.right) / 2 < width / 2) placement.left = anchor.left + "px";
+    else placement.right = width - anchor.right + "px";
+    return placement;
+  }
+
+  build() {
+    this.moved; // Placed again when its anchor element has moved - see follow().
+    const followsElement = this.anchor !== null && typeof(this.anchor.getBoundingClientRect) === "function";
+    if (this.showing && followsElement) this.follow();
+    else this.unfollow();
+    return overlay(
+      { key: "overlay", showing: this.showing },
+      zStack(
+        { key: "layer", style: { ...fitContainerStyle, pointerEvents: "none" } },
+        div({
+          key: "outside",
+          onmousedown: callback("outside", () => this.close && this.close()),
+          style: { ...zStackElementStyle, pointerEvents: "auto" },
+        }),
+        wrapper(
+          { key: "content", style: { position: "fixed", pointerEvents: "auto", maxWidth: "min(800px, 90vw)", ...this.placement(), ...this.style } },
+          this.popoverChildren,
+        ),
+      ),
+    );
+  }
+}

package/src/Portal.js

@@ -0,0 +1,132 @@
+import { Component, flush, withoutRecording, frozen } from "@liquefy/cascade.component";
+import { wrapper } from "./Layout.js";
+
+/**
+ * Portals - ported from flow.ui/basic/src/Portals.js: a place in the tree
+ * (portal()) whose content is supplied from somewhere else entirely
+ * (portalContents()) - a page putting its own buttons in the app's top
+ * bar, say, which the page knows nothing else about.
+ *
+ *  - portal({ style, children }): a div, showing whatever is currently
+ *    assigned to it - or its own children (a default) when nothing is, or
+ *    nothing but an empty list (an empty cart).
+ *  - portalContents({ portal, children }): builds nothing where it
+ *    stands; while it's shown, its children are shown in `portal` - a
+ *    portal, or the name of one to inherit() ("topBarPortal"), found when
+ *    it builds, so it can be created before it has a place in the tree
+ *    instead, and once it isn't (it's hidden, or its page is switched
+ *    away from), they're taken back out - see Component.onShow()/onHide().
+ *    The last one shown wins.
+ *
+ * The same mechanism as OverlayFrame/Overlay (see OverlayFrame.js - an
+ * overlay frame is a portal with a modal layer): the contents are
+ * typically rendered *after* the portal (a page's work area comes after
+ * the top bar), so assigning them is a write backwards in the pipeline -
+ * setState() puts it at the baseline, where the portal's build reads it,
+ * and flush() gets it rebuilt in the same wave, so the portal fills in the
+ * same frame, not the next.
+ *
+ * Who holds the portal: something that creates it itself and owns it (not
+ * one built in some build() and also referenced - see
+ * cascade.component/README.md), typically providing it for inherit() too,
+ * so that whatever is rendered below can find it without being handed it.
+ */
+export function portal(...parameters) {
+  return new Portal(...parameters);
+}
+
+export function portalContents(...parameters) {
+  return new PortalContents(...parameters);
+}
+
+export class Portal extends Component {
+  setProperties({ style, children }) {
+    this.style = frozen(style || null);
+    this.defaultContents = frozen(children || []);
+  }
+
+  // What some PortalContents has assigned is state: changed only by
+  // show()/hide(), never reset by a rebuild.
+  initializeState() {
+    return { contents: null };
+  }
+
+  initialUnobservables() {
+    return { assignedBy: null };
+  }
+
+  // Called from a PortalContents render: what is shown now is read
+  // without recording, so that render never depends on it - two contents
+  // taking turns would otherwise keep rerunning each other.
+  show(contentsProvider, contents) {
+    this.unobservable.assignedBy = contentsProvider;
+    const current = withoutRecording(() => this.contents);
+    if (current !== contents) flush(() => this.setState({ contents }));
+  }
+
+  // Only the PortalContents that assigned what's shown can take it back -
+  // one that has since been taken over by another doesn't clear its
+  // successor's.
+  hide(contentsProvider) {
+    const u = this.unobservable;
+    if (u.assignedBy !== contentsProvider) return;
+    u.assignedBy = null;
+    flush(() => this.setState({ contents: null }));
+  }
+
+  build() {
+    const assigned = this.contents && this.contents.length > 0;
+    return wrapper({ key: "portal", style: this.style || {} }, assigned ? this.contents : this.defaultContents);
+  }
+}
+
+export class PortalContents extends Component {
+  setProperties({ portal, children }) {
+    this.portal = portal || null;
+    this.portalChildren = frozen(children || []);
+  }
+
+  initialUnobservables() {
+    return { shownIn: null };
+  }
+
+  // Build-only - so it's also placed like any other component by one that
+  // places its subtree itself (cascade.DOM's FlipAnimationContainer), where
+  // it expands to nothing. A build only runs while something is showing
+  // this component (rendering or expanding it pulls it), so building is
+  // where the contents are assigned - again whenever they change.
+  build() {
+    this.assign();
+    return null;
+  }
+
+  // Shown again (see Component.onShow()): an up-to-date build doesn't
+  // rerun, so assign the contents here. Read without recording - this runs
+  // inside whoever is rendering.
+  onShow() {
+    withoutRecording(() => this.assign());
+  }
+
+  // No longer shown (hidden, its page switched away from, dropped): take
+  // the contents back.
+  onHide() {
+    const u = this.unobservable;
+    if (u.shownIn) {
+      u.shownIn.hide(this);
+      u.shownIn = null;
+    }
+  }
+
+  assign() {
+    const u = this.unobservable;
+    const portal = typeof(this.portal) === "string" ? this.inherit(this.portal) : this.portal;
+    if (u.shownIn && u.shownIn !== portal) {
+      u.shownIn.hide(this);
+      u.shownIn = null;
+    }
+    if (portal) {
+      portal.show(this, this.portalChildren);
+      u.shownIn = portal;
+    }
+  }
+}