@sesamy/components

Sesamy web components built with Stencil. The long-term replacement for the legacy sesamy-components library. Components use the shared sesamy-js singleton (window.sesamy) exclusively for auth and API access — they never talk to Sesamy APIs directly.

Principles

• Shadow DOM everywhere. Publisher CSS can never break a component and components never leak styles into the page.
• Theming via design tokens. Every visual value reads a --sesamy-* custom property with a built-in fallback (see src/global/tokens.css). Tokens inherit through the shadow boundary, so publishers theme with plain CSS on :root, a wrapper, or a single instance.
• ::part() for surgical overrides, slots for content. Each component documents its parts and slots in its generated readme (e.g. src/components/license-claim/readme.md).
• SSR-ready discipline. No window/document access at module scope; data loads after hydration. Server-side rendering (declarative shadow DOM / hydrate module) can be enabled later without redesign.
• Zero-config on publisher pages. Components resolve the sesamy-js instance the page already initialized. SPAs can inject an instance via the client property instead.

Usage

Script tag (served by scripts-host alongside sesamy-js):

<sesamy-license-claim pool-id="pool_acme_fsecure" heading="F-Secure Total">
  <span slot="description">Your ACME Plus subscription includes a 1-year license.</span>
</sesamy-license-claim>

Theming:

:root {
  --sesamy-color-primary: #6320ee;
  --sesamy-radius: 16px;
}
sesamy-license-claim::part(key) {
  background: #efe7ff;
}

React (see @sesamy/components-react):

import { SesamyLicenseClaim } from '@sesamy/components-react';

<SesamyLicenseClaim poolId="pool_acme_fsecure" onSesamyLicenseClaimed={onClaimed} />;

Development

pnpm components storybook        # component demo/docs at localhost:6006 (mocked sesamy-js)
pnpm components storybook:build  # static demo site → storybook-static/
pnpm components dev              # bare-bones playground at localhost:3333
pnpm components test             # vitest via @stencil/vitest (stencil-test)
pnpm components build            # dist + custom elements + React wrappers
pnpm components type-check

Storybook is the primary demo: one story per component state plus a Themed story showing token + ::part() customization. Stories live in stories/ (outside src/ so Stencil and vitest ignore them) and mock window.sesamy — no backend needed.

The build also regenerates ../components-react/src/components.ts — commit it together with component changes.