@oneuptime/common 12.0.33 → 12.0.34

package/Tests/ResponsiveVisibility.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, test } from "@jest/globals";
+import {
+  PHONE_WIDTH_IN_PX,
+  LAPTOP_WIDTH_IN_PX,
+  describeVisibility,
+  findHidingElement,
+  isVisibleAtWidth,
+  resolveDisplay,
+} from "./ResponsiveVisibility";
+
+/*
+ * The header suites below lean on this helper to prove a button is on screen at
+ * phone width. A helper that answered "visible" too easily would make all of
+ * them pass while the bug they cover is still shipped, so it gets its own
+ * cover — including the two class strings the real regression turned on:
+ * "hidden lg:flex" (the wrapper that hid the profile button) and "lg:hidden"
+ * (which must NOT read as hidden on a phone).
+ */
+describe("resolveDisplay", () => {
+  test("an unprefixed utility applies at every width", () => {
+    expect(resolveDisplay("flex items-center", PHONE_WIDTH_IN_PX)).toBe("flex");
+    expect(resolveDisplay("flex items-center", LAPTOP_WIDTH_IN_PX)).toBe(
+      "flex",
+    );
+  });
+
+  test("markup that sets no display at all resolves to null, not hidden", () => {
+    expect(
+      resolveDisplay("relative z-20 items-center", PHONE_WIDTH_IN_PX),
+    ).toBe(null);
+    expect(resolveDisplay("", PHONE_WIDTH_IN_PX)).toBe(null);
+    expect(resolveDisplay(null, PHONE_WIDTH_IN_PX)).toBe(null);
+  });
+
+  test("a breakpoint variant only wins once the viewport reaches it", () => {
+    expect(resolveDisplay("hidden lg:flex", 1023)).toBe("hidden");
+    expect(resolveDisplay("hidden lg:flex", 1024)).toBe("flex");
+  });
+
+  test("the largest matching breakpoint wins, whatever the source order", () => {
+    expect(resolveDisplay("lg:flex hidden sm:block", LAPTOP_WIDTH_IN_PX)).toBe(
+      "flex",
+    );
+    expect(resolveDisplay("lg:flex hidden sm:block", 700)).toBe("block");
+    expect(resolveDisplay("lg:flex hidden sm:block", 400)).toBe("hidden");
+  });
+
+  test("lg:hidden is a wide-screen rule, so a phone still sees the element", () => {
+    expect(resolveDisplay("flex lg:hidden", PHONE_WIDTH_IN_PX)).toBe("flex");
+    expect(resolveDisplay("flex lg:hidden", LAPTOP_WIDTH_IN_PX)).toBe("hidden");
+  });
+
+  test("state variants are ignored — they cannot answer a layout question", () => {
+    expect(resolveDisplay("hidden group-hover:flex", LAPTOP_WIDTH_IN_PX)).toBe(
+      "hidden",
+    );
+    expect(resolveDisplay("hidden lg:hover:flex", LAPTOP_WIDTH_IN_PX)).toBe(
+      "hidden",
+    );
+  });
+
+  test("a max-width variant throws rather than being quietly ignored", () => {
+    expect(() => {
+      return resolveDisplay("max-lg:hidden", PHONE_WIDTH_IN_PX);
+    }).toThrow(/max-width variants/);
+  });
+});
+
+describe("isVisibleAtWidth", () => {
+  type BuildTreeFunction = (wrapperClass: string) => HTMLElement;
+
+  const buildTree: BuildTreeFunction = (wrapperClass: string): HTMLElement => {
+    const root: HTMLElement = document.createElement("div");
+    root.className = "relative flex";
+    const wrapper: HTMLElement = document.createElement("div");
+    wrapper.className = wrapperClass;
+    const button: HTMLElement = document.createElement("button");
+    button.className = "h-9 w-9";
+    wrapper.appendChild(button);
+    root.appendChild(wrapper);
+    return button;
+  };
+
+  test("an ancestor's `hidden` takes the whole subtree off a phone screen", () => {
+    const button: HTMLElement = buildTree("hidden lg:flex");
+
+    expect(isVisibleAtWidth(button, PHONE_WIDTH_IN_PX)).toBe(false);
+    expect(isVisibleAtWidth(button, LAPTOP_WIDTH_IN_PX)).toBe(true);
+  });
+
+  test("nothing hidden anywhere up the tree means visible", () => {
+    const button: HTMLElement = buildTree("flex items-center gap-2");
+
+    expect(isVisibleAtWidth(button, PHONE_WIDTH_IN_PX)).toBe(true);
+    expect(findHidingElement(button, PHONE_WIDTH_IN_PX)).toBe(null);
+  });
+
+  test("an element that was never rendered is not visible", () => {
+    expect(isVisibleAtWidth(null, PHONE_WIDTH_IN_PX)).toBe(false);
+  });
+
+  test("the failure message names the element and the classes doing the hiding", () => {
+    const button: HTMLElement = buildTree("hidden lg:flex");
+
+    expect(describeVisibility(button, PHONE_WIDTH_IN_PX)).toBe(
+      'hidden at 375px by <div class="hidden lg:flex">',
+    );
+    expect(describeVisibility(button, LAPTOP_WIDTH_IN_PX)).toBe(
+      "visible at 1280px",
+    );
+    expect(describeVisibility(null, PHONE_WIDTH_IN_PX)).toBe(
+      "the element was never rendered",
+    );
+  });
+});

package/Tests/ResponsiveVisibility.ts

