@circlesquare/embedding-next 1.0.1 → 2.1.0

package/README.md

@@ -1,6 +1,7 @@
 # @circlesquare/embedding-next
 
-Next.js components for embedding your clubs events and court availability.
+Next.js components for embedding your club's events and court availability, in your website's
+colors, corners and typeface.
 
 ## Installation
 
@@ -10,14 +11,24 @@ npm install @circlesquare/embedding-next
 yarn add @circlesquare/embedding-next
 ```
 
+The package needs React 18 or later.
+
 ## Usage
 
-All components must be used in client components. Add `'use client'` at the top of your file.
+The components are client components (`'use client'`). You can render them from a Server
+Component page or from your own client component.
+
+Every component needs your merchant id. It looks like `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`, and
+you find it in the manager under
+[**Settings** > **Developer**](https://manager.circlesquare.app/settings/developer).
+
+### Config provider (optional)
 
-### Config Provider (Optional)
+The provider holds the options every component below it shares, so you set your merchant id and
+your look once, for example in your root layout. A component's own props override the provider's
+for that component only.
 
 ```tsx
-'use client'
 import { CircleSquareEmbeddingConfigProvider } from '@circlesquare/embedding-next'
 
 export default function RootLayout({ children }) {
@@ -32,18 +43,22 @@ export default function RootLayout({ children }) {
   )
 }
 ```
-_Note: When using React 19 wrapping children with `<></>` might be required_
 
-#### Provider Config
-- `merchantId` (required): Your CircleSquare merchant ID
-- `backgroundColor` (optional): Background color for the embedded content
-- `language` (optional): Language of the embedded content (en / de). Will otherwise be selected automatically.
+_Note: With React 19, wrapping children in `<></>` might be required._
+
+#### Provider props
+
+| Prop              | Required | Description                                                                                                                         |
+| ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `merchantId`      | No       | Your CircleSquare merchant ID, for every component below                                                                            |
+| `backgroundColor` | No       | Background color for the embedded content                                                                                           |
+| `language`        | No       | Language of the embedded content (`en` / `de`). Will otherwise be selected automatically.                                           |
+| Look options      | No       | `appearance`, `surfaceColor`, `textColor` and the others in [Match the widgets to your website](#match-the-widgets-to-your-website) |
 
-### Events Component
+### Events component
 
 ```tsx
