@sesamy/sesamy-components

v2.21.9

Published

4 days ago

Shareable web components library built with Vite + Svelte

0High
0Medium
0Low

markusahlstrand

julianidiart

kortes

🌐 sesamy-components

A shareable web components library using Vite, Svelte, Storybook and TypeScript.

This library provides typed web components that can be used with plain HTML or within any major frameworks, such as React, Angular, Vue or Svelte (see compatibility).

Installation

You can install the package with:

npm install @sesamy/sesamy-components
# or
yarn add @sesamy/sesamy-components

CDN Usage

You can also use the components directly via CDN:

<script type="module" src="https://unpkg.com/@sesamy/sesamy-components"></script>

Components

sesamy-login

A web component that provides authentication functionality, displaying a login button for unauthenticated users and an avatar with a dropdown menu for authenticated users.

Props/Attributes:

buttonText: Text to display on the login button
loading: Boolean to show loading state
loggedIn: Boolean indicating if user is logged in
userAvatar: URL to the user's avatar image
lang: Language setting for the component
variant: Appearance variant ('text', 'picture', or 'link')
class: CSS classes to apply to the component

Events:

login: Dispatched when login action is triggered

Basic Usage Example:

<!-- Simple login button -->
<sesamy-login></sesamy-login>

<!-- Customized login button -->
<sesamy-login button-text="Sign In Now"></sesamy-login>

Design tokens:

<sesamy-login
  style="
    --sesamy-font-family: Georgia; /* Sets font family, default Helvetica */
    --sesamy-login-button-background-color: blue; /* Sets background color of the login button, default transparent */
    --sesamy-login-button-text-color: green; /* Sets text color of the login button, default black */
    --sesamy-login-button-border-color: pink; /* Sets border color of the login button, default black */
    --sesamy-login-button-border-width: 5px; /* Sets border width of the login button, default 1px */
    --sesamy-login-button-border-radius: 20px; /* Sets border radius of the login button, default */
    --sesamy-login-button-font-weight: 100; /* Sets font weight of the login button, default 700 */
    --sesamy-login-popup-width: 400px; /* Sets width of the login popup, default 18rem */
    --sesamy-login-popup-bgcolor: green; /* Sets background color of the login popup, default white */
    --sesamy-login-popup-textcolor: pink; /* Sets text color of the login popup, default black */
    --sesamy-login-popup-border-color: red; /* Sets border color of the login popup, default #e5e7eb */
    --sesamy-login-popup-border-width: 5px; /* Sets border width of the login popup, default 1px */
    --sesamy-login-popup-border-radius: 20px; /* Sets border radius of the login popup, default 0.125rem */
    --sesamy-login-popup-zindex: 100; /* Sets z-index of the login popup, default 10 */
  "
></sesamy-login>

Slots

The sesamy-login component provides several slots for customizing its appearance and behavior:

button-text

Purpose: Replaces the default login button text.
Behavior: Content in this slot will be rendered as the main text of the login button, replacing the default (localized) "login" text.

Example:

<sesamy-login>
  <span slot="button-text">Sign in with Email</span>
</sesamy-login>

button-text-prefix

Purpose: Inserts content before the login button text.
Behavior: Content in this slot will appear before the main button text, useful for adding icons or labels.

Example:

<sesamy-login>
  <span slot="button-text-prefix">🔒</span>
</sesamy-login>

button-text-suffix

Purpose: Inserts content after the login button text.
Behavior: Content in this slot will appear after the main button text, useful for adding icons or additional info.

Example:

<sesamy-login>
  <span slot="button-text-suffix">→</span>
</sesamy-login>

avatar

Purpose: Replaces the default avatar shown when logged in.
Behavior: Content in this slot will be rendered instead of the default avatar image/button when the user is authenticated.

Example:

<sesamy-login>
  <img
    slot="avatar"
    src="/my-avatar.png"
    alt="User avatar"
    style="width:32px;height:32px;border-radius:50%"
  />
</sesamy-login>

popup-menu

Purpose: Replaces the default popup menu shown when clicking the avatar.
Behavior: Content in this slot will be rendered instead of the default menu (email/account/logout) when the user is authenticated and opens the menu.

Example:

<sesamy-login>
  <div slot="popup-menu">
    <a href="/profile">Profile</a>
    <a href="/logout">Logout</a>
  </div>
</sesamy-login>

Note:

All slots are optional. If not provided, the component will render its default content for each area.

sesamy-content-container

A web component that controls access to content based on user authentication and entitlements, with support for different content locking mechanisms.

Props/Attributes:

item-src: URL of the content item
pass: Semicolon-separated list of pass IDs that grant access
access-level: Access level required ('public', 'logged-in', or 'entitlement')
publisher-content-id: ID of the content from the publisher
lock-mode: Content locking mechanism ('embed', 'encode', 'signedUrl', 'event', or 'proxy')
locked-content-selector: CSS selector for locked content when using signed URLs

Events:

