feat: show alternatives banner on unavailable book pages

[Sadashii]

Closes #12743

This PR adds a warning banner recommending available alternative books on the Book Edition page when a book is in preview_only, checkedout, waitlist, or locate physical states.

Technical

• Extracted availability state resolution logic to a new @public function get_lending_state in lending.py.
• Registered the helper as a template global in code.py.
• Added <ol-banner> inside the EditionNavBar macro, wrapped within a responsive div using .desktop-only / .mobile-only CSS utility classes to avoid layout conflicts.
• Simplified view.html layout by delegating the banner rendering to the navbar component, and removed the unused data-workid carousel attribute.
• Refactored get_pending_action_banner in mybooks.py and updated AGENTS.md to follow i18n best practices (combining localized segments into single formatted strings with placeholders).
• Implemented unit tests covering all lending states in test_lending.py.
• Added data-lending-state attribute to #contentBody and visibility/tracking hooks in lazy-carousel.js to instrument discovery of recommended books.

Analytics & Experiment Tracking

Added tracking for the discovery of the recommended books carousel under the category OpenRelatedBooks to compare natural discovery vs banner-driven discovery:

• OpenRelatedBooks|BannerClick: Tracked when a user clicks the link on the warning banner to jump to the recommendations.
• OpenRelatedBooks|FromBanner: Tracked when the related books carousel lazy-loads/is discovered after the user clicked the banner link (URL hash is #related-work-carousel).
• OpenRelatedBooks|ScrolledDownAvailable: Tracked when the related books carousel lazy-loads/is discovered by scrolling down normally when the book is available.
• OpenRelatedBooks|ScrolledDownUnavailable: Tracked when the related books carousel lazy-loads/is discovered by scrolling down normally when the book is unavailable (in one of the 4 warning states).

Testing

1. Run python unit tests:
   uv run --with-requirements requirements_test.txt pytest openlibrary/tests/core/test_lending.py
2. Run template compilation tests:
   uv run --with-requirements requirements_test.txt pytest openlibrary/tests/test_templates.py
3. Verify pre-commit checks run successfully:
   pre-commit run --files openlibrary/core/lending.py openlibrary/plugins/openlibrary/code.py openlibrary/templates/type/edition/view.html openlibrary/tests/core/test_lending.py openlibrary/macros/EditionNavBar.html openlibrary/plugins/openlibrary/js/lazy-carousel.js

Screenshot

1. Added banner clicking on which smooth-scrolls the user down to the carousel section, banner will show above the navbar on both mobile and desktop - style changes to the banner will be made via feat(components): add ol-toast and ol-banner web components #12868

2. Moved the carousel section inside the right-side segment for better looks and behaviour

3. (Partially related) Switched the patron intent banner to use ol-banner

Stakeholders

@mekarpeles

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR improves in-page navigation and availability messaging on edition pages by enabling smooth scrolling, adjusting anchor offsets, and surfacing lending-state-driven banners/sections.

Changes:

• Add get_lending_state to resolve user-facing lending/availability state (with new tests) and expose it to templates.
• Update edition templates/macros to pass lending state into EditionNavBar and reposition the Related Books carousel as a tab section target.
• Improve scrolling UX (smooth scroll + updated scroll-padding-top) and adjust carousel layout CSS; update pending-action banner rendering & i18n strings.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
static/css/page-book.css	Adjusts scroll padding offsets for anchor navigation across breakpoints.
static/css/components/work.css	Tweaks carousel container margin for related books layout.
static/css/base/common.css	Enables smooth scrolling with reduced-motion fallback.
openlibrary/core/lending.py	Adds get_lending_state helper for templates and other call sites.
openlibrary/tests/core/test_lending.py	Adds test coverage for get_lending_state.
openlibrary/plugins/openlibrary/code.py	Exposes get_lending_state as a template global.
openlibrary/templates/type/edition/view.html	Computes lending state once and wires it into EditionNavBar; relocates Related Books section.
openlibrary/macros/EditionNavBar.html	Adds conditional availability banner linking to related books.
openlibrary/templates/account/view.html	Switches pending-action banner to <ol-banner> output.
openlibrary/plugins/upstream/mybooks.py	Refactors translated pending-action message to use placeholders around an HTML link.
openlibrary/i18n/messages.pot	Updates extracted strings and source references for i18n.
AGENTS.md	Documents i18n guidance for link placeholders inside a single translatable string.

[Sadashii]

Note to self, a follow up PR on ol banner has to be merged first with some additions to be made here, do not merge this before that.

[lokesh]

LGTM

[Sadashii]

@RayBB need your inputs on the extracted get_lending_state function (it is slightly drifted) and about the urgency of migrating LoanStatus macro to utilize this.

Drift:
One behavioral divergence already exists: the new function adds an early elif is_waiting: return
 "waitlist" before the partner/open/printdisabled checks. The original only surfaces waitlist
 state inside the is_lendable branch. It's covered by test_get_lending_state_waiting_loan, so it
 looks int

[lokesh]

@Sadashii
Can you check on the following issues:

1 ) Persistence working correctly when X clicked in banner
Two distinct dismissal paths existed and only one survives the swap:

