@cedros/data-react 0.1.0

package/dist/site-templates/docs-styles.css

@@ -0,0 +1,259 @@
+/* ─── Syntax highlighting (GitHub-light inspired, dark-mode aware) ──── */
+
+.cedros-site__prose .hljs {
+  color: var(--cds-fg);
+  background: transparent;
+}
+
+.hljs-comment,
+.hljs-quote {
+  color: color-mix(in srgb, var(--cds-muted) 85%, var(--cds-fg) 15%);
+  font-style: italic;
+}
+
+.hljs-keyword,
+.hljs-selector-tag,
+.hljs-type {
+  color: #cf222e;
+}
+
+.hljs-string,
+.hljs-addition {
+  color: #0a3069;
+}
+
+.hljs-number,
+.hljs-literal,
+.hljs-variable,
+.hljs-template-variable {
+  color: #0550ae;
+}
+
+.hljs-title,
+.hljs-section,
+.hljs-attr {
+  color: #953800;
+}
+
+.hljs-built_in,
+.hljs-name {
+  color: #8250df;
+}
+
+.hljs-deletion {
+  color: #82071e;
+  background: #ffebe9;
+}
+
+@media (prefers-color-scheme: dark) {
+  .hljs-keyword,
+  .hljs-selector-tag,
+  .hljs-type {
+    color: #ff7b72;
+  }
+
+  .hljs-string,
+  .hljs-addition {
+    color: #a5d6ff;
+  }
+
+  .hljs-number,
+  .hljs-literal,
+  .hljs-variable,
+  .hljs-template-variable {
+    color: #79c0ff;
+  }
+
+  .hljs-title,
+  .hljs-section,
+  .hljs-attr {
+    color: #ffa657;
+  }
+
+  .hljs-built_in,
+  .hljs-name {
+    color: #d2a8ff;
+  }
+
+  .hljs-deletion {
+    color: #ffdcd7;
+    background: #67060c;
+  }
+}
+
+/* ─── Code block copy button ──── */
+
+.cedros-site__code-block {
+  position: relative;
+}
+
+.cedros-site__code-copy {
+  position: absolute;
+  top: 0.45rem;
+  right: 0.45rem;
+  padding: 0.2rem 0.5rem;
+  font-size: 0.7rem;
+  border: 1px solid var(--cds-border);
+  border-radius: calc(var(--cds-radius) - 2px);
+  background: var(--cds-bg);
+  color: var(--cds-muted);
+  cursor: pointer;
+  opacity: 0;
+  transition: opacity 0.15s;
+}
+
+.cedros-site__code-block:hover .cedros-site__code-copy {
+  opacity: 1;
+}
+
+.cedros-site__code-copy:hover {
+  color: var(--cds-fg);
+  border-color: var(--cds-fg);
+}
+
+/* ─── Callout / alert styles (remark-github-blockquote-alert) ──── */
+
+.markdown-alert {
+  margin: 0;
+  padding: 0.65rem 0.85rem;
+  border-left: 3px solid var(--cds-border);
+  border-radius: calc(var(--cds-radius) - 2px);
+  background: color-mix(in srgb, var(--cds-muted-bg) 72%, var(--cds-bg) 28%);
+}
+
+.markdown-alert .markdown-alert-title {
+  font-weight: 600;
+  font-size: 0.82rem;
+  margin-bottom: 0.35rem;
+  display: flex;
+  align-items: center;
+  gap: 0.35rem;
+}
+
+.markdown-alert-note {
+  border-left-color: #0969da;
+}
+
+.markdown-alert-tip {
+  border-left-color: #1a7f37;
+}
+
+.markdown-alert-important {
+  border-left-color: #8250df;
+}
+
+.markdown-alert-warning {
+  border-left-color: #9a6700;
+}
+
+.markdown-alert-caution {
+  border-left-color: #cf222e;
+}
+
+/* ─── Prose table styles ──── */
+
+.cedros-site__prose table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 0.85rem;
+}
+
+.cedros-site__prose th,
+.cedros-site__prose td {
+  padding: 0.45rem 0.65rem;
+  border: 1px solid var(--cds-border);
+  text-align: left;
+}
+
+.cedros-site__prose th {
+  background: var(--cds-muted-bg);
+  font-weight: 600;
+}
+
+/* ─── Collapsible sidebar sections ──── */
+
+.cedros-site__docs-section summary {
+  cursor: pointer;
+  list-style: none;
+  user-select: none;
+}
+
+.cedros-site__docs-section summary::-webkit-details-marker {
+  display: none;
+}
+
+.cedros-site__docs-section summary::before {
+  content: "▸ ";
+  font-size: 0.65em;
+  vertical-align: middle;
+}
+
+.cedros-site__docs-section[open] summary::before {
+  content: "▾ ";
+}
+
+/* ─── Mobile sidebar drawer ──── */
+
+.cedros-site__sidebar-toggle {
+  display: none;
+  width: 100%;
+  padding: 0.55rem 0.75rem;
+  font-size: 0.85rem;
+  font-weight: 600;
+  border: 1px solid var(--cds-border);
+  border-radius: var(--cds-radius);
+  background: var(--cds-bg);
+  color: var(--cds-fg);
+  cursor: pointer;
+  text-align: left;
+}
+
+.cedros-site__sidebar-overlay {
+  display: none;
+}
+
+@media (max-width: 900px) {
+  .cedros-site__sidebar-toggle {
+    display: block;
+  }
+
+  .cedros-site__docs-sidebar {
+    display: none;
+  }
+
+  .cedros-site__docs-sidebar--open {
+    display: grid;
+    position: fixed;
+    inset: 0;
+    z-index: 100;
+    overflow-y: auto;
+    max-width: 320px;
+    box-shadow: 4px 0 12px rgba(0, 0, 0, 0.15);
+  }
+
+  .cedros-site__sidebar-overlay {
+    display: block;
+    position: fixed;
+    inset: 0;
+    z-index: 99;
+    background: rgba(0, 0, 0, 0.3);
+  }
+}
+
+/* ─── TOC scroll-spy active link ──── */
+
+.cedros-site__toc-link--active {
+  color: var(--cds-link);
+  font-weight: 600;
+}
+
+/* ─── Autolinked heading anchors ──── */
+
+.cedros-site__prose :where(h2, h3, h4) a {
+  color: inherit;
+  text-decoration: none;
+}
+
+.cedros-site__prose :where(h2, h3, h4) a:hover {
+  text-decoration: underline;
+}

