@preprio/toolkit 0.1.0-beta.6 → 0.2.0-beta.3

package/dist/react/components.d.cts

@@ -0,0 +1,167 @@
+type Dictionary = Record<string, unknown>;
+declare const dictionaries: {
+    en: Dictionary;
+    nl: Dictionary;
+};
+type Locale = keyof typeof dictionaries;
+
+interface PreprSegment {
+    readonly _id: string;
+    readonly name: string;
+}
+/**
+ * Per-feature config. `false` is shorthand for `{ enabled: false }`; the object
+ * form leaves room for per-feature options later without a breaking change.
+ */
+type PreprFeatureConfig = boolean | {
+    enabled?: boolean;
+};
+/** Toolkit features a consumer can turn off. Omitted keys stay enabled. */
+interface PreprFeatures {
+    /** Segment picker, `Prepr-Segments` header and its cookie/query param. */
+    segments?: PreprFeatureConfig;
+    /** A/B variant switch, `Prepr-ABtesting` header and its cookie/query param. */
+    abTesting?: PreprFeatureConfig;
+    /**
+     * The site's own click-to-edit: the toolbar's Edit mode control, the stega
+     * tooltip/overlay and the close-edit pill.
+     *
+     * NOT a security control, and NOT the Prepr editor's live preview. When the
+     * site is framed by the editor, `prepr:initVE` still activates edit mode —
+     * that is the CMS operating inside its own iframe, not an affordance offered
+     * to visitors. See iframe-bridge.ts.
+     */
+    editMode?: PreprFeatureConfig;
+}
+interface PreprToolbarOptions {
+    debug?: boolean;
+    locale?: Locale;
+    /** Disable features app-wide. Pass the same object to the middleware. */
+    features?: PreprFeatures;
+}
+/**
+ * Options for the preview runtime. Two independent axes: `features` decides
+ * *what runs*, `ui` decides *whether the toolbar is visible*.
+ */
+interface PreprPreviewOptions extends PreprToolbarOptions {
+    /**
+     * Mount the visible `<prepr-toolbar>` element. Default `true`.
+     *
+     * `false` keeps every non-visual side effect wired — click-to-edit, the
+     * editor bridge, scroll restore, cookies and headers — with no chrome of its
+     * own. That is how a site gets live editing, or editor scroll restore, while
+     * rendering its own UI instead of the bar.
+     *
+     * Already implied inside the editor's iframe (the CMS owns the chrome there)
+     * and by `?prepr_hide_bar=true`, so this option is for consumers who want a
+     * headless preview by their own choice.
+     */
+    ui?: boolean;
+    /**
+     * Replace the `*.prepr.io` editor-origin wildcard with an exact list.
+     * Intended for self-hosted editors; when set, the wildcard no longer applies.
+     */
+    allowedEditorOrigins?: string[];
+}
+interface PreprToolbarProps {
+    readonly activeSegment: string | null;
+    readonly activeVariant: string | null;
+    /** Available segments to personalize on. */
+    readonly segments?: readonly PreprSegment[];
+    /** @deprecated Alias for `segments`. */
+    readonly data?: readonly PreprSegment[];
+}
+/**
+ * Prop type for the framework `<PreprToolbar>` components: the toolbar data
+ * plus the options bag core `createPreprPreview` accepts.
+ */
+interface PreprToolbarComponentProps extends PreprToolbarProps {
+    options?: PreprPreviewOptions;
+}
+
+/**
+ * Navigation seam that keeps the controller framework-free. Next.js/Astro inject
+ * their router here; the default uses `window.location`.
+ */
+interface PreprNavigationAdapter {
+    navigate(url: string): void;
+    currentPath(): string;
+    /**
+     * Refresh after a preview-mode toggle. Defaults to `window.location.reload()`;
+     * SPA routers can pass a soft refresh like Next.js `router.refresh()`.
+     */
+    reload?(): void;
+}
+
+/**
+ * Loader + typed facade for Prepr's CDN tracking pixel, so consumers don't have
+ * to paste a `<script>` tag. The pixel itself lives on the CDN; this only sets
+ * up the handoff.
+ *
+ * The CDN script expects a queue stub to already exist when it loads, so the
+ * contract must be reproduced exactly:
+ *   - `window.prepr` pushes `arguments` onto `.queue` until the real script
+ *     lands and replaces `.process`.
+ *   - `.t` must be a `Date.now()` timestamp.
+ *   - The tag is inserted async, `src` cache-busted every 24h via
+ *     `Math.ceil(Date.now() / cacheTime) * cacheTime`.
+ */
+/** Config accepted by the CDN pixel. */
+interface PreprPixelConfig {
+    destinations?: {
+        googleTagManager?: boolean;
+    };
+    variantImpressionThreshold?: number;
+}
+type PreprQueueArgs = unknown[];
+interface PreprQueueFn {
+    (...args: PreprQueueArgs): void;
+    queue: PreprQueueArgs[];
+    t: number;
+    process?: (...args: PreprQueueArgs) => void;
+}
+declare global {
+    interface Window {
+        prepr?: PreprQueueFn;
+    }
+}
+
+interface PreprPreviewProps extends PreprToolbarComponentProps {
+    /**
+     * Router binding for segment/variant switches and the preview-mode refresh.
+     * Optional: the default adapter drives `window.location`, which is correct
+     * for any router that keeps the URL bar in sync.
+     *
+     * Pass one to get soft navigation instead of full page loads. Only worth it
+     * with `segments` or `abTesting` enabled — with both off the sole reachable
+     * path is the preview-mode refresh, which reloads either way.
+     */
+    navigation?: PreprNavigationAdapter;
+}
+/**
+ * Mounts the Prepr preview runtime — the toolbar, click-to-edit, and the
+ * editor bridge — in any React app. Renders nothing: the toolbar UI is a
+ * custom element `createPreprPreview` mounts imperatively.
+ *
+ * Framework-free. Next.js users want `PreprToolbar` from
+ * `@preprio/toolkit/nextjs` instead, which binds the App Router for them.
+ *
+ * Mount it once per page. Two mounted copies start two editor bridges and
+ * announce the preview twice.
+ */
+declare function PreprPreview({ options, navigation, ...props }: PreprPreviewProps): null;
+interface PreprTrackingPixelProps {
+    /** Prepr tracking/access token. */
+    id: string;
+    config?: PreprPixelConfig;
+}
+/**
+ * Loads Prepr's CDN tracking pixel on mount. Renders nothing.
+ *
+ * The pixel queues a single `pageload` event when it installs. Client-side
+ * route changes emit nothing on their own — call `trackEvent('pageload')` from
+ * the router to count them.
+ */
+declare function PreprTrackingPixel({ id, config, }: PreprTrackingPixelProps): null;
+
+export { PreprPreview, type PreprPreviewProps, PreprTrackingPixel, type PreprTrackingPixelProps };