@@ -0,0 +1,183 @@
+/*
+ * Answers "would a browser paint this element at viewport width W?" for markup
+ * styled with Tailwind display utilities.
+ *
+ * jsdom has no stylesheet, so `toBeVisible()` cannot see a `hidden lg:flex`
+ * wrapper: to jsdom the element is present and visible at every width, which is
+ * exactly the blind spot that let the header ship with its whole right rail —
+ * profile button included — wrapped in `hidden lg:flex` and therefore missing
+ * on every phone and tablet. These helpers read the class attribute instead and
+ * resolve the display the same way the cascade would.
+ *
+ * Scope: `display` only, and only unprefixed or min-width-breakpoint-prefixed
+ * utilities. State variants (hover:, focus:, dark: ...) are ignored on purpose —
+ * they cannot answer the question this asks. A `max-*` breakpoint variant on a
+ * display utility throws rather than being silently ignored, so this never
+ * quietly reports "visible" about markup it does not model.
+ */
+
+export const TAILWIND_BREAKPOINTS_IN_PX: Record<string, number> = {
+  sm: 640,
+  md: 768,
+  lg: 1024,
+  xl: 1280,
+  "2xl": 1536,
+};
+
+// Widths worth asserting at. Named so failures read as devices, not numbers.
+export const PHONE_WIDTH_IN_PX: number = 375;
+export const TABLET_WIDTH_IN_PX: number = 768;
+export const LAPTOP_WIDTH_IN_PX: number = 1280;
+
+const DISPLAY_UTILITIES: Array<string> = [
+  "block",
+  "inline-block",
+  "inline",
+  "flex",
+  "inline-flex",
+  "table",
+  "inline-table",
+  "table-caption",
+  "table-cell",
+  "table-column",
+  "table-column-group",
+  "table-footer-group",
+  "table-header-group",
+  "table-row-group",
+  "table-row",
+  "flow-root",
+  "grid",
+  "inline-grid",
+  "contents",
+  "list-item",
+  "hidden",
+];
+
+const BREAKPOINT_ORDER: Array<string> = ["sm", "md", "lg", "xl", "2xl"];
+
+/**
+ * The `display` Tailwind resolves for one class attribute at a given viewport
+ * width, or null when the markup sets no display at all (the element then keeps
+ * whatever the user agent gives it, which is never `none`).
+ */
+export function resolveDisplay(
+  classAttribute: string | null | undefined,
+  viewportWidthInPx: number,
+): string | null {
+  let winner: string | null = null;
+  // -1 so an unprefixed utility (precedence 0) always beats "nothing yet".
+  let winningPrecedence: number = -1;
+
+  for (const token of (classAttribute || "").split(/\s+/)) {
+    if (!token) {
+      continue;
+    }
+
+    const parts: Array<string> = token.split(":");
+    const utility: string = parts[parts.length - 1]!;
+
+    if (!DISPLAY_UTILITIES.includes(utility)) {
+      continue;
+    }
+
+    // Unprefixed: applies at every width.
+    if (parts.length === 1) {
+      if (winningPrecedence <= 0) {
+        winner = utility;
+        winningPrecedence = 0;
+      }
+      continue;
+    }
+
+    if (parts.length !== 2) {
+      // e.g. lg:hover:flex — a state variant, which says nothing about layout.
+      continue;
+    }
+
+    const variant: string = parts[0]!;
+
+    if (variant.startsWith("max-")) {
+      throw new Error(
+        `resolveDisplay does not model max-width variants, and "${token}" is one. ` +
+          `Teach it the reverse-ordered cascade before using it on this markup.`,
+      );
+    }
+
+    const breakpointIndex: number = BREAKPOINT_ORDER.indexOf(variant);
+
+    if (breakpointIndex === -1) {
+      // A state or other non-breakpoint variant.
+      continue;
+    }
+
+    if (TAILWIND_BREAKPOINTS_IN_PX[variant]! > viewportWidthInPx) {
+      // The media query does not match at this width.
+      continue;
+    }
+
+    const precedence: number = breakpointIndex + 1;
+
+    if (precedence >= winningPrecedence) {
+      winner = utility;
+      winningPrecedence = precedence;
+    }
+  }
+
+  return winner;
+}
+
+/**
+ * The element — itself or the nearest ancestor — that takes this subtree off
+ * the screen at the given width, or null when nothing does.
+ */
+export function findHidingElement(
+  element: Element | null,
+  viewportWidthInPx: number,
+): Element | null {
+  let node: Element | null = element;
+
+  while (node) {
+    if (
+      resolveDisplay(node.getAttribute("class"), viewportWidthInPx) === "hidden"
+    ) {
+      return node;
+    }
+
+    node = node.parentElement;
+  }
+
+  return null;
+}
+
+/** Whether the element is painted at the given viewport width. */
+export function isVisibleAtWidth(
+  element: Element | null,
+  viewportWidthInPx: number,
+): boolean {
+  return (
+    Boolean(element) && findHidingElement(element, viewportWidthInPx) === null
+  );
+}
+
+/**
+ * A failure message that names the element doing the hiding and the classes
+ * that do it, so a broken expectation points straight at the markup to fix.
+ */
+export function describeVisibility(
+  element: Element | null,
+  viewportWidthInPx: number,
+): string {
+  if (!element) {
+    return "the element was never rendered";
+  }
+
+  const hiding: Element | null = findHidingElement(element, viewportWidthInPx);
+
+  if (!hiding) {
+    return `visible at ${viewportWidthInPx}px`;
+  }
+
+  return `hidden at ${viewportWidthInPx}px by <${hiding.tagName.toLowerCase()} class="${hiding.getAttribute(
+    "class",
+  )}">`;
+}