@jsenv/navi 0.29.52 → 0.29.53

package/dist/jsenv_navi_side_effects.js

@@ -194,6 +194,120 @@ const smallTouchScreenSignal = computed(() => {
   return false;
 });
 
+/**
+ * The part of the window an app actually has, in two levels.
+ *
+ * Two, and not one, for a reason worth stating up front: a fixed bar is one of
+ * the things that reduce the free region, so it cannot ALSO be placed against
+ * that region — it would push itself off the edge it is pinned to. What is
+ * anchored and what is anchored-inside are two different rectangles.
+ *
+ * 1. `--navi-app-inset-{top,right,bottom,left}` — from the window's edges to
+ *    the app's own rectangle. Whatever is pinned to an edge (a fixed bar, a
+ *    side panel, a popup aimed at a corner) is pinned to THAT, so an app
+ *    pretending to be a 600px handheld inside a 1500px window stays one
+ *    rectangle instead of a column with its furniture spread across the glass.
+ *
+ * 2. `--navi-safe-area-inset-{top,right,bottom,left}` — from the window's edges
+ *    to the band left free INSIDE that rectangle. Whatever flows, scrolls, or
+ *    gets painted keeps to it.
+ *
+ * Level 2 is a sum, and the contract for taking part in it is only "publish
+ * what you take on one edge": the device's own notch (`env(safe-area-inset-*)`,
+ * which is the browser's version of this very idea), the fixed bars
+ * (fixed_bar_space.js), and anything an app adds. That is the point of naming
+ * it at all — a component that must stay clear of what covers the screen reads
+ * ONE set of numbers, and never has to learn what is covering it.
+ *
+ * `max()` between the notch and the bars rather than a sum: a bar pinned to an
+ * edge already reaches under the notch and counts it in its own size (see
+ * fixed_bar.jsx), so adding both would reserve it twice.
+ *
+ * Sizes only, not placement, for the time being — see "Current limitations" in
+ * docs/css_architecture.md.
+ */
+
+const SAFE_AREA_CSS = /* css */ `
+  @layer navi {
+    :root {
+      /* The room each kind of furniture takes, declared here at zero and
+         written by whoever takes it. A slot rather than a value: the sum below
+         has to be readable whether or not the app ever mounts a fixed bar. */
+      --navi-fixed-bar-space-top: 0px;
+      --navi-fixed-bar-space-right: 0px;
+      --navi-fixed-bar-space-bottom: 0px;
+      --navi-fixed-bar-space-left: 0px;
+
+      /* Level 1. Centered bands, so that declaring one ceiling
+         (--navi-app-max-width) is all an app has to do to be a narrow screen in
+         a wide window; an app that wants them uneven writes these directly. */
+      --navi-app-inset-top: max(
+        0px,
+        (var(--navi-vvh) - var(--navi-app-max-height, var(--navi-vvh))) / 2
+      );
+      --navi-app-inset-bottom: var(--navi-app-inset-top);
+      --navi-app-inset-left: max(
+        0px,
+        (var(--navi-vvw) - var(--navi-app-max-width, var(--navi-vvw))) / 2
+      );
+      --navi-app-inset-right: var(--navi-app-inset-left);
+
+      /* Level 2. */
+      --navi-safe-area-inset-top: calc(
+        var(--navi-app-inset-top) +
+          max(env(safe-area-inset-top), var(--navi-fixed-bar-space-top))
+      );
+      --navi-safe-area-inset-right: calc(
+        var(--navi-app-inset-right) +
+          max(env(safe-area-inset-right), var(--navi-fixed-bar-space-right))
+      );
+      --navi-safe-area-inset-bottom: calc(
+        var(--navi-app-inset-bottom) +
+          max(env(safe-area-inset-bottom), var(--navi-fixed-bar-space-bottom))
+      );
+      --navi-safe-area-inset-left: calc(
+        var(--navi-app-inset-left) +
+          max(env(safe-area-inset-left), var(--navi-fixed-bar-space-left))
+      );
+
+      /* The document is the scrollport in the common case, and something the
+         browser scrolls to — an anchor, a focused field, a restored position —
+         landing under a bar is never what anyone wants. */
+      scroll-padding-top: var(--navi-safe-area-inset-top);
+      scroll-padding-right: var(--navi-safe-area-inset-right);
+      scroll-padding-bottom: var(--navi-safe-area-inset-bottom);
+      scroll-padding-left: var(--navi-safe-area-inset-left);
+    }
+
+    /* Put this on whatever scrolls under the furniture.
+
+       There are TWO rooms to give back, and forgetting the second one is the
+       classic bug:
+
+       - padding, so the end of the content can be scrolled out from under it.
+         Without it the last screenful stays covered, unreachable.
+       - scroll-padding, so anything the browser scrolls TO lands in front of it
+         rather than under. The padding above does not help here: it moves the
+         content, not the place the browser scrolls the target to.
+
+       Marked by the app rather than picked by navi: which element scrolls is
+       the app's business, and an app with more than one would have to fight a
+       component that chose for it. An app is free to read the variables itself
+       instead. */
+    [data-navi-safe-area] {
+      padding-top: var(--navi-safe-area-inset-top);
+      padding-right: var(--navi-safe-area-inset-right);
+      padding-bottom: var(--navi-safe-area-inset-bottom);
+      padding-left: var(--navi-safe-area-inset-left);
+
+      scroll-padding-top: var(--navi-safe-area-inset-top);
+      scroll-padding-right: var(--navi-safe-area-inset-right);
+      scroll-padding-bottom: var(--navi-safe-area-inset-bottom);
+      scroll-padding-left: var(--navi-safe-area-inset-left);
+    }
+  }
+`;
+
 installImportMetaCssBuild(import.meta);/**
  * Regroup CSS vars that makes sense to share across all navi components.
  */
