@byline/admin 6.1.0 → 6.2.0

package/src/presentation/tab-strip-geometry.test.node.ts

@@ -0,0 +1,254 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import { computeRevealScroll, computeStripState } from './tab-strip-geometry'
+
+describe('computeStripState', () => {
+  it('reports no overflow when the row fits the container', () => {
+    const state = computeStripState({
+      rowWidth: 500,
+      containerWidth: 600,
+      triggerWidth: 40,
+      triggerGap: 8,
+      scrollLeft: 0,
+    })
+
+    expect(state.overflowing).toBe(false)
+  })
+
+  /**
+   * The trigger must never be the reason the trigger appears. A row that fits
+   * the bare container fits, full stop — reserving the trigger's width before
+   * deciding would summon a menu for tabs that were never cut off.
+   */
+  it('does not overflow for a row that fits the container but not the reserved width', () => {
+    const state = computeStripState({
+      rowWidth: 570,
+      containerWidth: 600,
+      triggerWidth: 40,
+      triggerGap: 8,
+      scrollLeft: 0,
+    })
+
+    expect(state.overflowing).toBe(false)
+  })
+
+  it('decides overflow independently of the trigger width', () => {
+    const measurements = { rowWidth: 570, containerWidth: 600, triggerGap: 8, scrollLeft: 0 }
+
+    const narrow = computeStripState({ ...measurements, triggerWidth: 0 })
+    const wide = computeStripState({ ...measurements, triggerWidth: 200 })
+
+    expect(narrow.overflowing).toBe(wide.overflowing)
+  })
+
+  it('gives the row the full container width when it is not overflowing', () => {
+    const state = computeStripState({
+      rowWidth: 500,
+      containerWidth: 600,
+      triggerWidth: 40,
+      triggerGap: 8,
+      scrollLeft: 0,
+    })
+
+    expect(state.viewportWidth).toBe(600)
+  })
+
+  it('takes the trigger and its gap out of the viewport once overflowing', () => {
+    const state = computeStripState({
+      rowWidth: 800,
+      containerWidth: 600,
+      triggerWidth: 40,
+      triggerGap: 8,
+      scrollLeft: 0,
+    })
+
+    expect(state).toMatchObject({ overflowing: true, viewportWidth: 552 })
+  })
+
+  it('treats an unmeasured container as not overflowing', () => {
+    const state = computeStripState({
+      rowWidth: 800,
+      containerWidth: 0,
+      triggerWidth: 40,
+      triggerGap: 8,
+      scrollLeft: 0,
+    })
+
+    expect(state.overflowing).toBe(false)
+  })
+
+  it('never reports a negative viewport when the trigger is wider than the container', () => {
+    const state = computeStripState({
+      rowWidth: 800,
+      containerWidth: 30,
+      triggerWidth: 40,
+      triggerGap: 8,
+      scrollLeft: 0,
+    })
+
+    expect(state.viewportWidth).toBe(0)
+  })
+
+  it('reports both edges reached when the row does not overflow', () => {
+    const state = computeStripState({
+      rowWidth: 500,
+      containerWidth: 600,
+      triggerWidth: 40,
+      triggerGap: 8,
+      scrollLeft: 0,
+    })
+
+    expect(state).toMatchObject({ atStart: true, atEnd: true })
+  })
+
+  it('reports the start edge only while scrolled to the left', () => {
+    const state = computeStripState({
+      rowWidth: 800,
+      containerWidth: 600,
+      triggerWidth: 40,
+      triggerGap: 8,
+      scrollLeft: 0,
+    })
+
+    expect(state).toMatchObject({ atStart: true, atEnd: false })
+  })
+
+  it('reports neither edge mid-scroll', () => {
+    const state = computeStripState({
+      rowWidth: 800,
+      containerWidth: 600,
+      triggerWidth: 40,
+      triggerGap: 8,
+      scrollLeft: 100,
+    })
+
+    expect(state).toMatchObject({ atStart: false, atEnd: false })
+  })
+
+  it('reports the end edge when scrolled fully right', () => {
+    const state = computeStripState({
+      rowWidth: 800,
+      containerWidth: 600,
+      triggerWidth: 40,
+      triggerGap: 8,
+      scrollLeft: 248,
+    })
+
+    expect(state).toMatchObject({ atStart: false, atEnd: true })
+  })
+
+  /**
+   * Fractional layout widths are routine at non-integer device pixel ratios,
+   * so a scroll position a fraction short of the end still counts as the end.
+   * Without this the trailing fade never clears.
+   */
+  it('treats a sub-pixel shortfall as having reached the end', () => {
+    const state = computeStripState({
+      rowWidth: 800,
+      containerWidth: 600,
+      triggerWidth: 40,
+      triggerGap: 8,
+      scrollLeft: 247.6,
+    })
+
+    expect(state.atEnd).toBe(true)
+  })
+})
+
+describe('computeRevealScroll', () => {
+  const base = {
+    viewportWidth: 400,
+    rowWidth: 1000,
+    padding: 8,
+  }
+
+  it('leaves the scroll position alone when the tab is already fully visible', () => {
+    const next = computeRevealScroll({
+      ...base,
+      scrollLeft: 100,
+      tabOffsetLeft: 150,
+      tabWidth: 80,
+    })
+
+    expect(next).toBeNull()
+  })
+
+  it('scrolls left to bring a tab off the left edge into view', () => {
+    const next = computeRevealScroll({
+      ...base,
+      scrollLeft: 200,
+      tabOffsetLeft: 150,
+      tabWidth: 80,
+    })
+
+    expect(next).toBe(142)
+  })
+
+  it('scrolls right to bring a tab off the right edge into view', () => {
+    const next = computeRevealScroll({
+      ...base,
+      scrollLeft: 0,
+      tabOffsetLeft: 420,
+      tabWidth: 80,
+    })
+
+    expect(next).toBe(108)
+  })
+
+  it('clamps to the start rather than scrolling past it', () => {
+    const next = computeRevealScroll({
+      ...base,
+      scrollLeft: 20,
+      tabOffsetLeft: 0,
+      tabWidth: 80,
+    })
+
+    expect(next).toBe(0)
+  })
+
+  it('clamps to the end rather than scrolling past it', () => {
+    const next = computeRevealScroll({
+      ...base,
+      scrollLeft: 500,
+      tabOffsetLeft: 940,
+      tabWidth: 60,
+    })
+
+    expect(next).toBe(600)
+  })
+
+  /**
+   * A single label can be wider than the whole strip. Aligning its right edge
+   * would push the start of the label — the part that identifies it — off the
+   * left of the viewport, so an over-wide tab is always aligned to its start.
+   */
+  it('aligns a tab wider than the viewport to its left edge', () => {
+    const next = computeRevealScroll({
+      ...base,
+      scrollLeft: 0,
+      tabOffsetLeft: 500,
+      tabWidth: 450,
+    })
+
+    expect(next).toBe(492)
+  })
+
+  it('does not fight a reveal that would not move the scroll position', () => {
+    const next = computeRevealScroll({
+      ...base,
+      scrollLeft: 0,
+      tabOffsetLeft: 0,
+      tabWidth: 450,
+    })
+
+    expect(next).toBeNull()
+  })
+})