package/dist/site-templates/docsNavigation.d.ts

@@ -0,0 +1,18 @@
+import type { DocsIndexEntry } from "./contentIndex.js";
+export interface DocsSidebarItem {
+    key: string;
+    label: string;
+    href: string;
+    isActive?: boolean;
+    depth?: 0 | 1 | 2;
+    badge?: string;
+}
+export interface DocsSidebarSection {
+    key: string;
+    label: string;
+    items: DocsSidebarItem[];
+    /** When true, section renders collapsed by default in the sidebar. */
+    collapsed?: boolean;
+}
+export declare function buildDocsSidebarSections(docs: DocsIndexEntry[], basePath?: string): DocsSidebarSection[];
+export declare function withActiveDocsSidebar(sections: DocsSidebarSection[], currentPath?: string): DocsSidebarSection[];

package/dist/site-templates/docsNavigation.js

@@ -0,0 +1,50 @@
+import { isRouteActive, normalizeRoutePath } from "./routing.js";
+export function buildDocsSidebarSections(docs, basePath = "/docs") {
+    const grouped = new Map();
+    docs.forEach((doc) => {
+        const sectionLabel = doc.category ?? "Overview";
+        const sectionKey = sectionLabel.toLowerCase().replace(/\s+/gu, "-");
+        const current = grouped.get(sectionKey) ?? { label: sectionLabel, items: [] };
+        current.items.push({
+            key: doc.slug,
+            label: doc.title,
+            href: `${basePath}/${doc.slug}`
+        });
+        grouped.set(sectionKey, current);
+    });
+    return [...grouped.entries()]
+        .map(([key, value]) => ({
+        key,
+        label: value.label,
+        items: [...value.items].sort((left, right) => left.label.localeCompare(right.label))
+    }))
+        .sort((left, right) => left.label.localeCompare(right.label));
+}
+export function withActiveDocsSidebar(sections, currentPath) {
+    if (!currentPath) {
+        return sections.map((section) => ({
+            ...section,
+            items: section.items.map((item) => ({
+                ...item,
+                isActive: item.isActive ?? false
+            }))
+        }));
+    }
+    const candidateLengths = sections
+        .flatMap((section) => section.items)
+        .filter((item) => item.isActive === undefined && isRouteActive(item.href, currentPath))
+        .map((item) => normalizeRoutePath(item.href).length);
+    const longestCandidateLength = candidateLengths.length > 0 ? Math.max(...candidateLengths) : 0;
+    return sections.map((section) => ({
+        ...section,
+        items: section.items.map((item) => {
+            const inferredActive = longestCandidateLength > 0 &&
+                normalizeRoutePath(item.href).length === longestCandidateLength &&
+                isRouteActive(item.href, currentPath);
+            return {
+                ...item,
+                isActive: item.isActive ?? inferredActive
+            };
+        })
+    }));
+}

