New web component ol-chip by lokesh · Pull Request #12012 · internetarchive/openlibrary

lokesh · 2026-03-05T05:00:46Z

tag.mp4

This makes progress on both the following tasks:

Standardize Subject Tags UX - Standardize Subject Tags UX using BEM CSS #11728
Revamp of the search and facets UI w/focus on mobile

Adds an ol-chip web component and uses it to replace the plain text/link facets on search results pages and the related subjects section on subject pages.

To limit scope, a follow-up PR will be used to replace other tags/chips and remove old code.

Changes

New components:

OLChip — A pill-shaped interactive chip that supports selected state (with checkmark icon), optional count badge, link mode (href), small/medium sizes, and accessible labels via chip-label prop. Fires ol-chip-select event on click.
OLChipGroup — A flex-wrap container for consistent chip spacing.

Template updates:

Search facets (work_search_facets.html) — Facet entries now render as <ol-chip size="small">
Selected facets (work_search_selected_facets.html) — Selected filters render as <ol-chip selected> with accessible chip-label tooltips (e.g. "Written in: English").
Related subjects (RelatedSubjects.html) — Subject links wrapped in <ol-chip-group> with small chips.
Design pattern library (design.html) — Added chip examples (default, selected, small, with count, as link, interactive toggle). Restructured page with sidebar nav.

Styling & layout:

Pre-hydration styles in head.html to prevent layout shift before Lit hydrates.
Updated page-design.css with sidebar nav layout for the design pattern library.
Minor facet layout fixes in legacy.css and headings.css.

Technical

chip-label prop forwards as aria-label to the inner <a>/<button>

Screenshots

Testing

Visit /search?q=dogs — facets in the sidebar should render as small chips
Click a facet — selected facets above results should show as selected chips with ✓ icon
Visit a subject page like /subjects/fiction — related subjects should render as chips
Visit /developers/design — chip examples section should be interactive

Stakeholders

@mekarpeles @cdrini @jimchamp @RayBB

- Imported OLChip component in index.js. - Replaced span elements with ol-chip components in work_search_facets.html for better UI representation of facet entries. - Updated work_search_selected_facets.html to use ol-chip for selected facets, enhancing the display and interaction. - Modified CSS for facets to improve layout and styling, including flex properties for better responsiveness. - Added import for ol-chip styles in page-user.less to ensure proper styling is applied.

- Renamed event from 'chip-click' to 'ol-chip-select' for clarity. - Simplified CSS properties in OLChip for consistency and readability. - Adjusted padding and font sizes in ol-chip.less for better alignment. - Updated facet template links to use consistent capitalization for "More" and "Less".

Co-authored-by: Cursor <cursoragent@cursor.com> # Conflicts: # openlibrary/components/lit/index.js

- Introduced CSS variables for padding and icon sizes in OLChip for improved customization. - Updated styles for selected state and small size variations to enhance visual consistency. - Added comprehensive examples and documentation for the OLChip component in design.html, showcasing various use cases including default, selected, small size, and interactive toggle functionalities.

- Changed the color of the selected state in the OLChip component for better visibility. - Removed unused small size examples from design.html to streamline the documentation and improve clarity. - Added positioning and padding adjustments in legacy.less for better layout consistency.

…tion - Changed the event name from 'update:page' to 'ol-pagination-change' in the OlPagination component for better clarity and consistency. - Updated the event detail structure to include an object with the page number. - Revised design.html to reflect the new event name in examples, improving documentation accuracy. - Enhanced CSS styles in page-design.less for better layout and spacing in the design pattern library.

- Modified the condition for skipping empty facet counts to improve performance. - Introduced tooltips for facets in the selected facets template to enhance user experience. - Added a comment regarding the handling of the 'public_scan_b' facet for future consideration.

- Introduced the OLChipGroup component to enhance the grouping of chips in the UI. - Updated the RelatedSubjects macro to utilize OLChipGroup for better visual organization of subject links. - Imported the new OLChip component styles in the page-subject.less file for consistent styling.

- Port facet layout changes (flex, gap) from legacy.less to legacy.css - Port h4.facetHead styling (inline-flex, .facet-icon) from headings.less to headings.css - Convert page-design.css from LESS syntax to native CSS (flat selectors, CSS custom properties) - Create ol-chip.css from ol-chip.less and add imports to page-subject.css and page-user.css - Resolve all merge conflicts from LESS-to-CSS migration Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…ight for better alignment

for more information, see https://pre-commit.ci

