🌐 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

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"
>
  <<<<<<< HEAD =======
  <div slot="features">✔️ Unlimited access<br />✔️ Cancel anytime</div>
  >>>>>>> main
</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>

Development

Your components source code lives in 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 lib folder and editing lib/index.js.

Testing your components

You can start a development server with:

npm start

Then open your browser to localhost:5173.

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

If you need unit tests, you can take a look at Jest and Jest testing library.

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 lib/ folder directly by default.

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

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 lib/src folder.
• Add the class in the lib/src/sesamy-component.d.ts file to get the types exported.
• Add the component to the lib/src/index.ts file to export it.
• Add a story in the stories folder.