@stapel/search-react 0.41.1 → 0.42.0

package/src/default/ViewSwitch.tsx

@@ -122,6 +122,42 @@ export interface ViewSwitchProps {
   readonly views: readonly SearchView[];
   readonly value: string;
   readonly onChange: (id: string) => void;
+  /**
+   * THE GLYPHS ALONE — the phone form, and it is a different control rather
+   * than the same one at a smaller type step.
+   *
+   * Named + glyph is two labels wide, and on a 390px toolbar it shares a line
+   * with the sort select. The select has a floor (the width of its own longest
+   * option — see `SortSelect`), so the switch is what gave: it was CUT by the
+   * select's leading edge mid-word, and the last arrangement on offer read as
+   * a truncated word with no indication there was a control there at all. A
+   * segmented control cut in half is worse than one with no words: the first
+   * looks broken, the second looks deliberate.
+   *
+   * So below the pane's phone breakpoint each option is its glyph and nothing
+   * else, and the NAME moves to where a name belongs — `aria-label`, off the
+   * same i18n key the wide form prints, so nothing is lost to a screen reader
+   * or to a locale. A view with no `icon` keeps its name: an option drawn as
+   * an empty box is not a smaller control, it is an unreachable one.
+   */
+  readonly compact?: boolean;
+}
+
+/**
+ * One option's face. Compact, that is the glyph carrying the view's NAME:
+ * `role="img"` is what makes an `aria-label` computable here — the glyph
+ * inside is `aria-hidden`, and a bare `<span>` has no role for a name to
+ * attach to, so the radio the browser builds around it would be nameless.
+ */
+function ViewOptionLabel(props: {
+  readonly name: string;
+  readonly icon: ReactNode;
+}): ReactElement {
+  return (
+    <span role="img" aria-label={props.name} data-testid="search-view-option-icon">
+      {props.icon}
+    </span>
+  );
 }
 
 /**
@@ -131,17 +167,29 @@ export interface ViewSwitchProps {
 export function ViewSwitch(props: ViewSwitchProps): ReactElement | null {
   const t = useT();
   if (props.views.length < 2) return null;
+  const compact = props.compact === true;
   return (
     <Segmented<string>
       aria-label={t(SEARCH_I18N_KEYS.viewLabel)}
       value={props.value}
       data-testid="search-view-switch"
+      data-view-switch={compact ? "compact" : "named"}
       onChange={props.onChange}
-      options={props.views.map((view) => ({
-        value: view.id,
-        label: t(view.labelKey),
-        ...(view.icon !== undefined ? { icon: view.icon } : {}),
-      }))}
+      // It keeps the width its glyphs need and no more: the group it sits in
+      // wraps as a unit when the line is short, and a switch that shrank
+      // instead would be the cut control this form exists to end.
+      style={{ flex: "0 0 auto" }}
+      options={props.views.map((view) => {
+        const name = t(view.labelKey);
+        if (compact && view.icon !== undefined) {
+          return { value: view.id, label: <ViewOptionLabel name={name} icon={view.icon} /> };
+        }
+        return {
+          value: view.id,
+          label: name,
+          ...(view.icon !== undefined ? { icon: view.icon } : {}),
+        };
+      })}
     />
   );
 }

package/src/default/index.ts

@@ -53,6 +53,7 @@ export {
   railScrollbarCss,
   railStyle,
 } from "./SearchPage.js";
+export { RAIL_OFFSET_PROPERTY, useRailFits } from "./railFit.js";
 export type {
   SearchPageProps,
   SearchFiltersLayout,
@@ -61,6 +62,7 @@ export type {
   SearchFiltersOpenReason,
   SearchBlockRhythm,
   SearchRailFrom,
+  SearchRailScroll,
   SearchRailScrollbar,
 } from "./SearchPage.js";
 

package/src/default/railFit.ts

@@ -0,0 +1,90 @@
+/**
+ * DOES THE FILTER RAIL FIT UNDER THE HOST'S HEADER?
+ *
+ * The question exists only for `railScroll="page"` — the arm where the rail is
+ * NOT a scroll container of its own and the page is the only thing that
+ * scrolls. There a rail taller than the window cannot be sticky: a stuck box
+ * is cut off at the foot of the screen and its last controls become
+ * unreachable, because the scroll that would reveal them is the page's and the
+ * page is not moving the rail. So the rail sticks while it fits and stands in
+ * flow while it does not, and "fits" is a measurement, not a breakpoint:
+ * the same catalogue draws four facet groups on one leaf and twenty on the
+ * next.
+ *
+ * Two numbers, and both are read from the browser rather than restated:
+ *
+ *  - the rail's own height — `ResizeObserver`, because the rail changes height
+ *    without the window changing at all (a facet group unfolds, an answer
+ *    lands with more values, the schema arrives and reorders the panel);
+ *  - the room under the host's chrome — `window.innerHeight` minus the offset
+ *    the rail already carries as `scroll-margin-top`. That property is the
+ *    same offset said in the one property that MEANS it (the header covers
+ *    that much of the top of the scrollport), and the engine resolves it to
+ *    pixels — a `var()`, a `calc()` or a `rem` included — so the fit test
+ *    needs no CSS parser of its own to read what a host wrote.
+ *
+ * The house rule from `useElementWidth` holds here too: **zero is not a
+ * measurement**. A detached or `display: none` rail reports 0 and would
+ * otherwise be declared to fit forever. And the honest answer before the first
+ * measurement is "no": a static rail scrolls with the page under every
+ * circumstance, so an unmeasured frame degrades to the arm that cannot hide a
+ * control.
+ */
+import { useEffect, useState } from "react";
+import type { RefObject } from "react";
+
+/** The CSS property the rail's top offset is carried in — see the note above.
+ * Exported so a test can assert the two halves read and write the same one. */
+export const RAIL_OFFSET_PROPERTY = "scrollMarginTop";
+
+/**
+ * Measure whether `ref`'s element is short enough to stand under the chrome
+ * its own `scroll-margin-top` names.
+ *
+ * `enabled` is the `railScroll === "page"` arm: under `"internal"` nothing is
+ * measured and nothing is listened to, so the default arm carries no observer
+ * and no listener at all.
+ */
+export function useRailFits(
+  ref: RefObject<HTMLElement | null>,
+  enabled: boolean
+): boolean {
+  const [fits, setFits] = useState(false);
+
+  useEffect(() => {
+    if (!enabled) {
+      // Leaving the arm resets the answer: a rail that stops being measured
+      // must not keep the last measurement's `position: sticky`.
+      setFits(false);
+      return undefined;
+    }
+    const element = ref.current;
+    if (element === null) return undefined;
+
+    const measure = (): void => {
+      const height = element.getBoundingClientRect().height;
+      // Zero is not a measurement — see the note above.
+      if (height <= 0) return;
+      const offset = Number.parseFloat(
+        window.getComputedStyle(element)[RAIL_OFFSET_PROPERTY]
+      );
+      const room = window.innerHeight - (Number.isFinite(offset) ? offset : 0);
+      const next = height <= room;
+      setFits((previous) => (previous === next ? previous : next));
+    };
+
+    measure();
+    // The window's own height is not the element's: a rotation, a devtools
+    // pane or a resized window changes the room without changing the rail.
+    window.addEventListener("resize", measure);
+    const observer =
+      typeof ResizeObserver === "undefined" ? null : new ResizeObserver(measure);
+    observer?.observe(element);
+    return () => {
+      window.removeEventListener("resize", measure);
+      observer?.disconnect();
+    };
+  }, [ref, enabled]);
+
+  return fits;
+}