sesamyUnlocked: Dispatched when content is unlocked (with item-src and publisher-content-id in detail)

Basic Usage Example:

<!-- Basic content container with preview and locked content -->
<sesamy-content-container item-src="https://example.com/article.html">
  <div slot="preview">This is a preview visible to everyone</div>
  <div slot="content">This is the full content for authorized users</div>
</sesamy-content-container>

<!-- Content visible only to logged-in users -->
<sesamy-content-container access-level="logged-in">
  <div slot="preview">Please log in to view this content</div>
  <div slot="content">This content is for logged-in users only</div>
</sesamy-content-container>

sesamy-paywall

A web component that displays a paywall for content, loading paywall settings from a remote URL and supporting different templates (Article, Boxes, Login).

Props/Attributes:

settings-url: URL to fetch paywall settings (required)
item-src: URL of the content item
price: Price of the content
currency: Currency code for the price
redirect-url: URL to redirect after purchase
utm-source, utm-medium, utm-campaign, utm-term, utm-content: UTM parameters for tracking
pass: Pass ID for access

Events:

sesamyPaywallAccessChecked: Emitted after access check, with { hasAccess, paywallId, articleUrl, passes } in detail.
sesamyPaywallProductSelected: Emitted when a product/subscription is selected and the continue button is pressed, with { product, checkoutId, paywallId } in detail.
sesamyPaywallCheckoutRedirect: Emitted before redirecting to checkout, with { checkout, paywallId, paymentMethod } in detail. Slots:
below-headline: Content rendered below the paywall headline (e.g., additional info, custom elements)
features: Content rendered in the features section of the paywall (e.g., feature list, benefits)

Basic Usage Example:

<!-- Article paywall -->
<sesamy-paywall
  settings-url="https://api.example.com/paywall/settings"
  item-src="https://example.com/article"
  price="99"
  currency="USD"
>
  <div slot="features">✔️ Unlimited access<br />✔️ Cancel anytime</div>
</sesamy-paywall>

<!-- Login paywall with below-headline slot -->
<sesamy-paywall settings-url="https://api.example.com/paywall/login-settings">
  <div slot="below-headline">Additional content below headline</div>
</sesamy-paywall>

Slots

The sesamy-paywall component provides two main slots for customization:

below-headline

Purpose: Inserts custom content directly below the paywall headline.
Behavior: The content you provide in this slot will be rendered in addition to the default paywall content, immediately below the headline. Use this for adding extra information, banners, or custom elements.

Example:

<sesamy-paywall settings-url="https://api.example.com/paywall/login-settings">
  <div slot="below-headline">Special offer for new users!</div>
</sesamy-paywall>

features

Purpose: Replaces the default features section of the paywall.
Behavior: When you provide content in the features slot, it will completely replace the built-in features list or section. Use this slot to fully customize the list of benefits, features, or selling points shown to the user.

Example:

<sesamy-paywall settings-url="https://api.example.com/paywall/settings">
  <div slot="features">
    <ul>
      <li>✔️ Unlimited access</li>
      <li>✔️ Cancel anytime</li>
      <li>✔️ Exclusive articles</li>
    </ul>
  </div>
</sesamy-paywall>

Note:

The below-headline slot adds to the paywall, while the features slot replaces the default features section entirely.

sesamy-visibility

A simple web component that conditionally renders content based on user authentication status.

Basic Usage Example:

<sesamy-visibility>
  <div slot="logged-in">This content is only visible when logged in</div>
  <div slot="not-logged-in">This content is only visible when not logged in</div>
</sesamy-visibility>

sesamy-avatar

A web component that displays a user avatar image with configurable size and loading state.

Props/Attributes:

src: URL of the avatar image
alt: Alt text for the image
size: Size of the avatar ('sm', 'md', or 'lg')
loading: Boolean to show loading state

Basic Usage Example:

<!-- Default avatar -->
<sesamy-avatar src="https://example.com/user.jpg" alt="User avatar"></sesamy-avatar>

<!-- Large avatar with loading state -->
<sesamy-avatar src="https://example.com/user.jpg" size="lg" loading></sesamy-avatar>

sesamy-button

A customizable button web component with multiple variants and sizes.

Props/Attributes:

variant: Button style variant ('primary', 'secondary', or 'tertiary')
size: Button size ('sm', 'md', or 'lg')
loading: Boolean to show loading spinner
disabled: Boolean to disable the button
href: URL if the button should act as a link
type: Button type ('button', 'submit', etc.)
class: Additional CSS classes

Basic Usage Example:

<!-- Primary button -->
<sesamy-button variant="primary">Subscribe</sesamy-button>

<!-- Secondary button with loading state -->
<sesamy-button variant="secondary" loading>Processing...</sesamy-button>

<!-- Button as a link -->
<sesamy-button href="/checkout" variant="primary">Go to Checkout</sesamy-button>

sesamy-login-menu-item

A web component for individual menu items in the login dropdown menu. Can be used to customize the logged-in user menu.

Props/Attributes:

