adkit-react 0.1.0

package/README.md

@@ -0,0 +1,122 @@
+# adkit-react
+
+A drop-in React component for selling direct, bookable ads on your site — no AdSense required.
+
+## Installation
+
+```bash
+npm install adkit-react
+```
+
+## Quick Start
+
+```tsx
+import { AdkitProvider, AdSlot } from "adkit-react"
+import "adkit-react/styles.css"
+
+function App() {
+  return (
+    <AdkitProvider siteId="your-site-id">
+      <AdSlot slot="sidebar" aspectRatio="1:1" price={2500} />
+    </AdkitProvider>
+  )
+}
+```
+
+## Components
+
+### `<AdkitProvider>`
+
+Wrap your app (or ad-containing subtree) with the provider to share your site ID across all slots.
+
+```tsx
+<AdkitProvider siteId="your-site-id">
+  {children}
+</AdkitProvider>
+```
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `siteId` | `string` | Yes | Your Adkit site ID |
+| `children` | `ReactNode` | Yes | Child components |
+
+### `<AdSlot>`
+
+Renders an ad placement. When no ad is booked, displays a placeholder inviting visitors to rent the space.
+
+```tsx
+<AdSlot
+  slot="sidebar"
+  aspectRatio="16:9"
+  price={2500}
+  size="lg"
+  theme="auto"
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `slot` | `string` | — | **Required.** Unique slot name (letters, numbers, hyphens, underscores) |
+| `aspectRatio` | `AspectRatio` | — | **Required.** `"16:9"` \| `"4:3"` \| `"1:1"` \| `"9:16"` \| `"banner"` |
+| `siteId` | `string` | — | Manual override (not needed inside `AdkitProvider`) |
+| `price` | `number` | `2500` | Daily rental price in cents (2500 = $25.00) |
+| `size` | `"sm"` \| `"md"` \| `"lg"` | `"lg"` | Placeholder content size |
+| `theme` | `"light"` \| `"dark"` \| `"auto"` | `"auto"` | Color theme (`"auto"` follows system) |
+| `className` | `string` | — | Additional CSS classes |
+| `styles` | `AdSlotStyles` | — | Custom style overrides for placeholder |
+| `silent` | `boolean` | `false` | Disable all event tracking |
+
+### `<BookingModal>`
+
+Exported for advanced use cases. Normally opened automatically when a visitor clicks an empty slot.
+
+## Types
+
+```tsx
+import type { AspectRatio, AdSlotProps, AdSlotStyles } from "adkit-react"
+
+const ratio: AspectRatio = "16:9"
+
+const customStyles: AdSlotStyles = {
+  borderColor: "#3b82f6",
+  backgroundColor: "transparent",
+  textColorPrimary: "#1a1a1a",
+  textColorSecondary: "#666",
+  buttonColor: "#3b82f6"
+}
+```
+
+## Styling
+
+Import the default styles:
+
+```tsx
+import "adkit-react/styles.css"
+```
+
+Control slot width via `className`:
+
+```tsx
+<AdSlot slot="sidebar" aspectRatio="1:1" className="w-[300px]" />
+```
+
+The aspect ratio is enforced by the component — only width needs to be set.
+
+## Hooks
+
+### `useAdkit()`
+
+Access the Adkit context from any child component:
+
+```tsx
+import { useAdkit } from "adkit-react"
+
+function MyComponent() {
+  const { siteId } = useAdkit()
+  // ...
+}
+```
+
+## License
+
+Proprietary. See LICENSE for details.

package/dist/index.d.mts

@@ -0,0 +1,95 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React from 'react';
+
+type AspectRatio = "16:9" | "4:3" | "1:1" | "9:16" | "banner";
+/**
+ * Event types sent to the Adkit API
+ *
+ * - slot_mount: Fires once per slot per page load (installation verification)
+ * - slot_view: Fires once when ≥50% visible (billable impression)
+ * - slot_click: Fires on user click
+ * - slot_duplicate: Diagnostics only — never billable, never blocks rendering
+ */
+type AdkitEventType = "slot_mount" | "slot_view" | "slot_click" | "slot_duplicate";
+/**
+ * Custom style overrides for the AdSlot placeholder.
+ *
+ * IMPORTANT: These styles affect the PLACEHOLDER only, not rendered ads.
+ * When a real ad is displayed, the advertiser controls the creative.
+ * Publishers cannot override ad content styling.
+ */
+type AdSlotStyles = {
+    /** Border color of the dashed placeholder outline */
+    borderColor?: string;
+    /** Background color of the placeholder (default: transparent) */
+    backgroundColor?: string;
+    /** Primary text color for placeholder (price, CTA) */
+    textColorPrimary?: string;
+    /** Secondary text color for placeholder (label, subtext) */
+    textColorSecondary?: string;
+    /** Button background color on hover (placeholder only) */
+    buttonColor?: string;
+};
+type AdSlotProps = {
+    /**
+     * Semantic slot name (e.g. "sidebar", "header-1", "footer").
+     * Must be unique per placement. Only letters, numbers, hyphens, and underscores allowed.
+     */
+    slot: string;
+    /**
+     * Manual site ID override. Only needed without a Provider.
+     * With AdkitProvider, siteId is inherited from context.
+     */
+    siteId?: string;
+    /**
+     * Aspect ratio of the ad slot. Required.
+     * Determines the type/format of ad that will be displayed.
+     */
+    aspectRatio: AspectRatio;
+    /** Daily rental price in cents (e.g. 2500 = $25.00) */
+    price?: number;
+    /** Size variant for the placeholder content */
+    size?: "sm" | "md" | "lg";
+    /** Color theme. "auto" follows system preference. */
+    theme?: "light" | "dark" | "auto";
+    /** Additional CSS class names */
+    className?: string;
+    /** Custom style overrides for the placeholder (does not affect rendered ads) */
+    styles?: AdSlotStyles;
+    /** Disable all event tracking */
+    silent?: boolean;
+};
+
+declare function AdSlot({ slot, siteId: manualSiteId, aspectRatio, price, size, theme, className, styles, silent }: AdSlotProps): react_jsx_runtime.JSX.Element;
+
+type AdkitProviderProps = {
+    /** Your Adkit site ID */
+    siteId: string;
+    children: React.ReactNode;
+};
+declare function AdkitProvider({ siteId, children }: AdkitProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * BookingModal — intentionally simple.
+ *
+ * This modal is informational only. It exists to build trust with the visitor
+ * before redirecting them to adkit.io where the actual booking flow lives.
+ * No forms, no checkout, no data fetching — just copy and a redirect.
+ */
+type BookingModalProps = {
+    siteId: string;
+    slot: string;
+    /** Daily price in cents (e.g. 2500 = $25) */
+    price: number;
+    onClose: () => void;
+};
+declare function BookingModal({ siteId, slot, price, onClose }: BookingModalProps): react_jsx_runtime.JSX.Element;
+
+type AdkitContextValue = {
+    siteId: string;
+    registerSlot: (identity: string) => boolean;
+    unregisterSlot: (identity: string) => void;
+};
+declare function useAdkit(): AdkitContextValue;
+
+export { AdSlot, type AdSlotProps, type AdSlotStyles, type AdkitEventType, AdkitProvider, type AdkitProviderProps, type AspectRatio, BookingModal, useAdkit };

package/dist/index.d.ts

@@ -0,0 +1,95 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React from 'react';
+
+type AspectRatio = "16:9" | "4:3" | "1:1" | "9:16" | "banner";
+/**
+ * Event types sent to the Adkit API
+ *
+ * - slot_mount: Fires once per slot per page load (installation verification)
+ * - slot_view: Fires once when ≥50% visible (billable impression)
+ * - slot_click: Fires on user click
+ * - slot_duplicate: Diagnostics only — never billable, never blocks rendering
+ */
+type AdkitEventType = "slot_mount" | "slot_view" | "slot_click" | "slot_duplicate";
+/**
+ * Custom style overrides for the AdSlot placeholder.
+ *
+ * IMPORTANT: These styles affect the PLACEHOLDER only, not rendered ads.
+ * When a real ad is displayed, the advertiser controls the creative.
+ * Publishers cannot override ad content styling.
+ */
+type AdSlotStyles = {
+    /** Border color of the dashed placeholder outline */
+    borderColor?: string;
+    /** Background color of the placeholder (default: transparent) */
+    backgroundColor?: string;
+    /** Primary text color for placeholder (price, CTA) */
+    textColorPrimary?: string;
+    /** Secondary text color for placeholder (label, subtext) */
+    textColorSecondary?: string;
+    /** Button background color on hover (placeholder only) */
+    buttonColor?: string;
+};
+type AdSlotProps = {
+    /**
+     * Semantic slot name (e.g. "sidebar", "header-1", "footer").
+     * Must be unique per placement. Only letters, numbers, hyphens, and underscores allowed.
+     */
+    slot: string;
+    /**
+     * Manual site ID override. Only needed without a Provider.
+     * With AdkitProvider, siteId is inherited from context.
+     */
+    siteId?: string;
+    /**
+     * Aspect ratio of the ad slot. Required.
+     * Determines the type/format of ad that will be displayed.
+     */
+    aspectRatio: AspectRatio;
+    /** Daily rental price in cents (e.g. 2500 = $25.00) */
+    price?: number;
+    /** Size variant for the placeholder content */
+    size?: "sm" | "md" | "lg";
+    /** Color theme. "auto" follows system preference. */
+    theme?: "light" | "dark" | "auto";
+    /** Additional CSS class names */
+    className?: string;
+    /** Custom style overrides for the placeholder (does not affect rendered ads) */
+    styles?: AdSlotStyles;
+    /** Disable all event tracking */
+    silent?: boolean;
+};
+
+declare function AdSlot({ slot, siteId: manualSiteId, aspectRatio, price, size, theme, className, styles, silent }: AdSlotProps): react_jsx_runtime.JSX.Element;
+
+type AdkitProviderProps = {
+    /** Your Adkit site ID */
+    siteId: string;
+    children: React.ReactNode;
+};
+declare function AdkitProvider({ siteId, children }: AdkitProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * BookingModal — intentionally simple.
+ *
+ * This modal is informational only. It exists to build trust with the visitor
+ * before redirecting them to adkit.io where the actual booking flow lives.
+ * No forms, no checkout, no data fetching — just copy and a redirect.
+ */
+type BookingModalProps = {
+    siteId: string;
+    slot: string;
+    /** Daily price in cents (e.g. 2500 = $25) */
+    price: number;
+    onClose: () => void;
+};
+declare function BookingModal({ siteId, slot, price, onClose }: BookingModalProps): react_jsx_runtime.JSX.Element;
+
+type AdkitContextValue = {
+    siteId: string;
+    registerSlot: (identity: string) => boolean;
+    unregisterSlot: (identity: string) => void;
+};
+declare function useAdkit(): AdkitContextValue;
+
+export { AdSlot, type AdSlotProps, type AdSlotStyles, type AdkitEventType, AdkitProvider, type AdkitProviderProps, type AspectRatio, BookingModal, useAdkit };