• Click-through (clicking "Continue"): the inline script at account/view.html:31-33 clears the pending_action cookie. ✅ Still works — .pending-action-link is inside the server-rendered message HTML,
  captured into ol-banner's light-DOM _content, so the selector still matches.
• Explicit dismiss (X button): OLD site/banner with cookie_duration_days=1 → legacy dismiss → /hide_banner sets pending_action=1 → server stops rendering for a day. NEW ol-banner fires
  ol-banner-dismiss with empty id → listener returns early → no cookie written → the original pending_action JSON cookie is untouched → banner re-renders on the next page load. ❌ Regression.

2 ) Analytics double-fire on the related-books carousel
The ping is emitted per-carousel, but the experiment wants per-section discovery. Two carousels under one #related-work-carousel anchor → two pings.

Impact — worse than a flat 2×: Both placeholders live adjacent in .related-books with rootMargin: '200px', so they intersect near-simultaneously and almost always both fire. But the multiplier is
inconsistent:

• work with subjects + authors → 2 pings
• work with only one → 1 ping

So FromBanner / ScrolledDownAvailable / ScrolledDownUnavailable are inflated by a variable factor that correlates with the book's metadata richness. That corrupts not just absolute counts but the
banner-vs-natural ratio the experiment exists to measure (richer books may skew toward one cohort).

Fix: track once per section. Simplest is a module-scoped guard:
// top of module
let relatedBooksTracked = false;
// in the block
if (!relatedBooksTracked && (config.key === 'related-subjects-carousel' || config.key === 'related-authors-carousel')) {
relatedBooksTracked = true;
...
}

** 3 ) Broken dismiss-tracking selector **

Root cause: class renamed across the component swap. querySelector('.page-banner--dismissable-close') now returns null, the if (dismiss) guard is false, and the PreserveIntent|Dismiss attribute is
never attached. Dismiss analytics silently lost.

Fix: stop trying to decorate the button. Listen for the component's own event (it bubbles, composed: true) and send the ping directly:
container.addEventListener('ol-banner-dismiss', function() {
if (window.archive_analytics && window.archive_analytics.ol_send_event_ping) {
window.archive_analytics.ol_send_event_ping({ category: 'PreserveIntent', action: 'Dismiss' });
}
});

[RayBB]

@Sadashii I'm not super familiar with get_lending_state, is there something particular you wanted to know from me about it?

In terms of the loanstatus macro. If you mean converting it to Jinja, we certainly could but I wouldn't let you block on it. I think it's moderately difficult compared to the other templates and we haven't converted anything like that yet.

Let me know how I can be helpful!

[Sadashii]

@lokesh good catches, resolved.
@RayBB I was just wondering if a seperate effort should be made about switching LoanStatus macro to this handler (with the appropriate additons) to help the jinja migration efforts, i.e. if these changes are in your present timeline.

[lokesh]

Thanks for addressing the previous comments.

Here are some additional items that came up in the automatic review that need a look over:

1. openlibrary/plugins/openlibrary/js/lazy-carousel.js:8 — ordinary nav-bar "Related Books" clicks are misattributed as FromBanner. The click listener matches a[href="#related-work-carousel"], but in EditionNavBar.html both the warning banner and the regular nav-menu item use that same href. Clicking the plain nav item (never touching the banner) sets bannerClicked=true, so the subsequent carousel load fires OpenRelatedBooks|FromBanner instead of ScrolledDown*. This corrupts the exact banner-vs-natural experiment the PR exists to measure. Match the banner specifically (e.g. data-ol-link-track="OpenRelatedBooks|BannerClick" or an id) instead of the shared href.

2. static/css/components/work.css:313 — .lazy-carousel { margin: 0 !important } is unscoped and leaks site-wide. The rule pairs .related-books .carousel-container (correctly scoped) with a bare .lazy-carousel, which is the class emitted by RawQueryCarousel.html:33 for every QueryCarousel — home page, subject pages, author pages, "You might also like". So this zeroes carousel margins everywhere, and !important blocks downstream overrides. Scope it: .related-books .lazy-carousel.

3. openlibrary/core/lending.py (elif is_waiting: return "waitlist") — the waitlist branch is hoisted above printdisabled/open/borrowable, diverging from LoanStatus.html. In the source macro, waitlist state only surfaces inside the is_lendable block, below the partner/open/printdisabled/borrowable checks. A print-disabled user (or a user whose book is readable/borrowable) who also holds a not-yet-their-turn waiting_loan is now classified "waitlist" → wrongly shown the "unavailable" banner, while the read button rendered by LoanStatus.html on the same page still shows readable/borrow. The two views disagree.

[RayBB]

@Sadashii I see what you're asking. Since basically all of openlibrary/macros/EditionNavBar.html is being touched, and it doesn't make any network calls I would love if you converted it to Jinja! That would be a great step in the right direction and good to get more people understanding it.

#13077 has the most recent example of how we did it (you might need to merge master or rebase).

Summary is you should be able to:

1. Create EditionNavBar.html.jinja
2. Call: $:render_jinja_template("EditionNavBar.html.jinja", XYZ)

Don't spent too much time on it if you get stuck but it would be very easy for AI to convert that particular macro.

What do you think?

[Sadashii]

@lokesh

1. Applied
2. Reverted per our conversations that moving the banner to the sidebar squishes it more.
3. Fixed the precedence to follow LoanStatus as exactly, a seperate PR post-this should also refactor LoanStatus macro to utilize get_lending_state to have a single source of truth.

@RayBB

Sounds good, will update this and LoanStatus macro to jinja in a seperate PR. Had Antigravity take a look and should be a clean change.

[lokesh]

One question and one comment.

1. What does dismissing the banner do? Does it come back if I reload the page?
2. I don't think it should block the PR, but I want to just note that the top of page banner might not be the best UI pattern for this scenario. It screams "you came here to read this, it's unavailable, let me rescue you". But people land on this page with diverse intents. And seeing a banner, first thing, before they get a chance to orient themselves, and a banner that has negative framing "this book is unavailable" gives a bad first impression.

In the future we might want to consider a lighter contextual treatment. For example, an empty-state near the Read/Borrow CTA "Not available to read on OL - see similar available books"

---

One more thing: I just noticed that the "You might also like" carousel only includes books that are available to read. Which is surprising, though not necessarily a bad thing. But we should at minimum update the heading to something like "Available books like this one"

[mekarpeles]

