@internetarchive/collection-browser 4.7.0 → 4.8.0

package/docs/design/column-virtualization.md

@@ -0,0 +1,214 @@
+# Horizontal column virtualization with page snapping
+
+## Goal
+A Lit component that scrolls thousands of fixed-width data columns horizontally.
+Free scroll/fling during the gesture; on release, eases to the nearest page
+boundary. Only a window of pages is in the DOM at any time.
+
+## Constraints
+- Dataset is fully in memory (thousands of column entries). No fetching.
+- Column width is fixed and uniform. `colsPerPage` is derived from measured
+  viewport width, so a page is never wider than the viewport.
+- Lit + LitElement. Page count can reach the high hundreds.
+
+## Chosen approach
+Native scrolling over a full-width sizer, with absolutely positioned page
+elements at computed offsets, plus CSS scroll-snap for the page easing.
+Positions are pure arithmetic — no measurement, no size estimation.
+
+### Windowing controller
+```ts
+export class PageWindow implements ReactiveController {
+  first = 0;
+  last = -1;
+  private scroller?: HTMLElement;
+  private viewportW = 0;
+  private frame = 0;
+  private ro?: ResizeObserver;
+
+  constructor(
+    private host: ReactiveControllerHost,
+    private cfg: {colWidth: number; colsPerPage: number; total: number; buffer?: number}
+  ) {
+    host.addController(this);
+  }
+
+  get pageWidth() { return this.cfg.colWidth * this.cfg.colsPerPage; }
+  get pageCount() { return Math.ceil(this.cfg.total / this.cfg.colsPerPage); }
+  get totalWidth() { return this.cfg.colWidth * this.cfg.total; }
+
+  attach = (el?: Element) => {
+    if (!(el instanceof HTMLElement) || el === this.scroller) return;
+    this.scroller = el;
+    el.addEventListener('scroll', this.onScroll, {passive: true});
+    this.ro = new ResizeObserver(([e]) => {
+      this.viewportW = e.contentRect.width;
+      this.recompute();
+    });
+    this.ro.observe(el);
+  };
+
+  private onScroll = () => {
+    if (this.frame) return;
+    this.frame = requestAnimationFrame(() => {
+      this.frame = 0;
+      this.recompute();
+    });
+  };
+
+  private recompute() {
+    const pw = this.pageWidth;
+    const buf = this.cfg.buffer ?? 1;
+    const left = this.scroller!.scrollLeft;
+    const first = Math.max(0, Math.floor(left / pw) - buf);
+    const last = Math.min(this.pageCount - 1, Math.floor((left + this.viewportW) / pw) + buf);
+    if (first === this.first && last === this.last) return; // most scroll events end here
+    this.first = first;
+    this.last = last;
+    this.host.requestUpdate();
+  }
+
+  hostDisconnected() {
+    this.scroller?.removeEventListener('scroll', this.onScroll);
+    this.ro?.disconnect();
+    if (this.frame) cancelAnimationFrame(this.frame);
+  }
+}
+```
+
+### Template
+Snap alignment lives on permanent empty stubs, one per page, *not* on the
+rendered pages. See "Snap targets" below for why.
+```ts
+render() {
+  const w = this.win;
+  const all = [];
+  for (let i = 0; i < w.pageCount; i++) all.push(i);
+  const live = [];
+  for (let i = w.first; i <= w.last; i++) live.push(i);
+
+  return html`
+    <div class="scroller" ${ref(this.win.attach)}>
+      <div class="sizer" style="width:${w.totalWidth}px">
+        ${repeat(all, i => i, i => html`
+          <div class="snap-stub"
+               style="left:${i * w.pageWidth}px;width:${w.pageWidth}px"></div>`)}
+        ${repeat(live, i => i, i => html`
+          <div class="page"
+               style="left:${i * w.pageWidth}px;width:${w.pageWidth}px">
+            ${this.renderPage(i)}
+          </div>`)}
+      </div>
+    </div>`;
+}
+```
+
+### CSS
+```css
+.scroller {
+  overflow-x: auto;
+  overflow-y: hidden;
+  contain: strict;              /* requires explicit dimensions on .scroller */
+  scroll-snap-type: x mandatory;
+  /* scroll-snap-stop stays at its default `normal` so a fling can cross
+     many pages before resting. `always` would force one page per gesture. */
+}
+.sizer { position: relative; height: 100%; }
+.snap-stub {
+  position: absolute; top: 0; height: 100%;
+  scroll-snap-align: start;
+  pointer-events: none;
+  contain: strict;
+}
+.page {
+  position: absolute; top: 0; height: 100%;
+  contain: content;
+  content-visibility: auto;
+  contain-intrinsic-size: auto none;
+}
+```
+
+### Landed-page reporting
+```ts
+const onEnd = () => {
+  this.currentPage = Math.round(el.scrollLeft / this.win.pageWidth);
+};
+if ('onscrollend' in window) {
+  el.addEventListener('scrollend', onEnd);
+} else {
+  el.addEventListener('scroll', () => {
+    clearTimeout(this.endTimer);
+    this.endTimer = setTimeout(onEnd, 120);
+  }, {passive: true});
+}
+```
+
+## Invariants — do not "optimize" these away
+1. **The early-out in `recompute` must stay.** Scroll fires far more often than
+   the window changes. Re-render happens roughly once per page boundary
+   crossed, not once per scroll event.
+2. **Keyed `repeat()`, keyed by page index.** Switching to `map()` re-renders
+   every live page on each window shift instead of creating one and removing one.
+3. **Nothing reads layout in the scroll handler.** Viewport width comes from
+   `ResizeObserver` only. No `getBoundingClientRect` on the scroll path.
+4. **Cells are plain DOM inside a page component.** Do not make each cell its
+   own custom element — element upgrade plus shadow-root creation will dominate
+   every other cost here.
+
+## Snap targets
+The browser re-evaluates its snap target continuously as a fling decelerates.
+If the target box isn't mounted, or gets unmounted by a window shift
+mid-fling, the result is a visible jump or a landing on the wrong boundary —
+intermittent, and only on fast flings. The stubs decouple snap geometry from
+virtualization: they always exist, so the geometry is always complete. Empty,
+contained, childless divs cost very little.
+
+If page count ever reaches the tens of thousands, flip to the alternative:
+move `scroll-snap-align` onto `.page`, and defer *shrinking* the window until
+`scrollend` so a selected target is never unmounted while scrolling.
+
+## Rejected alternatives (with reasons — do not substitute)
+- **`@lit-labs/virtualizer`** — works horizontally via
+  `flow({direction: 'horizontal'})`, but its value is measuring items of
+  unknown size, which is exactly what we don't need. Still 0.7.x under the
+  `@lit-labs` scope and self-described as late prerelease. Documented
+  Chromium flow-layout jank from correcting size estimates during smooth
+  scroll (maintainers say unfixable without replacing native scrolling with
+  JS scrolling), plus a Safari first-render transform bug
+  (https://github.com/lit/lit/issues/3243). Both stem from estimation.
+- **TanStack Virtual** — good library, correct fallback *if column widths ever
+  become variable*. Unnecessary overhead while widths are uniform.
+- **`content-visibility: auto` alone** — skips layout/paint for offscreen
+  pages but still creates all DOM. Used here as a second layer on top of
+  windowing, not as a replacement.
+- **JS-animated `scrollLeft`** — the only way to control snap easing, but it
+  costs compositor-driven smoothness. Ship native snap first.
+
+## Browser support notes
+- Scroll snap: Baseline widely available since 2022 (Chrome 69, Firefox 68,
+  Safari 11).
+- `scrollend`: Baseline since Dec 2025 (Chrome 114, Firefox 109, Safari 26.2).
+  Feature-detect with the timer fallback above if the support floor includes
+  older Safari.
+- `content-visibility`: Baseline 2024 (Chrome 85, Firefox 125, Safari 18);
+  the web-features entry is more conservative about Safari. Treat as
+  progressive enhancement — unsupported browsers just render everything.
+- `scrollsnapchanging` (fires when the browser decides where it *will* land,
+  useful for a live page indicator mid-fling): Chromium-only, Chrome 129+,
+  no Firefox or Safari. Optional enhancement over the `scrollend` path only.
+
+## Acceptance criteria
+- [ ] Scrolling the full dataset keeps live page elements at `2*buffer + visible`;
+      verify in DevTools that DOM node count stays flat.
+- [ ] Performance profile during a sustained fling shows no layout thrash and
+      re-render count proportional to pages crossed, not scroll events.
+- [ ] Release mid-page always eases to a page boundary — test slow drag, fast
+      fling across 50+ pages, trackpad, mouse wheel, and keyboard.
+- [ ] Verified in Safari specifically (snap and first-render behavior).
+- [ ] Resize recomputes `colsPerPage` and the window without losing position.
+- [ ] `currentPage` is correct after every rest, including programmatic scrolls.
+
+## Deferred
+Page-element recycling (fixed slot pool, `pageIndex % N`, update data and
+`left` in place). Only pursue if a profile shows element *creation* cost
+during flings. Not needed up front.

package/package.json

@@ -3,13 +3,29 @@
   "description": "The Internet Archive Collection Browser.",
   "license": "AGPL-3.0-only",
   "author": "Internet Archive",
-  "version": "4.7.0",
+  "version": "4.8.0",
   "main": "dist/index.js",
   "module": "dist/index.js",
+  "packageManager": "pnpm@11.27.1",
   "engines": {
     "node": ">=22",
     "pnpm": ">=11"
   },
+  "scripts": {
+    "start": "vite",
+    "prepare:ghpages": "rimraf ghpages && pnpm run prepare && vite build",
+    "prepare": "rimraf dist && tsc && husky install",
+    "lint": "eslint . && prettier \"**/*.ts\" --check",
+    "format": "eslint . --fix && prettier \"**/*.ts\" --write",
+    "circular": "madge --circular --extensions ts .",
+    "test": "tsc && pnpm run lint && pnpm run circular && wtr --coverage",
+    "test:fast": "tsc && wtr --coverage",
+    "test:watch": "tsc && concurrently -k -r \"tsc --watch --preserveWatchOutput\" \"wtr --watch\"",
+    "deploy": "pnpm run deploy:run -e $(git branch --show-current)",
+    "deploy:run": "pnpm run prepare:ghpages && touch ghpages/.nojekyll && pnpm run deploy:gh",
+    "deploy:gh": "gh-pages -t -d ghpages -m \"Build for $(git log --pretty=format:\"%h %an %ai %s\" -n1) [skip ci]\"",
+    "typecheck": "tsc --noEmit"
+  },
   "types": "dist/index.d.ts",
   "dependencies": {
     "@a11y/focus-trap": "^1.0.5",
@@ -17,6 +33,7 @@
     "@internetarchive/elements": "^1.1.0",
     "@internetarchive/feature-feedback": "^1.0.0",
     "@internetarchive/field-parsers": "^1.0.0",
+    "@internetarchive/ia-clearable-text-input": "^1.2.0",
     "@internetarchive/ia-dropdown": "^2.0.0",
     "@internetarchive/iaux-item-metadata": "^1.0.5",
     "@internetarchive/infinite-scroller": "^2.0.0",
@@ -45,6 +62,7 @@
     "@web/dev-server": "^0.4.6",
     "@web/dev-server-rollup": "^0.6.4",
     "@web/test-runner": "^0.20.0",
+    "@web/test-runner-commands": "^0.9.0",
     "concurrently": "^9.1.2",
     "eslint": "^9.22.0",
     "eslint-config-prettier": "^10.1.1",
@@ -108,19 +126,5 @@
       "eslint --fix",
       "prettier --write"
     ]
-  },
-  "scripts": {
-    "start": "vite",
-    "prepare:ghpages": "rimraf ghpages && pnpm run prepare && vite build",
-    "lint": "eslint . && prettier \"**/*.ts\" --check",
-    "format": "eslint . --fix && prettier \"**/*.ts\" --write",
-    "circular": "madge --circular --extensions ts .",
-    "test": "tsc && pnpm run lint && pnpm run circular && wtr --coverage",
-    "test:fast": "tsc && wtr --coverage",
-    "test:watch": "tsc && concurrently -k -r \"tsc --watch --preserveWatchOutput\" \"wtr --watch\"",
-    "deploy": "pnpm run deploy:run -e $(git branch --show-current)",
-    "deploy:run": "pnpm run prepare:ghpages && touch ghpages/.nojekyll && pnpm run deploy:gh",
-    "deploy:gh": "gh-pages -t -d ghpages -m \"Build for $(git log --pretty=format:\"%h %an %ai %s\" -n1) [skip ci]\"",
-    "typecheck": "tsc --noEmit"
   }