-'use client'
-import { CSEvents, CsEventType } from "@circlesquare/embedding-next";
+import { CSEvents, CsEventType } from '@circlesquare/embedding-next'
 
 export default function EventsPage() {
   return (
@@ -59,48 +74,169 @@ export default function EventsPage() {
 }
 ```
 
-#### CSEvents Config
-- `merchantId` (optional if in provider): Your CircleSquare merchant ID
-- `hostId` (optional): Filter events by host ID
-- `backgroundColor` (optional): Background color for the embedded content
-- `language` (optional): Language of the embedded content (en / de). Will otherwise be selected automatically.
-- `eventTypes` (optional): Array of event types to filter
-  - `OpenPlay`
-  - `Training`
-  - `Other`
-  - `League`
-  - `Americano`
-  - `AmericanoTournament`
-  - `KnockOutTournament`
-  - `RoundRobinTournament`
-- `className` (optional): Additional CSS class for the container
-- `fallback` (optional): A component to display in case the embedding iframe can not be loaded or displayed. If not provided, the default component will be used.
-- `timeoutMs` (optional): Time after which the fallback component is displayed. Defaults to 3000 (3 seconds)
-
-
-### Court Availability Component
+#### CSEvents props
+
+| Prop              | Required                 | Description                                                                                                     |
+| ----------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `merchantId`      | Unless set in a provider | Your CircleSquare merchant ID. With only `hostId`, the component lists that host's events.                      |
+| `hostId`          | No                       | Filter events by host ID                                                                                        |
+| `eventTypes`      | No                       | Array of event types to filter, from `CsEventType` (below). All types by default.                               |
+| `sports`          | No                       | Array of sports to filter, from `CsSport` (below). All of your club's sports by default.                        |
+| `sportIds`        | No                       | Deprecated, use `sports`. Array of sport IDs to filter.                                                         |
+| `backgroundColor` | No                       | Background color for the embedded content                                                                       |
+| `language`        | No                       | Language of the embedded content (`en` / `de`). Will otherwise be selected automatically.                       |
+| Look options      | No                       | See [Match the widgets to your website](#match-the-widgets-to-your-website)                                     |
+| `className`       | No                       | Additional CSS class for the element that holds the widget                                                      |
+| `fallback`        | No                       | A component to display in case the widget can not be loaded or displayed. If not provided, the default is used. |
+| `timeoutMs`       | No                       | Time after which the fallback component is displayed. Defaults to 8000 (8 seconds).                             |
+
+`CsEventType` values:
+
+- `OpenPlay`
+- `Training`
+- `Other`
+- `League`
+- `Americano`
+- `AmericanoTournament`
+- `RoundRobinTournament`
+- `Tournament`
+- `LevelingSession`
+
+`CsSport` values:
+
+- `Tennis`
+- `Padel`
+- `Pickleball`
+- `BeachVolleyball`
+- `Football`
+- `Badminton`
+- `Squash`
+
+```tsx
+<CSEvents sports={[CsSport.Padel, CsSport.Pickleball]} />
+```
+
+A sport the widget doesn't know is left out, and the browser console names it. If no sport you
+named is left, the widget shows all of them.
+
+### Court availability component
 
 ```tsx
-'use client'
 import { CSCourtAvailability } from '@circlesquare/embedding-next'
 
 export default function CourtsPage() {
   return (
     <div>
       <h1>Court Availability</h1>
-      <CSCourtAvailability
-        merchantId="your-merchant-id"
-        backgroundColor="#F5F5F5"
-      />
+      <CSCourtAvailability merchantId="your-merchant-id" backgroundColor="#F5F5F5" />
     </div>
   )
 }
 ```
 
-#### CSCourtAvailability Config
-- `merchantId` (optional if in provider): Your CircleSquare merchant ID
-- `language` (optional): Language of the embedded content (en / de). Will otherwise be selected automatically.
-- `backgroundColor` (optional): Background color for the embedded content
-- `className` (optional): Additional CSS class for the container
-- `fallback` (optional): A component to display in case the embedding iframe can not be loaded or displayed. If not provided, the default component will be used.
-- `timeoutMs` (optional): Time after which the fallback component is displayed. Defaults to 3000 (3 seconds)
+#### CSCourtAvailability props
+
+| Prop              | Required                 | Description                                                                                                     |
+| ----------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `merchantId`      | Unless set in a provider | Your CircleSquare merchant ID                                                                                   |
+| `sports`          | No                       | Array of sports to show, from `CsSport` as for `CSEvents`. All of your club's sports by default.                |
+| `sportIds`        | No                       | Deprecated, use `sports`. Array of sport IDs to show.                                                           |
+| `language`        | No                       | Language of the embedded content (`en` / `de`). Will otherwise be selected automatically.                       |
+| `backgroundColor` | No                       | Background color for the embedded content                                                                       |
+| Look options      | No                       | See [Match the widgets to your website](#match-the-widgets-to-your-website)                                     |
+| `className`       | No                       | Additional CSS class for the element that holds the widget                                                      |
+| `fallback`        | No                       | A component to display in case the widget can not be loaded or displayed. If not provided, the default is used. |
+| `timeoutMs`       | No                       | Time after which the fallback component is displayed. Defaults to 8000 (8 seconds).                             |
+
+A component without a merchant ID (or, for `CSEvents`, without a host ID) renders nothing and logs
+the reason in the browser console.
+
+## Match the widgets to your website
+
+You can give the widgets your website's colors, corners and typeface. Every option is optional.
+Without them, the widgets use CircleSquare's own look on a white background. Set them on the
+provider for every widget, or on a single component.
+
+```tsx
+<CircleSquareEmbeddingConfigProvider
+  merchantId="your-merchant-id"
+  appearance="dark"
+  backgroundColor="transparent"
+  surfaceColor="#0E1828"
+  textColor="#FFFFFF"
+  accentColor="#C6F432"
+  accentTextColor="#0A1220"
+  eventColor="#38BDF8"
+  borderRadius={24}
+  fontFamily="Inter"
+>
+  {children}
+</CircleSquareEmbeddingConfigProvider>
+```
+
+| Option            | What it changes                                                                                                                                                                                   | Default                                                      |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| `appearance`      | `"light"` or `"dark"`. Use `"dark"` on a website with a dark background.                                                                                                                          | `"light"`                                                    |
+| `backgroundColor` | The background behind the widget. `"transparent"` lets your page show through.                                                                                                                    | White, or none with `appearance="dark"`                      |
+| `surfaceColor`    | The widget's own surfaces: the card around the court grid, popovers and dialogs.                                                                                                                  | CircleSquare's                                               |
+| `textColor`       | The text. Secondary text, lines and unavailable time slots are lighter shades of it.                                                                                                              | CircleSquare's                                               |
+| `accentColor`     | Your brand color: the visitor's own bookings, the selected time slot, the main button and the focus outline.                                                                                      | CircleSquare's                                               |
+| `accentTextColor` | Text on the accent color, such as the label of the main button.                                                                                                                                   | Black or white, whichever is easier to read on `accentColor` |
+| `eventColor`      | Events shown in the court grid.                                                                                                                                                                   | CircleSquare's                                               |
+| `borderRadius`    | The corners of cards and buttons. A number is in pixels (`8`). A string in `px` or `rem` works too (`"0.5rem"`). Smaller elements such as grid cells scale with it, and `0` gives square corners. | `12`                                                         |
+| `fontFamily`      | The typeface, one from the list below.                                                                                                                                                            | `"Inter"`                                                    |
+
+Colors can be written as hex (`#C6F432`), with a color function such as `rgb(198, 244, 50)`,
+`hsl()` or `oklch()`, or as a CSS color name (`white`). `backgroundColor` also takes a CSS
+gradient. CSS variables such as `var(--brand)` don't work, because the widget runs in a frame that
+can't read your page's styles.
+
+The widget ignores a value it can't read and keeps its own color, corner or typeface. For colors,
+the browser console also shows a warning such as
+`[CircleSquare] accentColor "#C6F43" is not a colour, leaving the widget's own`.
+
+**Typefaces.** The widget can't use the fonts your website loads, so `fontFamily` takes one of the
+typefaces CircleSquare serves: `Barlow`, `DM Sans`, `Inter`, `Lato`, `Manrope`, `Montserrat`,
+`Nunito`, `Open Sans`, `Oswald`, `Poppins` or `Roboto`. CircleSquare serves the font files itself,
+so the widget sends no requests to Google Fonts and needs no cookie consent.
+
+### Settings for a single widget
+
+Each component takes the same options as props, and they override the provider's for that widget
+only:
+
+```tsx
+<CSEvents accentColor="#B33E25" />
+```
+
+## When a widget can't load
+
+If a widget hasn't loaded after 8 seconds, for example because the visitor's ad blocker drops it,
+a notice with a link to your club's page on CircleSquare takes its place. The notice uses your
+colors and corners. If the widget loads later, it replaces the notice. `timeoutMs` changes how long
+the component waits, and `fallback` replaces the notice with your own:
+
+```tsx
+<CSCourtAvailability timeoutMs={12000} fallback={<p>Book your court at the front desk.</p>} />
+```
+
+If your website has a content security policy, it needs `frame-src https://circlesquare.app`.
+
+## Changes in 2.1
+
+- `sports` names the sports with `CsSport` (`[CsSport.Padel]`), so you no longer need our sport
+  IDs.
+- `sportIds` is deprecated. It still works, alongside `sports`, until 3.0.
+
+## Changes in 2.0
+
+- The look: `appearance`, `surfaceColor`, `textColor`, `accentColor`, `accentTextColor`,
+  `eventColor`, `borderRadius` and `fontFamily`, on the provider or on each component.
+- `sportIds` on both components; `hostId` alone lists a host's events.
+- `CsEventType.Tournament` and `CsEventType.LevelingSession`.
+- `CsEventType.KnockOutTournament` is gone.
+- The widget keeps loading behind the fallback notice and replaces it once it shows. The default
+  `timeoutMs` is 8000 instead of 3000.
+- `className` goes on the element that holds the widget, not on the iframe itself.
+- The components are client components themselves, so a Server Component can render them.
+- The package is an ES module with an `exports` map, and needs no `next` peer.

package/dist/cs-court-availability.d.ts

@@ -0,0 +1,6 @@
+import { type EmbeddedFrameOptions } from './embedded-frame.js';
+import type { CsCourtAvailabilityConfig } from './types.js';
+export interface CSCourtAvailabilityProps extends CsCourtAvailabilityConfig, EmbeddedFrameOptions {
+}
+/** The club's courts, bookable by the day, framed from CircleSquare. */
+export declare function CSCourtAvailability({ className, fallback, timeoutMs, ...own }: CSCourtAvailabilityProps): import("react").JSX.Element | null;

package/dist/cs-court-availability.js

@@ -0,0 +1,17 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect } from 'react';
+import { EmbeddedFrame } from './embedded-frame.js';
+import { mergeConfig, useCircleSquareEmbeddingConfig } from './embedding-config.js';
+/** The club's courts, bookable by the day, framed from CircleSquare. */
+export function CSCourtAvailability({ className, fallback, timeoutMs, ...own }) {
+    const config = mergeConfig(useCircleSquareEmbeddingConfig(), own);
+    const hasClub = Boolean(config.merchantId);
+    useEffect(() => {
+        if (!hasClub)
+            console.error('[CircleSquare] merchantId is required for court availability');
+    }, [hasClub]);
+    if (!hasClub)
+        return null;
+    return (_jsx(EmbeddedFrame, { widget: "courts", config: config, className: className, fallback: fallback, timeoutMs: timeoutMs }));
+}

package/dist/cs-events.d.ts

@@ -0,0 +1,6 @@
+import { type EmbeddedFrameOptions } from './embedded-frame.js';
+import type { CsEventsConfig } from './types.js';
+export interface CSEventsProps extends CsEventsConfig, EmbeddedFrameOptions {
+}
+/** The club's events, or an organizer's with `hostId`, framed from CircleSquare. */
+export declare function CSEvents({ className, fallback, timeoutMs, ...own }: CSEventsProps): import("react").JSX.Element | null;

package/dist/cs-events.js

@@ -0,0 +1,17 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect } from 'react';
+import { EmbeddedFrame } from './embedded-frame.js';
+import { mergeConfig, useCircleSquareEmbeddingConfig } from './embedding-config.js';
+/** The club's events, or an organizer's with `hostId`, framed from CircleSquare. */
+export function CSEvents({ className, fallback, timeoutMs, ...own }) {
+    const config = mergeConfig(useCircleSquareEmbeddingConfig(), own);
+    const hasOwner = Boolean(config.merchantId || config.hostId);
+    useEffect(() => {
+        if (!hasOwner)
+            console.error('[CircleSquare] merchantId or hostId is required for events');
+    }, [hasOwner]);
+    if (!hasOwner)
+        return null;
+    return (_jsx(EmbeddedFrame, { widget: "events", config: config, className: className, fallback: fallback, timeoutMs: timeoutMs }));
+}

