@spectare-personalisation/react 0.4.0 → 0.6.0

package/dist/index.d.cts

@@ -44,12 +44,59 @@ interface PersonalisedSectionProps {
     align?: 'left' | 'center' | 'right';
     /**
      * Brand accent. Passed through to ComponentRenderer, which emits it into the scoped
-     * token set. Defaults to #60a5fa.
+     * token set. Defaults to #60a5fa (dark) or #2563eb (light).
      */
     accent?: string;
+    /** dark (default) or light, matching your page's ground. See ComponentRenderer. */
+    theme?: 'dark' | 'light';
 }
-declare function PersonalisedSection({ orgSlug, baseUrl, brand, pageHint, className, style, initialAssembly, initialIntent, initialVariantId, directSummary, zone, align, accent, }: PersonalisedSectionProps): react_jsx_runtime.JSX.Element | null;
+declare function PersonalisedSection({ orgSlug, baseUrl, brand, pageHint, className, style, initialAssembly, initialIntent, initialVariantId, directSummary, zone, align, accent, theme, }: PersonalisedSectionProps): react_jsx_runtime.JSX.Element | null;
 
+/**
+ * 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";
+type SpTheme = 'dark' | 'light';
+/** 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, theme }?: {
+    accent?: string;
+    unit?: 'px' | 'rem';
+    scope?: string;
+    theme?: SpTheme;
+}): string;
+
+type Unit = 'px' | 'rem';
 type Align = 'left' | 'center' | 'right';
 /**
  * A single line above everything else. Deliberately the plainest component in the set: no
@@ -60,21 +107,24 @@ type Align = 'left' | 'center' | 'right';
  * 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 }: {
+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 }: {
+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 }: {
+declare function AtomCard({ title, content, summary, layout, stats, ctaText, ctaUrl, full, variant, unit }: {
     title?: string;
     content?: string;
+    summary?: string;
     layout?: string[];
     stats?: {
         value: string;
@@ -83,20 +133,24 @@ declare function AtomCard({ title, content, layout, stats, ctaText, ctaUrl, full
     ctaText?: string;
     ctaUrl?: string;
     full?: boolean;
+    variant?: string;
+    unit?: Unit;
 }): react_jsx_runtime.JSX.Element;
-declare function StatGrid({ stats, caption }: {
+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 }: {
+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 }: {
+declare function ComparisonTable({ brand, competitor, rows, unit }: {
     brand?: string;
     competitor: string;
     rows?: {
@@ -104,20 +158,23 @@ declare function ComparisonTable({ brand, competitor, rows }: {
         spectare: string;
         them: string;
     }[];
+    unit?: Unit;
 }): react_jsx_runtime.JSX.Element;
-declare function FeatureList({ items }: {
+declare function FeatureList({ items, unit }: {
     items?: {
         text: string;
         sub?: string;
     }[];
+    unit?: Unit;
 }): react_jsx_runtime.JSX.Element;
-declare function TestimonialCard({ quote, name, role, company }: {
+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 }: {
+declare function ImageCtaHero({ src, alt, headline, subheading, ctaLabel, ctaHref, align, unit }: {
     src?: string;
     alt?: string;
     headline?: string;
@@ -125,8 +182,9 @@ declare function ImageCtaHero({ src, alt, headline, subheading, ctaLabel, ctaHre
     ctaLabel?: string;
     ctaHref?: string;
     align?: Align;
+    unit?: Unit;
 }): react_jsx_runtime.JSX.Element | null;
-declare function CtaStrip({ headline, primary, secondary, align }: {
+declare function CtaStrip({ headline, primary, secondary, align, unit }: {
     headline: string;
     primary: {
         label: string;
@@ -137,6 +195,7 @@ declare function CtaStrip({ headline, primary, secondary, align }: {
         href: string;
     };
     align?: Align;
+    unit?: Unit;
 }): react_jsx_runtime.JSX.Element;
 interface ComponentRendererProps {
     assembly: ComponentAssembly;
@@ -158,49 +217,33 @@ interface ComponentRendererProps {
      * from it, so one value covers all three. Defaults to #60a5fa.
      */
     accent?: string;
+    /**
+     * dark (default) is the package's original near-black card set. light renders white cards
+     * with a dark text ramp for light host pages; without it the components paint near-white
+     * text and near-black slabs onto a light ground. Both palettes hold the same contrast
+     * floors (see tests/unit/token-contrast.test.ts).
+     */
+    theme?: SpTheme;
+    /**
+     * 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, accent }: 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;
+declare function ComponentRenderer({ assembly, brand, xray, zone, align, accent, theme, unit, renderOverride, renderItem, rootProps }: ComponentRendererProps): react_jsx_runtime.JSX.Element;
 
 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 };

package/dist/index.d.ts

@@ -44,12 +44,59 @@ interface PersonalisedSectionProps {
     align?: 'left' | 'center' | 'right';
     /**
      * Brand accent. Passed through to ComponentRenderer, which emits it into the scoped
-     * token set. Defaults to #60a5fa.
+     * token set. Defaults to #60a5fa (dark) or #2563eb (light).
      */
     accent?: string;
