gbs-add-block 1.2.18 → 1.2.19

package/source/beta-components/shared/__tests__/position.test.ts

@@ -1,170 +1,143 @@
-import { describe, expect, it } from "vitest";
-import { placePopover, type AnchorRect, type PlacementOptions } from "../core/position";
-
-const VIEWPORT = { width: 1000, height: 800 };
-
-const anchorAt = (left: number, top: number, width = 120, height = 32): AnchorRect => ({
-  left,
-  top,
-  width,
-  height,
-  right: left + width,
-  bottom: top + height,
-});
-
-const options = (overrides: Partial<PlacementOptions> = {}): PlacementOptions => ({
-  side: "bottom",
-  align: "start",
-  gap: 4,
-  edge: 8,
-  rtl: false,
-  fitHeight: false,
-  minHeight: 140,
-  ...overrides,
-});
-
-describe("below the anchor", () => {
-  it("sits under the anchor, aligned to its left edge", () => {
-    const placement = placePopover(anchorAt(100, 100), { width: 200, height: 150 }, VIEWPORT, options());
-    expect(placement).toMatchObject({ side: "bottom", left: 100, top: 136 });
-  });
-
-  it("aligns to the right edge when asked", () => {
-    const placement = placePopover(
-      anchorAt(100, 100),
-      { width: 200, height: 150 },
-      VIEWPORT,
-      options({ align: "end" }),
-    );
-    // The anchor's right edge is 220, so a 200-wide panel starts at 20.
-    expect(placement.left).toBe(20);
-  });
-
-  it("moves above when there is no room below and it fits above", () => {
-    const placement = placePopover(anchorAt(100, 700), { width: 200, height: 150 }, VIEWPORT, options());
-    expect(placement).toMatchObject({ side: "top", top: 546 });
-  });
-
-  it("stays below when it fits neither side, rather than running off the top", () => {
-    const placement = placePopover(anchorAt(100, 300), { width: 200, height: 780 }, VIEWPORT, options());
-    expect(placement.side).toBe("bottom");
-  });
-
-  it("pulls a panel that fits neither side back inside the viewport", () => {
-    // 780 tall against 456px below and 288px above: it cannot sit under the
-    // anchor without its foot leaving the screen, and nothing in the top layer
-    // can be scrolled into view.
-    const placement = placePopover(anchorAt(100, 300), { width: 200, height: 780 }, VIEWPORT, options());
-    expect(placement.top).toBe(800 - 780 - 8);
-    expect(placement.top + 780).toBeLessThanOrEqual(800);
-  });
-
-  it("keeps the top gutter when the panel is taller than the viewport", () => {
-    const placement = placePopover(anchorAt(100, 300), { width: 200, height: 900 }, VIEWPORT, options());
-    expect(placement.top).toBe(8);
-  });
-});
-
-describe("fitHeight", () => {
-  it("takes the roomier side and caps the height to it", () => {
-    // 700px from the top: 68px below, 688px above.
-    const placement = placePopover(
-      anchorAt(100, 700),
-      { width: 200, height: 600 },
-      VIEWPORT,
-      options({ fitHeight: true }),
-    );
-    expect(placement.side).toBe("top");
-    expect(placement.maxHeight).toBe(688);
-  });
-
-  it("never caps below minHeight, however cramped the viewport", () => {
-    const placement = placePopover(
-      anchorAt(100, 380),
-      { width: 200, height: 300 },
-      { width: 1000, height: 420 },
-      options({ fitHeight: true, minHeight: 140 }),
-    );
-    expect(placement.maxHeight).toBeGreaterThanOrEqual(140);
-  });
-});
-
-describe("staying on screen", () => {
-  it("pulls a panel back from the right edge", () => {
-    const placement = placePopover(anchorAt(950, 100), { width: 300, height: 100 }, VIEWPORT, options());
-    expect(placement.left).toBe(1000 - 300 - 8);
-  });
-
-  it("pulls a side panel back inside when it fits on neither side", () => {
-    // 600 wide with 448px to the right and 488px to the left: too wide to flip,
-    // so without a clamp its right edge would sit 144px past the viewport.
-    const placement = placePopover(
-      anchorAt(500, 300, 40),
-      { width: 600, height: 100 },
-      VIEWPORT,
-      options({ side: "right" }),
-    );
-    expect(placement.side).toBe("right");
-    expect(placement.left).toBe(1000 - 600 - 8);
-  });
-
-  it("keeps the left gutter when the panel is wider than the viewport", () => {
-    const placement = placePopover(anchorAt(10, 100), { width: 1200, height: 100 }, VIEWPORT, options());
-    expect(placement.left).toBe(8);
-  });
-});
-
-describe("sideways", () => {
-  it("opens to the right of the anchor, top edges level", () => {
-    const placement = placePopover(
-      anchorAt(100, 100),
-      { width: 200, height: 150 },
-      VIEWPORT,
-      options({ side: "right" }),
-    );
-    expect(placement).toMatchObject({ side: "right", left: 224, top: 100 });
-  });
-
-  it("flips to the left when the right has no room", () => {
-    const placement = placePopover(
-      anchorAt(850, 100),
-      { width: 200, height: 150 },
-      VIEWPORT,
-      options({ side: "right" }),
-    );
-    expect(placement).toMatchObject({ side: "left", left: 646 });
-  });
-
-  it("keeps a tall panel inside the viewport", () => {
-    const placement = placePopover(
-      anchorAt(100, 760),
-      { width: 200, height: 400 },
-      VIEWPORT,
-      options({ side: "right" }),
-    );
-    expect(placement.top).toBe(800 - 400 - 8);
-  });
-});
-
-describe("right to left", () => {
-  it("mirrors which edge `start` means", () => {
-    const placement = placePopover(
-      anchorAt(100, 100),
-      { width: 200, height: 150 },
-      VIEWPORT,
-      options({ rtl: true }),
-    );
-    // Reading starts on the right, so the panel's right edge meets the anchor's.
-    expect(placement.left).toBe(20);
-  });
-
-  it("mirrors left and right", () => {
-    const placement = placePopover(
-      anchorAt(500, 100),
-      { width: 200, height: 150 },
-      VIEWPORT,
-      options({ side: "right", rtl: true }),
-    );
-    expect(placement).toMatchObject({ side: "left", left: 296 });
-  });
-});
+import { describe, expect, it } from "vitest";
+import { placePopover, type AnchorRect, type PlacementOptions } from "../core/position";
+
+const VIEWPORT = { width: 1000, height: 800 };
+
+const anchorAt = (left: number, top: number, width = 120, height = 32): AnchorRect => ({
+  left,
+  top,
+  width,
+  height,
+  right: left + width,
+  bottom: top + height,
+});
+
+const options = (overrides: Partial<PlacementOptions> = {}): PlacementOptions => ({
+  side: "bottom",
+  align: "start",
+  gap: 4,
+  edge: 8,
+  rtl: false,
+  fitHeight: false,
+  minHeight: 140,
+  ...overrides,
+});
+
+describe("below the anchor", () => {
+  it("sits under the anchor, aligned to its left edge", () => {
+    const placement = placePopover(anchorAt(100, 100), { width: 200, height: 150 }, VIEWPORT, options());
+    expect(placement).toMatchObject({ side: "bottom", left: 100, top: 136 });
+  });
+
+  it("aligns to the right edge when asked", () => {
+    const placement = placePopover(
+      anchorAt(100, 100),
+      { width: 200, height: 150 },
+      VIEWPORT,
+      options({ align: "end" }),
+    );
+    // The anchor's right edge is 220, so a 200-wide panel starts at 20.
+    expect(placement.left).toBe(20);
+  });
+
+  it("moves above when there is no room below and it fits above", () => {
+    const placement = placePopover(anchorAt(100, 700), { width: 200, height: 150 }, VIEWPORT, options());
+    expect(placement).toMatchObject({ side: "top", top: 546 });
+  });
+
+  it("stays below when it fits neither side, rather than running off the top", () => {
+    const placement = placePopover(anchorAt(100, 300), { width: 200, height: 780 }, VIEWPORT, options());
+    expect(placement.side).toBe("bottom");
+  });
+});
+
+describe("fitHeight", () => {
+  it("takes the roomier side and caps the height to it", () => {
+    // 700px from the top: 68px below, 688px above.
+    const placement = placePopover(
+      anchorAt(100, 700),
+      { width: 200, height: 600 },
+      VIEWPORT,
+      options({ fitHeight: true }),
+    );
+    expect(placement.side).toBe("top");
+    expect(placement.maxHeight).toBe(688);
+  });
+
+  it("never caps below minHeight, however cramped the viewport", () => {
+    const placement = placePopover(
+      anchorAt(100, 380),
+      { width: 200, height: 300 },
+      { width: 1000, height: 420 },
+      options({ fitHeight: true, minHeight: 140 }),
+    );
+    expect(placement.maxHeight).toBeGreaterThanOrEqual(140);
+  });
+});
+
+describe("staying on screen", () => {
+  it("pulls a panel back from the right edge", () => {
+    const placement = placePopover(anchorAt(950, 100), { width: 300, height: 100 }, VIEWPORT, options());
+    expect(placement.left).toBe(1000 - 300 - 8);
+  });
+
+  it("keeps the left gutter when the panel is wider than the viewport", () => {
+    const placement = placePopover(anchorAt(10, 100), { width: 1200, height: 100 }, VIEWPORT, options());
+    expect(placement.left).toBe(8);
+  });
+});
+
+describe("sideways", () => {
+  it("opens to the right of the anchor, top edges level", () => {
+    const placement = placePopover(
+      anchorAt(100, 100),
+      { width: 200, height: 150 },
+      VIEWPORT,
+      options({ side: "right" }),
+    );
+    expect(placement).toMatchObject({ side: "right", left: 224, top: 100 });
+  });
+
+  it("flips to the left when the right has no room", () => {
+    const placement = placePopover(
+      anchorAt(850, 100),
+      { width: 200, height: 150 },
+      VIEWPORT,
+      options({ side: "right" }),
+    );
+    expect(placement).toMatchObject({ side: "left", left: 646 });
+  });
+
+  it("keeps a tall panel inside the viewport", () => {
+    const placement = placePopover(
+      anchorAt(100, 760),
+      { width: 200, height: 400 },
+      VIEWPORT,
+      options({ side: "right" }),
+    );
+    expect(placement.top).toBe(800 - 400 - 8);
+  });
+});
+
+describe("right to left", () => {
+  it("mirrors which edge `start` means", () => {
+    const placement = placePopover(
+      anchorAt(100, 100),
+      { width: 200, height: 150 },
+      VIEWPORT,
+      options({ rtl: true }),
+    );
+    // Reading starts on the right, so the panel's right edge meets the anchor's.
+    expect(placement.left).toBe(20);
+  });
+
+  it("mirrors left and right", () => {
+    const placement = placePopover(
+      anchorAt(500, 100),
+      { width: 200, height: 150 },
+      VIEWPORT,
+      options({ side: "right", rtl: true }),
+    );
+    expect(placement).toMatchObject({ side: "left", left: 296 });
+  });
+});

