oc-ui-kit

UI kit — a library of reusable web components built with Lit and TypeScript, documented with Storybook 10, and published to npm via GitHub Actions.

Getting Started

Installation

npm install @purse-eu/oc-ui-kit lit

Usage

<!-- In your HTML -->
<script type="module">
  import '@purse-eu/oc-ui-kit';
</script>

<p-consent variant="save_card"></p-consent>
<p-tokens-list>
  <!-- Slotted token components go here (open shadow DOM, standard <slot>) -->
</p-tokens-list>

// In TypeScript
import { PConsent, PTokensList } from '@purse-eu/oc-ui-kit';

Development

Prerequisites

• Node.js 20+
• npm

Install dependencies

npm install

Run Storybook (development)

npm run storybook

Storybook runs on http://localhost:6006.

Build the library

npm run build

Output is in the dist/ folder:

• dist/index.js — ES module
• dist/index.umd.cjs — UMD (CommonJS)
• dist/index.d.ts — TypeScript type declarations

Type check

npm run type-check

Build Storybook static site

npm run build-storybook

Components

| Component | Tag | Description | | -------------------- | ------------------------ | -------------------------------------------------------------------------------- | | PConsent | <p-consent> | Consent collection with three variants: save_card, transfer_card, account_creation. | | POtp | <p-otp> | OTP verification (SMS / email) with retry cooldown and error/success states. | | PProductEducation | <p-product-education> | Modal explaining the One Check flow. Focus-trapped, Escape to close. | | PTokensList | <p-tokens-list> | Section heading for saved-token lists. Exposes a <slot> for projected tokens. |

Testing

Visual regression tests run every story through Storybook's Vitest addon, take a screenshot, and diff against a baseline using Vitest 4's built-in toMatchScreenshot (pixelmatch, 1% allowed mismatch).

npm test           # run once (CI mode)
npm run test:watch # watch mode
npm run test:update # update baselines after an intentional visual change

Baselines are committed under src/components/p-*/__screenshots__/.

Regenerating baselines for CI

CI runs the suite inside the Microsoft Playwright Docker image so font rendering is deterministic. macOS and Linux render glyphs differently, so baselines generated locally on macOS will not match CI. To regenerate baselines inside the same container CI uses:

docker run --rm -v "$PWD:/work" -w /work mcr.microsoft.com/playwright:v1.59.1-noble \
  sh -c "npm ci && npm run test:update"

Then commit the updated PNGs in src/components/**/__screenshots__/. Keep the image tag in sync with the playwright devDependency version.

Publishing

The library is published automatically to npm when a tag matching v* is pushed:

git tag v1.0.0
git push origin v1.0.0

Requires an NPM_TOKEN secret configured in the GitHub repository settings.

CI

On every push to main, .github/workflows/on-push-main.yaml runs:

• release-manager — creates a release when the version is bumped.
• visual-tests (non-blocking) — runs npm test inside mcr.microsoft.com/playwright:v1.59.1-noble. On failure, uploads *-diff.png / *-actual.png from the __screenshots__ folders as a 7-day artifact. Marked continue-on-error: true — failure is surfaced in the UI but does not block the release job.

Storybook is deployed to GitHub Pages by .github/workflows/storybook.yml.