package/dist/site-templates/index.d.ts

@@ -0,0 +1,28 @@
+export { SiteLayout, type SiteLayoutProps, type SiteNavigationItem } from "./SiteLayout.js";
+export { TopNav, type TopNavProps } from "./TopNav.js";
+export { SiteFooter, type SiteFooterProps, type SiteFooterLink } from "./SiteFooter.js";
+export { DashboardShell, type DashboardShellProps, type DashboardNavItem } from "./DashboardShell.js";
+export { DashboardOverviewTemplate, type DashboardOverviewTemplateProps, type DashboardPanel, type DashboardStat } from "./DashboardOverviewTemplate.js";
+export { isRouteActive, normalizeRoutePath, withActiveRouteState, type RouteAwareItem, type RouteMatcherOptions } from "./routing.js";
+export { buildContentListHref, collectFilterValues, collectDimensionValues, matchesFilterDimensions, prepareBlogIndex, prepareDocsIndex, type BlogIndexEntry, type BlogIndexQuery, type DocsIndexEntry, type DocsIndexQuery, type FilterDimension, type FilterDimensionValues, type PaginationResult } from "./contentIndex.js";
+export { buildDocsSidebarSections, withActiveDocsSidebar, type DocsSidebarItem, type DocsSidebarSection } from "./docsNavigation.js";
+export { MarkdownContent, type MarkdownContentProps } from "./MarkdownContent.js";
+export { extractTocFromMarkdown, type TocEntry } from "./tocExtractor.js";
+export { DocsSidebar, type DocsSidebarProps } from "./DocsSidebar.js";
+export { TocScrollSpy, type TocScrollSpyProps } from "./tocScrollSpy.js";
+export { CodeBlock, type CodeBlockProps } from "./codeBlock.js";
+export { Breadcrumbs, ContentPagination, type PaginationProps } from "./contentUi.js";
+export { HomePageTemplate, type HomePageTemplateProps, type HomeFeature } from "./HomePageTemplate.js";
+export { DocsIndexTemplate, DocArticleTemplate, type DocsIndexTemplateProps, type DocArticleTemplateProps, type DocsIndexItem } from "./DocsTemplates.js";
+export { BlogIndexTemplate, BlogPostTemplate, type BlogIndexTemplateProps, type BlogPostTemplateProps, type BlogPostSummary, type BlogTippingConfig, type BlogPaywallConfig } from "./BlogTemplates.js";
+export { TipWidget } from "./tipControls.js";
+export type { TipWidgetProps, TipCurrency, TipParams, TipPayClient } from "./tipControls.js";
+export { ContentPaywall } from "./paywallControls.js";
+export type { ContentPaywallProps, PaywallPrice, PaywallPayClient } from "./paywallControls.js";
+export { BlogSearchInput, FilterDimensionChips, BookmarkButton } from "./blogControls.js";
+export type { BlogSearchInputProps, FilterDimensionChipsProps, BookmarkButtonProps } from "./blogControls.js";
+export { SolanaMicropayments, createSolanaTipClient, detectSolanaWallet, SOL_CURRENCY, USDC_CURRENCY, type SolanaMicropaymentsProps, } from "./solanaMicropayments.js";
+export { ensureRecipientAta } from "./solanaAtaSetup.js";
+export { LegalPageTemplate, type LegalPageTemplateProps } from "./LegalPageTemplate.js";
+export { ContactPageTemplate, type ContactPageTemplateProps, type ContactDetail } from "./ContactPageTemplate.js";
+export { NotFoundTemplate, type NotFoundTemplateProps } from "./NotFoundTemplate.js";

