@gravity-ai/react 1.1.4 → 1.1.6

package/README.md

@@ -1,6 +1,6 @@
 # @gravity-ai/react
 
-React components for rendering Gravity AI advertisements with automatic impression and click tracking.
+React components for rendering Gravity ads with automatic impression and click tracking.
 
 ## Installation
 
@@ -8,13 +8,157 @@ React components for rendering Gravity AI advertisements with automatic impressi
 npm install @gravity-ai/react
 ```
 
-> **Note:** This package has a peer dependency on React 17+.
+> Peer dependency: React 17+
 
-## Documentation
+## Quick Start
 
-For full documentation, examples, and API reference, visit:
+```tsx
+import { GravityAd } from '@gravity-ai/react';
 
-**[https://www.trygravity.ai/api](https://www.trygravity.ai/api)**
+function ChatResponse({ ads }) {
+  return ads.map((ad, i) => <GravityAd key={i} ad={ad} />);
+}
+```
+
+That's it. The component renders a styled ad card using inline styles and automatically fires the impression pixel when the ad scrolls into view.
+
+## API Response Shape
+
+The components expect the objects returned by the Gravity API:
+
+```ts
+interface AdResponse {
+  adText: string;
+  title?: string;
+  cta?: string;
+  brandName?: string;
+  url?: string;
+  favicon?: string;
+  impUrl?: string;   // impression tracking pixel
+  clickUrl?: string;  // click-through URL
+}
+```
+
+## Components
+
+### `<GravityAd />`
+
+Full-featured ad card with favicon, brand name, title, body text, and CTA button. All styles are inline — no injected stylesheets, no CSS class names, no CSS-in-JS. What you see in the JSX is what renders.
+
+```tsx
+<GravityAd
+  ad={ad}
+  variant="card"       // "card" | "inline" | "minimal"
+  showLabel={true}     // show "Sponsored" label
+  labelText="Sponsored"
+  openInNewTab={true}
+  onImpression={() => console.log('seen')}
+  onClickTracked={() => console.log('clicked')}
+/>
+```
+
+**Variants:**
+
+| Variant | Description |
+|---------|-------------|
+| `card` | Default. Vertical card with border, shadow, and padding. |
+| `inline` | Horizontal layout for sidebars or toolbars. |
+| `minimal` | No border, shadow, or background. Blends with host content. |
+
+### Styling with `style` and `slotProps`
+
+Override the outer container with the `style` prop:
+
+```tsx
+<GravityAd ad={ad} style={{ maxWidth: 400, borderRadius: 16 }} />
+```
+
+Override any inner element with `slotProps`:
+
+```tsx
+<GravityAd
+  ad={ad}
+  slotProps={{
+    cta: { style: { background: '#E11D48', borderRadius: 999 } },
+    label: { style: { display: 'none' } },
+    title: { style: { fontSize: 16 } },
+  }}
+/>
+```
+
+Each `slotProps` key maps to a DOM element:
+
+| Key | Element | What it controls |
+|-----|---------|------------------|
+| `container` | Outer `<a>` | Same as top-level `style` prop |
+| `inner` | Padding wrapper `<div>` | Layout, padding, gap |
+| `header` | Header row `<div>` | Favicon + brand + label row |
+| `favicon` | Favicon `<img>` | Size, border-radius |
+| `brand` | Brand name `<span>` | Font, color |
+| `label` | "Sponsored" `<span>` | Pill styling, visibility |
+| `body` | Body wrapper `<div>` | Title + text layout |
+| `title` | Title `<p>` | Font, color |
+| `text` | Ad text `<p>` | Font, color |
+| `cta` | CTA button `<span>` | Background, border-radius, padding |
+
+Each slot accepts `{ style?: CSSProperties; className?: string }`.
+
+For the full styling guide with DOM structure and common recipes, see **[STYLING.md](./STYLING.md)**.
+
+### `<AdText />`
+
+Unstyled text-only renderer. Use when you want full control over presentation.
+
+```tsx
+<AdText
+  ad={ad}
+  className="my-custom-style"
+  style={{ fontSize: 14 }}
+/>
+```
+
+Renders `ad.adText` as a link (if `clickUrl` exists) or a span. No built-in styles beyond `text-decoration: none; color: inherit`.
+
+## Impression Tracking
+
+Both components use `IntersectionObserver` to fire the impression pixel **only when the ad is actually visible** to the user (50% of the element in the viewport). This is a significant improvement over fire-on-mount — publishers won't report impressions for ads rendered below the fold that were never seen.
+
+The impression fires exactly once per ad. If the ad object changes (different `impUrl`), the tracking resets for the new ad.
+
+To disable automatic tracking:
+
+```tsx
+<GravityAd ad={ad} disableImpressionTracking />
+```
+
+## Hooks
+
+### `useAdTracking`
+
+Low-level hook for building fully custom ad components:
+
+```tsx
+import { useAdTracking } from '@gravity-ai/react';
+
+function CustomAd({ ad }) {
+  const { containerRef, handleClick } = useAdTracking({
+    ad,
+    onImpression: () => console.log('impression fired'),
+    onClickTracked: () => console.log('click tracked'),
+  });
+
+  return (
+    <a ref={containerRef} href={ad.clickUrl} onClick={handleClick}>
+      {ad.adText}
+    </a>
+  );
+}
+```
+
+The hook returns:
+- `containerRef` — attach to the DOM element for IntersectionObserver-based impression tracking
+- `handleClick` — call on click to fire the click tracking callback
+- `impressionFired` — boolean indicating whether the impression has already been fired
 
 ## License
 

package/dist/index.d.mts

@@ -1,154 +1,142 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { CSSProperties, ReactNode } from 'react';
 
-/**
- * Ad response from the Gravity API
- * This mirrors the type from @gravity-ai/api for convenience
- */
 interface AdResponse {
-    /** The advertisement copy text */
     adText: string;
-    /** Ad title */
     title?: string;
-    /** Call-to-action text (e.g., 'Learn More', 'Shop Now') */
     cta?: string;
-    /** Brand/advertiser name */
     brandName?: string;
-    /** Landing page URL */
     url?: string;
-    /** Favicon URL */
     favicon?: string;
-    /** Impression tracking URL - fire this when ad is displayed */
     impUrl?: string;
-    /** Click-through tracking URL - use this as href for ad clicks */
     clickUrl?: string;
 }
+type GravityAdVariant = 'card' | 'inline' | 'minimal' | 'bubble' | 'contextual' | 'native' | 'footnote' | 'quote' | 'suggestion' | 'accent' | 'side-panel' | 'labeled' | 'spotlight' | 'embed' | 'split-action' | 'pill' | 'banner' | 'divider' | 'toolbar' | 'tooltip' | 'notification' | 'hyperlink' | 'text-link';
 /**
- * Visual theme presets for the ad banner
- */
-type AdTheme = 'light' | 'dark' | 'minimal' | 'branded';
-/**
- * Banner size presets
- */
-type AdSize = 'small' | 'medium' | 'large' | 'responsive';
-/**
- * Props for the AdBanner component
+ * Style + className overrides for individual elements inside `<GravityAd />`.
+ *
+ * Each key maps 1:1 to a DOM element in the component's JSX tree.
+ * Pass `style` to merge onto the element's inline styles, or `className`
+ * to append a CSS class.
  */
-interface AdBannerProps {
-    /** The ad response from Gravity API */
+interface GravityAdSlotProps {
+    /** Outer `<a>` wrapper (same as the top-level `style`/`className` props) */
+    container?: {
+        style?: CSSProperties;
+        className?: string;
+    };
+    /** Inner padding/layout wrapper */
+    inner?: {
+        style?: CSSProperties;
+        className?: string;
+    };
+    /** Header row (favicon + brand + label) */
+    header?: {
+        style?: CSSProperties;
+        className?: string;
+    };
+    /** Favicon `<img>` */
+    favicon?: {
+        style?: CSSProperties;
+        className?: string;
+    };
+    /** Brand name `<span>` */
+    brand?: {
+        style?: CSSProperties;
+        className?: string;
+    };
+    /** "Sponsored" label `<span>` */
+    label?: {
+        style?: CSSProperties;
+        className?: string;
+    };
+    /** Body wrapper (title + text) */
+    body?: {
+        style?: CSSProperties;
+        className?: string;
+    };
+    /** Title `<p>` */
+    title?: {
+        style?: CSSProperties;
+        className?: string;
+    };
+    /** Ad text `<p>` */
+    text?: {
+        style?: CSSProperties;
+        className?: string;
+    };
+    /** CTA button `<span>` */
+    cta?: {
+        style?: CSSProperties;
+        className?: string;
+    };
+    /** Icon wrapper (larger background container around favicon) */
+    iconWrapper?: {
+        style?: CSSProperties;
+        className?: string;
+    };
+    /** Colored accent bar (top of `accent` variant) */
+    accentBar?: {
+        style?: CSSProperties;
+        className?: string;
+    };
+    /** Secondary CTA (`split-action` variant) */
+    secondaryCta?: {
+        style?: CSSProperties;
+        className?: string;
+    };
+    /** Footer area */
+    footer?: {
+        style?: CSSProperties;
+        className?: string;
+    };
+    /** Tooltip arrow element */
+    arrow?: {
+        style?: CSSProperties;
+        className?: string;
+    };
+    /** Context header text (`contextual` variant) */
+    contextHeader?: {
+        style?: CSSProperties;
+        className?: string;
+    };
+}
+interface GravityAdProps {
     ad: AdResponse | null;
-    /** Visual theme preset */
-    theme?: AdTheme;
-    /** Size preset */
-    size?: AdSize;
-    /** Custom class name for the container */
+    variant?: GravityAdVariant;
     className?: string;
-    /** Custom inline styles for the container */
     style?: CSSProperties;
-    /** Custom styles for the ad text */
-    textStyle?: CSSProperties;
-    /** Custom class name for the ad text */
-    textClassName?: string;
-    /** Whether to show the "Sponsored" label */
+    /** Targeted style overrides for inner elements. */
+    slotProps?: GravityAdSlotProps;
     showLabel?: boolean;
-    /** Custom label text (default: "Sponsored") */
     labelText?: string;
-    /** Custom styles for the label */
-    labelStyle?: CSSProperties;
-    /** Custom click handler (called in addition to tracking) */
     onClick?: () => void;
-    /** Callback when impression is tracked */
     onImpression?: () => void;
-    /** Callback when click is tracked */
     onClickTracked?: () => void;
-    /** Custom content to render when ad is null */
     fallback?: ReactNode;
-    /** Whether to disable automatic impression tracking */
     disableImpressionTracking?: boolean;
-    /** Whether to open link in new tab (default: true) */
     openInNewTab?: boolean;
-    /** Custom border radius */
-    borderRadius?: number | string;
-    /** Custom background color (overrides theme) */
-    backgroundColor?: string;
-    /** Custom text color (overrides theme) */
-    textColor?: string;
-    /** Custom accent/brand color */
-    accentColor?: string;
 }
-/**
- * Props for the AdText component (minimal text-only rendering)
- */
 interface AdTextProps {
-    /** The ad response from Gravity API */
     ad: AdResponse | null;
-    /** Custom class name */
     className?: string;
-    /** Custom inline styles */
     style?: CSSProperties;
-    /** Custom click handler */
     onClick?: () => void;
-    /** Callback when impression is tracked */
     onImpression?: () => void;
-    /** Callback when click is tracked */
     onClickTracked?: () => void;
-    /** Content to render when ad is null */
     fallback?: ReactNode;
-    /** Whether to disable automatic impression tracking */
     disableImpressionTracking?: boolean;
-    /** Whether to open link in new tab (default: true) */
     openInNewTab?: boolean;
 }
 
-/**
- * AdBanner - A customizable component for rendering Gravity AI advertisements
- *
- * @example
- * ```tsx
- * import { AdBanner } from '@gravity-ai/react';
- *
- * function MyComponent() {
- *   const [ad, setAd] = useState(null);
- *
- *   useEffect(() => {
- *     client.getAd({ messages, sessionId, placements }).then(res => setAd(res?.[0] || null));
- *   }, [messages]);
- *
- *   return (
- *     <AdBanner
- *       ad={ad}
- *       theme="dark"
- *       size="medium"
- *       showLabel
- *     />
- *   );
- * }
- * ```
- */
-declare function AdBanner({ ad, theme, size, className, style, textStyle, textClassName, showLabel, labelText, labelStyle, onClick, onImpression, onClickTracked, fallback, disableImpressionTracking, openInNewTab, borderRadius, backgroundColor, textColor, accentColor, }: AdBannerProps): react_jsx_runtime.JSX.Element;
-declare namespace AdBanner {
+declare function GravityAd({ ad, variant, className, style, slotProps, showLabel, labelText, onClick, onImpression, onClickTracked, fallback, disableImpressionTracking, openInNewTab, }: GravityAdProps): react_jsx_runtime.JSX.Element;
+declare namespace GravityAd {
     var displayName: string;
 }
 
 /**
- * AdText - A minimal text-only component for rendering Gravity AI advertisements
- *
- * Use this when you want full control over styling and just need the ad text
- * with automatic tracking.
- *
- * @example
- * ```tsx
- * import { AdText } from '@gravity-ai/react';
- *
- * function MyComponent() {
- *   return (
- *     <AdText
- *       ad={ad}
- *       className="my-custom-ad-style"
- *     />
- *   );
- * }
- * ```
+ * Unstyled text-only ad renderer with automatic tracking.
+ * Use when you want full control over presentation.
  */
 declare function AdText({ ad, className, style, onClick, onImpression, onClickTracked, fallback, disableImpressionTracking, openInNewTab, }: AdTextProps): react_jsx_runtime.JSX.Element;
 declare namespace AdText {
@@ -161,12 +149,11 @@ interface UseAdTrackingOptions {
     onImpression?: () => void;
     onClickTracked?: () => void;
 }
-/**
- * Hook to handle ad impression and click tracking
- */
-declare function useAdTracking({ ad, disableImpressionTracking, onImpression, onClickTracked, }: UseAdTrackingOptions): {
+interface UseAdTrackingReturn {
+    containerRef: React.RefObject<HTMLElement | null>;
     handleClick: () => void;
-    impressionTracked: boolean;
-};
+    impressionFired: boolean;
+}
+declare function useAdTracking({ ad, disableImpressionTracking, onImpression, onClickTracked, }: UseAdTrackingOptions): UseAdTrackingReturn;
 
-export { AdBanner, type AdBannerProps, type AdResponse, type AdSize, AdText, type AdTextProps, type AdTheme, useAdTracking };
+export { type AdResponse, AdText, type AdTextProps, GravityAd, type GravityAdProps, type GravityAdSlotProps, type GravityAdVariant, useAdTracking };