feat(ui): a popover's align along its side, and within= for the bounds it flips against

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

LANGUAGE.md

@@ -495,8 +495,10 @@ applies to both:
     press outside it only closes it.
   - `anchor="cell"` puts a popover beside the element with that id (the nearest, looking out from
     the popover), and a bare `anchor` beside the element before it. `placement` is `right` (the
-    default), `left`, `bottom` or `top`, its margin on that side is the gap, and where it would
-    leave the screen it opens to the other side and is kept on it.
+    default), `left`, `bottom` or `top`, its margin on that side is the gap, and `align` is `start`
+    (the default), `center` or `end` along that side. Where it would leave its bounds it opens to
+    the other side and is kept inside them: `within="panel"` names the element, and by default it
+    is the nearest scroll box (or `overflow` box) around it, else the screen.
   - `title="..."` shows a tooltip (`.ui-tooltip`) after the pointer rests for half a second. A
     newline or a written `\n` in it starts another line (`.ui-tooltip-text` each).
   - `<progress value max>` and `<meter value min max>` fill (`.ui-fill`) as far as their value.

changes/defaults-views-templates.md

@@ -87,6 +87,8 @@ What a game's screens found missing, now in `ludic.ui`:
   `pointer-events: none` lets it through;
 - `on-down` and `on-up` on a button (the pointer, Enter or A), with `:active` true while it is held
   there rather than whenever the pointer is down over it;
+- an anchored popover's `align="start|center|end"`, and `within="id"` (by default the nearest
+  scroll box around it) for the bounds it is flipped against and kept inside;
 - a transition lands exactly on its end value (it had stopped a rounding error short of it, at every
   frame rate).
 

examples/library/ui_popover_align.ludic

@@ -0,0 +1,20 @@
+# ui_popover_align.ludic — anchored popovers aligned along their side (start, center, end), kept
+# within a named container (within="panel") and, by default, within the scroll box they are in,
+# flipping to the other side against it rather than against the screen.
+import "ludic.ui"
+import "ui_popover_align_parts/Menus.ludic"
+program UiPopoverAlign {
+  numbers float
+  function at(n: UiNode, base: UiNode) -> string { return `{int(n.x - base.x)},{int(n.y - base.y)}` }
+  entry {
+    ui_backend(new UiBackend)
+    ui_show("Menus", null, 0.0, 0.0, 400.0, 400.0)
+    let root: UiNode = ui_nodes("Menus", null)
+    ui_place(root, 0.0, 0.0, 400.0, 400.0)
+    let panel = root.children[0].children[0]
+    let list = root.children[0].children[1]
+    let b = list.children[1]
+    let p3 = list.children[2]
+    print(`centred, flipped in the panel {at(panel.children[1], panel)} | end below {at(panel.children[2], panel)} | above b in the list {int(p3.y + p3.ch - b.y)} inside {p3.y >= list.y}`)
+  }
+}

examples/library/ui_popover_align_parts/Menus.lss

@@ -0,0 +1,8 @@
+.page { width: 400px; height: 400px }
+.panel { width: 200px; height: 150px; position: relative }
+.a { position: absolute; left: 150px; top: 50px; width: 40px; height: 20px; padding: 0 }
+.p1 { width: 60px; height: 40px }
+.p2 { width: 80px; height: 30px }
+.list { overflow: auto; width: 150px; height: 100px }
+.gap { height: 60px }
+.p3 { width: 50px; height: 40px }

examples/library/ui_popover_align_parts/Menus.ludic

@@ -0,0 +1,3 @@
+# Menus.ludic - popovers anchored inside a panel and inside a scroll box, aligned along their side
+component Menus {
+}

examples/library/ui_popover_align_parts/Menus.xml

@@ -0,0 +1,12 @@
+<div class="page">
+  <div id="panel" class="panel">
+    <button id="a" class="a">a</button>
+    <div popover anchor="a" placement="right" align="center" within="panel" class="p1"></div>
+    <div popover anchor="a" placement="bottom" align="end" class="p2"></div>
+  </div>
+  <div class="list">
+    <p class="gap">x</p>
+    <button id="b">b</button>
+    <div popover anchor="b" placement="bottom" class="p3"></div>
+  </div>
+</div>