package/dist/site-templates/index.js

@@ -0,0 +1,25 @@
+export { SiteLayout } from "./SiteLayout.js";
+export { TopNav } from "./TopNav.js";
+export { SiteFooter } from "./SiteFooter.js";
+export { DashboardShell } from "./DashboardShell.js";
+export { DashboardOverviewTemplate } from "./DashboardOverviewTemplate.js";
+export { isRouteActive, normalizeRoutePath, withActiveRouteState } from "./routing.js";
+export { buildContentListHref, collectFilterValues, collectDimensionValues, matchesFilterDimensions, prepareBlogIndex, prepareDocsIndex } from "./contentIndex.js";
+export { buildDocsSidebarSections, withActiveDocsSidebar } from "./docsNavigation.js";
+export { MarkdownContent } from "./MarkdownContent.js";
+export { extractTocFromMarkdown } from "./tocExtractor.js";
+export { DocsSidebar } from "./DocsSidebar.js";
+export { TocScrollSpy } from "./tocScrollSpy.js";
+export { CodeBlock } from "./codeBlock.js";
+export { Breadcrumbs, ContentPagination } from "./contentUi.js";
+export { HomePageTemplate } from "./HomePageTemplate.js";
+export { DocsIndexTemplate, DocArticleTemplate } from "./DocsTemplates.js";
+export { BlogIndexTemplate, BlogPostTemplate } from "./BlogTemplates.js";
+export { TipWidget } from "./tipControls.js";
+export { ContentPaywall } from "./paywallControls.js";
+export { BlogSearchInput, FilterDimensionChips, BookmarkButton } from "./blogControls.js";
+export { SolanaMicropayments, createSolanaTipClient, detectSolanaWallet, SOL_CURRENCY, USDC_CURRENCY, } from "./solanaMicropayments.js";
+export { ensureRecipientAta } from "./solanaAtaSetup.js";
+export { LegalPageTemplate } from "./LegalPageTemplate.js";
+export { ContactPageTemplate } from "./ContactPageTemplate.js";
+export { NotFoundTemplate } from "./NotFoundTemplate.js";

package/dist/site-templates/monetization-styles.css