type: Type of menu item ('EMAIL', 'ACCOUNT', 'LOGOUT', or 'LINK')
href: URL for link type items
target: Link target attribute (e.g., '_blank')
text: Custom text for the menu item

Basic Usage Example:

<!-- Account link -->
<sesamy-login-menu-item type="ACCOUNT"></sesamy-login-menu-item>

<!-- Custom link -->
<sesamy-login-menu-item
  type="LINK"
  href="https://example.com/settings"
  text="Settings"
></sesamy-login-menu-item>

<!-- Logout button -->
<sesamy-login-menu-item type="LOGOUT"></sesamy-login-menu-item>

Internationalization

The components support multiple languages out of the box. Supported languages:

🇬🇧 English (en)
🇸🇪 Swedish (sv)
🇳🇴 Norwegian Bokmål (nb)
🇩🇰 Danish (da)
🇫🇮 Finnish (fi)
🇮🇹 Italian (it)
🇵🇱 Polish (pl)
🇨🇿 Czech (cs)

Set the language using the lang attribute on supported components:

<sesamy-login lang="sv"></sesamy-login>

Development

Your components source code lives in packages/lib/ folder. Only components with the .wc.svelte extension will be exported as web components and available in your library. This means that you can also use regular Svelte components with the .svelte extension as child components for your implementation details.

You can add additional components by adding them to the packages/lib/src folder and editing packages/lib/index.ts.

Available Scripts

| Command | Description | | ---------------------- | -------------------------------------------------- | | yarn dev | Start the development server | | yarn build | Build both library and demo | | yarn build:lib | Build the library only | | yarn storybook | Start Storybook for component development | | yarn build:storybook | Build Storybook for deployment | | yarn test | Run Playwright tests | | yarn check | Run Svelte type checking | | yarn pull-translations | Pull latest translations from i18nexus |

Testing your components

You can start a development server with:

yarn dev

Then open your browser to localhost:5173.

This will build the demo application located in the packages/demo/ folder, in which you can use and test your web components during development.

Storybook

For component development and visual testing, use Storybook:

yarn storybook

Then open your browser to localhost:6006.

End-to-End Tests

Run Playwright tests with:

yarn test

For running E2E tests in Docker (ensuring consistent snapshots):

yarn e2e

To update snapshots:

yarn e2e:snapshots

Using the built web components with the demo app

The demo application is provided for development and testing of your components, that's why it imports the .svelte files from the packages/lib/ folder directly by default.

If you prefer, you can import the built web components from the dist/ folder instead, by editing packages/demo/src/App.svelte and replacing the import statement with import '../../../dist/lib'; if you have the bundleComponents option enabled.

You'll also have to make sure to run the yarn build script to generate the dist/lib/ folder first.

Building the library

The command yarn build will create the web components library in the dist/lib/ folder. It creates both an ES module (dist/lib/<your-lib>.js) suitable for bundler (non-minified), a minified ES module (dist/lib/<your-lib>.min.js) and a regular UMD script (dist/lib/<your-lib>.umd.js).

The build is automatically called when executing yarn publish to distribute your library, thanks to the prepublishOnly script entry in package.json.

Notes and limitations

This template does not provide any web components polyfills for older browsers support. It's usually best to leave that task to the host application, hence why they're left out.

Props

Any props accepted by your web component are automatically transformed to element attributes. Since camelCase or PascalCase does not work in HTML, you have to make sure to name your props in lowercase.

<script>
  export let myvalue = 'Default';
</script>

Events

The Svelte syntax event for listening to events like on:myevent doesn't work with events dispatched from a Svelte web component (#3119).

You need to use a workaround for that, by creating a CustomEvent and dispatching it.

Here's an example:

// MyComponent.wc.svelte
<svelte:options tag="my-component" />
<script>
  import { get_current_component } from 'svelte/internal';
  const component = get_current_component();

  // example function for dispatching events
  const dispatchEvent = (name, detail) =>
    component.dispatchEvent(new CustomEvent(name, { detail }));
</script>
<button onclick="{()" ="">dispatchEvent("test", "Hello!")}> Click to dispatch event</button>

Create a new component

These are the files needed to create a new component:

Add the my-component.wc.svelte file in the packages/lib/src folder.
Add the class in the packages/lib/src/sesamy-components.d.ts file to get the types exported.
Add the component to the packages/lib/index.ts file to export it.
Add a story in the packages/lib/src/stories folder.

License

This project is proprietary software by Sesamy.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

🌐 sesamy-components

Table of Contents

Installation

CDN Usage

Components

sesamy-login

Slots

button-text

button-text-prefix

button-text-suffix

avatar

popup-menu

sesamy-content-container

sesamy-paywall

Slots

below-headline

features

sesamy-visibility

sesamy-avatar

sesamy-button

sesamy-login-menu-item

Internationalization

Development

Available Scripts

Testing your components

Storybook

End-to-End Tests

Using the built web components with the demo app

Building the library

Notes and limitations

Props

Events

Create a new component

License