package/src/presentation/tab-strip-geometry.ts

@@ -0,0 +1,158 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+/**
+ * Pure geometry for the admin tab strip's overflow behaviour.
+ *
+ * The DOM reads and the React state live in `tabs.tsx`; every decision they
+ * drive is made here, so the rules are testable without a layout engine.
+ */
+
+/**
+ * Layout widths tolerate sub-pixel error at fractional device pixel ratios. A
+ * scroll position within this many pixels of an edge counts as having reached
+ * it — without the tolerance a trailing fade would never clear.
+ */
+const EDGE_EPSILON = 1
+
+/** Breathing room left beside a tab when scrolling it into view. */
+const DEFAULT_REVEAL_PADDING = 8
+
+export interface StripMeasurements {
+  /**
+   * Intrinsic content width of the tablist row.
+   *
+   * The row is laid out at `max-content`, so this is the width the tabs want
+   * regardless of how much room the viewport currently gives them. A row that
+   * shrank to its container would report the container's width back and the
+   * strip could never detect overflow at all.
+   */
+  rowWidth: number
+  /**
+   * Usable width of the strip container.
+   *
+   * Independent of whether the trigger is rendered — the container is sized by
+   * the layout above it, not by its own children.
+   */
+  containerWidth: number
+  /** Width the overflow trigger occupies when it is rendered. */
+  triggerWidth: number
+  /** Gap between the viewport and the trigger. */
+  triggerGap: number
+  /** Current horizontal scroll offset of the viewport. */
+  scrollLeft: number
+}
+
+export interface StripState {
+  /** Whether the row needs the scrolling viewport and the overflow trigger. */
+  overflowing: boolean
+  /** Width available to the scrolling viewport. */
+  viewportWidth: number
+  /** Whether the viewport is scrolled fully left (hides the leading fade). */
+  atStart: boolean
+  /** Whether the viewport is scrolled fully right (hides the trailing fade). */
+  atEnd: boolean
+}
+
+export interface RevealMeasurements {
+  viewportWidth: number
+  scrollLeft: number
+  /** The tab's offset from the start of the row. */
+  tabOffsetLeft: number
+  tabWidth: number
+  rowWidth: number
+  padding?: number
+}
+
+/**
+ * Resolve whether the strip overflows, and where it sits within its scroll
+ * range.
+ *
+ * Overflow is decided against the bare container, and deliberately takes no
+ * account of the trigger: a row that fits the container fits, and reserving
+ * the trigger's width first would summon a menu for tabs that were never cut
+ * off. The trigger is subtracted only afterwards, to size the viewport it now
+ * shares the container with.
+ *
+ * That ordering is also what keeps the result stable. The trigger's presence
+ * changes the viewport but never `containerWidth` — which the layout above
+ * sets — and never `rowWidth`, which the row holds at `max-content`. So the
+ * overflow answer cannot feed back into its own inputs.
+ */
+export function computeStripState({
+  rowWidth,
+  containerWidth,
+  triggerWidth,
+  triggerGap,
+  scrollLeft,
+}: StripMeasurements): StripState {
+  // A container with no measured width has not been laid out yet. Reporting
+  // overflow here would flash a trigger onto the first paint.
+  const measured = containerWidth > 0
+  const overflowing = measured && rowWidth > containerWidth
+
+  if (overflowing === false) {
+    return {
+      overflowing: false,
+      viewportWidth: Math.max(0, containerWidth),
+      atStart: true,
+      atEnd: true,
+    }
+  }
+
+  const viewportWidth = Math.max(0, containerWidth - triggerWidth - triggerGap)
+  const maxScroll = Math.max(0, rowWidth - viewportWidth)
+
+  return {
+    overflowing: true,
+    viewportWidth,
+    atStart: scrollLeft <= EDGE_EPSILON,
+    atEnd: scrollLeft >= maxScroll - EDGE_EPSILON,
+  }
+}
+
+/**
+ * The scroll offset that brings one tab into view, or `null` when the tab is
+ * already visible and the viewport should be left untouched.
+ *
+ * Returning `null` rather than the current offset is the point: this runs on
+ * selection and on focus, and writing `scrollLeft` unconditionally would
+ * cancel a scroll the reader is in the middle of.
+ */
+export function computeRevealScroll({
+  viewportWidth,
+  scrollLeft,
+  tabOffsetLeft,
+  tabWidth,
+  rowWidth,
+  padding = DEFAULT_REVEAL_PADDING,
+}: RevealMeasurements): number | null {
+  const maxScroll = Math.max(0, rowWidth - viewportWidth)
+  const clamp = (value: number) => Math.min(Math.max(value, 0), maxScroll)
+
+  const leadingEdge = tabOffsetLeft - padding
+  const trailingEdge = tabOffsetLeft + tabWidth + padding
+
+  let next: number
+
+  if (tabWidth + padding * 2 >= viewportWidth) {
+    // The tab is wider than the viewport, so it cannot be framed. Align its
+    // start: aligning the end would push the beginning of the label — the part
+    // that identifies it — off the left of the viewport.
+    next = leadingEdge
+  } else if (leadingEdge < scrollLeft) {
+    next = leadingEdge
+  } else if (trailingEdge > scrollLeft + viewportWidth) {
+    next = trailingEdge - viewportWidth
+  } else {
+    return null
+  }
+
+  const clamped = clamp(next)
+  return clamped === scrollLeft ? null : clamped
+}