package/dist/react/components.d.ts

@@ -0,0 +1,167 @@
+type Dictionary = Record<string, unknown>;
+declare const dictionaries: {
+    en: Dictionary;
+    nl: Dictionary;
+};
+type Locale = keyof typeof dictionaries;
+
+interface PreprSegment {
+    readonly _id: string;
+    readonly name: string;
+}
+/**
+ * Per-feature config. `false` is shorthand for `{ enabled: false }`; the object
+ * form leaves room for per-feature options later without a breaking change.
+ */
+type PreprFeatureConfig = boolean | {
+    enabled?: boolean;
+};
+/** Toolkit features a consumer can turn off. Omitted keys stay enabled. */
+interface PreprFeatures {
+    /** Segment picker, `Prepr-Segments` header and its cookie/query param. */
+    segments?: PreprFeatureConfig;
+    /** A/B variant switch, `Prepr-ABtesting` header and its cookie/query param. */
+    abTesting?: PreprFeatureConfig;
+    /**
+     * The site's own click-to-edit: the toolbar's Edit mode control, the stega
+     * tooltip/overlay and the close-edit pill.
+     *
+     * NOT a security control, and NOT the Prepr editor's live preview. When the
+     * site is framed by the editor, `prepr:initVE` still activates edit mode —
+     * that is the CMS operating inside its own iframe, not an affordance offered
+     * to visitors. See iframe-bridge.ts.
+     */
+    editMode?: PreprFeatureConfig;
+}
+interface PreprToolbarOptions {
+    debug?: boolean;
+    locale?: Locale;
+    /** Disable features app-wide. Pass the same object to the middleware. */
+    features?: PreprFeatures;
+}
+/**
+ * Options for the preview runtime. Two independent axes: `features` decides
+ * *what runs*, `ui` decides *whether the toolbar is visible*.
+ */
+interface PreprPreviewOptions extends PreprToolbarOptions {
+    /**
+     * Mount the visible `<prepr-toolbar>` element. Default `true`.
+     *
+     * `false` keeps every non-visual side effect wired — click-to-edit, the
+     * editor bridge, scroll restore, cookies and headers — with no chrome of its
+     * own. That is how a site gets live editing, or editor scroll restore, while
+     * rendering its own UI instead of the bar.
+     *
+     * Already implied inside the editor's iframe (the CMS owns the chrome there)
+     * and by `?prepr_hide_bar=true`, so this option is for consumers who want a
+     * headless preview by their own choice.
+     */
+    ui?: boolean;
+    /**
+     * Replace the `*.prepr.io` editor-origin wildcard with an exact list.
+     * Intended for self-hosted editors; when set, the wildcard no longer applies.
+     */
+    allowedEditorOrigins?: string[];
+}
+interface PreprToolbarProps {
+    readonly activeSegment: string | null;
+    readonly activeVariant: string | null;
+    /** Available segments to personalize on. */
+    readonly segments?: readonly PreprSegment[];
+    /** @deprecated Alias for `segments`. */
+    readonly data?: readonly PreprSegment[];
+}
+/**
+ * Prop type for the framework `<PreprToolbar>` components: the toolbar data
+ * plus the options bag core `createPreprPreview` accepts.
+ */
+interface PreprToolbarComponentProps extends PreprToolbarProps {
+    options?: PreprPreviewOptions;
+}
+
+/**
+ * Navigation seam that keeps the controller framework-free. Next.js/Astro inject
+ * their router here; the default uses `window.location`.
+ */
+interface PreprNavigationAdapter {
+    navigate(url: string): void;
+    currentPath(): string;
+    /**
+     * Refresh after a preview-mode toggle. Defaults to `window.location.reload()`;
+     * SPA routers can pass a soft refresh like Next.js `router.refresh()`.
+     */
+    reload?(): void;
+}
+
+/**
+ * Loader + typed facade for Prepr's CDN tracking pixel, so consumers don't have
+ * to paste a `<script>` tag. The pixel itself lives on the CDN; this only sets
+ * up the handoff.
+ *
+ * The CDN script expects a queue stub to already exist when it loads, so the
+ * contract must be reproduced exactly:
+ *   - `window.prepr` pushes `arguments` onto `.queue` until the real script
+ *     lands and replaces `.process`.
+ *   - `.t` must be a `Date.now()` timestamp.
+ *   - The tag is inserted async, `src` cache-busted every 24h via
+ *     `Math.ceil(Date.now() / cacheTime) * cacheTime`.
+ */
+/** Config accepted by the CDN pixel. */
+interface PreprPixelConfig {
+    destinations?: {
+        googleTagManager?: boolean;
+    };
+    variantImpressionThreshold?: number;
+}
+type PreprQueueArgs = unknown[];
+interface PreprQueueFn {
+    (...args: PreprQueueArgs): void;
+    queue: PreprQueueArgs[];
+    t: number;
+    process?: (...args: PreprQueueArgs) => void;
+}
+declare global {
+    interface Window {
+        prepr?: PreprQueueFn;
+    }
+}
+
+interface PreprPreviewProps extends PreprToolbarComponentProps {
+    /**
+     * Router binding for segment/variant switches and the preview-mode refresh.
+     * Optional: the default adapter drives `window.location`, which is correct
+     * for any router that keeps the URL bar in sync.
+     *
+     * Pass one to get soft navigation instead of full page loads. Only worth it
+     * with `segments` or `abTesting` enabled — with both off the sole reachable
+     * path is the preview-mode refresh, which reloads either way.
+     */
+    navigation?: PreprNavigationAdapter;
+}
+/**
+ * Mounts the Prepr preview runtime — the toolbar, click-to-edit, and the
+ * editor bridge — in any React app. Renders nothing: the toolbar UI is a
+ * custom element `createPreprPreview` mounts imperatively.
+ *
+ * Framework-free. Next.js users want `PreprToolbar` from
+ * `@preprio/toolkit/nextjs` instead, which binds the App Router for them.
+ *
+ * Mount it once per page. Two mounted copies start two editor bridges and
+ * announce the preview twice.
+ */
+declare function PreprPreview({ options, navigation, ...props }: PreprPreviewProps): null;
+interface PreprTrackingPixelProps {
+    /** Prepr tracking/access token. */
+    id: string;
+    config?: PreprPixelConfig;
+}
+/**
+ * Loads Prepr's CDN tracking pixel on mount. Renders nothing.
+ *
+ * The pixel queues a single `pageload` event when it installs. Client-side
+ * route changes emit nothing on their own — call `trackEvent('pageload')` from
+ * the router to count them.
+ */
+declare function PreprTrackingPixel({ id, config, }: PreprTrackingPixelProps): null;
+
+export { PreprPreview, type PreprPreviewProps, PreprTrackingPixel, type PreprTrackingPixelProps };