@@ -0,0 +1,154 @@
+/* TipWidget styles */
+.cedros-site__tip-widget {
+  display: grid;
+  gap: 0.75rem;
+  border: 1px solid var(--cds-border);
+  border-radius: var(--cds-radius);
+  padding: 1.25rem;
+  background: var(--cds-bg);
+}
+
+.cedros-site__tip-title {
+  margin: 0;
+  font-size: 1.05rem;
+}
+
+.cedros-site__tip-description {
+  margin: 0;
+  font-size: 0.82rem;
+  color: var(--cds-muted);
+}
+
+.cedros-site__tip-currency {
+  width: 100%;
+  border: 1px solid var(--cds-border);
+  border-radius: calc(var(--cds-radius) - 2px);
+  background: color-mix(in srgb, var(--cds-bg) 90%, var(--cds-muted-bg) 10%);
+  color: var(--cds-fg);
+  height: 2.25rem;
+  padding: 0 0.6rem;
+}
+
+.cedros-site__tip-presets {
+  display: inline-flex;
+  flex-wrap: wrap;
+  gap: 0.35rem;
+}
+
+.cedros-site__tip-amount input {
+  width: 100%;
+  border: 1px solid var(--cds-border);
+  border-radius: calc(var(--cds-radius) - 2px);
+  background: color-mix(in srgb, var(--cds-bg) 90%, var(--cds-muted-bg) 10%);
+  color: var(--cds-fg);
+  height: 2.25rem;
+  padding: 0 0.6rem;
+}
+
+.cedros-site__tip-submit {
+  border: none;
+  border-radius: calc(var(--cds-radius) - 2px);
+  background: var(--cds-link);
+  color: var(--cds-bg);
+  padding: 0.55rem 1.2rem;
+  font-size: 0.85rem;
+  cursor: pointer;
+}
+
+.cedros-site__tip-submit:hover {
+  opacity: 0.9;
+}
+
+.cedros-site__tip-submit:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.cedros-site__tip-status {
+  margin: 0;
+  font-size: 0.82rem;
+}
+
+.cedros-site__tip-status--success {
+  color: #16a34a;
+}
+
+.cedros-site__tip-status--error {
+  color: #dc2626;
+}
+
+/* ContentPaywall styles */
+.cedros-site__paywall {
+  position: relative;
+}
+
+.cedros-site__paywall-fade {
+  position: relative;
+  overflow: hidden;
+  max-height: 18rem;
+}
+
+.cedros-site__paywall-fade::after {
+  content: "";
+  position: absolute;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  height: 6rem;
+  background: linear-gradient(to bottom, transparent, var(--cds-bg));
+  pointer-events: none;
+}
+
+.cedros-site__paywall-lock {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 0.6rem;
+  padding: 2rem 1rem;
+  color: var(--cds-muted);
+}
+
+.cedros-site__paywall-lock p {
+  margin: 0;
+  font-size: 0.9rem;
+}
+
+.cedros-site__paywall-cta {
+  display: grid;
+  gap: 0.75rem;
+  justify-items: center;
+  padding: 1.25rem;
+  border: 1px solid var(--cds-border);
+  border-radius: var(--cds-radius);
+  background: var(--cds-muted-bg);
+  margin-top: 0.75rem;
+}
+
+.cedros-site__paywall-price {
+  margin: 0;
+  font-size: 1.1rem;
+  font-weight: 600;
+}
+
+.cedros-site__paywall-actions {
+  display: inline-flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  justify-content: center;
+}
+
+/* Metered paywall banner */
+.cedros-site__metered-banner {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  margin-top: 1.25rem;
+  padding: 0.65rem 1rem;
+  border: 1px solid var(--cds-border);
+  border-radius: var(--cds-radius);
+  background: var(--cds-muted-bg);
+  color: var(--cds-muted);
+  font-size: 0.82rem;
+  text-align: center;
+}

package/dist/site-templates/paywallControls.d.ts

