Webdev 8458 migrate item navigator

[iisa]

WEBDEV-8458 Migrate item-navigator into elements

Ports @internetarchive/iaux-item-navigator into the elements repo as a
production component (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
• Live demo (this PR): https://internetarchive.github.io/elements/pr/pr-64/ — open Production-Ready → <ia-item-navigator>, then expand Import, Usage & Settings for the live toggles/theming controls.
• Current main (for comparison): https://internetarchive.github.io/elements/

What's included

The full upstream package (16 source files) — the navigator shell and both bundled menus:

• ia-item-navigator — fullscreen-capable frame: header/main slots, a collapsible drawer driven by a menuContents provider array, a minimized menuShortcuts rail, responsive overlay/shift, loader, 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 — viewable-files menu (scrollable volume list, active-file highlight, PDF flagging, tri-state title sort).
• ia-share-panel — social share links + copyable iframe/bbcode embed snippets.

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

Key decisions

• Naming: adopted the elements ia-* / IA* convention across all tags and classes (upstream mixed iaux-*, un-prefixed, and Lit-2 casing).
• Zero runtime deps added, except one: modal-manager / shared-resize-observer were type-only upstream → replaced with local interfaces; all 11 icons inlined as Lit templates. Only new runtime dep is @internetarchive/metadata-service (genuinely used in the item converter).
• Theming: public knobs exposed as --item-navigator-* with private --x-- aliases + inline defaults. Consolidated onto a small palette: --item-navigator-border-color, --item-navigator-text-color, --item-navigator-icon-color / -active-color / -inactive-color, --item-navigator-share-embed-bg, plus surface/animation knobs.
• Sizing: anchored to a self-contained 10px base (--item-navigator-base-font-size) with em units, reproducing petabox's scale without forcing a 10px root on the rest of the demo.

Notable fixes vs. source

• Menu toggle bound @click=${this.toggleMenu}, setting menuOpened to a PointerEvent (only "worked" because truthy) → now stays boolean.
• Drawer sub-panel closes independently of the drawer; theater stays flush with the drawer edge through the menu animation (shift ≥600px / overlay <600px); fullscreen now fills the viewport; slider header action fixed.
• execCommand('copy') → async Clipboard API (with fallback); sort works on a copy instead of mutating the reactive prop; dropped a dead never-rendered method.

Demo

Self-contained ia-item-navigator story (Production-Ready): realistic archive.org items (images / PDFs / video) where clicking a viewable file swaps the theater iframe; slotted header + theater; share panel + populated shortcut rail; and a Styles panel that lists every theming/layout toggle, shows the CSS var each control sets, and has a Reset.

Testing

• 76 navigator tests (Vitest browser mode); all eligible runtime files at 100% coverage.
• npm run build, npm run lint, and the madge circular check all pass.

Follow-up (out of scope, tracked)

Shared dark-surface palette tokens for the near-blacks / border / scrim that have no house equivalent today — WEBDEV-8796 / #66.

QA Steps

Setup: open the live demo → Production-Ready → <ia-item-navigator>, expand Import, Usage & Settings.

• Renders — dark theater frame + header bar; left rail shows Viewable Files, Share, and ⋯, all ~24px.
• Drawer — ⋯ animates open/closed; while closed, Tab doesn't enter it.
• Shortcuts — clicking Viewable Files / Share opens the drawer straight to that panel.
• Sub-panel close — header ✕ closes the panel but leaves the drawer open; Esc closes panel first, then drawer.
• Viewable Files — long titles wrap, PDFs tagged, active file highlighted; sort cycles neutral→asc→desc; clicking a file swaps the theater iframe.
• Share — social links open real URLs; embed block copies and flashes "Copied".
• Toggles — Loaded (spinner↔theater), View available (placeholder), Header (hides bar), Fullscreen (fills viewport + in-frame Exit), Animate (instant↔animated).
• Responsive — >600px: theater eases in sync with the drawer; <600px: drawer overlays a full-width theater.
• Theming — each Styles control shows the CSS var it sets and updates live; Reset restores defaults.
• A11y — menu buttons keyboard-operable; close buttons labelled; ::part(minimized-menu) targets the rail.
• Automated — npm test (76 navigator tests), npm run build, npm run lint pass.

[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-25 04:54 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 96.49682% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 84.42%. Comparing base (cd1ffd3) to head (7a790b9).

Files with missing lines	Patch %	Lines
demo/story-components/story-styles-settings.ts	0.00%	10 Missing ⚠️
demo/story-template.ts	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #64      +/-   ##
==========================================
+ Coverage   78.62%   84.42%   +5.80%     
==========================================
  Files          17       27      +10     
  Lines         697     1008     +311     
  Branches      189      255      +66     
==========================================
+ Hits          548      851     +303     
- Misses        100      108       +8     
  Partials       49       49              

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

Done — all 13 glyphs are standalone .svg files now (~18KB of path data out of the JS bundle). Verified none of the path strings remain in the emitted dist JS.

ia-item-navigator/icons/ellipses.svg
ia-item-navigator/icons/collapse-sidebar.svg
ia-item-navigator/menus/icons/share.svg
ia-item-navigator/menus/icons/twitter.svg
ia-item-navigator/menus/icons/facebook.svg
ia-item-navigator/menus/icons/tumblr.svg
ia-item-navigator/menus/icons/pinterest.svg
ia-item-navigator/menus/icons/email.svg
ia-item-navigator/menus/icons/link.svg
ia-item-navigator/menus/icons/viewable-files.svg
ia-item-navigator/menus/icons/sort-asc.svg
ia-item-navigator/menus/icons/sort-desc.svg
ia-item-navigator/menus/icons/sort-neutral.svg

One wrinkle worth flagging, since it drove the approach: these icons are recolored via CSS (--item-navigator-icon-color, plus active/inactive states on the menu buttons). <img src> — the pattern ia-combo-box and ia-dropdown-search-bar use — can't be recolored, so it would have dropped that theming.

So they render through a small maskedIcon() helper using mask-image + background-color: the mask supplies the shape, CSS supplies the paint. Same .svg-import mechanism as the other components, still themeable. Host CSS moved from fill to background-color, and the original .fill-color rules are kept alongside it so any inline-<svg> icon a consumer passes in (bookreader's bookmarks/search/downloads providers) keeps theming with no change on their side.

The loader's book/ring is the one exception and stays inline — a mask can't animate the spinning sub-path.

Also worth knowing if you hit this elsewhere: the url() has to be quoted. Bundlers inline small SVGs as data: URIs whose markup contains apostrophes, and an unquoted url() silently drops the whole mask-image declaration — the glyph then paints as a solid block.

[jbuckner]

We do this in offshoot here... how does this work with offshoot's? https://git.archive.org/www/offshoot/-/blob/main/src/scenes/details-page/theater/ia-theater-unavailable.ts#L71

[iisa]

we can remove. this is legacy from porting, currently live in petabox

[jbuckner]

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

[iisa]

totally!

[jbuckner]

What happens when we use the actual ModalManager?

[iisa]

Nothing happens — which is why I've removed it rather than keeping the local type.

The navigator accepted modal and never read it. Nothing downstream read it back off the navigator either: in bookreader the menu providers get the modal manager directly through baseProviderConfig (ia-bookreader.js:346-357), a path that doesn't go through the navigator at all — that's how BookmarksProvider ends up calling this.modal.showModal(). Offshoot never passed one.

Worth noting it's vestigial upstream too: iaux-item-navigator has exactly two modal mentions, the import and @property() modal?: ModalManager — it never forwards or calls it. So the port wasn't dropping behavior; there wasn't any.

ModalManagerInterface is gone with it, so service-interfaces now describes only the resize observer, which the navigator does genuinely use.

Consumers still binding .modal are unaffected — setting an unknown property on a Lit element is a no-op, and their providers keep their own reference. Confirmed in the demo: assigning .modal after the removal doesn't throw and the navigator renders and operates normally.

[jbuckner]

Same comment... can we externalize this so it doesn't inflate the bundle size?

[iisa]

Done — this one is menus/icons/viewable-files.svg now, alongside the other twelve. Same maskedIcon() treatment as the rest (details in the icons.ts thread): mask supplies the shape, background-color supplies the paint, so it still follows --item-navigator-icon-color.

Worth noting for consumers: this module's viewableFilesIcon export keeps its name and its TemplateResult type — it just renders a masked <span> now instead of an inline <svg>. bookreader and offshoot both import it, and neither needs a change unless they target it with their own svg/path CSS.

[jbuckner]

Looking at a lot of these custom elements, I think we should somehow scope their names to the element they're a part of since they're going to exist in the global namespace, ie ia-itemnav-viewable-files-panel

[iisa]

Done — sub-elements are now scoped under ia-itemnav-* (tags, files and classes). Files changed:

Renamed

ia-itemnav-loader.ts                  → ia-itemnav-loading-view.ts
ia-itemnav-loader.test.ts             → ia-itemnav-loading-view.test.ts
ia-menu-slider.ts                     → ia-itemnav-menu-slider.ts
ia-menu-slider.test.ts                → ia-itemnav-menu-slider.test.ts
ia-menu-button.ts                     → ia-itemnav-menu-button.ts
ia-menu-button.test.ts                → ia-itemnav-menu-button.test.ts
ia-no-theater-available.ts            → ia-itemnav-no-theater-available.ts
ia-no-theater-available.test.ts       → ia-itemnav-no-theater-available.test.ts
menus/ia-share-panel.ts               → menus/ia-itemnav-share-panel.ts
menus/ia-share-panel.test.ts          → menus/ia-itemnav-share-panel.test.ts
menus/ia-sort-files-button.ts         → menus/ia-itemnav-sort-files-button.ts
menus/ia-sort-files-button.test.ts    → menus/ia-itemnav-sort-files-button.test.ts
menus/ia-viewable-files-panel.ts      → menus/ia-itemnav-viewable-files-panel.ts
menus/ia-viewable-files-panel.test.ts → menus/ia-itemnav-viewable-files-panel.test.ts

Added

src/elements/ia-item-navigator/element-names.test.ts

Modified

README.md
src/elements/index.ts
src/elements/ia-item-navigator/ia-item-navigator.ts
src/elements/ia-item-navigator/ia-item-navigator.test.ts
src/elements/ia-item-navigator/ia-item-navigator-story.ts

ia-item-navigator itself keeps its name. The loader became ia-itemnav-loading-view rather than ia-itemnav-loader because @internetarchive/ia-item-navigator already registers that exact name — along with ia-menu-slider and ia-no-theater-available, so those three would have thrown on double registration while consumers still load both packages.

[jbuckner]

What is the intended behavior here? This feels code smelly to put an arbitrary 350ms timeout on this scroll. Can we be more deterministic about this?

[jbuckner]

Do you need to wrap this in html since you're just returning the template or nothing?

[iisa]

No — good catch, it was only there to satisfy the TemplateResult return type. Widening the signature lets the branch return as-is:

render(): TemplateResult | typeof nothing {
  return this.fileList.length ? this.fileListTemplate : nothing;
}

Existing coverage already asserts the empty case renders no ul, and I confirmed in the demo that the list still renders populated (7 items), disappears when fileList is emptied, and comes back on repopulate.

[jbuckner]

Based on the comment regarding "providers and shortcuts", this interface seems to be doing a lot more than that... passing itemMD, baseHost, observer, modal, etc. Can we scope this more concretely to those behaviors?

Also, how does this interact with offshoot's <ia-theater>?

[jbuckner]

Why not just import the shared resize observer?

[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?

[jbuckner]

What happens when we use the actual Modal Manager and Shared Resize Observer?

[iisa]

Two different answers, since the navigator treats them very differently.

Modal manager — nothing happens, so I've removed the property (details in the service-interfaces.ts thread). The navigator never read it, and nothing downstream reads it back: bookreader's providers get the modal directly via baseProviderConfig, bypassing the navigator entirely. It was unused upstream too.

Shared resize observer — a real instance drops straight in, because this one is genuinely load-bearing. The navigator implements the handler interface and uses it for real behavior:

• observes #frame and flips between overlay and shift at the 600px breakpoint
• observes the header slot and re-renders when its height changes
• removes both on disconnect and when the observer property is swapped

The local interface is just the structural subset it calls — addObserver / removeObserver with { target, handler } — which a real SharedResizeObserver already satisfies. bookreader passes one today (new SharedResizeObserver() at ia-bookreader.js:129) and it works unchanged.

Happy to import the type from @internetarchive/shared-resize-observer instead of declaring it locally, per your other comment — that's a type-only import so it stays out of the runtime dependency tree either way.

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