packages/ludic.ui/index.ludic

@@ -27,6 +27,7 @@ import "scroll.ludic"
 import "scroll_bar.ludic"
 import "popover.ludic"
 import "popover_anchor.ludic"
+import "popover_within.ludic"
 import "tooltip.ludic"
 import "life.ludic"
 import "tpl.ludic"

packages/ludic.ui/popover_anchor.ludic

@@ -1,7 +1,6 @@
-# popover_anchor.ludic - a popover beside what it belongs to: `<div popover anchor="cell">` sits beside
-# the element with that id (the nearest one, looking out from the popover), and a bare `anchor` beside
-# the element just before it. `placement` is right (the default), left, bottom or top; its margin on
-# that side is the gap. Where it would leave the screen it goes to the other side, and it is kept on it.
+# popover_anchor.ludic - `<div popover anchor="cell">` sits beside the element with that id (the
+# nearest), a bare `anchor` beside the one before it: `placement` right, left, bottom or top (its margin
+# is the gap), `align` start, center or end along that side, flipped and kept within its bounds.
 function pp_anchor_all(n: UiNode) -> void {
   if n.children == null { return }
   for i in 0 .. len(n.children) {
@@ -42,6 +41,8 @@ function pp_by_id(n: UiNode, id: string, skip: UiNode) -> UiNode {
 function pp_anchor(p: UiNode, a: UiNode) -> void {
   if a == null { return }
   let side = ui_attr_text(p, "placement")
+  let align = ui_attr_text(p, "align")
+  pp_bounds(p)
   let w = p.cw
   let h = p.ch
   var x = a.x
@@ -49,16 +50,16 @@ function pp_anchor(p: UiNode, a: UiNode) -> void {
   if side == "top" or side == "bottom" {
     let below = a.y + a.ch + p.mt
     let above = a.y - h - p.mb
-    y = pp_side(side == "top", above, below, h, ly_vp_y, ly_vp_h)
-    x = a.x + p.ml
+    y = pp_side(side == "top", above, below, h, pp_by, pp_bh)
+    x = pp_along(align, a.x, a.cw, w) + p.ml
   } else {
     let right = a.x + a.cw + p.ml
     let left = a.x - w - p.mr
-    x = pp_side(side == "left", left, right, w, ly_vp_x, ly_vp_w)
-    y = a.y + p.mt
+    x = pp_side(side == "left", left, right, w, pp_bx, pp_bw)
+    y = pp_along(align, a.y, a.ch, h) + p.mt
   }
-  x = Math.max(ly_vp_x, Math.min(x, ly_vp_x + ly_vp_w - w))
-  y = Math.max(ly_vp_y, Math.min(y, ly_vp_y + ly_vp_h - h))
+  x = Math.max(pp_bx, Math.min(x, pp_bx + pp_bw - w))
+  y = Math.max(pp_by, Math.min(y, pp_by + pp_bh - h))
   ly_place(p, x, y, w, h)
   sc_apply(p)
 }

packages/ludic.ui/popover_within.ludic

@@ -0,0 +1,39 @@
+# popover_within.ludic - what an anchored popover is kept inside: the element named by within="id",
+# else the nearest scroll box (or overflow box) around it, else the screen; it flips against the same
+var pp_bx: float = 0.0
+var pp_by: float = 0.0
+var pp_bw: float = 0.0
+var pp_bh: float = 0.0
+function pp_bounds(p: UiNode) -> void {
+  pp_bx = ly_vp_x
+  pp_by = ly_vp_y
+  pp_bw = ly_vp_w
+  pp_bh = ly_vp_h
+  var box: UiNode = null
+  let id = ui_attr_text(p, "within")
+  if id != "" {
+    var at = p.parent
+    while at != null and box == null {
+      box = pp_by_id(at, id, p)
+      at = at.parent
+    }
+    if box == null { ui_err(`within="{id}": no element has that id`) }
+  } else {
+    var at = p.parent
+    while at != null and box == null {
+      if at.kind == UI_SCROLL { box = at }
+      at = at.parent
+    }
+  }
+  if box == null { return }
+  pp_bx = box.x
+  pp_by = box.y
+  pp_bw = box.cw
+  pp_bh = box.ch
+}
+# where a popover of `size` starts along its anchor's side: level with its start, centred, or its end
+function pp_along(align: string, at: float, span: float, size: float) -> float {
+  if align == "center" { return at + (span - size) / 2.0 }
+  if align == "end" { return at + span - size }
+  return at
+}

tools/ludic-cli/test.ludic

@@ -765,6 +765,7 @@ function cmd_dev_test() -> int {
   controller_case("library/ui_ease", "", "60: 1480 680 slid 1 landed 1 left 0; 120: 1480 680 slid 1 landed 1 left 0; 180: 1480 680 slid 1 landed 1 left 0; 240: 1480 680 slid 1 landed 1 left 0;", "ui_ease.ludic (L11: a transition and an animation at 60, 120, 180 and 240 Hz are the same half way and land exactly on their targets)")
   controller_case("library/ui_gamepad", "", "last 6 vol 0 q 0 open false | last 0 vol 0 q 0 open false | last 0 vol 2 q 0 open false | last 0 vol 2 q 2 open false | last 0 vol 2 q 2 open true | last 0 vol 2 q 2 open false", "ui_gamepad.ludic (L11: the pad and held keys - a held direction repeats on the clock at any rate, A presses, left and right step, B closes a popover)")
   controller_case("library/ui_pointer", "", "pointerdown 100,80 0 0; pointerup 300,300 0 0; wheel 50,50 0 1; dragged 200 | zoomed 1 pad 7 10 1 2 hold true 0 0 active 16711680 | zoomed 1 pad 7 10 1 2 hold false 1 0 | zoomed 1 pad 7 10 1 2 hold true 1 0 | zoomed 1 pad 7 10 1 2 hold false 2 0 3817286", "ui_pointer.ludic (L11: pointer events for natives and markup, capture until release, a button over a native keeps its press; on-down, on-up and :active)")
+  controller_case("library/ui_popover_align", "", "centred, flipped in the panel 90,40 | end below 110,70 | above b in the list 0 inside 1", "ui_popover_align.ludic (L11: anchored popovers aligned along their side, flipped and kept within a named container or their scroll box)")
   controller_case("library/ui_inputs", "", "count 12 12 32 0.5 0 | 20 32 0.5 0 | 19 32 0.5 0 | How many to carry | Space bar listening 1 19 9 0.5 0 | 19 9 0.5 0 | 19 0 0.5 0 | 60% 0.50 s | 19 0 0.6 9 | 7!", "ui_inputs.ludic (L11: number fields, key capture with Esc and Backspace, notes, range formats, an event named set, a string prop given a number)")
   controller_case("library/ui_boxes", "", "list 120 of 200 | text at 32 152 wide, 3 lines, row 60 | zero 0x0 | half 140x36 pad 4 2 | order abc at 16 | fill 98x8 of 200x12", "ui_boxes.ludic (L11: flex-shrink to the leftover room, text wrapping beside its siblings, zero sizes, calc(), order, the range track as a row)")
   controller_case("library/ui_look", "", "root div.in.i.m pad 5 margin 9 color #ff0000 text Hi 2,53 #102030 | text Hi 0,50 #eeeeee | opacity 0.25 | nine 40 #ffffff nine 40 #ff0000 of 2 image photo.png #ffffff | image icon:tent #00ff00 | text first line 29,205 #eeeeee | text second line 29,223 #eeeeee by id at 84,50 | flipped at 246,268 100x32", "ui_look.ludic (L11: nested components styled by specificity, text-shadow, ui_opacity, border-image tints, pictures, tooltip lines, anchored popovers)")