@spectare-personalisation/react 0.2.2 → 0.5.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
-type ComponentName = 'HeroStatement' | 'AtomCard' | 'StatGrid' | 'CodeBlock' | 'ComparisonTable' | 'FeatureList' | 'TestimonialCard' | 'ImageCtaHero' | 'CtaStrip';
-type AssemblyZone = 'hero' | 'body' | 'proof' | 'cta';
+type ComponentName = 'AnnouncementBar' | 'HeroStatement' | 'AtomCard' | 'StatGrid' | 'CodeBlock' | 'ComparisonTable' | 'FeatureList' | 'TestimonialCard' | 'ImageCtaHero' | 'CtaStrip';
+type AssemblyZone = 'announce' | 'hero' | 'body' | 'proof' | 'cta';
 type ComponentAssembly = Array<{
     component: ComponentName;
     slots?: Record<string, unknown>;
@@ -25,13 +25,130 @@ interface PersonalisedSectionProps {
         audience: string;
         stage: string;
     };
+    /**
+     * Seed conversion attribution with a server-rendered arrangement: pass the variantId that
+     * /api/assemble/ssr returned alongside initialAssembly. Without it, a visit where the client
+     * classification matches the server's (so no client render happens) has no variant for a
+     * later conversion to credit.
+     */
+    initialVariantId?: string;
+    /**
+     * Explicit visitor-typed context (e.g. a demo input box). Bypasses the session token cache
+     * and re-qualifies immediately with the direct flag, which the server cost-caps (cheaper
+     * model on a cache miss) and never writes to the shared cache.
+     */
+    directSummary?: string;
     /** Render only components assigned to this zone. */
     zone?: AssemblyZone;
     /** Alignment for statement-style components, to match the host page. */
     align?: 'left' | 'center' | 'right';
+    /**
+     * Brand accent. Passed through to ComponentRenderer, which emits it into the scoped
+     * token set. Defaults to #60a5fa.
+     */
+    accent?: string;
 }
-declare function PersonalisedSection({ orgSlug, baseUrl, brand, pageHint, className, style, initialAssembly, initialIntent, zone, align, }: PersonalisedSectionProps): react_jsx_runtime.JSX.Element | null;
+declare function PersonalisedSection({ orgSlug, baseUrl, brand, pageHint, className, style, initialAssembly, initialIntent, initialVariantId, directSummary, zone, align, accent, }: PersonalisedSectionProps): react_jsx_runtime.JSX.Element | null;
 