package/dist/embedded-frame.d.ts

@@ -0,0 +1,16 @@
+import { type ReactNode } from 'react';
+import { type EmbeddedWidget, type FrameConfig } from './frame-url.js';
+export declare const DEFAULT_TIMEOUT_MS = 8000;
+export interface EmbeddedFrameOptions {
+    /** A class for the element that holds the frame, or the notice in its place. */
+    className?: string;
+    /** Shown instead of the default notice when the frame does not show in time. */
+    fallback?: ReactNode;
+    /** How long a frame may take to report its height before the fallback shows. */
+    timeoutMs?: number;
+}
+/** One framed page on the host's page, as tall as its content. */
+export declare function EmbeddedFrame({ widget, config, className, fallback, timeoutMs, }: EmbeddedFrameOptions & {
+    widget: EmbeddedWidget;
+    config: FrameConfig;
+}): import("react").JSX.Element;

package/dist/embedded-frame.js

@@ -0,0 +1,95 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useRef, useState } from 'react';
+import { FallbackNotice } from './fallback-notice.js';
+import { getConfigWarning, getFrameUrl } from './frame-url.js';
+/* A FRAME THAT DOES NOT SHOW, because our site is down, the visitor's
+   network or a blocker drops it, or the host's policy forbids frames,
+   leaves an empty box where the club sells its courts. A frame shows once
+   it reports its height, so a frame that has not done so in time gives way
+   to a notice with a link to the club on CircleSquare. The frame keeps
+   loading behind the notice and replaces it when it reports, so the wait is
+   the loader's: a slow phone sees the notice only when the frame would keep
+   it waiting long. */
+export const DEFAULT_TIMEOUT_MS = 8000;
+/* What the frame posts whenever its content resizes (apps/web/src/lib/embed.ts). */
+const isSetHeightMessage = (data, containerId) => {
+    if (typeof data !== 'object' || data === null)
+        return false;
+    const message = data;
+    return (message.type === 'setHeight' &&
+        message.containerId === containerId &&
+        typeof message.height === 'number' &&
+        Number.isFinite(message.height));
+};
+/* The frame's name for a screen reader. The server renders it, where the
+   visitor's language is unknown, so only a configured language changes it. */
+const FRAME_TITLES = {
+    courts: { en: 'CircleSquare court availability', de: 'CircleSquare-Platzverfügbarkeit' },
+    events: { en: 'CircleSquare events', de: 'CircleSquare-Events' },
+};
+const getFrameTitle = (widget, { language }) => FRAME_TITLES[widget][language?.toLowerCase() === 'de' ? 'de' : 'en'];
+const isBrowserColour = (value) => typeof CSS === 'undefined' || CSS.supports('color', value);
+/** One framed page on the host's page, as tall as its content. */
+export function EmbeddedFrame({ widget, config, className, fallback, timeoutMs = DEFAULT_TIMEOUT_MS, }) {
+    const containerId = useId();
+    const frameUrl = getFrameUrl({ widget, containerId, config });
+    const { href, origin } = frameUrl;
+    const frameRef = useRef(null);
+    const [height, setHeight] = useState();
+    const [hasTimedOut, setHasTimedOut] = useState(false);
+    const configWarning = getConfigWarning(config, { isColour: isBrowserColour });
+    useEffect(() => {
+        if (configWarning)
+            console.warn(configWarning);
+    }, [configWarning]);
+    useEffect(() => {
+        const fallbackTimer = window.setTimeout(() => {
+            console.warn(`[CircleSquare] the ${widget} frame did not show within ${timeoutMs} ms, linking to CircleSquare instead`);
+            setHasTimedOut(true);
+        }, timeoutMs);
+        /* The host's window receives every message on its page, the host's own
+           included: only a height message from this very frame, sent by the
+           origin it was loaded from and naming this container, is ours. */
+        const handleMessage = (event) => {
+            if (event.source !== frameRef.current?.contentWindow || event.origin !== origin)
+                return;
+            if (!isSetHeightMessage(event.data, containerId))
+                return;
+            window.clearTimeout(fallbackTimer);
+            setHasTimedOut(false);
+            setHeight(event.data.height);
+        };
+        /* A press on the host's page never reaches the frame's document, so a
+           popover open in the frame would stay open: the frame is told of every
+           click, in the capture phase, so a host's handler that stops the click
+           cannot keep it from the frame. */
+        const handleHostPress = () => frameRef.current?.contentWindow?.postMessage({ type: 'hostPress' }, origin);
+        window.addEventListener('message', handleMessage);
+        document.addEventListener('click', handleHostPress, true);
+        /* The frame reports its height when it first lays out and then only
+           when it resizes, so it loads once this listens: a frame in the
+           server's HTML could report before the host's page hydrates, and that
+           report would be lost. Setting the same address again would reload it. */
+        const frame = frameRef.current;
+        if (frame && frame.src !== href)
+            frame.src = href;
+        return () => {
+            window.clearTimeout(fallbackTimer);
+            window.removeEventListener('message', handleMessage);
+            document.removeEventListener('click', handleHostPress, true);
+        };
+    }, [href, origin, containerId, widget, timeoutMs]);
+    return (_jsxs("div", { className: className, style: { width: '100%' }, children: [_jsx("iframe", { ref: frameRef, title: getFrameTitle(widget, config), style: {
+                    display: 'block',
+                    width: '100%',
+                    border: 'none',
+                    height: hasTimedOut ? 0 : height,
+                    /* The framed page's root is light in both appearances, a dark frame
+                       dark from <body> down (apps/web/src/lib/embed-theme.ts). An iframe
+                       in another scheme than its document gets an opaque canvas, which
+                       hides the host's page behind it, so the iframe stays light on a
+                       host that declares itself dark too. */
+                    colorScheme: 'light',
+                } }), hasTimedOut && (fallback ?? _jsx(FallbackNotice, { widget: widget, config: config }))] }));
+}