+    /** dark (default) or light, matching your page's ground. See ComponentRenderer. */
+    theme?: 'dark' | 'light';
 }
-declare function PersonalisedSection({ orgSlug, baseUrl, brand, pageHint, className, style, initialAssembly, initialIntent, initialVariantId, directSummary, zone, align, accent, }: PersonalisedSectionProps): react_jsx_runtime.JSX.Element | null;
+declare function PersonalisedSection({ orgSlug, baseUrl, brand, pageHint, className, style, initialAssembly, initialIntent, initialVariantId, directSummary, zone, align, accent, theme, }: PersonalisedSectionProps): react_jsx_runtime.JSX.Element | null;
 
+/**
+ * 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";
+type SpTheme = 'dark' | 'light';
+/** 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, theme }?: {
+    accent?: string;
+    unit?: 'px' | 'rem';
+    scope?: string;
+    theme?: SpTheme;
+}): string;
+
+type Unit = 'px' | 'rem';
 type Align = 'left' | 'center' | 'right';
 /**
  * A single line above everything else. Deliberately the plainest component in the set: no
@@ -60,21 +107,24 @@ type Align = 'left' | 'center' | 'right';
  * 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 }: {
+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 }: {
+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 }: {
+declare function AtomCard({ title, content, summary, layout, stats, ctaText, ctaUrl, full, variant, unit }: {
     title?: string;
     content?: string;
+    summary?: string;
     layout?: string[];
     stats?: {
         value: string;
@@ -83,20 +133,24 @@ declare function AtomCard({ title, content, layout, stats, ctaText, ctaUrl, full
     ctaText?: string;
     ctaUrl?: string;
     full?: boolean;
+    variant?: string;
+    unit?: Unit;
 }): react_jsx_runtime.JSX.Element;
-declare function StatGrid({ stats, caption }: {
+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 }: {
+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 }: {
+declare function ComparisonTable({ brand, competitor, rows, unit }: {
     brand?: string;
     competitor: string;
     rows?: {
@@ -104,20 +158,23 @@ declare function ComparisonTable({ brand, competitor, rows }: {
         spectare: string;
         them: string;
     }[];
+    unit?: Unit;
 }): react_jsx_runtime.JSX.Element;
-declare function FeatureList({ items }: {
+declare function FeatureList({ items, unit }: {
     items?: {
         text: string;
         sub?: string;
     }[];
+    unit?: Unit;
 }): react_jsx_runtime.JSX.Element;
-declare function TestimonialCard({ quote, name, role, company }: {
+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 }: {
+declare function ImageCtaHero({ src, alt, headline, subheading, ctaLabel, ctaHref, align, unit }: {
     src?: string;
     alt?: string;
     headline?: string;
@@ -125,8 +182,9 @@ declare function ImageCtaHero({ src, alt, headline, subheading, ctaLabel, ctaHre
     ctaLabel?: string;
     ctaHref?: string;
     align?: Align;
+    unit?: Unit;
 }): react_jsx_runtime.JSX.Element | null;
-declare function CtaStrip({ headline, primary, secondary, align }: {
+declare function CtaStrip({ headline, primary, secondary, align, unit }: {
     headline: string;
     primary: {
         label: string;
@@ -137,6 +195,7 @@ declare function CtaStrip({ headline, primary, secondary, align }: {
         href: string;
     };
     align?: Align;
+    unit?: Unit;
 }): react_jsx_runtime.JSX.Element;
 interface ComponentRendererProps {
     assembly: ComponentAssembly;
@@ -158,49 +217,33 @@ interface ComponentRendererProps {
      * from it, so one value covers all three. Defaults to #60a5fa.
      */
     accent?: string;
+    /**
+     * dark (default) is the package's original near-black card set. light renders white cards
+     * with a dark text ramp for light host pages; without it the components paint near-white
+     * text and near-black slabs onto a light ground. Both palettes hold the same contrast
+     * floors (see tests/unit/token-contrast.test.ts).
+     */
+    theme?: SpTheme;
+    /**
+     * 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, accent }: 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;
+declare function ComponentRenderer({ assembly, brand, xray, zone, align, accent, theme, unit, renderOverride, renderItem, rootProps }: ComponentRendererProps): react_jsx_runtime.JSX.Element;
 
 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 };