The facet tooltips (e.g. "Written in", "Published by") were set via the title attribute on the host element, which screen readers can't reach inside shadow DOM. Add a chip-label property that forwards as aria-label to the inner <a>/<button>, so assistive tech announces the full context like "Written in: English". Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Modify .stylelintrc.json to allow specific ol- types in selector-type-no-unknown rule. - Remove unused import for ol-chip.css in page-user.css to streamline styles. - Change color property in h4.facetHead from a hex value to a CSS variable for better maintainability.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

for more information, see https://pre-commit.ci

…pGroup for accessibility

…ct.css. Add pre-hydration styles for ol-chip and ol-read-more components in head.html to prevent layout shifts.

- Consolidate check and close icons into a single _renderIcons method. - Update CSS class names for icons to improve clarity and maintainability. - Implement hover effects to toggle icon visibility based on chip selection state.

…hover effects - Rename CSS classes for clarity, changing .icon to .icon-slot and introducing .icon-carousel. - Implement a carousel effect for icons on hover, enhancing user interaction. - Adjust icon visibility and transitions to create a smoother experience when selecting the chip.

- Add a new section on compound components in web-components.md to clarify usage and best practices. - Update README.md to include a link to the new design documentation. - Refine OLChip styles to improve hover effects and responsiveness, ensuring better user interaction across devices. - Update tooltip translations in work_search_selected_facets.html for improved accessibility.

for more information, see https://pre-commit.ci

These changes now live in dedicated branches for smaller PRs: - docs/ai/ updates → ai-design branch - OlPagination event rename → pagination-event branch Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

for more information, see https://pre-commit.ci

# Conflicts: # openlibrary/templates/design.html

for more information, see https://pre-commit.ci

- Modified the search form in work_search.html to include an additional class 'search-row'. - Added CSS rules for the 'search-row' class to provide a margin-bottom of 8px for better spacing.

…t and will-change, scope p rule Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

lokesh · 2026-03-17T06:06:02Z

        href: { type: String },
        count: { type: String },
-        chipLabel: { type: String, attribute: 'chip-label' },
+        accessibleLabel: { type: String, attribute: 'accessible-label' },


Why accessible-label instead of aria-label?

Native HTML attributes should always behave predictably on custom elements — aria-label on a host element should apply to that element, not get silently forwarded to an inner child. Using a distinct prop name makes it clear this is custom behavior that targets the <a> or <button> inside the shadow DOM.

# Conflicts: # openlibrary/i18n/messages.pot # openlibrary/templates/design.html

for more information, see https://pre-commit.ci

cdrini · 2026-03-13T16:58:16Z