package/dist/embedding-config.d.ts

@@ -0,0 +1,10 @@
+import { type ReactNode } from 'react';
+import type { CsEmbeddingBaseConfig } from './types.js';
+/** The configuration the nearest provider shares, or null outside one. */
+export declare const useCircleSquareEmbeddingConfig: () => CsEmbeddingBaseConfig | null;
+export interface CircleSquareEmbeddingConfigProviderProps extends CsEmbeddingBaseConfig {
+    children: ReactNode;
+}
+/** The configuration every widget below shares, the club's look included; a widget's own props win. */
+export declare function CircleSquareEmbeddingConfigProvider({ children, ...config }: CircleSquareEmbeddingConfigProviderProps): import("react").JSX.Element;
+export declare function mergeConfig<T extends CsEmbeddingBaseConfig>(shared: CsEmbeddingBaseConfig | null, own: T): T;

package/dist/embedding-config.js

@@ -0,0 +1,17 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from 'react';
+const CircleSquareEmbeddingConfigContext = createContext(null);
+/** The configuration the nearest provider shares, or null outside one. */
+export const useCircleSquareEmbeddingConfig = () => useContext(CircleSquareEmbeddingConfigContext)?.config ?? null;
+/** The configuration every widget below shares, the club's look included; a widget's own props win. */
+export function CircleSquareEmbeddingConfigProvider({ children, ...config }) {
+    return (_jsx(CircleSquareEmbeddingConfigContext.Provider, { value: { config }, children: children }));
+}
+/* An option a widget leaves undefined keeps the provider's, as the old
+   package had it; the loader's `Object.assign` would let an explicit
+   `undefined` erase it, which a React prop passed through often is. */
+export function mergeConfig(shared, own) {
+    const defined = Object.fromEntries(Object.entries(own).filter(([, value]) => value !== undefined));
+    return { ...shared, ...defined };
+}