-}
+}

package/src/app-root.ts

@@ -1052,9 +1052,7 @@ export class AppRoot extends LitElement {
       --modalBorder: 2px solid var(--primaryButtonBGColor, #194880);
       --modalTitleLineHeight: 4rem;
       --modalTitleFontSize: 1.8rem;
-      --modalCornerRadius: 0;
       --modalBottomPadding: 0;
-      --modalBottomMargin: 0;
       --modalScrollOffset: 0;
       --modalCornerRadius: 0.5rem;
     }

package/src/assets/img/icons/check.ts

@@ -0,0 +1,5 @@
+import { svg } from 'lit';
+
+export default svg`
+<svg viewBox="0 0 100 100" xmlns="http://www.w3.org/2000/svg"><path d="m14 53 24 24 48-52" fill="none" stroke="currentColor" stroke-width="14" stroke-linecap="round" stroke-linejoin="round"/></svg>
+`;

package/src/collection-facets/facet-row-template.ts

@@ -0,0 +1,242 @@
+import { css, html, nothing, TemplateResult } from 'lit';
+import eyeIcon from '../assets/img/icons/eye';
+import eyeClosedIcon from '../assets/img/icons/eye-closed';
+import type { FacetOption, FacetBucket, FacetState } from '../models';
+import type { CollectionTitles } from '../data-source/models';
+
+export type FacetRowTemplateOptions = {
+  /** The name of the facet group to which this facet belongs (e.g., "mediatype") */
+  facetType: FacetOption;
+
+  /** The facet bucket containing details about the state, count, and key for this row */
+  bucket: FacetBucket;
+
+  /** The collection name cache for converting collection identifiers to titles */
+  collectionTitles?: CollectionTitles;
+
+  /**
+   * Whether to omit the negative/hide button from this facet row if possible.
+   * Has no effect if the facet bucket is itself hidden, in which case the hide
+   * button *must* be shown to represent the state accurately.
+   */
+  omitHideButton?: boolean;
+
+  /**
+   * Called when either checkbox is clicked. Leave it out when an ancestor
+   * handles the rows' clicks by delegation instead.
+   */
+  onCheckboxClick?: (e: Event, negative: boolean) => void;
+};
+
+/**
+ * Returns the composed facet state corresponding to a positive or negative facet's checked state
+ */
+export function getFacetState(checked: boolean, negative: boolean): FacetState {
+  if (!checked) return 'none';
+  return negative ? 'hidden' : 'selected';
+}
+
+/**
+ * Template for a full facet row, including the positive/negative checks,
+ * the display name, and the count. The row is plain DOM so that long lists
+ * (e.g. the More... dialog) can render many rows without creating an
+ * element per row. Render it inside a shadow root that includes
+ * `facetRowStyles`.
+ */
+export function facetRowTemplate({
+  facetType,
+  bucket,
+  collectionTitles,
+  omitHideButton = false,
+  onCheckboxClick,
+}: FacetRowTemplateOptions): TemplateResult {
+  const showOnlyCheckboxId = `${facetType}:${bucket.key}-show-only`;
+  const negativeCheckboxId = `${facetType}:${bucket.key}-negative`;
+
+  const extraNoteSpan = bucket.extraNote
+    ? html`<span class="facet-note">${bucket.extraNote}</span>`
+    : nothing;
+
+  // For collections, we render the collection title as a link.
+  // For other facet types, we just have a static value to use.
+  const bucketTextDisplay =
+    facetType !== 'collection'
+      ? html`${bucket.displayText ?? bucket.key} ${extraNoteSpan}`
+      : html`<a href="/details/${bucket.key}">
+          ${collectionTitles?.get(bucket.key) ?? bucket.key}
+        </a> `;
+
+  const bucketCountText = bucket.count > 0 ? bucket.count.toLocaleString() : '';
+
+  const facetHidden = bucket.state === 'hidden';
+  const facetSelected = bucket.state === 'selected';
+
+  const titleText = `${facetType}: ${bucket.displayText ?? bucket.key}`;
+  const onlyShowText = facetSelected
+    ? `Show all ${facetType}s`
+    : `Only show ${titleText}`;
+  const hideText = `Hide ${titleText}`;
+  const unhideText = `Unhide ${titleText}`;
+  const showHideText = facetHidden ? unhideText : hideText;
+  const ariaLabel = `${titleText}, ${bucket.count} results`;
+
+  const showOnlyClicked = onCheckboxClick
+    ? (e: Event) => onCheckboxClick(e, false)
+    : undefined;
+  const hideClicked = onCheckboxClick
+    ? (e: Event) => onCheckboxClick(e, true)
+    : undefined;
+
+  // Added data-testid for Playwright testing
+  return html`
+    <div class="facet-row-container">
+      <div class="facet-checkboxes">
+        <input
+          type="checkbox"
+          .name=${facetType}
+          .value=${bucket.key}
+          @click=${showOnlyClicked}
+          .checked=${facetSelected}
+          class="select-facet-checkbox"
+          title=${onlyShowText}
+          id=${showOnlyCheckboxId}
+          data-testid=${showOnlyCheckboxId}
+        />
+        <div
+          class="hide-facet-container"
+          ?hidden=${omitHideButton && !facetHidden}
+        >
+          <input
+            type="checkbox"
+            id=${negativeCheckboxId}
+            .name=${facetType}
+            .value=${bucket.key}
+            @click=${hideClicked}
+            .checked=${facetHidden}
+            class="hide-facet-checkbox"
+          />
+          <label
+            for=${negativeCheckboxId}
+            class="hide-facet-icon${facetHidden ? ' active' : ''}"
+            title=${showHideText}
+            data-testid=${negativeCheckboxId}
+          >
+            <span class="sr-only">${showHideText}</span>
+            <span class="eye eye-open">${eyeIcon}</span>
+            <span class="eye eye-closed">${eyeClosedIcon}</span>
+          </label>
+        </div>
+      </div>
+      <label
+        for=${showOnlyCheckboxId}
+        class="facet-info-display"
+        title=${onlyShowText}
+        aria-label=${ariaLabel}
+      >
+        <div class="facet-title">${bucketTextDisplay}</div>
+        <div class="facet-count">${bucketCountText}</div>
+      </label>
+    </div>
+  `;
+}
+
+const facetRowBorderTop = css`var(--facet-row-border-top, 1px solid transparent)`;
+const facetRowBorderBottom = css`var(--facet-row-border-bottom, 1px solid transparent)`;
+const checkboxHeight = css`15px`;
+
+/**
+ * Styles for `facetRowTemplate`. Include `srOnlyStyle` alongside these.
+ */
+export const facetRowStyles = css`
+  .facet-checkboxes {
+    margin: 0 5px 0 0;
+    display: flex;
+    height: ${checkboxHeight};
+  }
+  .facet-checkboxes input:first-child {
+    margin-right: 5px;
+  }
+  .facet-checkboxes input {
+    height: ${checkboxHeight};
+    width: ${checkboxHeight};
+    margin: 0;
+  }
+  .facet-row-container {
+    display: flex;
+    font-weight: 500;
+    font-size: 1.2rem;
+    margin: 0 auto;
+    padding: 0.25rem 0;
+    height: auto;
+    border-top: ${facetRowBorderTop};
+    border-bottom: ${facetRowBorderBottom};
+  }
+  .facet-info-display {
+    display: flex;
+    flex: 1 1 0%;
+    cursor: pointer;
+    flex-wrap: wrap;
+  }
+  .facet-title {
+    word-break: break-word;
+    display: inline-block;
+    flex: 1 1 0%;
+  }
+  .facet-note {
+    color: #bbb;
+  }
+  .facet-count {
+    text-align: right;
+  }
+  .select-facet-checkbox {
+    cursor: pointer;
+    display: inline-block;
+  }
+  .hide-facet-checkbox {
+    position: absolute;
+    clip: rect(0, 0, 0, 0);
+    pointer-events: none;
+  }
+  .hide-facet-checkbox:focus-visible + .hide-facet-icon {
+    outline-style: auto;
+    outline-offset: 2px;
+  }
+  .hide-facet-icon {
+    width: ${checkboxHeight};
+    height: ${checkboxHeight};
+    cursor: pointer;
+    display: flex;
+  }
+  .eye {
+    width: ${checkboxHeight};
+    height: ${checkboxHeight};
+    opacity: 0.3;
+  }
+  .hide-facet-icon:hover .eye,
+  .active .eye {
+    opacity: 1;
+  }
+  .hide-facet-icon:hover .eye-open,
+  .hide-facet-icon .eye-closed {
+    display: none;
+  }
+  .hide-facet-icon:hover .eye-closed,
+  .hide-facet-icon.active .eye-closed {
+    display: inline;
+  }
+  .hide-facet-icon.active .eye-open {
+    display: none;
+  }
+  .sorting-icon {
+    cursor: pointer;
+  }
+
+  a:link,
+  a:visited {
+    text-decoration: none;
+    color: var(--ia-theme-link-color, #4b64ff);
+  }
+  a:hover {
+    text-decoration: underline;
+  }
+`;