@@ -0,0 +1,22 @@
+export interface PaywallPrice {
+    amount: number;
+    currency: string;
+}
+/** Provided by @cedros/pay-react (or any compatible implementation). */
+export interface PaywallPayClient {
+    purchase?: () => Promise<void>;
+    subscribe?: () => Promise<void>;
+    useCredits?: () => Promise<void>;
+    creditsBalance?: number;
+}
+export interface ContentPaywallProps {
+    mode: "preview" | "locked";
+    previewContent?: string;
+    previewHtml?: string;
+    allowUnsafeHtmlFallback?: boolean;
+    price?: PaywallPrice;
+    payClient: PaywallPayClient;
+    purchaseLabel?: string;
+    subscriptionLabel?: string;
+}
+export declare function ContentPaywall({ mode, previewContent, previewHtml, allowUnsafeHtmlFallback, price, payClient, purchaseLabel, subscriptionLabel }: ContentPaywallProps): React.JSX.Element;

package/dist/site-templates/paywallControls.js

@@ -0,0 +1,9 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { MarkdownContent } from "./MarkdownContent.js";
+export function ContentPaywall({ mode, previewContent, previewHtml, allowUnsafeHtmlFallback, price, payClient, purchaseLabel = "Purchase", subscriptionLabel = "Subscribe" }) {
+    const showCredits = payClient.useCredits &&
+        payClient.creditsBalance !== undefined &&
+        payClient.creditsBalance > 0;
+    return (_jsxs("div", { className: "cedros-site__paywall", children: [mode === "preview" && (_jsx("div", { className: "cedros-site__paywall-fade", children: _jsx(MarkdownContent, { bodyMarkdown: previewContent, bodyHtml: previewHtml, allowUnsafeHtmlFallback: allowUnsafeHtmlFallback }) })), mode === "locked" && (_jsxs("div", { className: "cedros-site__paywall-lock", children: [_jsxs("svg", { width: "32", height: "32", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": "true", children: [_jsx("rect", { x: "3", y: "11", width: "18", height: "11", rx: "2", ry: "2" }), _jsx("path", { d: "M7 11V7a5 5 0 0110 0v4" })] }), _jsx("p", { children: "Unlock this article" })] })), _jsxs("div", { className: "cedros-site__paywall-cta", children: [price && price.amount > 0 && (_jsxs("p", { className: "cedros-site__paywall-price", children: [price.amount, " ", price.currency] })), _jsxs("div", { className: "cedros-site__paywall-actions", children: [payClient.purchase && (_jsx("button", { type: "button", className: "cedros-site__tip-submit", onClick: () => void payClient.purchase(), children: purchaseLabel })), payClient.subscribe && (_jsx("button", { type: "button", className: "cedros-site__pill", onClick: () => void payClient.subscribe(), children: subscriptionLabel })), showCredits && (_jsxs("button", { type: "button", className: "cedros-site__pill", onClick: () => void payClient.useCredits(), children: ["Use Credits (", payClient.creditsBalance, ")"] }))] })] })] }));
+}

package/dist/site-templates/routing.d.ts

@@ -0,0 +1,12 @@
+export interface RouteMatcherOptions {
+    exact?: boolean;
+}
+export interface RouteAwareItem {
+    route: string;
+    isActive?: boolean;
+}
+export declare function normalizeRoutePath(route: string): string;
+export declare function isRouteActive(route: string, currentPath: string, options?: RouteMatcherOptions): boolean;
+export declare function withActiveRouteState<T extends RouteAwareItem>(items: T[], currentPath: string, options?: RouteMatcherOptions): Array<T & {
+    isActive: boolean;
+}>;

package/dist/site-templates/routing.js

@@ -0,0 +1,36 @@
+export function normalizeRoutePath(route) {
+    if (!route) {
+        return "/";
+    }
+    const [pathOnly] = route.split(/[?#]/u, 1);
+    if (!pathOnly || pathOnly === "/") {
+        return "/";
+    }
+    const withLeadingSlash = pathOnly.startsWith("/") ? pathOnly : `/${pathOnly}`;
+    return withLeadingSlash.replace(/\/+$/u, "") || "/";
+}
+export function isRouteActive(route, currentPath, options = {}) {
+    const normalizedRoute = normalizeRoutePath(route);
+    const normalizedCurrentPath = normalizeRoutePath(currentPath);
+    if (options.exact || normalizedRoute === "/") {
+        return normalizedRoute === normalizedCurrentPath;
+    }
+    return (normalizedCurrentPath === normalizedRoute ||
+        normalizedCurrentPath.startsWith(`${normalizedRoute}/`));
+}
+export function withActiveRouteState(items, currentPath, options = {}) {
+    const candidates = items
+        .filter((item) => item.isActive === undefined && isRouteActive(item.route, currentPath, options))
+        .map((item) => normalizeRoutePath(item.route).length);
+    const longestCandidateLength = candidates.length > 0 ? Math.max(...candidates) : 0;
+    return items.map((item) => {
+        const normalizedRouteLength = normalizeRoutePath(item.route).length;
+        const inferredActive = longestCandidateLength > 0 &&
+            normalizedRouteLength === longestCandidateLength &&
+            isRouteActive(item.route, currentPath, options);
+        return {
+            ...item,
+            isActive: item.isActive ?? inferredActive
+        };
+    });
+}

package/dist/site-templates/solanaAtaSetup.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Helper for admin to pre-create Associated Token Accounts (ATAs) for
+ * SPL token tipping. Browser wallets expose signAndSendTransaction
+ * rather than raw Signer, so we manually check + create.
+ *
+ * @param recipient - Solana wallet address of the tip recipient
+ * @param mint - SPL token mint address (e.g. USDC)
+ * @param rpcEndpoint - Solana RPC URL, defaults to mainnet-beta
+ * @returns The ATA address as a base58 string
+ */
+export declare function ensureRecipientAta(recipient: string, mint: string, rpcEndpoint?: string): Promise<string>;

package/dist/site-templates/solanaAtaSetup.js

@@ -0,0 +1,38 @@
+/**
+ * Helper for admin to pre-create Associated Token Accounts (ATAs) for
+ * SPL token tipping. Browser wallets expose signAndSendTransaction
+ * rather than raw Signer, so we manually check + create.
+ *
+ * @param recipient - Solana wallet address of the tip recipient
+ * @param mint - SPL token mint address (e.g. USDC)
+ * @param rpcEndpoint - Solana RPC URL, defaults to mainnet-beta
+ * @returns The ATA address as a base58 string
+ */
+export async function ensureRecipientAta(recipient, mint, rpcEndpoint = "https://api.mainnet-beta.solana.com") {
+    const { Connection, PublicKey, Transaction } = await import("@solana/web3.js");
+    const { getAssociatedTokenAddress, createAssociatedTokenAccountInstruction, } = await import("@solana/spl-token");
+    const connection = new Connection(rpcEndpoint, "confirmed");
+    const recipientPubkey = new PublicKey(recipient);
+    const mintPubkey = new PublicKey(mint);
+    const ata = await getAssociatedTokenAddress(mintPubkey, recipientPubkey);
+    const info = await connection.getAccountInfo(ata);
+    if (info) {
+        // ATA already exists
+        return ata.toBase58();
+    }
+    // Create ATA — requires connected wallet to sign + pay fees
+    const wallet = window.solana;
+    if (!wallet)
+        throw new Error("No Solana wallet detected");
+    if (!wallet.isConnected)
+        await wallet.connect();
+    if (!wallet.publicKey)
+        throw new Error("Wallet not connected");
+    const payerPubkey = new PublicKey(wallet.publicKey.toString());
+    const tx = new Transaction().add(createAssociatedTokenAccountInstruction(payerPubkey, ata, recipientPubkey, mintPubkey));
+    tx.feePayer = payerPubkey;
+    tx.recentBlockhash = (await connection.getLatestBlockhash()).blockhash;
+    const { signature } = await wallet.signAndSendTransaction(tx);
+    await connection.confirmTransaction(signature, "confirmed");
+    return ata.toBase58();
+}