package/src/presentation/tabs.module.css

@@ -1,31 +1,149 @@
 /**
  * Tabs — navigation bar for admin form layouts.
  *
+ * The strip is a scrolling viewport plus an overflow trigger that appears only
+ * when the tabs exceed the column. `--byline-admin-tabs-trigger-size` and
+ * `--byline-admin-tabs-trigger-gap` are set on the element by tabs.tsx, so the
+ * trigger is laid out from the same numbers the overflow geometry reserves
+ * space with.
+ *
  * Override handles:
- *   .byline-admin-tabs        — the tablist container
- *   .byline-admin-tab         — each tab button
- *   .byline-admin-tab-active  — added when the tab is the active one
- *   .byline-admin-tab-label   — the inner label span (with optional badge)
- *   .byline-admin-tab-badge   — the inline error-count badge
+ *   .byline-admin-tabs                   — the strip container
+ *   .byline-admin-tabs-viewport          — the horizontally scrolling viewport
+ *   .byline-admin-tablist                — the tablist row inside the viewport
+ *   .byline-admin-tab                    — each tab button
+ *   .byline-admin-tab-active             — added when the tab is the active one
+ *   .byline-admin-tab-label              — the inner label span (with optional badge)
+ *   .byline-admin-tab-badge              — the inline error-count badge
+ *   .byline-admin-tabs-overflow-trigger  — the "all tabs" menu button
+ *   .byline-admin-tabs-overflow-icon     — the icon inside that button
+ *   .byline-admin-tabs-overflow-menu     — the menu popup
+ *   .byline-admin-tabs-overflow-item     — each menu item
  */
 
 .tabs,
 :global(.byline-admin-tabs) {
+  position: relative;
   display: flex;
+  align-items: stretch;
+  gap: var(--byline-admin-tabs-trigger-gap, 12px);
+}
+
+/* The strip's hairline, drawn as a pseudo-element rather than a border so it
+   spans the viewport and the trigger together and so the active tab's 2px
+   underline can paint over it. */
+.tabs::after,
+:global(.byline-admin-tabs)::after {
+  content: "";
+  position: absolute;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  z-index: 0;
+  height: var(--border-width-thin);
+  background-color: var(--gray-200);
+}
+
+.viewport,
+:global(.byline-admin-tabs-viewport) {
+  position: relative;
+  z-index: 1;
+  flex: 1 1 auto;
+  /* A flex item refuses to shrink below its content's min-content width
+     unless told otherwise, which would push the row past the column instead
+     of scrolling it. */
+  min-width: 0;
+  overflow-x: auto;
+  overflow-y: hidden;
+  /* Stops a horizontal flick or trackpad swipe at either end of the strip
+     from chaining into the browser's back/forward navigation. */
+  overscroll-behavior-x: contain;
+  scrollbar-width: none;
+}
+
+.viewport::-webkit-scrollbar,
+:global(.byline-admin-tabs-viewport)::-webkit-scrollbar {
+  display: none;
+}
+
+/* Drag-to-scroll affordance. Only an overflowing strip has anywhere to go, so
+   only an overflowing strip offers the grab cursor. The tabs keep their own
+   pointer cursor, so they still read as clickable. */
+.viewport[data-draggable="true"],
+:global(.byline-admin-tabs-viewport)[data-draggable="true"] {
+  cursor: grab;
+}
+
+.viewport[data-dragging="true"],
+:global(.byline-admin-tabs-viewport)[data-dragging="true"] {
+  cursor: grabbing;
+  /* Suppress text selection for the duration: without this a drag across the
+     labels selects them, and the selection highlight follows the pointer. */
+  user-select: none;
+  -webkit-user-select: none;
+}
+
+.viewport[data-dragging="true"] :global(.byline-admin-tab),
+:global(.byline-admin-tabs-viewport)[data-dragging="true"] :global(.byline-admin-tab) {
+  cursor: grabbing;
+}
+
+/* Edge fades, applied as a mask so they neither scroll with the content nor
+   need elements of their own. Each side is sized to zero unless that edge has
+   something beyond it, which tabs.tsx reports via the data attributes. */
+.viewport,
+:global(.byline-admin-tabs-viewport) {
+  --fade-start: 0px;
+  --fade-end: 0px;
+  -webkit-mask-image: linear-gradient(
+    to right,
+    transparent 0,
+    black var(--fade-start),
+    black calc(100% - var(--fade-end)),
+    transparent 100%
+  );
+  mask-image: linear-gradient(
+    to right,
+    transparent 0,
+    black var(--fade-start),
+    black calc(100% - var(--fade-end)),
+    transparent 100%
+  );
+}
+
+.viewport[data-at-start="false"],
+:global(.byline-admin-tabs-viewport)[data-at-start="false"] {
+  --fade-start: 1.5rem;
+}
+
+.viewport[data-at-end="false"],
+:global(.byline-admin-tabs-viewport)[data-at-end="false"] {
+  --fade-end: 1.5rem;
+}
+
+.tablist,
+:global(.byline-admin-tablist) {
+  /* `max-content` keeps the row at its intrinsic width whatever the viewport
+     is doing. A row that shrank to fit would report the viewport's width back
+     to the overflow geometry, which could then never detect overflow. It also
+     makes the row the offset parent the reveal arithmetic measures against. */
+  position: relative;
+  display: flex;
+  width: max-content;
   gap: var(--spacing-16);
-  border-bottom: var(--border-width-thin) var(--border-style-solid) var(--gray-200);
 }
 
 .tab,
 :global(.byline-admin-tab) {
   position: relative;
-  margin-bottom: -1px;
+  flex: none;
   padding: 0.625rem 0;
   border-bottom: 2px solid transparent;
   background: none;
   color: var(--gray-500);
   font-size: 1.1rem;
   font-weight: var(--font-weight-medium);
+  white-space: nowrap;
   cursor: pointer;
   transition:
     color 150ms ease,
@@ -39,9 +157,12 @@
   border-bottom-color: var(--gray-300);
 }
 