package/dist/fallback-notice.d.ts

@@ -0,0 +1,9 @@
+import { type EmbeddedWidget, type FrameConfig } from './frame-url.js';
+/**
+ * What a frame that does not show is replaced with: a link to the club on CircleSquare, in the
+ * host's look as far as its options give it.
+ */
+export declare function FallbackNotice({ widget, config }: {
+    widget: EmbeddedWidget;
+    config: FrameConfig;
+}): import("react").JSX.Element;

package/dist/fallback-notice.js

@@ -0,0 +1,76 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { getFallbackUrl } from './frame-url.js';
+const FALLBACK_TEXTS = {
+    courts: {
+        en: {
+            title: 'Court availability cannot be displayed',
+            text: 'You can still book your court directly on CircleSquare.',
+            action: 'Book a court on CircleSquare',
+        },
+        de: {
+            title: 'Die Platzverfügbarkeit kann nicht angezeigt werden',
+            text: 'Du kannst deinen Platz aber direkt bei CircleSquare buchen.',
+            action: 'Platz bei CircleSquare buchen',
+        },
+    },
+    events: {
+        en: {
+            title: 'Events cannot be displayed',
+            text: 'You can find all our events directly on CircleSquare.',
+            action: 'View events on CircleSquare',
+        },
+        de: {
+            title: 'Events können nicht angezeigt werden',
+            text: 'Alle unsere Events findest du direkt bei CircleSquare.',
+            action: 'Events bei CircleSquare anzeigen',
+        },
+    },
+};
+/* The kit's ink, its text and its primary button, for a host that sets neither. */
+const KIT_INK = '#10261E';
+/* The notice shows only after a timeout, in the browser, so it may read the visitor's language. */
+const getTexts = (widget, config) => {
+    const language = (config.language || window.navigator.language || '').slice(0, 2).toLowerCase();
+    return FALLBACK_TEXTS[widget][language === 'de' ? 'de' : 'en'];
+};
+/* A bare number is pixels, as the framed page reads `borderRadius`. */
+const toRadius = (radius) => typeof radius === 'number' || /^\d+(\.\d+)?$/.test(radius ?? '') ? `${radius}px` : radius;
+/* Inline, as everything here, to hold against the host's rules for `p` and `a`. */
+const PARAGRAPH = { color: 'inherit', fontFamily: 'inherit', lineHeight: 1.4 };
+/**
+ * What a frame that does not show is replaced with: a link to the club on CircleSquare, in the
+ * host's look as far as its options give it.
+ */
+export function FallbackNotice({ widget, config }) {
+    const texts = getTexts(widget, config);
+    const radius = toRadius(config.borderRadius);
+    const accent = config.accentColor || KIT_INK;
+    return (_jsxs("div", { "data-circlesquare-fallback": "", style: {
+            boxSizing: 'border-box',
+            display: 'flex',
+            flexDirection: 'column',
+            alignItems: 'center',
+            gap: 8,
+            padding: '32px 24px',
+            textAlign: 'center',
+            border: '1px solid rgba(128, 128, 128, 0.3)',
+            borderRadius: radius || 12,
+            background: config.surfaceColor || config.backgroundColor || 'transparent',
+            color: config.textColor || (config.appearance === 'dark' ? '#FFFFFF' : KIT_INK),
+            fontFamily: config.fontFamily ? `"${config.fontFamily}", system-ui, sans-serif` : 'inherit',
+        }, children: [_jsx("p", { style: { ...PARAGRAPH, margin: 0, fontSize: 18, fontWeight: 700 }, children: texts.title }), _jsx("p", { style: { ...PARAGRAPH, margin: '0 0 8px', fontSize: 15, opacity: 0.75 }, children: texts.text }), _jsx("a", { href: getFallbackUrl({ widget, config }).href, target: "_blank", rel: "noopener", style: {
+                    display: 'inline-block',
+                    padding: '10px 20px',
+                    borderRadius: radius || 999,
+                    background: accent,
+                    color: '#FFFFFF',
+                    fontFamily: 'inherit',
+                    fontSize: 15,
+                    fontWeight: 700,
+                    lineHeight: 1.4,
+                    textDecoration: 'none',
+                }, children: _jsx("span", { style: {
+                        color: config.accentTextColor || `oklch(from ${accent} clamp(0, (0.62 - l) * 1000, 1) 0 0)`,
+                    }, children: texts.action }) })] }));
+}