@@ -214,8 +328,9 @@ const css = /* css */`
 
       /* What navi treats as "the screen" when it sizes something that escapes
          normal flow (a dialog in the top layer, a popover, anything built on
-         them). The visual viewport by default — but an app that never spans
-         the whole window says so here, ONCE, without ever naming a component:
+         them): the app's own rectangle, which is the visual viewport minus the
+         bands an app asks for. An app that never spans the whole window says so
+         ONCE, without ever naming a component:
 
            :root {
              --navi-app-max-width: 600px;
@@ -235,17 +350,19 @@ const css = /* css */`
          from it as before. A single popup that genuinely needs more can still
          raise its own maxWidth/maxHeight prop.
 
-         Sizes only, not placement: what is anchored to an edge (a SidePanel, a
-         fixed bar, a "bottom-start" positionArea) still sits against the
-         window's edge, not the app column's. See "Current limitations" in
-         docs/css_architecture.md. */
-      --navi-app-width: min(
-        var(--navi-vvw),
-        var(--navi-app-max-width, var(--navi-vvw))
+         Read from the insets rather than as a min() of its own so that the
+         width and the placement come from ONE description of where the app is
+         (see layout/safe_area.js). Placement does not follow yet everywhere —
+         see "Current limitations" in docs/css_architecture.md. */
+      --navi-app-width: calc(
+        var(--navi-vvw) - var(--navi-app-inset-left) - var(
+            --navi-app-inset-right
+          )
       );
-      --navi-app-height: min(
-        var(--navi-vvh),
-        var(--navi-app-max-height, var(--navi-vvh))
+      --navi-app-height: calc(
+        var(--navi-vvh) - var(--navi-app-inset-top) - var(
+            --navi-app-inset-bottom
+          )
       );
 
       --navi-focus-outline-width: 2px;
@@ -385,6 +502,8 @@ const css = /* css */`
     }
   }
 
+  ${SAFE_AREA_CSS}
+
   /* Hidden appearance */
   input[navi-visually-hidden],
   button[navi-visually-hidden],