WEBDEV-8458 Migrate item-navigator into elements

[iisa]

WEBDEV-8458 Migrate item-navigator into elements

Ports @internetarchive/iaux-item-navigator into elements as ia-item-navigator, re-styled to the elements CSS conventions, with a live demo and full test coverage.

• Ticket: https://webarchive.jira.com/browse/WEBDEV-8458
• Demo: https://internetarchive.github.io/elements/pr/pr-64/#elem-ia-item-navigator
• All elements in this PR: https://internetarchive.github.io/elements/pr/pr-64/
• Current main: https://internetarchive.github.io/elements/

What ships

A fullscreen-capable shell — header/main slots, a drawer driven by a menuContents provider array, a minimized menuShortcuts rail, overlay/shift at 600px — plus its internals (ia-itemnav-menu-slider, -menu-button, -no-theater-available) and two bundled menus: -viewable-files-panel with -sort-files-button (volume list, active-file highlight, PDF flagging, tri-state sort) and -share-panel (social links, copyable iframe/bbcode embeds).

Lives at src/elements/ia-item-navigator/, exported from src/elements/index.ts.

Key decisions

• Sub-elements are namespaced under ia-itemnav- — tags, files and classes. Not cosmetic: upstream registers ia-menu-slider, ia-itemnav-loader and ia-no-theater-available verbatim, and elements re-exports the navigator from its root barrel — so any @internetarchive/elements import would register those twice and throw NotSupportedError at module evaluation while consumers still load the old package.
• Icons are assets, not bundle. 14 standalone .svg files — ~18KB of path data out of the JS bundle — drawn through a maskedIcon() helper so they stay recolorable.
• No dependencies added. Not one. The navigator now takes a dependency only where it constructs or calls something, and neither of the two it inherited survived that test — see below.
• The loading spinner is gone. loaded still gates the reader; an indicator returns on WEBDEV-8951.
• Sizing anchors to a self-contained 10px base in em, matching petabox's scale without forcing a 10px root on the demo.

Dependencies: both inherited ones removed

Reviewing the two type-shaped dependencies turned up the same answer twice, for different reasons.

@internetarchive/metadata-service is gone. It sat in dependencies, so every consumer of this package installed it — plus field-parsers, iaux-item-metadata, result-type and typescript-memoize — whether or not they touched the navigator. It was used for exactly one field, item.metadata.identifier, which is the one field upstream deliberately leaves unwrapped because it can only ever be a string. So item is now identifier: string.

The property is renamed, not just retyped, so a consumer still passing an object gets an unknown property and fails visibly rather than quietly supplying a shape the navigator can't read. It also matches the child element, which already declared identifier.

The shared resize observer is gone too — the whole concept, not just the type. The navigator required a host-injected observer for two things, and neither needed JavaScript. Details below.

Panel open/close semantics

The navigator owns whether the drawer and a panel are open. The slider reports what the user did and renders what comes back — one copy of the state, in one place.

That makes each surface mean what it says:

• Closed means closed. A closed panel is inert, so tab order and the accessibility tree match the screen, and aria-expanded reports what's actually open.
• Focus follows state — into a surface when it opens, back to whatever opened it when it closes, including from the shortcut rail.
• Closing the drawer closes its panel, so nothing stale reappears on the next open.
• Opening straight to a panel is one movement — the drawer carries the panel in rather than both sliding.
• The scroll reacts to the file list or selection changing, so it waits on nothing. That also covers two cases it previously missed: bookreader reuses one panel element, so firstUpdated fired only on the first open; offshoot reuses it on a file click, so the active row could move without the panel following.

None of this was modelled before. The navigator held menuOpened/openMenu while the slider held its own selectedMenu, plus open and animateMenuOpen. Since menuTypeSelected is composed, selecting a channel toggled both copies independently and the navigator then overwrote the slider's — they agreed only because the two toggle expressions happened to match. A static attribute set slider.open once, so it stayed true forever; nothing ever set animateMenuOpen, so .animate never fired. With no single fact to react to, the scroll had to guess when layout would settle — which is where a 350ms timer came from.

Transitions themselves didn't change; they follow the state flip now instead of being something to schedule around.

Layout drives the breakpoint

The host used to inject a shared resize observer. It fed two things:

The overlay/shift breakpoint is a container query now. It keys off the frame's own width exactly as before — a narrow navigator inside a wide page still overlays — but the browser evaluates it during layout rather than in a callback. openMenuState and the overlay/shift classes are gone; shift is the default and the query overrides it.