+/* An inset ring rather than an outset one: the viewport clips overflow, and an
+   outset focus ring on the first or last tab would be cut in half. */
 .tab:focus-visible,
 :global(.byline-admin-tab):focus-visible {
-  box-shadow: 0 0 0 2px var(--blue-500);
+  box-shadow: inset 0 0 0 2px var(--blue-500);
+  border-radius: var(--radius-sm, 3px);
 }
 
 .tab-active,
@@ -74,12 +195,73 @@
   font-size: 0.7rem;
 }
 
+.overflow-trigger,
+:global(.byline-admin-tabs-overflow-trigger) {
+  position: relative;
+  z-index: 1;
+  flex: none;
+  align-self: center;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--byline-admin-tabs-trigger-size, 32px);
+  height: var(--byline-admin-tabs-trigger-size, 32px);
+  padding: 0;
+  border: var(--border-width-thin) var(--border-style-solid) transparent;
+  border-radius: var(--radius-sm, 3px);
+  background: none;
+  color: var(--gray-500);
+  cursor: pointer;
+  transition:
+    color 150ms ease,
+    background-color 150ms ease;
+}
+
+.overflow-trigger:hover,
+:global(.byline-admin-tabs-overflow-trigger):hover {
+  color: var(--gray-800);
+  background-color: var(--gray-100);
+}
+
+.overflow-trigger:focus-visible,
+:global(.byline-admin-tabs-overflow-trigger):focus-visible {
+  outline: 2px solid var(--blue-500);
+  outline-offset: 1px;
+}
+
+.overflow-icon,
+:global(.byline-admin-tabs-overflow-icon) {
+  width: 1.125rem;
+  height: 1.125rem;
+}
+
+.overflow-menu,
+:global(.byline-admin-tabs-overflow-menu) {
+  min-width: 12rem;
+  max-height: 60vh;
+  overflow-y: auto;
+}
+
+.overflow-item,
+:global(.byline-admin-tabs-overflow-item) {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--spacing-8);
+}
+
+.overflow-item[data-active="true"],
+:global(.byline-admin-tabs-overflow-item)[data-active="true"] {
+  color: var(--primary-600);
+  font-weight: var(--font-weight-medium);
+}
+
 /* ─── Dark theme variants ───────────────────────────────────── */
 
 :is([data-theme="dark"], :global(.dark)) {
-  .tabs,
-  :global(.byline-admin-tabs) {
-    border-bottom-color: var(--gray-700);
+  .tabs::after,
+  :global(.byline-admin-tabs)::after {
+    background-color: var(--gray-700);
   }
 
   .tab,
@@ -104,4 +286,20 @@
     color: var(--primary-200);
     border-bottom-color: var(--primary-400);
   }
+
+  .overflow-trigger,
+  :global(.byline-admin-tabs-overflow-trigger) {
+    color: var(--gray-400);
+  }
+
+  .overflow-trigger:hover,
+  :global(.byline-admin-tabs-overflow-trigger):hover {
+    color: var(--gray-200);
+    background-color: var(--gray-800);
+  }
+
+  .overflow-item[data-active="true"],
+  :global(.byline-admin-tabs-overflow-item)[data-active="true"] {
+    color: var(--primary-200);
+  }
 }