Archr.se | Product Score Web Component

A framework-agnostic web component that renders Archr's product scoring information from input data, including overall score and detailed aspect scores.

Features

• Data Driven: Renders directly from a score-data JSON attribute.
• 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.
• Responsive Design: Includes basic responsive styling.
• 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.
• Safe Fallback Behavior: If score-data is missing or invalid, the component stays hidden.

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 and pass score-data as JSON.

   <product-score
       score-data='{"overall_score":8.4,"aspect_scores":[{"aspect":{"name":"Climate"},"value":8.8}]}'
   ></product-score>
   
   <product-score
       size="small"
       score-data='{"overall_score":4.9,"aspect_scores":[{"aspect":{"name":"Circularity"},"value":4.1}]}'
   ></product-score>

   • score-data must be valid JSON.
   • overall_score is required and must be numeric.
   • aspect_scores is optional.

If you are setting values from JavaScript/framework code, generate the JSON string with JSON.stringify:

const payload = {
  overall_score: 8.4,
  aspect_scores: [
    { aspect: { name: 'Climate' }, value: 8.8 },
    { aspect: { name: 'Circularity' }, value: 7.9 },
  ],
};

element.setAttribute('score-data', JSON.stringify(payload));

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

* **`score-data` (Required)**
  * Type: `string` (JSON)
  * Description: JSON payload used for rendering. Required shape:
  * `overall_score`: number (required)
  * `aspect_scores`: array (optional), where each item contains:
    * `aspect.name`: string
    * `value`: number
  * Behavior: The component hides itself when JSON is invalid or `overall_score` cannot be parsed to a finite number.

• size (Optional)
  • Type: "small" | "medium" | "large"
  • Default: medium
  • Description: Controls the width of the overall score display. Accepts:
    • small — 70px width
    • medium — 80px width (default)
    • large — 100px 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: Styles are encapsulated in Shadow DOM. The current implementation does not expose CSS Custom Properties or ::part selectors for external theming.

Browser Support

This component relies on modern browser features:

• Custom Elements v1
• Shadow DOM v1
• ES Modules (depending on your import method)

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.