+        if (this.href) {
+            return html`
+                <a class="chip" href=${this.href}
+                    aria-label=${this.chipLabel || nothing}


Introducing the chip-label as a new vocabulary is a bit confusing ; if we can use the existing html attribute aria-label that would make it a little less of a learning curve.

Note chatgpt also notes this might be an option:

static get observedAttributes() {
return ['aria-label', 'aria-expanded', 'aria-pressed'];
}

cdrini · 2026-03-20T16:49:02Z

+
+        return html`
+            <span class="icon-slot">
+                <span class="icon-carousel">


We at some point need to have a reckoning for how we do icons, since inlining them every time will be difficult to scale / others to reuse.

The lazy middle-of-the-road approach might be to have lit components in a icons/ directory for every svg, so that we can easily keep them DRY.

cdrini · 2026-03-20T16:53:27Z

                $else:
                    $ display = _('no')
-            <span class="small"><a href="$facet_url" title="$link_title" data-ol-link-track="$add_track(header)">$display</a></span>&nbsp;<span class="smaller gray">$commify(count)</span>
+            <ol-chip size="small" href="$facet_url" title="$link_title" data-ol-link-track="$add_track(header)" count="$commify(count)">$display</ol-chip>


I see what you mean, it would be good to have a "commify"-like function to convert this to eg "12K" instead of "12,000" ; especially with the new inline flow of the chips.

cdrini · 2026-03-20T17:02:08Z

+            align-items: center;
+            padding: var(--chip-padding-block) var(--chip-padding-inline);
+            border: var(--border-width) solid var(--color-border-subtle);
+            border-radius: var(--border-radius-pill);


This is looking a bit funky for multi-line cases ; we likely want the border-radius to be the same in the single-line and multi-line cases.

Also a question of whether we want the number to appear at the end of the flowing text, as opposed to pinned to the right of the chip.

cdrini · 2026-03-20T17:08:16Z

+        return html`
+            <span class="icon-slot">
+                <span class="icon-carousel">
+                    <svg


We think having the "x" on the right would be a bit cleaner, also for mobile.

cdrini

Lgtm, this looks fantastic!! A few small pieces of feedback.

lokesh and others added 24 commits February 12, 2026 22:07

Merge remote-tracking branch 'upstream/master' into web-component-chip

ae4c9c5

Co-authored-by: Cursor <cursoragent@cursor.com> # Conflicts: # openlibrary/components/lit/index.js

Update margin for h3 elements in link-box component

1596070

Update OLChip styles: change font family to button and adjust line he…

9724385

…ight for better alignment

[pre-commit.ci] auto fixes from pre-commit.com hooks

6ed2ff7

for more information, see https://pre-commit.ci

Wrap chip demo labels in design.html with i18n calls

7be40a8

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

[pre-commit.ci] auto fixes from pre-commit.com hooks

19a04d6

for more information, see https://pre-commit.ci

Toggle chip selection state in OLChip and set role attribute in OLChi…

4735a2b

…pGroup for accessibility

Remove ol-chip.css and update imports in page-user.css and page-subje…

c1957de

…ct.css. Add pre-hydration styles for ol-chip and ol-read-more components in head.html to prevent layout shifts.

[pre-commit.ci] auto fixes from pre-commit.com hooks

f7d0d82

for more information, see https://pre-commit.ci

Remove docs/ai and pagination event changes (moved to separate branches)

ec8b4ea

These changes now live in dedicated branches for smaller PRs: - docs/ai/ updates → ai-design branch - OlPagination event rename → pagination-event branch Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

[pre-commit.ci] auto fixes from pre-commit.com hooks

1847d3f

for more information, see https://pre-commit.ci

lokesh marked this pull request as ready for review March 11, 2026 18:42

lokesh requested a review from mekarpeles March 11, 2026 18:50

lokesh changed the title ~~Web component chip~~ New web component ol-chip Mar 11, 2026

Merge remote-tracking branch 'upstream/master' into web-component-chip

a2ad5ae

RayBB added the On Testing label Mar 11, 2026

lokesh removed the On Testing label Mar 11, 2026

lokesh and others added 2 commits March 11, 2026 15:47

Merge remote-tracking branch 'upstream/master' into web-component-chip

e278e32

# Conflicts: # openlibrary/templates/design.html

[pre-commit.ci] auto fixes from pre-commit.com hooks

c1c7cd0

for more information, see https://pre-commit.ci

lokesh added On Testing and removed On Testing labels Mar 11, 2026

Update work search form and add styling for search-row class

979d8bc

- Modified the search form in work_search.html to include an additional class 'search-row'. - Added CSS rules for the 'search-row' class to provide a margin-bottom of 8px for better spacing.

RayBB added the On Testing label Mar 15, 2026

lokesh requested a review from cdrini March 17, 2026 02:21

Review fixes: rename chip-label to accessible-label, drop aria-curren…

3f715c8

…t and will-change, scope p rule Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

lokesh commented Mar 17, 2026

View reviewed changes

evelynpham04 mentioned this pull request Mar 17, 2026

Standardize Subject Tags UX by adding BEM CSS #11939

Closed

lokesh and others added 2 commits March 20, 2026 09:55

Merge remote-tracking branch 'upstream/master' into web-component-chip

d6da4dc

# Conflicts: # openlibrary/i18n/messages.pot # openlibrary/templates/design.html

[pre-commit.ci] auto fixes from pre-commit.com hooks

44dbd72

for more information, see https://pre-commit.ci

cdrini approved these changes Mar 20, 2026

View reviewed changes

cdrini reviewed Mar 20, 2026

View reviewed changes

cdrini approved these changes Mar 20, 2026

View reviewed changes

cdrini merged commit c99e9ed into internetarchive:master Mar 20, 2026
4 checks passed

lokesh mentioned this pull request Mar 23, 2026

Adopt ol-chip component for subject tag displays across the site #12158

Closed

RayBB removed the On Testing label Mar 23, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

New web component ol-chip#12012

New web component ol-chip#12012
cdrini merged 31 commits intointernetarchive:masterfrom
lokesh:web-component-chip

lokesh commented Mar 5, 2026 •

edited

Loading

Uh oh!

lokesh Mar 17, 2026

Uh oh!

cdrini Mar 13, 2026

Uh oh!

cdrini Mar 20, 2026

Uh oh!

Uh oh!

cdrini Mar 20, 2026

Uh oh!

cdrini Mar 20, 2026

Uh oh!

cdrini Mar 20, 2026

Uh oh!

cdrini left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

lokesh commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Technical

Screenshots

Testing

Stakeholders

Uh oh!

lokesh Mar 17, 2026

Choose a reason for hiding this comment

Uh oh!

cdrini Mar 13, 2026

Choose a reason for hiding this comment

Uh oh!

cdrini Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cdrini Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

cdrini Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

cdrini Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

cdrini left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

lokesh commented Mar 5, 2026 •

edited

Loading