@yoamigo.com/core 0.4.7 → 1.0.0

package/dist/index.d.ts

@@ -1,44 +1,11 @@
+import { C as ChangeSource, Q as QueryFilter, b as CollectionRecord, o as CartItem, E as EditMode } from './cart-storage-DFdGPcwm.js';
+export { a as CollectionClient, d as CollectionClientConfig, t as ContentStoreContextType, v as ContentStoreMode, p as ContentStoreProvider, L as ListOptions, c as ListResponse, S as SingleResponse, f as clearSessionId, g as getCollectionClient, n as getLocalCartItemCount, k as getLocalCartItems, e as getSessionId, i as initBuilderSelection, r as resetCollectionClient, q as useContentStore } from './cart-storage-DFdGPcwm.js';
+export { D as BackgroundConfig, F as BackgroundImageConfig, C as ContentStoreProviderProd, q as EmbedFieldValue, r as EmbedType, I as ImageFieldValue, f as MarkdownText, g as MarkdownTextProps, O as OverlayConfig, P as PageInfo, c as StaticImage, d as StaticImageProps, M as StaticText, S as StaticTextProps, V as VideoFieldValue, y as YaContainer, B as YaContainerProps, m as YaEmbed, o as YaEmbedProps, Y as YaImage, h as YaImageProps, w as YaLink, x as YaLinkProps, j as YaVideo, l as YaVideoProps, b as background, e as embed, i as image, z as parseBackgroundConfig, p as parseEmbedUrl, A as serializeBackgroundConfig, n as serializeEmbedValue, s as serializeImageValue, k as serializeVideoValue, t as text, u as useContentStoreProd, v as video } from './content-helpers-DOUKazMz.js';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React$1, { ReactNode } from 'react';
-export { D as BackgroundConfig, F as BackgroundImageConfig, C as ContentStoreProviderProd, q as EmbedFieldValue, r as EmbedType, I as ImageFieldValue, f as MarkdownText, g as MarkdownTextProps, O as OverlayConfig, P as PageInfo, c as StaticImage, d as StaticImageProps, M as StaticText, S as StaticTextProps, V as VideoFieldValue, y as YaContainer, B as YaContainerProps, m as YaEmbed, o as YaEmbedProps, Y as YaImage, h as YaImageProps, w as YaLink, x as YaLinkProps, j as YaVideo, l as YaVideoProps, b as background, e as embed, i as image, z as parseBackgroundConfig, p as parseEmbedUrl, A as serializeBackgroundConfig, n as serializeEmbedValue, s as serializeImageValue, k as serializeVideoValue, t as text, u as useContentStoreProd, v as video } from './content-helpers-DOUKazMz.js';
-export { Link, LinkProps, NavigateFunction, Router, RouterProps, ScrollRestoration, useNavigate } from './router.js';
-export { Route, Switch, useParams } from 'wouter';
+export { Link, LinkProps, NavigateFunction, RouteDefinition, Router, RouterProps, ScrollRestoration, createRouteDefinition, extractRouteParams, filePathToRoutePath, generatePath, sortRoutesBySpecificity, useNavigate } from './router.js';
+export { Route, Switch, useLocation, useParams } from 'wouter';
 export { A as AssetResolverFn, C as ContentRegistry, c as contentRegistry, a as getAllContent, g as getContent, h as hasContent, r as registerContent, b as resolveAssetUrl, s as setAssetResolver } from './asset-resolver-BnIvDkVv.js';
-export { i as initBuilderSelection } from './builder-selection-CYP91nRu.js';
-
-type EditMode = 'read-only' | 'inline-edit';
-type ChangeSource = 'user' | 'ai' | 'initial';
-interface PageInfo {
-    path: string;
-    label: string;
-}
-interface ActiveFieldCallbacks {
-    close: () => void;
-}
-interface ContentStore {
-    getValue: (fieldId: string) => string;
-    setValue: (fieldId: string, value: string, source?: ChangeSource) => void;
-    getChangeSource: (fieldId: string) => ChangeSource;
-    clearChangeSource: (fieldId: string) => void;
-    mode: EditMode;
-    setMode: (mode: EditMode) => void;
-    subscribe: (listener: () => void) => () => void;
-    saveToWorker?: (fieldId: string, value: string) => Promise<void>;
-    activeFieldId: string | null;
-    setActiveField: (fieldId: string, callbacks: ActiveFieldCallbacks) => void;
-    clearActiveField: () => void;
-    getPages: () => PageInfo[];
-}
-type ContentStoreContextType = ContentStore;
-type ContentStoreMode = EditMode;
-declare function useContentStore(): ContentStoreContextType;
-interface ContentStoreProviderProps {
-    children: ReactNode;
-    initialContent?: Record<string, string>;
-    initialMode?: EditMode;
-    pages?: PageInfo[];
-}
-declare function ContentStoreProvider({ children, initialContent, initialMode, pages, }: ContentStoreProviderProps): react_jsx_runtime.JSX.Element;
 
 /** Common HTML elements that YaText can render as */
 type YaTextElement = 'span' | 'div' | 'p' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'label' | 'strong' | 'em';
@@ -126,6 +93,435 @@ interface TooltipProps {
 }
 declare function Tooltip({ content, children, position, delay, }: TooltipProps): react_jsx_runtime.JSX.Element;
 
