Webdev 8458 migrate item navigator

[iisa]

WEBDEV-8458 Migrate item-navigator into elements

Migrates @internetarchive/iaux-item-navigator into the elements repo as a
production component (ia-item-navigator), upgraded to the elements CSS
convention, with a demo and tests.

Ticket: https://webarchive.jira.com/browse/WEBDEV-8458

What's included

The full upstream package — the navigator shell and both bundled menus:

• ia-item-navigator — the fullscreen-capable frame: named header/main
  slots for host content, a collapsible drawer driven by a menuContents
  provider array, a minimized menuShortcuts rail, responsive overlay/shift,
  loading spinner, and no-theater placeholder.
• ia-menu-slider, ia-menu-button, ia-itemnav-loader,
  ia-no-theater-available — the shell's internal pieces.
• ia-viewable-files-panel + ia-sort-files-button — the viewable-files
  menu (scrollable volume list, active-file highlighting, PDF flagging,
  tri-state title sort).
• ia-share-panel — social share links + copyable iframe/bbcode embed
  snippets.

Lives at src/elements/ia-item-navigator/; the navigator and its
consumer-facing menus are exported from src/elements/index.ts.

Key decisions

• Naming: adopted the elements ia-* convention across all elements (tags +
  IA* class names). Upstream used a mix of iaux-*, un-prefixed
  (menu-button), and Lit-2 Ia* casing.
• Dependencies — minimized: modal-manager and shared-resize-observer
  were type-only imports upstream, so they're replaced with local interfaces
  (interfaces/service-interfaces.ts) — zero runtime deps. The only new runtime
  dependency is @internetarchive/metadata-service (^1.0.6), which is
  genuinely used (new MetadataResponse(...) in the item attribute
  converter). All 11 icons are inlined as Lit templates instead of pulling
  in the @internetarchive/icon-* packages.
• CSS convention: public theming vars are exposed as --item-navigator-*
  with component-private --x-- aliases and inline defaults; themeStyles is
  imported per component; hardcoded colors that map to the shared palette now
  use tokens. Truly-internal styles stay plain CSS, per the styles guide.
• Sizing: the component is anchored to a self-contained 10px base
  (--item-navigator-base-font-size, default 10px) with em units, rather
  than depending on the consumer's root font-size. This reproduces petabox's
  10px scale — which the upstream demo assumed via a document-root font-size —
  without forcing a 10px root on the rest of the elements demo.

Notable changes vs. the source

• Bug fix: the menu toggle bound @click=${this.toggleMenu}, passing the
  click event as the forceValue argument and setting menuOpened to a
  PointerEvent (it only "worked" because the object is truthy). Now wrapped so
  menuOpened stays boolean.
• execCommand('copy') upgraded to the async Clipboard API in the share
  panel, with an execCommand fallback only where the async API is missing.
• ia-sort-files-button sorts a copy rather than mutating the reactive
  fileListRaw prop in place.
• Dropped a dead, never-rendered method from the viewable-files panel.

Demo

Added an ia-item-navigator story (auto-discovered, Production-Ready). Folds in
the useful examples from the upstream demo, kept self-contained (no
metadata-service fetch or external image hotlinks):

• a realistic multi-volume item (the "Master Book of American Folk Song")
  driving the viewable-files panel, with a long wrapping title and PDF entries;
• a slotted header bar and a styled theater mock, showing the header/main
  slots in use;
• the share panel and a populated shortcut rail;
• live theming controls plus loaded / view-available / header / fullscreen
  toggles (fullscreen renders an in-frame "Exit fullscreen" control).

Testing

• 47 Vitest browser-mode tests across the component (full repo suite: 211).
• Covers: drawer open/close + toggle-button behavior, provider rendering,
  responsive overlay↔shift, no-theater state, slot-change and fullscreen
  events, menu selection/escape handling, file listing + PDF flags + URL
  building, sort cycling, share-option population + embed snippets + copy note.
• npm run build, npm run lint, and the madge circular check all pass.
• Verified live in the demo (renders under Production-Ready, drawer toggles,
  viewable-files sorts, share links resolve, embed copy works, icon/text sizes
  measured at the intended 10px-base scale), with no console errors.

Notes for reviewers

• Consumers import via
  @internetarchive/elements/ia-item-navigator/ia-item-navigator.
• The navigator is a shell — it doesn't render any specific viewer; the host
  slots the theater into slot="main" and supplies menu panel bodies as
  TemplateResults, so no heavy viewer dependencies come along.
• The branch is 5 logically-scoped commits (migrate shell+viewable-files → add
  share → promote to elements → enrich demo → anchor sizing); happy to squash
  before merge if preferred.

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://internetarchive.github.io/elements/pr/pr-64/
Built to branch ghpages at 2026-07-20 21:14 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 82.60870% with 52 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.81%. Comparing base (cd1ffd3) to head (cd3b373).

Files with missing lines	Patch %	Lines
...rc/elements/ia-item-navigator/ia-item-navigator.ts	68.80%	30 Missing and 4 partials ⚠️
src/elements/ia-item-navigator/ia-menu-slider.ts	86.44%	1 Missing and 7 partials ⚠️
...ia-item-navigator/menus/ia-viewable-files-panel.ts	82.14%	4 Missing and 1 partial ⚠️
...elements/ia-item-navigator/menus/ia-share-panel.ts	94.87%	1 Missing and 1 partial ⚠️
...ts/ia-item-navigator/menus/ia-sort-files-button.ts	90.47%	0 Missing and 2 partials ⚠️
...ments/ia-item-navigator/ia-no-theater-available.ts	87.50%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #64      +/-   ##
==========================================
+ Coverage   78.62%   79.81%   +1.19%     
==========================================
  Files          17       27      +10     
  Lines         697      996     +299     
  Branches      189      250      +61     
==========================================
+ Hits          548      795     +247     
- Misses        100      136      +36     
- Partials       49       65      +16     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.