package/dist/frame-url.d.ts

@@ -0,0 +1,30 @@
+import { type CsEventsConfig } from './types.js';
+export declare const DEFAULT_CS_BASE_URL = "https://circlesquare.app";
+export type EmbeddedWidget = 'courts' | 'events';
+/** A widget's configuration once the provider's and the component's are merged. */
+export type FrameConfig = CsEventsConfig;
+/**
+ * The frame's address. `csEmbedded` is sent as the loader sends it; the framed page knows it is
+ * framed from its path.
+ */
+export declare function getFrameUrl({ widget, containerId, config, }: {
+    widget: EmbeddedWidget;
+    containerId: string;
+    config: FrameConfig;
+}): URL;
+/**
+ * Where the fallback notice sends a visitor: the club's page on the tab the widget stands for, or
+ * the events on CircleSquare for an organizer's list.
+ */
+export declare function getFallbackUrl({ widget, config }: {
+    widget: EmbeddedWidget;
+    config: FrameConfig;
+}): URL;
+/**
+ * What the host asked for that the frame will not show, as one console warning, or null. The page
+ * leaves out a colour it cannot read and keeps the kit's own; the host's browser says so here,
+ * before the host wonders why the club's colour does not show. `isColour` is the browser's check.
+ */
+export declare function getConfigWarning(config: FrameConfig, { isColour }: {
+    isColour: (value: string) => boolean;
+}): string | null;