@usgb/spot-widgets

Web component widgets for precious metals spot price data. Single script include, works anywhere.

Widgets

| Widget | Tag | |--------|-----| | spot-price-chart | <spot-price-chart> |

Installation

npm

npm install @usgb/spot-widgets

CDN

<!-- Or self-hosted CDN -->
<script src="https://cdn.example.com/spot-widgets/1.0.0/spot-price-chart.js"></script>

Usage

Script Tag

<script src="https://unpkg.com/@usgb/spot-widgets/dist/spot-price-chart.js"></script>

<spot-price-chart></spot-price-chart>

<spot-price-chart metal="Silver" timeframe="1W" refresh-interval="60000"></spot-price-chart>

ES Module Import (Vite, Webpack, etc.)

// Side-effect import - component auto-registers
import '@usgb/spot-widgets'

// Then use anywhere in your app
<spot-price-chart metal="Gold" timeframe="1D"></spot-price-chart>

Verify Installation

Check in browser console:

customElements.get('spot-price-chart') !== undefined  // true if loaded

Attributes:

| Attribute | Values | Default | |-----------|--------|---------| | metal | Gold, Silver, Platinum, Palladium | Gold | | timeframe | 1D, 1W, 1M, 1Y | 1D | | refresh-interval | milliseconds | — |

Build

npm install
npm run build                           # Build all
npm run build:widget spot-price-chart   # Single widget

Output: dist/<widget-name>.js

Publish

npm Registry

npm run publish:npm              # Build and publish current version
npm run publish:npm:dry          # Dry run (preview only)

./scripts/publish.sh -v patch    # Bump patch version and publish
./scripts/publish.sh -v minor    # Bump minor version and publish  
./scripts/publish.sh -v major    # Bump major version and publish
./scripts/publish.sh -v 1.2.3    # Publish specific version

Requires NPM_TOKEN environment variable or npm login with @usgb scope access.

CDN (S3/R2)

CDN_BUCKET=my-bucket ./scripts/deploy.sh -v 1.0.0
CDN_BUCKET=my-bucket ./scripts/deploy.sh -w spot-price-chart -v 1.0.0
CDN_BUCKET=my-bucket ./scripts/deploy.sh -d   # Dry run

| Variable | Required | Default | |----------|----------|---------| | CDN_BUCKET | Yes | — | | CDN_PREFIX | No | spot-widgets |

Theming

Override via CSS custom properties:

spot-price-chart {
  --spot-widget-primary: #1a1a2e;
  --spot-widget-text-base: #ffffff;
  --spot-widget-grey-4: #3a3a5a;
  --spot-widget-grey-5: #2a2a4a;
  --spot-widget-grey-6: #3a3a5a;
  --spot-widget-grey-9: #aaaacc;
  --spot-widget-q2: #252540;
  --spot-widget-green-2: #16a34a;
  --spot-widget-red: #dc2626;
  --spot-widget-blue-1: #2563eb;
  --spot-widget-blue-4: #3b82f6;
}

Adding Widgets

1. Create src/components/NewWidget/
   • NewWidget.tsx
   • NewWidget.module.scss
   • web-component.ts
2. Add to WIDGETS in scripts/build.sh
3. Update this README

Development

npm run dev        # Dev server
npm run typecheck  # Type check