# Archr.se | Product Score Web Component
[](https://www.npmjs.com/package/@archr-se/score-card)
[](https://www.archr.se/)
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:
```bash
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):**
```javascript
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:
```html
```
* **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"`.
```html
```
> 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 `` tag in your HTML and pass `score-data` as JSON.
```html
```
* `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`:
```js
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](./examples/vite-vanilla/README.md)
- [Vite + React + @archr-se/score-card](./examples/vite-react/README.md)
- [Vite + Vue + @archr-se/score-card](./examples/vite-vue/README.md)
- [Vite + Svelte + @archr-se/score-card](./examples/vite-svelte/README.md)
- [Vite + Angular + @archr-se/score-card](./examples/vite-angular/README.md)
- [HTML + CDN + @archr-se/score-card](./examples/html-cdn/README.md)
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.