The header-slot registration was worse than redundant. It re-rendered so render() could measure the slotted header's offsetHeight and write it back as an inline height. offsetHeight excludes margins, so a header with vertical margins was pinned shorter than its own box and its bottom margin overlapped the reader — clipped rather than visibly broken, since the frame hides overflow. Removing the measurement lets the slot size itself, margins included, which fixes that bug.

Removing the registrations also removed a leak they carried: the slot's handler was an anonymous object built fresh on every call, so nothing could ever remove it. It survived both disconnect and observer swaps, holding a detached element against the host's long-lived singleton.

sharedObserver and service-interfaces.ts go with it, so hosts supply nothing. Consumers still setting the property are unaffected — an unknown property on a Lit element is a no-op.

Theming

17 public knobs, each with a private --x-- alias and an inline default. All prefixed --item-navigator-:

• Sizing — base-font-size 10px · menu-width 320px · menu-margin 42px · animation-timing 200ms · icon-size 2.4em · header-icon-size 2em · menu-button-label-display none
• Color — text-color var(--true-white) · icon-color and icon-active-color → text color · icon-inactive-color var(--lighter-gray) · border-color #4b4b4b · active-file-border-color #538bc5
• Surfaces — theater-bg-color #000 · menu-slider-bg #212121 · active-button-bg var(--mid-gray) · share-embed-bg #151515

Review responses

Ask	Resolution
Externalize the icon SVGs	✅ 14 .svg files, ~18KB of path data out of the bundle
Scope element names to the component	✅ ia-itemnav-* across tags, files, classes
350ms scroll timeout feels code-smelly	✅ symptom, not cause — panel state drives it now
Does render() need the html wrapper?	✅ no — signature widened, branch returns directly
CustomTheaterInterface overreaches; how does it meet offshoot's <ia-theater>?	✅ deleted — dead code, already dead upstream; unrelated to offshoot's theater
What happens with the actual ModalManager?	✅ nothing — never read, so removed
What happens with the actual SharedResizeObserver?	✅ moot — the navigator no longer uses one
Import the resize-observer type from its package	✅ moot — same reason; service-interfaces.ts is deleted
How does ia-no-theater-available meet offshoot's?	⬜ deferred — legacy from the port, still live in petabox

Demo & QA

Demo: https://internetarchive.github.io/elements/pr/pr-64/#elem-ia-item-navigator — toggles under Settings, theming under Import, Usage & Settings.

Shell — theater + header render; Header off hides the bar; View available off shows the placeholder with the right identifier; Loaded off leaves the frame empty (no spinner); Fullscreen fills the viewport with an in-frame Exit.

Drawer and panels

• ⋯ opens/closes the drawer; while closed, Tab doesn't enter it.
• A rail shortcut opens straight to that panel as one movement, not two slides.
• With the drawer open, clicking between panels swaps them; only the empty↔panel edges animate.
• ✕ closes the panel and leaves the drawer open; Esc closes panel first, then drawer.
• Focus lands in a panel on open and returns to the control that opened it on close.
• A closed panel hides completely — nothing behind the left-flush icons — and closing the drawer clears it, so reopening shows no stale panel.

Menus

• Viewable Files: titles wrap, PDF tagged, active file highlighted and scrolled into view; sort cycles neutral→asc→desc; selecting a file swaps the theater.
• Share: links open real URLs; embed field copies and flashes "Copied".

Responsive — narrow the browser: above 600px the theater eases in sync with the drawer and stays flush to its edge; below 600px the drawer overlays a full-width theater. Because this is a container query it tracks the component's width, so resizing the demo frame works as well as resizing the window.

Header — a slotted header with vertical margins should sit fully above the theater, with no clipping where the two meet.

Theming — the four sliders and ten color pickers update live and name the var each sets; base font size scales the whole component, icons included (evidence the aliases are wired, not just declared); palettes apply and Reset restores defaults.

Animation off — the check that matters most here. Set Animate off (--item-navigator-animation-timing: 0ms) and repeat the drawer-and-panel checks. Everything holds, which is the evidence nothing times against the transition.

Automated — pnpm test (110 navigator tests of 304), pnpm run build and the madge circular check pass. The navigator covers 100% of lines and functions, 97% of branches.

Follow-ups (tracked, out of scope)

• WEBDEV-8796 / #66 — shared dark-surface tokens for the near-blacks, border and scrim with no house equivalent.
• WEBDEV-8951 — offshoot's status indicators into elements; the loading indicator returns on top of it.
• WEBDEV-8952 — swap bookreader to the elements navigator.

Consumer note

Two breaking changes land here, both free while the component is unreleased, and both already on the migration tickets:

• item → identifier, and the two consumers need different fixes. bookreader holds a MetadataResponse and wants .metadata.identifier; offshoot passes public_metadata, a Metadata, and wants .identifier directly — which is a live bug today, since .metadata is absent there and the placeholder never receives an identifier.
• sharedObserver is no longer read. Consumers can drop the binding; leaving it in place is harmless.

[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-08-27 23:53 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 90.67797% with 33 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.60%. Comparing base (8c054a6) to head (30de5d1).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
...ments/ia-item-navigator/ia-item-navigator-story.ts	62.00%	13 Missing and 6 partials ⚠️
demo/story-components/story-styles-settings.ts	73.52%	0 Missing and 9 partials ⚠️
...ements/ia-item-navigator/ia-itemnav-menu-slider.ts	94.44%	0 Missing and 3 partials ⚠️
demo/story-template.ts	0.00%	1 Missing ⚠️
...rc/elements/ia-item-navigator/ia-item-navigator.ts	98.88%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #64      +/-   ##
==========================================
+ Coverage   81.12%   84.60%   +3.48%     
==========================================
  Files          27       38      +11     
  Lines         927     1273     +346     
  Branches      227      303      +76     
==========================================
+ Hits          752     1077     +325     
- Misses        113      115       +2     
- Partials       62       81      +19     

☔ 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.

[jbuckner]

Can we move these into standalone svg files so we're not packaging them as part of the JS bundle?

[iisa]

moved them to standalone .svg files — rendered with mask-image so they stay recolorable.

[jbuckner]

Can we import this from @internetarchive/shared-resize-observer instead of re-creating it?

[iisa]

totally!

[jbuckner]

Can we scope the name of all of the elements, ie ia-itemnav-* since they're going to exist in the global namespace and externalize all of the svgs so they don't inflate the size of the JS bundle?

[iisa]

@jbuckner thanks for the review — pushed a batch addressing most of it. Replies are on the individual threads; summary here.

Addressed

Externalized the SVGs (7962444) — all 13 glyphs are standalone .svg files now, ~18KB of path data out of the JS bundle, verified gone from the emitted dist. They render via a small maskedIcon() helper using mask-image + background-color rather than <img src>: these icons are recolored through --item-navigator-icon-color and the active/inactive states, and an <img> can't be recolored. The original .fill-color rules are kept alongside, so inline-<svg> icons a consumer passes in (bookreader's bookmarks/search/downloads providers) keep theming with no change on their side. The loader's book/ring stays inline — a mask can't animate the spinning sub-path.

Scoped the element names (dceca7a) — sub-elements are now ia-itemnav-*, with files and classes following the tags. This turned out to be more than hygiene: @internetarchive/ia-item-navigator registers ia-menu-slider, ia-itemnav-loader and ia-no-theater-available verbatim, and since we re-export the navigator from the root barrel, any @internetarchive/elements import would have registered those a second time and thrown NotSupportedError at module evaluation while consumers still load the old package. The loader became ia-itemnav-loading-view because the prefixed name is the one upstream already owns.

Each element now declares its tag in HTMLElementTagNameMap, so querySelector is typed and a mistyped tag in a template fails the build instead of silently rendering an inert element — there was no such check before. A test asserts the new names are registered and the old ones left free, so a half-finished rename can't pass quietly. I also added a short naming note to the README, since it only documented directory layout.

Dropped the modal manager (8cba8d4) — the navigator accepted modal and never read it, and nothing read it back out: bookreader's providers get the modal directly via baseProviderConfig, bypassing the navigator. It's unused upstream too. ModalManagerInterface went with it, so service-interfaces now describes only the resize observer — which is load-bearing (600px overlay/shift, header re-measure, cleanup on swap/disconnect), and a real SharedResizeObserver satisfies it as-is.

Removed the redundant html wrapper (6a28604) — you were right, it only existed to satisfy the return type.

Still open

• Importing the resize-observer type from @internetarchive/shared-resize-observer instead of declaring it locally — agreed, not done yet.
• The 350ms scroll timeout.
• Scoping custom-theater-interface (now one field smaller with modal gone) and how it relates to offshoot's <ia-theater>.
• Why the story uses its own resize-observer adapter — replied on the thread; happy to switch if you'd rather the demo use the real one.

Consumer impact from the renames is tracked in WEBDEV-8856 (bookreader) and WEBDEV-8857 (offshoot), including the ordering constraint that bookreader has to land first — offshoot reaches into its shadow root for the navigator tag.

npm test (273), npm run build and npm run lint all pass.