@salesmind-ai/design-system 0.2.1 → 0.3.1

package/dist/web/server/index.d.cts

@@ -0,0 +1,725 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Schema.org SEO Generator Types
+ *
+ * Framework-agnostic types for structured data generation.
+ * Extracted from website/src/lib/seo.ts for reuse across all consumers.
+ */
+/** Brand configuration required by schema generators */
+interface BrandConfig {
+    name: string;
+    url: string;
+    description: string;
+    tagline: string;
+    founder: string;
+}
+interface BreadcrumbItem {
+    name: string;
+    url: string;
+}
+interface ArticleMeta {
+    title: string;
+    description: string;
+    url: string;
+    image?: string;
+    publishedTime: string;
+    modifiedTime: string;
+    authorName: string;
+    authorUrl?: string;
+    authorSlug?: string;
+    section: string;
+    tags?: string[];
+    speakableCssSelectors?: string[];
+    about?: Record<string, unknown> | {
+        '@id': string;
+    };
+    video?: Record<string, unknown> | {
+        '@id': string;
+    };
+}
+interface FAQItem {
+    question: string;
+    answer: string;
+}
+interface PersonMeta {
+    name: string;
+    jobTitle: string;
+    slug?: string;
+    url?: string;
+    image?: string;
+    sameAs?: string[];
+    worksFor?: {
+        name: string;
+        '@id'?: string;
+    };
+    entityIdOverride?: string;
+}
+interface PricingPlan {
+    name: string;
+    description: string;
+    price: string;
+    priceCurrency?: string;
+    billingPeriod?: string;
+}
+/** Lightweight testimonial shape for schema generation */
+interface TestimonialForSchema {
+    id: string;
+    customer_name: string;
+    occupation?: string | null;
+    star_rating?: number | null;
+    review_date?: string | null;
+    review_source?: string | null;
+    review_link?: string | null;
+    quote?: string | null;
+    company?: string | null;
+    authorEntityId?: string;
+}
+/** Lightweight career/job shape for schema generation */
+interface CareerForSchema {
+    title: string;
+    slug: string;
+    department?: string | null;
+    location?: string | null;
+    type?: string | null;
+    description?: string | null;
+    created_at: string;
+    published_at?: string | null;
+}
+/** Lightweight transcript shape for schema generation */
+interface TranscriptForSchema {
+    title: string;
+    slug: string;
+    summary?: string | null;
+    video_link?: string | null;
+    transcript_text?: string | null;
+    duration?: string | null;
+    published_at?: string | null;
+    path?: string;
+    thumbnailUrl?: string;
+}
+/** Glossary term for DefinedTermSet schema */
+interface GlossaryTermForSchema {
+    term: string;
+    slug: string;
+    definition: string;
+    url?: string;
+}
+/** Single step in a HowTo schema */
+interface HowToStep {
+    name: string;
+    text: string;
+    url?: string;
+    image?: string;
+}
+/** HowTo metadata */
+interface HowToMeta {
+    name: string;
+    description: string;
+    /** ISO 8601 duration, e.g. "PT30M" */
+    totalTime?: string;
+    image?: string;
+}
+/** Service/growth motion for Service schema */
+interface ServiceMotion {
+    name: string;
+    slug: string;
+    description: string;
+    url: string;
+    price?: string;
+    priceCurrency?: string;
+}
+/** Item for ItemList schema (hub/listing pages) */
+interface ItemForList {
+    name: string;
+    url: string;
+    description?: string;
+    image?: string;
+    position?: number;
+}
+interface CustomerOrganizationMeta {
+    name: string;
+    slug: string;
+    url?: string;
+    logo?: string;
+    industry?: string;
+    description?: string;
+    sameAs?: string[];
+}
+interface VideoObjectMeta {
+    title: string;
+    path: string;
+    fragment?: string;
+    description?: string;
+    videoUrl?: string;
+    embedUrl?: string;
+    thumbnailUrl?: string;
+    duration?: string;
+    uploadDate?: string;
+    transcript?: string;
+}
+
+/**
+ * Schema.org Generator System
+ *
+ * Pure functions that generate structured data objects for SEO.
+ * Each generator accepts a `BrandConfig` and optional `locale` for `inLanguage` injection.
+ *
+ * Architecture:
+ * - Each generator returns an object with its own `@context` (standalone-safe).
+ * - `buildPageGraph()` strips individual `@context` and wraps all schemas
+ *   in a single `{"@context": "...", "@graph": [...]}` for unified output.
+ * - Use `JsonLd` React component to render the @graph into a single <script> tag.
+ *
+ * @example
+ * ```ts
+ * import { createSchemaGenerators, buildPageGraph } from '@salesmind-ai/design-system/web';
+ *
+ * const seo = createSchemaGenerators({
+ *   name: 'SalesMind AI',
+ *   url: 'https://sales-mind.ai',
+ *   description: 'AI sales automation',
+ *   tagline: 'AI-powered sales',
+ *   founder: 'Julien Gadea',
+ * });
+ *
+ * const graph = buildPageGraph(
+ *   seo.organization(),
+ *   seo.website(),
+ *   seo.webPage('/pricing', 'Pricing', '...'),
+ * );
+ * ```
+ */
+
+/**
+ * Create stable entity ID anchors for @graph cross-referencing.
+ * Every entity in the knowledge graph gets a permanent @id.
+ * Google resolves @id references across the entire site.
+ */
+declare function createEntityIds(brand: BrandConfig): {
+    readonly organization: `${string}/#organization`;
+    readonly website: `${string}/#website`;
+    readonly software: `${string}/#software`;
+    readonly product: `${string}/pricing#product`;
+    readonly webpage: (path: string) => string;
+    readonly article: (path: string) => string;
+    readonly faq: (path: string) => string;
+    readonly breadcrumb: (path: string) => string;
+    readonly person: (slug: string) => string;
+    readonly video: (path: string) => string;
+    readonly review: (id: string) => string;
+    readonly service: (slug: string) => string;
+    readonly customerOrganization: (slug: string) => string;
+    readonly customerPerson: (slug: string) => string;
+};
+/**
+ * Create all schema generators bound to a specific brand configuration.
+ * Returns an object with methods for each schema type.
+ */
+declare function createSchemaGenerators(brand: BrandConfig, supportedLanguages?: readonly string[]): {
+    /** Organization schema — Homepage + About page. */
+    organization(locale?: string): {
+        '@context': string;
+        '@type': string;
+        '@id': `${string}/#organization`;
+        name: string;
+        url: string;
+        logo: {
+            '@type': string;
+            url: string;
+        };
+        description: string;
+        inLanguage: string;
+        availableLanguage: string[];
+        founder: {
+            '@type': string;
+            name: string;
+        };
+        sameAs: string[];
+        contactPoint: Record<string, unknown>[];
+        areaServed: string;
+    };
+    /** WebSite schema — Homepage only (with SearchAction). */
+    website(locale?: string): {
+        '@context': string;
+        '@type': string;
+        '@id': `${string}/#website`;
+        name: string;
+        url: string;
+        description: string;
+        inLanguage: string;
+        publisher: {
+            '@type': string;
+            '@id': `${string}/#organization`;
+            name: string;
+        };
+        potentialAction: ({
+            '@type': string;
+            target: {
+                '@type': string;
+                urlTemplate: string;
+            };
+            'query-input': string;
+        } | {
+            '@type': string;
+            target: string;
+            'query-input'?: undefined;
+        })[];
+    };
+    /** WebPage schema — Every public page. Links to WebSite + Breadcrumb via @id. */
+    webPage(path: string, title: string, description: string, locale?: string, speakable?: Record<string, unknown>): {
+        speakable?: Record<string, unknown> | undefined;
+        '@context': string;
+        '@type': string;
+        '@id': string;
+        url: string;
+        name: string;
+        description: string;
+        inLanguage: string;
+        isPartOf: {
+            '@type': string;
+            '@id': `${string}/#website`;
+        };
+        breadcrumb: {
+            '@id': string;
+        };
+        potentialAction: {
+            '@type': string;
+            target: string;
+        };
+    };
+    /** SoftwareApplication schema — Platform Hub, Platform Feature, Pricing. */
+    softwareApplication(name?: string, description?: string, url?: string, locale?: string): {
+        '@context': string;
+        '@type': string;
+        '@id': `${string}/#software`;
+        name: string;
+        description: string;
+        url: string;
+        applicationCategory: string;
+        operatingSystem: string;
+        inLanguage: string;
+        availableLanguage: string[];
+        offers: {
+            '@type': string;
+            priceCurrency: string;
+            lowPrice: string;
+            highPrice: string;
+            offerCount: string;
+            priceSpecification: {
+                '@type': string;
+                description: string;
+            };
+        };
+        author: {
+            '@type': string;
+            '@id': `${string}/#organization`;
+            name: string;
+        };
+    };
+    /** Article schema — Blog posts, Comparison pages. */
+    article(meta: ArticleMeta, locale?: string): {
+        video?: Record<string, unknown> | {
+            '@id': string;
+        } | undefined;
+        about?: Record<string, unknown> | {
+            '@id': string;
+        } | undefined;
+        '@context': string;
+        '@type': string;
+        '@id': string;
+        headline: string;
+        description: string;
+        url: string;
+        image: string;
+        datePublished: string;
+        dateModified: string;
+        inLanguage: string;
+        author: {
+            '@id': string;
+            '@type'?: undefined;
+            name?: undefined;
+            url?: undefined;
+        } | {
+            '@type': string;
+            name: string;
+            url: string;
+            '@id'?: undefined;
+        };
+        publisher: {
+            '@type': string;
+            '@id': `${string}/#organization`;
+            name: string;
+            logo: {
+                '@type': string;
+                url: string;
+            };
+        };
+        isPartOf: {
+            '@type': string;
+            '@id': `${string}/#website`;
+        };
+        mainEntityOfPage: {
+            '@id': string;
+        };
+        articleSection: string;
+        keywords: string | undefined;
+        speakable: {
+            '@type': string;
+            cssSelector: string[];
+        };
+    };
+    /** FAQPage schema — FAQ hub, Solutions, Platform Features, Comparisons, Integrations. */
+    faqPage(items: FAQItem[], pageUrl: string, locale?: string): {
+        '@context': string;
+        '@type': string;
+        '@id': string;
+        inLanguage: string;
+        mainEntity: {
+            '@type': string;
+            name: string;
+            acceptedAnswer: {
+                '@type': string;
+                text: string;
+                inLanguage: string;
+            };
+        }[];
+    };
+    /** BreadcrumbList schema — Every public page. */
+    breadcrumb(items: BreadcrumbItem[], locale?: string): {
+        '@context': string;
+        '@type': string;
+        '@id': string;
+        inLanguage: string;
+        itemListElement: {
+            '@type': string;
+            position: number;
+            name: string;
+            item: string;
+        }[];
+    };
+    /** Person schema — Team page, Blog author, Comparison author. */
+    person(person: PersonMeta, locale?: string): {
+        '@context': string;
+        '@type': string;
+        '@id': string;
+        name: string;
+        jobTitle: string;
+        url: string | undefined;
+        image: string | undefined;
+        inLanguage: string;
+        worksFor: {
+            name: string;
+            '@id'?: string | undefined;
+        } | {
+            '@type': string;
+            '@id': `${string}/#organization`;
+            name: string;
+        };
+        sameAs: string[];
+    };
+    /** Review schema — Generated from testimonials. */
+    review(testimonial: TestimonialForSchema): {
+        publisher?: {
+            '@type': string;
+            name: string;
+        } | undefined;
+        itemReviewed: {
+            '@type': string;
+            '@id': `${string}/#software`;
+            name: string;
+        };
+        datePublished?: string | undefined;
+        reviewRating?: {
+            '@type': string;
+            ratingValue: string;
+            bestRating: string;
+            worstRating: string;
+        } | undefined;
+        '@context': string;
+        '@type': string;
+        '@id': string;
+        author: {
+            jobTitle?: string | undefined;
+            name: string;
+            '@id'?: string | undefined;
+            '@type': string;
+        };
+        reviewBody: string;
+    };
+    /** Product + multiple Offers schema — Pricing page. */
+    productWithOffers(plans: PricingPlan[], testimonials?: TestimonialForSchema[], locale?: string): {
+        offers: {
+            priceSpecification?: {
+                '@type': string;
+                price: string;
+                priceCurrency: string;
+                billingDuration: string;
+            } | undefined;
+            '@type': string;
+            name: string;
+            description: string;
+            price: string;
+            priceCurrency: string;
+            availability: string;
+            url: string;
+        }[];
+        aggregateRating?: {
+            '@type': string;
+            ratingValue: string;
+            ratingCount: string;
+            bestRating: string;
+            worstRating: string;
+        } | undefined;
+        '@context': string;
+        '@type': string;
+        '@id': `${string}/pricing#product`;
+        name: string;
+        description: string;
+        brand: {
+            '@type': string;
+            '@id': `${string}/#organization`;
+            name: string;
+        };
+        inLanguage: string;
+    };
+    /** VideoObject schema — Transcript detail pages. */
+    videoObject(transcript: TranscriptForSchema, locale?: string): {
+        transcript?: string | undefined;
+        inLanguage: string;
+        publisher: {
+            '@type': string;
+            '@id': `${string}/#organization`;
+            name: string;
+        };
+        thumbnailUrl?: string | undefined;
+        uploadDate?: string | undefined;
+        duration?: string | undefined;
+        embedUrl?: string | undefined;
+        contentUrl?: string | undefined;
+        '@context': string;
+        '@type': string;
+        '@id': string;
+        name: string;
+        description: string;
+    };
+    /** CustomerOrganization schema — Customer's company for Success Story pages. */
+    customerOrganization(meta: CustomerOrganizationMeta): {
+        sameAs?: string[] | undefined;
+        industry?: string | undefined;
+        description?: string | undefined;
+        logo?: string | undefined;
+        url?: string | undefined;
+        '@context': string;
+        '@type': string;
+        '@id': string;
+        name: string;
+    };
+    /** Generic VideoObject — Success story main video and shorts. */
+    videoObjectGeneric(meta: VideoObjectMeta, locale?: string): {
+        inLanguage: string;
+        publisher: {
+            '@id': `${string}/#organization`;
+        };
+        transcript?: string | undefined;
+        uploadDate?: string | undefined;
+        duration?: string | undefined;
+        thumbnailUrl?: string | undefined;
+        embedUrl?: string | undefined;
+        contentUrl?: string | undefined;
+        description?: string | undefined;
+        '@context': string;
+        '@type': string;
+        '@id': string;
+        name: string;
+    };
+    /** HowTo schema — Solution pages, tutorial blog posts. */
+    howTo(steps: HowToStep[], meta: HowToMeta, locale?: string): {
+        step: {
+            image?: string | undefined;
+            url?: string | undefined;
+            '@type': string;
+            position: number;
+            name: string;
+            text: string;
+        }[];
+        image?: string | undefined;
+        totalTime?: string | undefined;
+        '@context': string;
+        '@type': string;
+        name: string;
+        description: string;
+        inLanguage: string;
+    };
+    /** Service schema — Growth motion service offerings. */
+    service(motion: ServiceMotion, locale?: string): {
+        termsOfService: string;
+        offers?: {
+            '@type': string;
+            price: string;
+            priceCurrency: string;
+            availability: string;
+        } | undefined;
+        '@context': string;
+        '@type': string;
+        '@id': string;
+        name: string;
+        description: string;
+        url: string;
+        provider: {
+            '@type': string;
+            '@id': `${string}/#organization`;
+            name: string;
+        };
+        inLanguage: string;
+        availableLanguage: string[];
+        areaServed: string;
+    };
+    /** JobPosting schema — Career detail pages. */
+    jobPosting(job: CareerForSchema, locale?: string): {
+        inLanguage: string;
+        jobLocation: {
+            '@type': string;
+            address: {
+                '@type': string;
+                addressLocality: string;
+            };
+        };
+        '@context': string;
+        '@type': string;
+        '@id': string;
+        title: string;
+        description: string;
+        datePosted: string;
+        employmentType: string;
+        hiringOrganization: {
+            '@type': string;
+            '@id': `${string}/#organization`;
+            name: string;
+            sameAs: string;
+        };
+    } | {
+        inLanguage: string;
+        jobLocationType: string;
+        '@context': string;
+        '@type': string;
+        '@id': string;
+        title: string;
+        description: string;
+        datePosted: string;
+        employmentType: string;
+        hiringOrganization: {
+            '@type': string;
+            '@id': `${string}/#organization`;
+            name: string;
+            sameAs: string;
+        };
+    };
+    /** ItemList schema — Hub/listing pages. */
+    itemList(items: ItemForList[], listName: string): {
+        '@context': string;
+        '@type': string;
+        name: string;
+        numberOfItems: number;
+        itemListElement: {
+            image?: string | undefined;
+            description?: string | undefined;
+            '@type': string;
+            position: number;
+            name: string;
+            url: string;
+        }[];
+    };
+    /** DefinedTermSet schema — Glossary page. */
+    definedTermSet(terms: GlossaryTermForSchema[], locale?: string): {
+        '@context': string;
+        '@type': string;
+        '@id': string;
+        name: string;
+        inLanguage: string;
+        hasDefinedTerm: {
+            '@type': string;
+            name: string;
+            description: string;
+            url: string;
+        }[];
+    };
+    /** Speakable — marks content sections suitable for voice assistant reading. */
+    speakable(cssSelectors: string[]): Record<string, unknown>;
+    /** Access the entity IDs for cross-referencing */
+    entityIds: {
+        readonly organization: `${string}/#organization`;
+        readonly website: `${string}/#website`;
+        readonly software: `${string}/#software`;
+        readonly product: `${string}/pricing#product`;
+        readonly webpage: (path: string) => string;
+        readonly article: (path: string) => string;
+        readonly faq: (path: string) => string;
+        readonly breadcrumb: (path: string) => string;
+        readonly person: (slug: string) => string;
+        readonly video: (path: string) => string;
+        readonly review: (id: string) => string;
+        readonly service: (slug: string) => string;
+        readonly customerOrganization: (slug: string) => string;
+        readonly customerPerson: (slug: string) => string;
+    };
+};
+/**
+ * Compute AggregateRating from real testimonial data.
+ * Falls back to hardcoded 4.7/150 when no rated testimonials exist.
+ * Returns a fragment (no @context) — meant to be embedded in Product/SoftwareApp.
+ */
+declare function aggregateRatingFromTestimonials(testimonials: TestimonialForSchema[]): {
+    '@type': string;
+    ratingValue: string;
+    ratingCount: string;
+    bestRating: string;
+    worstRating: string;
+};
+/**
+ * Assemble multiple schema entities into a single @graph array.
+ * Strips individual `@context` from each schema — the wrapper provides it once.
+ *
+ * @example
+ * ```ts
+ * const graph = buildPageGraph(
+ *   seo.organization(),
+ *   seo.website(),
+ *   seo.webPage('/pricing', 'Pricing', '...'),
+ *   seo.breadcrumb(crumbs),
+ * );
+ * ```
+ */
+declare function buildPageGraph(...schemas: Record<string, unknown>[]): Record<string, unknown>;
+/**
+ * Build canonical URL from pathname.
+ * Removes trailing slash (except root) and query params.
+ *
+ * @param baseUrl - The site's base URL (e.g. "https://sales-mind.ai")
+ * @param pathname - The route path (e.g. "/pricing", "/blog/post/foo")
+ * @param locale - BCP-47 locale code. 'en' = no prefix (default). Others get /{locale}/ prefix.
+ */
+declare function canonicalUrl(baseUrl: string, pathname: string, locale?: string): string;
+
+/**
+ * JsonLd — Renders structured data as a `<script type="application/ld+json">` tag.
+ *
+ * Framework-agnostic: works with any React-based framework (Next.js, Vite, Remix, etc.).
+ * Safely serializes the data object and escapes `</script>` sequences.
+ *
+ * @example
+ * ```tsx
+ * import { JsonLd, buildPageGraph } from '@salesmind-ai/design-system/web';
+ *
+ * <JsonLd data={buildPageGraph(seo.organization(), seo.website())} />
+ * ```
+ */
+interface JsonLdProps {
+    /** The structured data object (schema.org format) */
+    data: Record<string, unknown>;
+    /** Optional nonce for CSP headers */
+    nonce?: string;
+}
+declare function JsonLd({ data, nonce }: JsonLdProps): react_jsx_runtime.JSX.Element;
+
+export { type ArticleMeta, type BrandConfig, type CareerForSchema, type CustomerOrganizationMeta, type FAQItem, type GlossaryTermForSchema, type HowToMeta, type HowToStep, type ItemForList, JsonLd, type JsonLdProps, type PersonMeta, type PricingPlan, type BreadcrumbItem as SeoBreadcrumbItem, type ServiceMotion, type TestimonialForSchema, type TranscriptForSchema, type VideoObjectMeta, aggregateRatingFromTestimonials, buildPageGraph, canonicalUrl, createEntityIds, createSchemaGenerators };