Archr.se | Product Score Web Component

A framework-agnostic web component that fetches and displays product scoring information, including overall score and detailed aspect scores, based on a product's EAN (European Article Number).

Features

• Data Driven: Fetches product details and scores dynamically from an API using the provided EAN.
• Informative Display: Shows a prominent overall score with colored background based on rating level, and a list of individual aspect scores that appear on hover/focus.
• Configurable API Endpoint: Specify the base URL for the API calls.
• Responsive Design: Includes basic responsive styling and uses container queries for better adaptability.
• Loading & Error States: Provides visual feedback during data fetching and displays clear error messages.
• Customizable: Uses CSS Custom Properties for easy theming and styling adjustments.
• Standard Web Component: Built with standard browser APIs (Custom Elements, Shadow DOM) for maximum compatibility and ease of use in any framework or vanilla HTML/JS project.
• Robust Fetching: Handles aborting previous requests if the EAN or API URL changes, preventing race conditions.

Installation

You can install the component via npm, pnpm, yarn, or bun if you are working within a project with a build process:

npm install @archr-se/score-card
# or
yarn add @archr-se/score-card
# or
pnpm add @archr-se/score-card
# or
bun add @archr-se/score-card

See the Usage section below for how to integrate it after installation or use it directly via CDN.

Usage

How you use the component depends on your project setup.

1. Import the component: How you import depends on your project setup.

   • Using Modules (e.g., with Vite, Webpack):

     import '@archr-se/score-card';
     // or potentially (if the main entry point exports the class):
     // import { ProductScore } from '@archr-se/score-card';
     // customElements.define('product-score', ProductScore); // if not auto-defined

   • Using a Script Tag with a Local Bundle: If you bundle the component into a UMD or IIFE file as part of your build process:

     <script src="path/to/your/product-score-bundle.js"></script>

   • Using a Script Tag via CDN (e.g., for WordPress, simple HTML): You can load the component directly from a CDN like unpkg or jsDelivr. This is the easiest way for simple integrations without a build step. Use the ES module version (.es.js) with type="module".

     <script type="module" src="https://unpkg.com/@archr-se/score-card@latest/dist/product-score-component.es.js"></script>
     
     <script type="module" src="https://cdn.jsdelivr.net/npm/@archr-se/score-card@latest/dist/product-score-component.es.js"></script>

     Replace @latest with a specific version (e.g., @1.0.0) in production to avoid unexpected updates. You can find available versions on NPM.

     The type="module" attribute is important when loading ES modules directly in the browser.

     If you needed compatibility with older environments that don't support modules, you might use the .umd.js file instead, but the module approach is generally preferred.

2. Use the HTML tag: Place the <product-score> tag in your HTML, providing the necessary attributes.

   <product-score
       ean="1234567890123"
       api-base-url="https://your-api.example.com"
   ></product-score>
   
   <product-score ean="9876543210987"></product-score>

   • Replace "1234567890123" with the actual EAN of the product.
   • Replace "https://your-api.example.com" with the base URL that archr.se has provided to you.

Examples

This repository includes examples demonstrating how to use the product-score component with various frameworks and build tools:

• Vite + Vanilla + @archr-se/score-card
• Vite + React + @archr-se/score-card
• Vite + Vue + @archr-se/score-card
• Vite + Svelte + @archr-se/score-card
• Vite + Angular + @archr-se/score-card
• HTML + CDN + @archr-se/score-card

Please refer to the README.md file within each example directory for specific setup and usage instructions.

Attributes

• ean (Required)
  • Type: string
  • Description: The European Article Number (barcode) of the product for which to fetch the score. The component will fetch data when this attribute is set and valid. Changing this attribute will trigger a new data fetch.
• api-base-url (Optional)
  • Type: string
  • Default: https://api.archr.se/
  • Description: The base URL for the API endpoint. The component constructs the final API URL by appending /api/public/product-score/{ean}/ to this base URL. Ensure the path ends correctly (the component handles extra slashes).
• size (Optional)
  • Type: "small" | "medium" | "large"
  • Default: medium
  • Description: Controls the width of the overall score display. Accepts:
    • small — 40px width
    • medium — 50px width (default)
    • large — 70px width

Styling

The component uses Shadow DOM to encapsulate its styles, preventing conflicts with global styles. The current implementation uses SVG images for score visualization with colors determined by score thresholds:

• Scores ≤ 2.5: Low score visualization (red)
• Scores ≤ 5.0: Mid-low score visualization (yellow/orange)
• Scores ≤ 7.5: Mid-high score visualization (light green)
• Scores > 7.5: High score visualization (green)

The component provides a clean, modern design with fixed styling. The aspect scores list has a maximum height of 300px with overflow scrolling.

Note: The current implementation does not support CSS Custom Properties for color theming or ::part selectors for targeting internal elements. These features may be added in future versions.

Browser Support

This component relies on modern browser features:

• Custom Elements v1
• Shadow DOM v1
• ES Modules (depending on your import method)
• Fetch API
• CSS Custom Properties

It should work in all evergreen browsers (Chrome, Firefox, Safari, Edge). Polyfills might be required for older browser support (e.g., IE11, though support is generally declining).

License

This project is licensed under All Rights Reserved.