+interface CollectionContentContextValue {
+    /** Get a value from the collection record */
+    getValue: (fieldId: string) => string;
+    /** Set a value (triggers local update + backend save). Only available in edit mode. */
+    setValue?: (fieldId: string, value: string, source?: ChangeSource) => void;
+    /** Save to backend (creates/updates StagedAppRecord). Only available in edit mode. */
+    saveToBackend?: (fieldId: string, value: string) => Promise<void>;
+    /** Get the change source for animation tracking */
+    getChangeSource?: (fieldId: string) => ChangeSource;
+    /** Clear change source after animation completes */
+    clearChangeSource?: (fieldId: string) => void;
+    /** Whether this content is from a collection */
+    isCollectionContent: true;
+    /** The prefix used for field IDs */
+    prefix: string;
+    /** The record ID (for UPDATE) or undefined (for CREATE) */
+    recordId?: string;
+    /** Collection slug for API calls */
+    collectionSlug?: string;
+    /** App ID for API calls */
+    appId?: string;
+    /** Whether editing is enabled */
+    isEditable: boolean;
+}
+interface CollectionContentProviderProps {
+    /** The collection record data (the `data` field from CollectionRecord) */
+    record: Record<string, unknown>;
+    /** Prefix for field IDs (e.g., "product" makes "product.name") */
+    prefix: string;
+    /** Child components */
+    children: ReactNode;
+    /** The AppRecord ID (required for UPDATE, optional for CREATE) */
+    recordId?: string;
+    /** Collection slug for API calls */
+    collectionSlug?: string;
+    /** App ID for API calls */
+    appId?: string;
+    /** Whether this is a new record or existing */
+    changeType?: 'CREATE' | 'UPDATE';
+}
+/**
+ * Hook to get collection content context.
+ * Returns null if not inside a CollectionContentProvider.
+ */
+declare function useCollectionContent(): CollectionContentContextValue | null;
+/**
+ * Provider that makes collection record data available to YaText, YaImage, etc.
+ *
+ * Fields are accessed using dot notation with the prefix:
+ * - `prefix="product"` + field `name` → `fieldId="product.name"`
+ * - Nested: `prefix="product"` + field `image.src` → `fieldId="product.image.src"`
+ *
+ * When edit props are provided, inline edits are saved to StagedAppRecord.
+ */
+declare function CollectionContentProvider({ record, prefix, children, recordId, collectionSlug, appId, changeType: _changeType, }: CollectionContentProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Collection Hooks
+ *
+ * React hooks for fetching collection data from the API.
+ * Used in templates for dynamic pages powered by collection records.
+ */
+
+interface UseCollectionListOptions {
+    /** Collection slug (e.g., 'products', 'posts') */
+    collection: string;
+    /** Optional filters to apply */
+    filters?: QueryFilter[];
+    /** Page number (1-indexed for convenience) */
+    page?: number;
+    /** Number of items per page */
+    pageSize?: number;
+    /** Field to order by */
+    orderBy?: string;
+    /** Order direction */
+    orderDir?: 'asc' | 'desc';
+    /** Whether to fetch (useful for conditional fetching) */
+    enabled?: boolean;
+}
+interface UseCollectionListResult<T = Record<string, unknown>> {
+    /** The fetched records, or null if not yet loaded */
+    data: CollectionRecord<T>[] | null;
+    /** Whether the initial fetch is in progress */
+    isLoading: boolean;
+    /** Error message if fetch failed */
+    error: string | null;
+    /** Total count of records matching the query */
+    totalCount: number;
+    /** Whether there are more pages */
+    hasMore: boolean;
+    /** Current page number */
+    currentPage: number;
+    /** Total number of pages */
+    totalPages: number;
+    /** Refetch the data */
+    refetch: () => void;
+    /** Go to a specific page */
+    goToPage: (page: number) => void;
+}
+interface UseCollectionRecordOptions {
+    /** Collection slug (e.g., 'products', 'posts') */
+    collection: string;
+    /** Field name that contains the slug (e.g., 'slug', 'handle') */
+    slugField: string;
+    /** Slug value to look up */
+    slugValue: string;
+    /** Whether to fetch (useful for conditional fetching) */
+    enabled?: boolean;
+}
+interface UseCollectionRecordResult<T = Record<string, unknown>> {
+    /** The fetched record, or null if not yet loaded */
+    data: CollectionRecord<T> | null;
+    /** Whether the fetch is in progress */
+    isLoading: boolean;
+    /** Error message if fetch failed */
+    error: string | null;
+    /** Whether the record was not found (404) */
+    notFound: boolean;
+    /** Refetch the data */
+    refetch: () => void;
+}
+/**
+ * Hook for fetching a list of collection records with pagination.
+ *
+ * @example
+ * ```tsx
+ * const { data: products, isLoading, goToPage } = useCollectionList({
+ *   collection: 'products',
+ *   pageSize: 12,
+ *   orderBy: 'createdAt',
+ *   orderDir: 'desc'
+ * })
+ * ```
+ */
+declare function useCollectionList<T = Record<string, unknown>>(options: UseCollectionListOptions): UseCollectionListResult<T>;
+/**
+ * Hook for fetching a single collection record by slug.
+ *
+ * @example
+ * ```tsx
+ * const { slug } = useParams()
+ * const { data: product, isLoading, notFound } = useCollectionRecord({
+ *   collection: 'products',
+ *   slugField: 'slug',
+ *   slugValue: slug!
+ * })
+ * ```
+ */
+declare function useCollectionRecord<T = Record<string, unknown>>(options: UseCollectionRecordOptions): UseCollectionRecordResult<T>;
+
+/**
+ * CollectionPage Components
+ *
+ * Higher-level wrapper components for common collection page patterns.
+ * These simplify creating list and detail pages powered by collection data.
+ *
+ * @example List Page
+ * ```tsx
+ * <CollectionListPage
+ *   collection="products"
+ *   pageSize={12}
+ *   render={({ data, isLoading }) => (
+ *     isLoading ? <Skeleton /> : <ProductGrid products={data} />
+ *   )}
+ * />
+ * ```
+ *
+ * @example Detail Page
+ * ```tsx
+ * <CollectionDetailPage
+ *   collection="products"
+ *   slugField="slug"
+ *   render={({ data, isLoading, notFound }) => {
+ *     if (isLoading) return <Skeleton />
+ *     if (notFound) return <NotFound />
+ *     return <ProductDetail product={data} />
+ *   }}
+ * />
+ * ```
+ */
+
+interface CollectionListPageProps<T = Record<string, unknown>> {
+    /** Collection slug (e.g., 'products', 'posts') */
+    collection: string;
+    /** Number of items per page */
+    pageSize?: number;
+    /** Initial page number */
+    page?: number;
+    /** Filters to apply */
+    filters?: QueryFilter[];
+    /** Field to order by */
+    orderBy?: string;
+    /** Order direction */
+    orderDir?: 'asc' | 'desc';
+    /** Whether to fetch data */
+    enabled?: boolean;
+    /** Render function that receives the list result */
+    render: (result: UseCollectionListResult<T>) => ReactNode;
+}
+/**
+ * Wrapper component for collection list pages.
+ *
+ * Handles data fetching and provides the result to a render function,
+ * giving you full control over the UI.
+ */
+declare function CollectionListPage<T = Record<string, unknown>>({ collection, pageSize, page, filters, orderBy, orderDir, enabled, render, }: CollectionListPageProps<T>): ReactNode;
+interface CollectionDetailPageProps<T = Record<string, unknown>> {
+    /** Collection slug (e.g., 'products', 'posts') */
+    collection: string;
+    /** Field name that contains the slug (e.g., 'slug', 'handle') */
+    slugField?: string;
+    /** URL parameter name for the slug (default: 'slug') */
+    slugParam?: string;
+    /** Override slug value (instead of reading from URL params) */
+    slug?: string;
+    /** Whether to fetch data */
+    enabled?: boolean;
+    /** Render function that receives the record result */
+    render: (result: CollectionDetailRenderProps<T>) => ReactNode;
+}
+interface CollectionDetailRenderProps<T = Record<string, unknown>> extends UseCollectionRecordResult<T> {
+    /** The slug value from URL params */
+    slug: string;
+}
+/**
+ * Wrapper component for collection detail pages.
+ *
+ * Automatically reads the slug from URL params (default: `:slug`)
+ * and fetches the matching record.
+ *
+ * @example
+ * ```tsx
+ * // For route /products/:slug
+ * <CollectionDetailPage
+ *   collection="products"
+ *   render={({ data, isLoading, notFound }) => {
+ *     if (isLoading) return <Skeleton />
+ *     if (notFound) return <NotFound />
+ *     return <ProductDetail product={data} />
+ *   }}
+ * />
+ * ```
+ */
+declare function CollectionDetailPage<T = Record<string, unknown>>({ collection, slugField, slugParam, slug: slugOverride, enabled, render, }: CollectionDetailPageProps<T>): ReactNode;
+/**
+ * Type helper for creating typed collection page components.
+ *
+ * @example
+ * ```tsx
+ * interface Product {
+ *   slug: string
+ *   name: string
+ *   price: number
+ * }
+ *
+ * // Products list page with type safety
+ * function ProductsPage() {
+ *   return (
+ *     <CollectionListPage<Product>
+ *       collection="products"
+ *       render={({ data }) => (
+ *         data?.map(p => <div key={p.id}>{p.data.name}</div>)
+ *       )}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+type CollectionData<T> = CollectionRecord<T>;
+/**
+ * Type helper for list page data
+ */
+type CollectionListData<T> = CollectionRecord<T>[];
+
+/**
+ * CollectionList
+ *
+ * Renders a filtered list of collection items with editing support.
+ * Each item is wrapped in CollectionContentProvider so YaText/YaImage
+ * components can read and edit collection fields.
+ *
+ * @example
+ * ```tsx
+ * <CollectionList
+ *   collection="products"
+ *   prefix="product"
+ *   filters={[{ field: 'category', operator: 'eq', value: 'guitars' }]}
+ *   pageSize={6}
+ *   skeleton={({ index }) => <ProductCardSkeleton key={index} />}
+ *   empty={<p>No products found</p>}
+ *   wrapper={({ children }) => (
+ *     <div className="grid grid-cols-3 gap-4">{children}</div>
+ *   )}
+ * >
+ *   {({ record, fieldPrefix }) => (
+ *     <div key={record.id}>
+ *       <YaImage fieldId={`${fieldPrefix}.image`} />
+ *       <YaText fieldId={`${fieldPrefix}.name`} />
+ *     </div>
+ *   )}
+ * </CollectionList>
+ * ```
+ */
+
+interface CollectionListRenderProps<T = Record<string, unknown>> {
+    /** The collection record */
+    record: CollectionRecord<T>;
+    /** Index of this item in the list */
+    index: number;
+    /** The unique fieldId prefix for this item (e.g., "product.abc123") */
+    fieldPrefix: string;
+}
+interface CollectionListProps<T = Record<string, unknown>> extends Omit<UseCollectionListOptions, 'enabled'> {
+    /** Base prefix for fieldIds. Each item gets `{prefix}.{recordId}` */
+    prefix: string;
+    /** Render function for each item */
+    children: (props: CollectionListRenderProps<T>) => ReactNode;
+    /** Render function for skeleton items during loading (REQUIRED for zero layout shift) */
+    skeleton: (props: {
+        index: number;
+    }) => ReactNode;
+    /** Empty state render (when no items match) */
+    empty?: ReactNode;
+    /** Error state render */
+    error?: (error: string) => ReactNode;
+    /** App ID for editing (auto-detected in builder context) */
+    appId?: string;
+    /** Whether to enable fetching (default: true) */
+    enabled?: boolean;
+    /** Render pagination controls */
+    pagination?: (props: CollectionListPaginationProps) => ReactNode;
+    /** Wrapper element/component for the list items */
+    wrapper?: (props: {
+        children: ReactNode;
+    }) => ReactNode;
+}
+interface CollectionListPaginationProps {
+    currentPage: number;
+    totalPages: number;
+    totalCount: number;
+    hasMore: boolean;
+    goToPage: (page: number) => void;
+}
+/**
+ * Renders a filtered collection list with editing support.
+ *
+ * Each record is wrapped in CollectionContentProvider with a unique prefix
+ * (`{prefix}.{recordId}`) so that multiple items can be rendered and edited
+ * on the same page without fieldId collisions.
+ */
+declare function CollectionList<T = Record<string, unknown>>({ collection, prefix, filters, page, pageSize, orderBy, orderDir, children, skeleton, empty, error, appId, enabled, pagination, wrapper: Wrapper, }: CollectionListProps<T>): ReactNode;
+
+/**
+ * CollectionItem
+ *
+ * Renders a single collection item with editing support.
+ * The item is wrapped in CollectionContentProvider so YaText/YaImage
+ * components can read and edit collection fields.
+ *
+ * @example
+ * ```tsx
+ * // By slug with required skeleton for zero layout shift
+ * <CollectionItem
+ *   collection="products"
+ *   slugField="slug"
+ *   slugValue="featured-guitar"
+ *   prefix="featured"
+ *   skeleton={<FeaturedProductSkeleton />}
+ * >
+ *   {({ record, notFound }) => (
+ *     notFound ? <NotFound /> :
+ *     <>
+ *       <YaImage fieldId="featured.image" />
+ *       <YaText fieldId="featured.name" />
+ *     </>
+ *   )}
+ * </CollectionItem>
+ *
+ * // By ID (uses slug lookup with id field)
+ * <CollectionItem
+ *   collection="products"
+ *   slugField="id"
+ *   slugValue={productId}
+ *   prefix="product"
+ *   skeleton={<ProductCardSkeleton />}
+ * >
+ *   {({ record }) => <ProductCard />}
+ * </CollectionItem>
+ * ```
+ */
+
+interface CollectionItemRenderProps<T = Record<string, unknown>> {
+    /** The fetched record, or null if not loaded/found */
+    record: CollectionRecord<T> | null;
+    /** Whether the fetch is in progress */
+    isLoading: boolean;
+    /** Whether the record was not found (404) */
+    notFound: boolean;
+    /** Error message if fetch failed */
+    error: string | null;
+    /** Refetch the record */
+    refetch: () => void;
+}
+interface CollectionItemProps<T = Record<string, unknown>> {
+    /** Collection slug (e.g., 'products', 'posts') */
+    collection: string;
+    /** Prefix for fieldIds (e.g., "featured" makes "featured.name") */
+    prefix: string;
+    /** Field name to use for lookup (e.g., 'slug', 'handle', 'id') */
+    slugField?: string;
+    /** Value to look up */
+    slugValue: string;
+    /** Render function */
+    children: (props: CollectionItemRenderProps<T>) => ReactNode;
+    /** Skeleton to show during loading (REQUIRED for zero layout shift) */
+    skeleton: ReactNode;
+    /** App ID for editing (auto-detected in builder context) */
+    appId?: string;
+    /** Whether to enable fetching (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Renders a single collection item with editing support.
+ *
+ * The record is wrapped in CollectionContentProvider with the specified prefix
+ * so YaText/YaImage can read fields like `{prefix}.name`, `{prefix}.image`, etc.
+ */
+declare function CollectionItem<T = Record<string, unknown>>({ collection, prefix, slugField, slugValue, children, skeleton, appId, enabled, }: CollectionItemProps<T>): ReactNode;
+
 /**
  * Animation state for a single field
  */
@@ -201,6 +597,108 @@ interface AIEditProviderProps {
  */
 declare function AIEditProvider({ children, staggerDelay }: AIEditProviderProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * useCart Hook
+ *
+ * React hook for managing shopping cart state.
+ * Supports both logged-in users (API persistence) and guests (localStorage fallback).
+ */
+
+interface UseCartOptions {
+    /** App ID to scope the cart */
+    appId?: string;
+    /** App user token for authenticated users */
+    userToken?: string | null;
+    /** API base URL */
+    apiUrl?: string;
+}
+interface UseCartResult {
+    /** Cart items */
+    items: CartItem[];
+    /** Total number of items (sum of quantities) */
+    itemCount: number;
+    /** Whether the cart is loading */
+    isLoading: boolean;
+    /** Error message if any */
+    error: string | null;
+    /** Add an item to the cart */
+    addItem: (productId: string, collectionSlug: string, quantity?: number, variantId?: string, data?: Record<string, unknown>) => Promise<void>;
+    /** Update item quantity (0 removes the item) */
+    updateQuantity: (itemId: string, quantity: number) => Promise<void>;
+    /** Remove an item from the cart */
+    removeItem: (itemId: string) => Promise<void>;
+    /** Clear all items from the cart */
+    clearCart: () => Promise<void>;
+    /** Merge guest cart into user cart after login */
+    mergeGuestCart: () => Promise<void>;
+    /** Refresh cart from server */
+    refresh: () => Promise<void>;
+}
+/**
+ * Hook for managing shopping cart.
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   items,
+ *   itemCount,
+ *   addItem,
+ *   removeItem,
+ *   clearCart,
+ * } = useCart({ userToken: authToken })
+ *
+ * // Add item
+ * await addItem('product-123', 'products', 2)
+ *
+ * // Remove item
+ * await removeItem('item-456')
+ * ```
+ */
+declare function useCart(options?: UseCartOptions): UseCartResult;
+
+interface CartProviderProps extends UseCartOptions {
+    /** Child components */
+    children: ReactNode;
+    /** Callback when user token changes (for cart merge) */
+    onUserTokenChange?: (hasToken: boolean) => void;
+}
+/**
+ * Cart provider component.
+ *
+ * @example
+ * ```tsx
+ * // In your app root
+ * function App() {
+ *   const [userToken, setUserToken] = useState<string | null>(null)
+ *
+ *   return (
+ *     <CartProvider userToken={userToken}>
+ *       <MyApp />
+ *     </CartProvider>
+ *   )
+ * }
+ *
+ * // In any child component
+ * function CartIcon() {
+ *   const { itemCount } = useCartContext()
+ *   return <Badge count={itemCount}>Cart</Badge>
+ * }
+ * ```
+ */
+declare function CartProvider({ children, userToken, onUserTokenChange, ...options }: CartProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access cart context.
+ * Must be used within a CartProvider.
+ *
+ * @throws Error if used outside CartProvider
+ */
+declare function useCartContext(): UseCartResult;
+/**
+ * Hook to access cart context with optional null return.
+ * Useful when cart might not be available.
+ */
+declare function useOptionalCartContext(): UseCartResult | null;
+
 /**
  * Text Diffing Utilities for AI Edit Animations
  *
@@ -572,4 +1070,665 @@ interface UseSafeTriangleReturn<T extends HTMLElement, U extends HTMLElement> {
  */
 declare function useSafeTriangle<T extends HTMLElement = HTMLElement, U extends HTMLElement = HTMLDivElement>(options?: UseSafeTriangleOptions): UseSafeTriangleReturn<T, U>;
 
-export { type AIEditContextValue, AIEditProvider, type AnimatedTextOptions, type AnimatedTextResult, type AnimationConfig, type AnimationMetadata, type AnimationOptions, type AnimationPhase, type AnimationResult, type AnimationState, type AnimationStrategy, type ContentStoreContextType, type ContentStoreMode, ContentStoreProvider, type ImageValue, type LinkValue, SafeHtml, type SafeHtmlProps, SafeTriangleBelow, type TextAnimationMetadata, type TextDiff, Tooltip, type TooltipProps, YaText, type YaTextProps, buildIntermediateText, calculateAnimationTiming, computeTextDiff, containsHtml, getTextCursorPosition, imageCrossfadeStrategy, linkTransitionStrategy, stripHtml, textTypingStrategy, useAIEditAnimation, useAIEditContext, useAIEditContextOptional, useAnimatedText, useContentStore, useSafeTriangle };
+/**
+ * useContent - Unified Content Access Hook
+ *
+ * Provides a single API for Ya* components to access content regardless
+ * of whether it comes from static content (ContentStoreProvider) or
+ * collection data (CollectionContentProvider).
+ *
+ * @example
+ * ```tsx
+ * // Simple text field
+ * const content = useContent<string>(fieldId)
+ * const text = content.value
+ *
+ * // Typed image field
+ * const content = useContent<ImageField>(fieldId)
+ * const { src, alt } = content.value
+ *
+ * // Compound fields (like YaLink)
+ * const textContent = useContent<string>(`${fieldId}.text`)
+ * const hrefContent = useContent<string>(`${fieldId}.href`)
+ * ```
+ */
+
+interface ContentHandle<T> {
+    /** Parsed value (for object types like ImageField) */
+    value: T;
+    /** Get raw string value */
+    get(): string;
+    /** Set value with optional change source for animations */
+    set(value: T | string, source?: ChangeSource): void;
+    /** Persist to backend (static or collection) */
+    save(): Promise<void>;
+    /** Current change source (for animations: 'user' | 'ai' | 'initial') */
+    changeSource: ChangeSource | undefined;
+    /** Clear change source after animation completes */
+    clearChangeSource(): void;
+    /** Current edit mode: 'read-only' | 'inline-edit' */
+    mode: EditMode;
+    /** Is this field in a collection context? */
+    isCollectionField: boolean;
+}
+/**
+ * Unified content access hook.
+ *
+ * Automatically routes to the correct provider based on fieldId:
+ * - If inside CollectionContentProvider and fieldId starts with prefix, uses collection context
+ * - Otherwise uses ContentStoreProvider
+ *
+ * @param fieldId - The field identifier (e.g., "hero.title" or "product.name")
+ * @returns ContentHandle<T> with value, get, set, save, and animation helpers
+ */
+declare function useContent<T = string>(fieldId: string): ContentHandle<T>;
+
+/** Simple text field - just a string */
+type TextField = string;
+/** Image field with metadata */
+interface ImageField {
+    /** Image source URL */
+    src: string;
+    /** Alt text for accessibility */
+    alt?: string;
+    /** CSS object-fit */
+    objectFit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
+    /** CSS object-position (e.g., "50% 50%", "top left") */
+    objectPosition?: string;
+}
+/** Link field with text and destination */
+interface LinkField {
+    /** Display text */
+    text: string;
+    /** URL or route path */
+    href: string;
+}
+/** Video field with playback options */
+interface VideoField {
+    /** Video source type */
+    type: 'upload' | 'youtube' | 'vimeo';
+    /** Video URL (for upload) or video ID (for embeds) */
+    src: string;
+    /** Poster image URL */
+    poster?: string;
+    /** Autoplay video (requires muted for browser policy) */
+    autoplay?: boolean;
+    /** Mute video audio */
+    muted?: boolean;
+    /** Loop video playback */
+    loop?: boolean;
+    /** Show video controls */
+    controls?: boolean;
+    /** Play inline on mobile (prevent fullscreen hijack) */
+    playsinline?: boolean;
+    /** Preload strategy */
+    preload?: 'none' | 'metadata' | 'auto';
+    /** CSS object-fit */
+    objectFit?: 'cover' | 'contain' | 'fill';
+    /** CSS aspect-ratio (e.g., "16/9") */
+    aspectRatio?: string;
+}
+/** Embed field for iframes (YouTube, Vimeo, Spotify, etc.) */
+interface EmbedField {
+    /** Embed type */
+    type: 'youtube' | 'vimeo' | 'spotify' | 'soundcloud' | 'custom';
+    /** Embed URL or ID */
+    src: string;
+    /** CSS aspect-ratio (e.g., "16/9") */
+    aspectRatio?: string;
+    /** Fixed height in pixels (overrides aspectRatio) */
+    height?: number;
+}
+/** Container/section field for background styling */
+interface ContainerField {
+    /** Background color */
+    backgroundColor?: string;
+    /** Background image URL */
+    backgroundImage?: string;
+    /** Background position */
+    backgroundPosition?: string;
+    /** Background size */
+    backgroundSize?: 'cover' | 'contain' | 'auto';
+}
+/** All field types union */
+type AnyField = TextField | ImageField | LinkField | VideoField | EmbedField | ContainerField;
+/** Parse raw string value into typed field */
+declare function parseFieldValue<T>(raw: string | undefined): T;
+/** Stringify field value for storage */
+declare function stringifyFieldValue<T>(value: T): string;
+
+/**
+ * useCheckout Hook
+ *
+ * React hook for initiating Stripe Checkout sessions.
+ */
+interface UseCheckoutOptions {
+    /** App ID to scope the checkout */
+    appId?: string;
+    /** App user token for authenticated users */
+    userToken?: string | null;
+    /** API base URL */
+    apiUrl?: string;
+}
+interface CheckoutOptions {
+    /** URL to redirect to on successful payment */
+    successUrl: string;
+    /** URL to redirect to if user cancels checkout */
+    cancelUrl: string;
+    /** Customer email (optional, auto-filled if user is logged in) */
+    customerEmail?: string;
+    /** Additional metadata to attach to the order */
+    metadata?: Record<string, string>;
+}
+interface CheckoutResult {
+    /** Stripe Checkout Session ID */
+    sessionId: string;
+    /** URL to redirect to for payment */
+    url: string;
+    /** Order ID in our database */
+    orderId: string;
+    /** Human-readable order number */
+    orderNumber: string;
+}
+interface UseCheckoutResult {
+    /** Initiate checkout and get the checkout URL */
+    initiateCheckout: (options: CheckoutOptions) => Promise<CheckoutResult>;
+    /** Whether checkout is being initiated */
+    isLoading: boolean;
+    /** Error message if checkout failed */
+    error: string | null;
+}
+/**
+ * Hook for initiating Stripe Checkout.
+ *
+ * @example
+ * ```tsx
+ * const { initiateCheckout, isLoading, error } = useCheckout({ userToken: authToken })
+ *
+ * const handleCheckout = async () => {
+ *   try {
+ *     const result = await initiateCheckout({
+ *       successUrl: `${window.location.origin}/checkout/success`,
+ *       cancelUrl: `${window.location.origin}/cart`,
+ *     })
+ *
+ *     // Redirect to Stripe Checkout
+ *     window.location.href = result.url
+ *   } catch (err) {
+ *     console.error('Checkout failed:', err)
+ *   }
+ * }
+ * ```
+ */
+declare function useCheckout(options?: UseCheckoutOptions): UseCheckoutResult;
+interface CheckoutSessionStatus {
+    sessionId: string;
+    status: 'open' | 'complete' | 'expired';
+    paymentStatus: 'no_payment_required' | 'paid' | 'unpaid';
+    customerEmail: string | null;
+    amountTotal: number | null;
+    currency: string | null;
+    order: {
+        id: string;
+        orderNumber: string;
+        status: string;
+    } | null;
+}
+interface UseCheckoutStatusOptions extends UseCheckoutOptions {
+    /** Stripe Checkout Session ID to check */
+    sessionId: string;
+    /** Whether to poll for status updates */
+    poll?: boolean;
+    /** Polling interval in milliseconds (default: 2000) */
+    pollInterval?: number;
+}
+interface UseCheckoutStatusResult {
+    /** Checkout session status */
+    status: CheckoutSessionStatus | null;
+    /** Whether status is loading */
+    isLoading: boolean;
+    /** Error message if any */
+    error: string | null;
+    /** Refresh status */
+    refresh: () => Promise<void>;
+}
+/**
+ * Hook for checking Stripe Checkout session status.
+ *
+ * @example
+ * ```tsx
+ * // On success page, check if payment completed
+ * const searchParams = new URLSearchParams(window.location.search)
+ * const sessionId = searchParams.get('session_id')
+ *
+ * const { status, isLoading } = useCheckoutStatus({
+ *   sessionId: sessionId!,
+ *   poll: true,
+ * })
+ *
+ * if (status?.paymentStatus === 'paid') {
+ *   // Show success message
+ * }
+ * ```
+ */
+declare function useCheckoutStatus(options: UseCheckoutStatusOptions): UseCheckoutStatusResult;
+
+/**
+ * useProducts Hook
+ *
+ * Thin wrapper around useCollectionList for fetching products.
+ * Provides product-specific filtering and types.
+ */
+
+interface Product {
+    /** Product name */
+    name: string;
+    /** URL-friendly slug */
+    slug?: string;
+    /** Price in cents */
+    price: number;
+    /** Product type */
+    productType: 'one_time' | 'subscription';
+    /** Product status */
+    status: 'draft' | 'active' | 'archived';
+    /** Product images */
+    images?: string[];
+    /** Short description */
+    description?: string;
+    /** Full description/details */
+    details?: string;
+    /** Product category */
+    category?: string;
+    /** Stripe integration */
+    stripe?: {
+        productId?: string;
+        priceId?: string;
+    };
+    /** Subscription details (for subscription products) */
+    subscription?: {
+        interval: 'month' | 'year';
+        intervalCount: number;
+        trialDays?: number;
+    };
+    /** Inventory tracking */
+    inventory?: {
+        trackQuantity: boolean;
+        quantity: number;
+    };
+    /** Any additional custom fields */
+    [key: string]: unknown;
+}
+interface UseProductsOptions {
+    /** Collection slug where products are stored (default: 'products') */
+    collection?: string;
+    /** Only fetch active products (default: true) */
+    activeOnly?: boolean;
+    /** Filter by category */
+    category?: string;
+    /** Filter by product type */
+    productType?: 'one_time' | 'subscription';
+    /** Additional filters */
+    filters?: QueryFilter[];
+    /** Page number */
+    page?: number;
+    /** Items per page */
+    pageSize?: number;
+    /** Field to sort by */
+    orderBy?: string;
+    /** Sort direction */
+    orderDir?: 'asc' | 'desc';
+    /** Whether to fetch */
+    enabled?: boolean;
+}
+interface UseProductsResult extends Omit<UseCollectionListResult<Product>, 'data'> {
+    /** The fetched products */
+    products: CollectionRecord<Product>[] | null;
+}
+interface UseProductOptions {
+    /** Collection slug where products are stored (default: 'products') */
+    collection?: string;
+    /** Product slug to fetch */
+    slug: string;
+    /** Whether to fetch */
+    enabled?: boolean;
+}
+interface UseProductResult {
+    /** The fetched product */
+    product: CollectionRecord<Product> | null;
+    /** Whether the fetch is in progress */
+    isLoading: boolean;
+    /** Error message if fetch failed */
+    error: string | null;
+    /** Whether the product was not found */
+    notFound: boolean;
+    /** Refetch the product */
+    refetch: () => void;
+}
+/**
+ * Hook for fetching a list of products from a collection.
+ *
+ * @example
+ * ```tsx
+ * // Fetch all active products
+ * const { products, isLoading, goToPage } = useProducts({
+ *   pageSize: 12,
+ * })
+ *
+ * // Fetch products by category
+ * const { products } = useProducts({
+ *   category: 'merch',
+ *   activeOnly: true,
+ * })
+ *
+ * // Fetch subscription products only
+ * const { products } = useProducts({
+ *   productType: 'subscription',
+ * })
+ * ```
+ */
+declare function useProducts(options?: UseProductsOptions): UseProductsResult;
+/**
+ * Hook for fetching a single product by slug.
+ *
+ * @example
+ * ```tsx
+ * const { slug } = useParams()
+ * const { product, isLoading, notFound } = useProduct({ slug: slug! })
+ *
+ * if (notFound) {
+ *   return <NotFoundPage />
+ * }
+ *
+ * if (product) {
+ *   return <ProductDetails product={product.data} />
+ * }
+ * ```
+ */
+declare function useProduct(options: UseProductOptions): UseProductResult;
+
+/**
+ * Subscription Types
+ *
+ * Type definitions for subscription management in yoamigo-core.
+ */
+type SubscriptionStatusType = 'active' | 'trialing' | 'past_due' | 'canceled' | 'incomplete' | 'incomplete_expired' | 'unpaid' | 'paused';
+interface SubscriptionProduct {
+    id: string;
+    name: string;
+    description?: string;
+}
+interface SubscriptionPrice {
+    id: string;
+    unitAmount: number;
+    currency: string;
+    interval: 'day' | 'week' | 'month' | 'year';
+    intervalCount: number;
+}
+interface SubscriptionDetails {
+    id: string;
+    status: SubscriptionStatusType;
+    currentPeriodStart: string;
+    currentPeriodEnd: string;
+    cancelAtPeriodEnd: boolean;
+    canceledAt?: string;
+    endedAt?: string;
+    trialStart?: string;
+    trialEnd?: string;
+    product: SubscriptionProduct;
+    price: SubscriptionPrice;
+}
+interface SubscribeParams {
+    /** Tier slug to subscribe to (e.g., "pro", "business") */
+    tierSlug: string;
+    /** URL to redirect to on successful subscription */
+    successUrl: string;
+    /** URL to redirect to if user cancels */
+    cancelUrl: string;
+    /** Quantity of the subscription (default: 1) */
+    quantity?: number;
+    /** Number of trial days (overrides price default if set) */
+    trialDays?: number;
+    /** Customer email (auto-filled if authenticated) */
+    customerEmail?: string;
+    /** Additional metadata */
+    metadata?: Record<string, string>;
+}
+interface SubscribeResult {
+    success: boolean;
+    checkoutUrl?: string;
+    sessionId?: string;
+    error?: string;
+}
+interface CustomerPortalParams {
+    /** URL to return to after portal session */
+    returnUrl: string;
+}
+interface CustomerPortalResult {
+    success: boolean;
+    portalUrl?: string;
+    error?: string;
+}
+interface SubscriptionStatusResult {
+    success: boolean;
+    status: SubscriptionStatusType | 'none';
+    subscriptions?: SubscriptionDetails[];
+    error?: string;
+}
+
+/**
+ * useSubscription Hook
+ *
+ * React hook for creating Stripe subscription checkout sessions.
+ * Used by template websites to allow customers to subscribe to recurring products.
+ *
+ * Uses tier-based subscriptions - users select tiers (e.g., "pro", "business"),
+ * not arbitrary price IDs. The API resolves tiers to the correct Stripe price
+ * based on the environment (staging vs production).
+ */
+
+interface UseSubscriptionOptions {
+    /** App ID to scope the subscription */
+    appId?: string;
+    /** App user token for authenticated users */
+    userToken?: string | null;
+    /** API base URL */
+    apiUrl?: string;
+}
+interface UseSubscriptionResult {
+    /** Create a subscription checkout session and get the checkout URL */
+    subscribe: (params: SubscribeParams) => Promise<SubscribeResult>;
+    /** Whether subscription checkout is being created */
+    isLoading: boolean;
+    /** Error message if subscription creation failed */
+    error: string | null;
+}
+/**
+ * Hook for creating subscription checkout sessions using tier-based pricing.
+ *
+ * @example
+ * ```tsx
+ * const { subscribe, isLoading, error } = useSubscription({ userToken: authToken })
+ *
+ * const handleSubscribe = async (tierSlug: string) => {
+ *   const result = await subscribe({
+ *     tierSlug, // e.g., "pro", "business"
+ *     // URLs are site-specific - use whatever routes your template defines
+ *     successUrl: `${window.location.origin}/your-success-page`,
+ *     cancelUrl: `${window.location.origin}/your-pricing-page`,
+ *   })
+ *
+ *   if (result.success && result.checkoutUrl) {
+ *     window.location.href = result.checkoutUrl
+ *   }
+ * }
+ * ```
+ */
+declare function useSubscription(options?: UseSubscriptionOptions): UseSubscriptionResult;
+
+/**
+ * useSubscriptionTiers Hook
+ *
+ * React hook for fetching available subscription tiers for an app.
+ * Tiers are returned pre-sorted by displayOrder for easy UI rendering.
+ */
+interface SubscriptionTier {
+    /** Unique identifier for the tier (e.g., "pro", "business") */
+    slug: string;
+    /** Display name (e.g., "Pro Plan") */
+    name: string;
+    /** Optional description */
+    description: string | null;
+    /** Price in cents (e.g., 1999 = $19.99) */
+    priceCents: number;
+    /** Billing interval: "month" or "year" */
+    billingInterval: 'month' | 'year';
+    /** Interval count (e.g., 1 for monthly, 12 for yearly) */
+    billingIntervalCount: number;
+    /** Currency code (e.g., "usd") */
+    currency: string;
+    /** List of feature descriptions */
+    features: string[];
+    /** Whether to show "Most Popular" or similar badge */
+    highlighted: boolean;
+    /** Sort order for UI display */
+    displayOrder: number;
+}
+interface UseSubscriptionTiersOptions {
+    /** App ID to fetch tiers for */
+    appId?: string;
+    /** API base URL */
+    apiUrl?: string;
+    /** Whether to fetch tiers immediately on mount (default: true) */
+    fetchOnMount?: boolean;
+}
+interface UseSubscriptionTiersResult {
+    /** Available subscription tiers (sorted by displayOrder) */
+    tiers: SubscriptionTier[];
+    /** Whether tiers are being loaded */
+    isLoading: boolean;
+    /** Error message if loading failed */
+    error: string | null;
+    /** Manually refresh the tiers */
+    refresh: () => Promise<void>;
+}
+/**
+ * Hook for fetching available subscription tiers.
+ *
+ * @example
+ * ```tsx
+ * const { tiers, isLoading, error } = useSubscriptionTiers()
+ *
+ * if (isLoading) return <Loading />
+ * if (error) return <Error message={error} />
+ *
+ * return (
+ *   <div className="pricing-grid">
+ *     {tiers.map(tier => (
+ *       <PricingCard
+ *         key={tier.slug}
+ *         tier={tier}
+ *         onSelect={() => handleSubscribe(tier.slug)}
+ *       />
+ *     ))}
+ *   </div>
+ * )
+ * ```
+ */
+declare function useSubscriptionTiers(options?: UseSubscriptionTiersOptions): UseSubscriptionTiersResult;
+
+/**
+ * useCustomerPortal Hook
+ *
+ * React hook for creating Stripe Customer Portal sessions.
+ * Allows customers to manage their subscriptions (update payment method,
+ * cancel subscription, view billing history, etc.).
+ */
+
+interface UseCustomerPortalOptions {
+    /** App ID to scope the portal */
+    appId?: string;
+    /** App user token for authenticated users (required for portal) */
+    userToken: string;
+    /** API base URL */
+    apiUrl?: string;
+}
+interface UseCustomerPortalResult {
+    /** Open the customer portal and get the portal URL */
+    openPortal: (params: CustomerPortalParams) => Promise<CustomerPortalResult>;
+    /** Whether portal session is being created */
+    isLoading: boolean;
+    /** Error message if portal creation failed */
+    error: string | null;
+}
+/**
+ * Hook for creating Stripe Customer Portal sessions.
+ *
+ * @example
+ * ```tsx
+ * const { openPortal, isLoading, error } = useCustomerPortal({ userToken: authToken })
+ *
+ * const handleManageSubscription = async () => {
+ *   const result = await openPortal({
+ *     returnUrl: `${window.location.origin}/account`,
+ *   })
+ *
+ *   if (result.success && result.portalUrl) {
+ *     window.location.href = result.portalUrl
+ *   }
+ * }
+ * ```
+ */
+declare function useCustomerPortal(options: UseCustomerPortalOptions): UseCustomerPortalResult;
+
+/**
+ * useSubscriptionStatus Hook
+ *
+ * React hook for fetching and polling the current user's subscription status.
+ * Provides information about active subscriptions, trial periods, and billing dates.
+ */
+
+interface UseSubscriptionStatusOptions {
+    /** App ID to scope the subscription status */
+    appId?: string;
+    /** App user token for authenticated users (required) */
+    userToken: string;
+    /** API base URL */
+    apiUrl?: string;
+    /** Whether to automatically fetch on mount (default: true) */
+    autoFetch?: boolean;
+    /** Poll interval in milliseconds (0 to disable polling, default: 0) */
+    pollInterval?: number;
+}
+interface UseSubscriptionStatusResult {
+    /** Aggregated subscription status ('active' if any subscription is active) */
+    status: SubscriptionStatusType | 'none' | null;
+    /** All subscriptions for the user */
+    subscriptions: SubscriptionDetails[];
+    /** Whether status is loading */
+    isLoading: boolean;
+    /** Error message if any */
+    error: string | null;
+    /** Manually refresh the subscription status */
+    refresh: () => Promise<void>;
+}
+/**
+ * Hook for checking the current user's subscription status.
+ *
+ * @example
+ * ```tsx
+ * const { status, subscriptions, isLoading, refresh } = useSubscriptionStatus({
+ *   userToken: authToken,
+ * })
+ *
+ * if (status === 'active') {
+ *   // Show premium content
+ * } else if (status === 'trialing') {
+ *   // Show trial banner with days remaining
+ * } else {
+ *   // Show upgrade prompt
+ * }
+ * ```
+ */
+declare function useSubscriptionStatus(options: UseSubscriptionStatusOptions): UseSubscriptionStatusResult;
+
+export { type AIEditContextValue, AIEditProvider, type AnimatedTextOptions, type AnimatedTextResult, type AnimationConfig, type AnimationMetadata, type AnimationOptions, type AnimationPhase, type AnimationResult, type AnimationState, type AnimationStrategy, type AnyField, CartItem, CartProvider, type CartProviderProps, type CheckoutOptions, type CheckoutResult, type CheckoutSessionStatus, type CollectionContentContextValue, CollectionContentProvider, type CollectionContentProviderProps, type CollectionData, CollectionDetailPage, type CollectionDetailPageProps, type CollectionDetailRenderProps, CollectionItem, type CollectionItemProps, type CollectionItemRenderProps, CollectionList, type CollectionListData, CollectionListPage, type CollectionListPageProps, type CollectionListPaginationProps, type CollectionListProps, type CollectionListRenderProps, CollectionRecord, type ContainerField, type ContentHandle, type CustomerPortalParams, type CustomerPortalResult, type EmbedField, type ImageField, type ImageValue, type LinkField, type LinkValue, type Product, QueryFilter, SafeHtml, type SafeHtmlProps, SafeTriangleBelow, type SubscribeParams, type SubscribeResult, type SubscriptionDetails, type SubscriptionPrice, type SubscriptionProduct, type SubscriptionStatusResult, type SubscriptionStatusType, type SubscriptionTier, type TextAnimationMetadata, type TextDiff, type TextField, Tooltip, type TooltipProps, type UseCartOptions, type UseCartResult, type UseCheckoutOptions, type UseCheckoutResult, type UseCheckoutStatusOptions, type UseCheckoutStatusResult, type UseCollectionListOptions, type UseCollectionListResult, type UseCollectionRecordOptions, type UseCollectionRecordResult, type UseCustomerPortalOptions, type UseCustomerPortalResult, type UseProductOptions, type UseProductResult, type UseProductsOptions, type UseProductsResult, type UseSubscriptionOptions, type UseSubscriptionResult, type UseSubscriptionStatusOptions, type UseSubscriptionStatusResult, type UseSubscriptionTiersOptions, type UseSubscriptionTiersResult, type VideoField, YaText, type YaTextProps, buildIntermediateText, calculateAnimationTiming, computeTextDiff, containsHtml, getTextCursorPosition, imageCrossfadeStrategy, linkTransitionStrategy, parseFieldValue, stringifyFieldValue, stripHtml, textTypingStrategy, useAIEditAnimation, useAIEditContext, useAIEditContextOptional, useAnimatedText, useCart, useCartContext, useCheckout, useCheckoutStatus, useCollectionContent, useCollectionList, useCollectionRecord, useContent, useCustomerPortal, useOptionalCartContext, useProduct, useProducts, useSafeTriangle, useSubscription, useSubscriptionStatus, useSubscriptionTiers };