+type Unit = 'px' | 'rem';
+type Align = 'left' | 'center' | 'right';
+/**
+ * A single line above everything else. Deliberately the plainest component in the set: no
+ * heading, no image, no padding to speak of. A bar that draws attention to itself competes with
+ * the page it is announcing something about.
+ *
+ * Uses the accent rather than a red or amber alert colour. This is a fact worth knowing, not a
+ * warning, and a venue putting "members book from Thursday" in an alarm colour reads as a problem
+ * rather than an offer.
+ */
+declare function AnnouncementBar({ text, link, unit }: {
+    text?: string;
+    link?: {
+        label: string;
+        href: string;
+    };
+    unit?: Unit;
+}): react_jsx_runtime.JSX.Element | null;
+declare function HeroStatement({ headline, subheading, align, unit }: {
+    headline: string;
+    subheading?: string;
+    align?: Align;
+    unit?: Unit;
+}): react_jsx_runtime.JSX.Element;
+declare function AtomCard({ title, content, layout, stats, ctaText, ctaUrl, full, unit }: {
+    title?: string;
+    content?: string;
+    layout?: string[];
+    stats?: {
+        value: string;
+        label: string;
+    }[];
+    ctaText?: string;
+    ctaUrl?: string;
+    full?: boolean;
+    unit?: Unit;
+}): react_jsx_runtime.JSX.Element;
+declare function StatGrid({ stats, caption, unit }: {
+    stats?: {
+        value: string;
+        label: string;
+    }[];
+    caption?: string;
+    unit?: Unit;
+}): react_jsx_runtime.JSX.Element;
+declare function CodeBlock({ code, lang, caption, unit }: {
+    code: string;
+    lang?: string;
+    caption?: string;
+    unit?: Unit;
+}): react_jsx_runtime.JSX.Element;
+declare function ComparisonTable({ brand, competitor, rows, unit }: {
+    brand?: string;
+    competitor: string;
+    rows?: {
+        label: string;
+        spectare: string;
+        them: string;
+    }[];
+    unit?: Unit;
+}): react_jsx_runtime.JSX.Element;
+declare function FeatureList({ items, unit }: {
+    items?: {
+        text: string;
+        sub?: string;
+    }[];
+    unit?: Unit;
+}): react_jsx_runtime.JSX.Element;
+declare function TestimonialCard({ quote, name, role, company, unit }: {
+    quote: string;
+    name: string;
+    role: string;
+    company?: string;
+    unit?: Unit;
+}): react_jsx_runtime.JSX.Element;
+declare function ImageCtaHero({ src, alt, headline, subheading, ctaLabel, ctaHref, align, unit }: {
+    src?: string;
+    alt?: string;
+    headline?: string;
+    subheading?: string;
+    ctaLabel?: string;
+    ctaHref?: string;
+    align?: Align;
+    unit?: Unit;
+}): react_jsx_runtime.JSX.Element | null;
+declare function CtaStrip({ headline, primary, secondary, align, unit }: {
+    headline: string;
+    primary: {
+        label: string;
+        href: string;
+    };
+    secondary?: {
+        label: string;
+        href: string;
+    };
+    align?: Align;
+    unit?: Unit;
+}): react_jsx_runtime.JSX.Element;
 interface ComponentRendererProps {
     assembly: ComponentAssembly;
     /** Your brand name, used as the left column header in ComparisonTable. Defaults to "Us". */
@@ -46,7 +163,74 @@ interface ComponentRendererProps {
      * default (HeroStatement left, CtaStrip centered).
      */
     align?: 'left' | 'center' | 'right';
+    /**
+     * Brand accent, as an explicit input rather than a custom property you override and hope
+     * wins on tag order. Any CSS colour. `--sp-accent-bg` and `--sp-accent-border` are derived
+     * from it, so one value covers all three. Defaults to #60a5fa.
+     */
+    accent?: string;
+    /**
+     * px (default) sizes components absolutely, predictable inside arbitrary host pages.
+     * rem tracks the reader's font-size preference; the root then also inherits the host's
+     * font size instead of pinning 16px.
+     */
+    unit?: Unit;
+    /**
+     * Substitute rendering for an item: return a node to replace the built-in renderer
+     * (including null to render nothing), or undefined to keep the default. How the Spectare
+     * app swaps the card-variant AtomCard for its server-rendered card face.
+     */
+    renderOverride?: (item: ComponentAssembly[0]) => React.ReactNode | undefined;
+    /**
+     * Wrap each rendered item, e.g. with source attribution or a debug badge. Receives the
+     * assembly item and its rendered node; whatever it returns is placed in the layout.
+     */
+    renderItem?: (item: ComponentAssembly[0], rendered: React.ReactNode) => React.ReactNode;
+    /** Extra attributes for the root element (e.g. a data marker a host overlay targets). */
+    rootProps?: Record<string, unknown>;
 }
-declare function ComponentRenderer({ assembly, brand, xray, zone, align }: ComponentRendererProps): react_jsx_runtime.JSX.Element;
+declare function ComponentRenderer({ assembly, brand, xray, zone, align, accent, unit, renderOverride, renderItem, rootProps }: ComponentRendererProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * The one place this package's design tokens are defined.
+ *
+ * Two things that are easy to get wrong here:
+ *
+ * 1. Tokens are declared on `.sp-root`, not `:root`. Declaring them at `:root` writes into
+ *    the host's document, allows only one theme per page, and means a customer overriding
+ *    `--sp-accent` competes with us at equal specificity so tag order decides the winner.
+ *    Scoping also lets two differently themed sections sit on one page.
+ *
+ * 2. `tokens.css` must stay byte-identical to `buildTokenCss({ scope: STYLESHEET_SCOPE })`,
+ *    which differs from the injected CSS in its selector and in nothing else.
+ *    tests/unit/react-tokens.test.ts enforces both halves, because a customer who imports the
+ *    stylesheet and a customer who renders the component must get the same page.
+ *
+ * components/ServerAssemblyRenderer.tsx in the Spectare app is a deliberate mirror of the
+ * values below. It is not the same file: that renderer uses rem, this one uses px.
+ */
+/** The package default. `spectare.js` and the WordPress plugin default to #2563eb, which is
+ *  a live inconsistency and a brand decision rather than a technical one, so it is left alone
+ *  here. Pass `accent` to override on either path. */
+declare const DEFAULT_ACCENT = "#60a5fa";
+/** Class the tokens are scoped to. Applied by ComponentRenderer to its own wrapper. */
+declare const SP_ROOT = "sp-root";
+/**
+ * Returns the stylesheet a renderer injects.
+ *
+ * @param accent brand colour. Accepts anything CSS does; `--sp-accent-bg` and
+ *               `--sp-accent-border` are derived from it so a customer sets one value
+ *               rather than three. Defaults to DEFAULT_ACCENT.
+ * @param unit   length unit for layout rules. 'px' for this package, 'rem' for the app's
+ *               server renderer, which sizes in rem throughout.
+ * @param scope  selector the custom properties are declared on. Defaults to `.sp-root`, which is
+ *               what a renderer injecting this at runtime wants. `tokens.css` is generated with
+ *               STYLESHEET_SCOPE instead, so importing it works without a wrapper.
+ */
+declare function buildTokenCss({ accent, unit, scope }?: {
+    accent?: string;
+    unit?: 'px' | 'rem';
+    scope?: string;
+}): string;
 
-export { type AssemblyZone, type ComponentAssembly, type ComponentName, ComponentRenderer, type ComponentRendererProps, PersonalisedSection, type PersonalisedSectionProps, filterAssemblyByZone };
+export { AnnouncementBar, type AssemblyZone, AtomCard, CodeBlock, ComparisonTable, type ComponentAssembly, type ComponentName, ComponentRenderer, type ComponentRendererProps, CtaStrip, DEFAULT_ACCENT, FeatureList, HeroStatement, ImageCtaHero, PersonalisedSection, type PersonalisedSectionProps, SP_ROOT, StatGrid, TestimonialCard, buildTokenCss, filterAssemblyByZone };