package/source/beta-components/shared/core/position.ts

@@ -94,16 +94,7 @@ export function placePopover(
         edge,
         viewport.width - size.width - edge,
       ),
-      // Clamped on both ends: when a panel fits neither above nor below, it is
-      // pulled back inside instead of hanging off the edge. Nothing in the top
-      // layer scrolls into view, so whatever leaves the viewport is lost. A
-      // panel taller than the viewport itself still starts at the top gutter,
-      // since `clamp` keeps the minimum when the maximum falls below it.
-      top: clamp(
-        below ? anchor.bottom + gap : anchor.top - gap - size.height,
-        edge,
-        viewport.height - size.height - edge,
-      ),
+      top: Math.max(edge, below ? anchor.bottom + gap : anchor.top - gap - size.height),
       maxHeight: fitHeight
         ? Math.max(minHeight, below ? roomBelow : roomAbove)
         : undefined,
@@ -122,11 +113,7 @@ export function placePopover(
 
   return {
     side: right ? "right" : "left",
-    left: clamp(
-      right ? anchor.right + gap : anchor.left - gap - size.width,
-      edge,
-      viewport.width - size.width - edge,
-    ),
+    left: Math.max(edge, right ? anchor.right + gap : anchor.left - gap - size.width),
     top: clamp(
       across(anchor.top, anchor.height, size.height),
       edge,

package/source/beta-components/shared/react/Popover.tsx

@@ -137,30 +137,17 @@ export function AnchoredPopover({
       target?.focus({ preventScroll: true });
     }
 
-    // Scrolling fires far faster than the screen refreshes, and each pass
-    // measures the anchor and writes styles back, so repositioning is coalesced
-    // into one frame rather than thrashing layout on every event.
-    let frame = 0;
-    const schedule = () => {
-      if (frame) return;
-      frame = requestAnimationFrame(() => {
-        frame = 0;
-        position();
-      });
-    };
-
-    const observer = observeResize ? new ResizeObserver(schedule) : null;
+    const observer = observeResize ? new ResizeObserver(position) : null;
     observer?.observe(el);
     if (observeResize === "both") observer?.observe(anchor);
-    window.addEventListener("resize", schedule, { passive: true });
+    window.addEventListener("resize", position);
     // Capture: a scroll in any ancestor moves the anchor, not just the page.
-    window.addEventListener("scroll", schedule, { capture: true, passive: true });
+    window.addEventListener("scroll", position, true);
 
     return () => {
-      if (frame) cancelAnimationFrame(frame);
       observer?.disconnect();
-      window.removeEventListener("resize", schedule);
-      window.removeEventListener("scroll", schedule, true);
+      window.removeEventListener("resize", position);
+      window.removeEventListener("scroll", position, true);
       const hadFocus = el.contains(document.activeElement);
       if (el.matches(":popover-open")) el.hidePopover();
       if (returnFocus && (hadFocus || document.activeElement === document.body) && anchor.isConnected) {

package/source/beta-components/switch/README.md

@@ -0,0 +1,46 @@
+# Switch
+
+A setting that takes effect the moment it is flipped, for React 19, styled to
+match the rest of the library. The control is a real
+`<input type="checkbox" role="switch">`, so forms, form libraries and assistive
+technology work as they do natively — and it is announced as "on"/"off" rather
+than "checked". No runtime dependencies besides React.
+
+```ts
+import { Switch } from "@/components/switch";
+import "@/components/switch/styles.css";
+```
+
+```tsx
+<Switch label="Email notifications" name="notify" checked={on} onCheckedChange={setOn} />
+
+{/* Return a promise and the switch shows the new setting, spins while it saves,
+    and puts itself back if the save fails. */}
+<Switch
+  label="Two-factor authentication"
+  description="Ask for a code from your authenticator app."
+  checked={enabled}
+  onCheckedChange={(next) => api.setTwoFactor(next)}
+/>
+
+{/* A settings row: label first, switch against the right edge. */}
+<Switch label="Weekly digest" labelPosition="start" defaultChecked />
+```
+
+**Props:** `checked` / `defaultChecked` / `onCheckedChange` (may return a
+promise), `value`, `label`, `description`, `error`, `size` (`sm` `md` `lg`),
+`labelPosition` (`end` `start`), `loading`, `disabled`, `readOnly`, `required`,
+`name`, `classNames` (`root` `control` `input` `track` `thumb` `label`
+`description` `error`), `localeText`, `ref` (the `<input>`), and every
+`<input>` attribute.
+
+**Keyboard:** **Space** toggles. **→** turns it on and **←** off (mirrored in
+right-to-left layouts), which is the ARIA switch pattern.
+
+The `idleToggle`, `request`, `settle` and `adopt` state machine behind the
+saving behaviour is exported from the framework-free `core`: it decides what a
+failed save goes back to, and ignores the answer to a request that a later one
+has already replaced.
+
+Use a **Checkbox** instead when the value is part of a form that is submitted
+later, and a Switch when flipping it *is* the action.

package/source/beta-components/switch/__tests__/core.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import { adopt, idleToggle, request, settle } from "../core/toggle";
+
+describe("switch toggling", () => {
+  it("shows the new setting before it has been saved", () => {
+    const state = request(idleToggle(false), true);
+    expect(state).toEqual({ checked: true, pending: true, fallback: false });
+  });
+
+  it("keeps the new setting once the save succeeds", () => {
+    const state = settle(request(idleToggle(false), true), true, true);
+    expect(state).toEqual({ checked: true, pending: null, fallback: true });
+  });
+
+  it("goes back where it was when the save fails", () => {
+    const state = settle(request(idleToggle(false), true), true, false);
+    expect(state).toEqual({ checked: false, pending: null, fallback: false });
+  });
+
+  it("returns to where the run of changes started, not to the opposite", () => {
+    // On, then off again while the first save is still running: failing the
+    // second must land on the original off, which is also where it looks like
+    // it is — flipping the visible value would turn it back on.
+    const first = request(idleToggle(false), true);
+    const second = request(first, false);
+    expect(second.fallback).toBe(false);
+    expect(settle(second, false, false).checked).toBe(false);
+  });
+
+  it("ignores the outcome of a change that was overtaken", () => {
+    const first = request(idleToggle(false), true);
+    const second = request(first, false);
+    // The first request finally answers, long after the second replaced it.
+    expect(settle(second, true, true)).toBe(second);
+    expect(settle(second, true, false)).toBe(second);
+  });
+
+  it("ignores an outcome when nothing is in flight", () => {
+    const idle = idleToggle(true);
+    expect(settle(idle, true, false)).toBe(idle);
+  });
+
+  it("does nothing when asked for the value it already shows", () => {
+    const idle = idleToggle(true);
+    expect(request(idle, true)).toBe(idle);
+  });
+
+  it("re-requests a value that is showing but not yet saved", () => {
+    // Pressed on, pressed off, pressed on again: the last press still needs an
+    // outcome of its own, so it cannot be dropped as a no-op.
+    const pending = request(request(idleToggle(false), true), false);
+    const again = request(pending, true);
+    expect(again.pending).toBe(true);
+    expect(again.fallback).toBe(false);
+  });
+
+  it("lets a controlled value win over anything in flight", () => {
+    const pending = request(idleToggle(false), true);
+    expect(adopt(pending, false)).toEqual({ checked: false, pending: null, fallback: false });
+    // An unchanged, settled value is left as it is, so React skips the render.
+    const idle = idleToggle(true);
+    expect(adopt(idle, true)).toBe(idle);
+  });
+});

package/source/beta-components/switch/core/index.ts

@@ -0,0 +1,2 @@
+export { adopt, idleToggle, request, settle, type ToggleState } from "./toggle";
+export type * from "./types";

package/source/beta-components/switch/core/toggle.ts

@@ -0,0 +1,54 @@
+/**
+ * The state of a switch whose change has to be saved somewhere.
+ *
+ * A switch is usually the whole interaction: there is no form to submit
+ * afterwards, so flipping it *is* the request. That leaves three things to
+ * agree on, and they are worth keeping out of the component and under test.
+ *
+ * The switch moves as soon as it is pressed, rather than waiting for the
+ * server, because a control that ignores a press feels broken. If the save
+ * fails it goes back to where it was — to `fallback`, the value from before the
+ * press, not simply the opposite of what is on screen, since the two differ
+ * once anything else has changed the value in the meantime.
+ *
+ * And a request that is overtaken is ignored: `settle` only accepts an outcome
+ * for the change still in flight (`pending`), so a late failure from an
+ * abandoned request cannot drag a newer value back with it.
+ */
+
+export interface ToggleState {
+  /** What the switch shows now. */
+  checked: boolean;
+  /** The change being saved, or null when nothing is in flight. */
+  pending: boolean | null;
+  /** What to go back to if the save fails. */
+  fallback: boolean;
+}
+
+export const idleToggle = (checked: boolean): ToggleState => ({
+  checked,
+  pending: null,
+  fallback: checked,
+});
+
+/** Shows `next` at once and remembers where to return to. */
+export function request(state: ToggleState, next: boolean): ToggleState {
+  if (next === state.checked && state.pending === null) return state;
+  return { checked: next, pending: next, fallback: state.pending === null ? state.checked : state.fallback };
+}
+
+/**
+ * Applies the outcome of the change that is in flight. An outcome for anything
+ * else — a request that was already overtaken — leaves the state alone.
+ */
+export function settle(state: ToggleState, requested: boolean, saved: boolean): ToggleState {
+  if (state.pending === null || state.pending !== requested) return state;
+  const checked = saved ? state.checked : state.fallback;
+  return { checked, pending: null, fallback: checked };
+}
+
+/** A value arriving from a controlled prop wins, and ends anything in flight. */
+export function adopt(state: ToggleState, checked: boolean): ToggleState {
+  if (checked === state.checked && state.pending === null) return state;
+  return idleToggle(checked);
+}

package/source/beta-components/switch/core/types.ts

@@ -0,0 +1,9 @@
+export type SwitchSize = "sm" | "md" | "lg";
+
+/** Which side of the track the label sits on. */
+export type SwitchLabelPosition = "end" | "start";
+
+export interface SwitchLocaleText {
+  /** Announced while a change is being saved. */
+  saving: string;
+}

package/source/beta-components/switch/index.ts

@@ -0,0 +1,5 @@
+export { Switch } from "./react/Switch";
+export type { SwitchProps } from "./react/Switch";
+export { defaultSwitchText } from "./react/locale";
+export type { SwitchSlot } from "./react/props";
+export * from "./core";