1. If we dismiss banner and refresh, should the banner persist? (Lokesh had +1'd)
2. Fixing the banner flexing span structure

[openlibrary-bot]

👋 This branch was rebased onto current master to resolve merge conflicts. Here's what was going on, in case it helps for next time:

Why the conflict happened

Your branch had drifted 17 commits behind master. The only file those commits and this PR both touched was openlibrary/i18n/messages.pot — it's machine-generated (regenerated from source strings via scripts/i18n-messages extract), and master had regenerated large chunks of it independently. Any two branches that both touch .pot around the same time will collide, even with no real logic conflict.

There was also a small package.json/package-lock.json conflict from an incidental @sentry/browser version bump (10.60.0 → 10.63.0) picked up by an npm install alongside an unrelated JS fix — unrelated to the feature, so master's pinned version won.

One real (non-generated) conflict: openlibrary/plugins/openlibrary/code.py — both your branch and master added new entries to the same Template.globals dict at the same spot. Simple additive conflict, resolved by keeping both.

Tips to avoid this proactively:

1. Rebase onto master periodically, especially for long-running branches (this one was open ~5 weeks). The longer a branch lives, the more likely messages.pot and package-lock.json drift.
2. Regenerate messages.pot after rebasing, don't hand-merge it: python ./scripts/i18n-messages extract (or let the generate-pot pre-commit hook do it — needs Docker, since it depends on infogami being importable). Whichever side's regeneration is more recent is generally right; there's nothing to "merge" semantically in a generated catalog.
3. Don't let dependency lockfile bumps ride along in unrelated commits. If npm install changes package-lock.json entries you didn't intend to touch, revert those hunks before committing — git diff package-lock.json is worth a glance before git add.
4. After rebasing, running pre-commit run --files $(git diff master..HEAD --name-only) locally catches lint/format issues before pushing — ruff check would have caught the small self-inflicted issue this rebase introduced (an orphaned get_lending_state reference from a conflict-resolution ordering mismatch, already fixed).

No action needed on your end — the branch is up to date with master and mergeable. Thanks for the PR! 🙌

— PAM (Open Library's Project AI Manager)

[openlibrary-bot]

Follow-up review after the rebase (all prior review threads are marked resolved — I independently re-verified each against the current code):

• ✅ get_book_provider(doc).short_name fix in lending.py — confirmed, calls the function and reads the attribute off the returned provider, not off the function itself.
• ✅ waiting_loan now drives is_waiting → "waitlist" — confirmed used, not dead.
• ✅ test_get_lending_state_partner mocks short_name, matching the corrected implementation.
• ✅ No !important remains anywhere in this PR's CSS diff.
• ✅ lazy-carousel.js matches data-ol-link-track="OpenRelatedBooks|BannerClick" specifically (fixes nav-bar-click misattribution) and guards on a module-scoped relatedBooksTracked flag (fixes the double-fire).
• ✅ account/view.html's ol-banner-dismiss handler unconditionally clears the pending_action cookie — the old "empty id → early return, cookie never cleared" regression is gone.
• ✅ banner-analytics.js listens for ol-banner-dismiss directly (e.detail.dismissId || e.target.id) instead of the renamed .page-banner--dismissable-close selector, and is wired up via initOlBannerDismissals() in js/index.js gated on ol-banner[dismissible].
• ✅ Single get_lending_state() call per book page, threaded down through EditionNavBar/databarWork/editions_datatable — not recomputed per row (editions_datatable only passes it for the highlighted/current edition row, correctly leaving other rows to resolve their own state).
• ✅ get_lending_state uses @public, no manual Template.globals registration needed.

One unrelated discovery while reading the surrounding code — flagging separately on LoanStatus.html, not blocking this PR.

[openlibrary-bot]

Pre-existing bug, not introduced by this PR (this line is unchanged context in the diff — same on master): get_book_provider.ia reads an .ia attribute off the function object get_book_provider, not off a provider instance. That attribute doesn't exist — there's no get_book_provider.ia = ... anywhere in book_providers.py. The module-level singleton you likely want is ia_provider (openlibrary/book_providers.py:752), or call get_book_provider_by_name("ia").

This branch ($else: under $if not waiting_loan:) is reachable whenever lending_state == 'waitlist' and the user has a real active waiting_loan — at that point this line raises AttributeError: 'function' object has no attribute 'ia'.

Flagging here because this PR's get_lending_state refactor sits right next to it, and @Sadashii's comment above mentions a follow-up PR to migrate LoanStatus onto get_lending_state as the single source of truth — worth fixing as part of that follow-up rather than in this PR.

Reviewed