@coherent.js/seo 1.0.0-beta.5 → 1.0.0-beta.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coherent.js/seo",
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0-beta.6",
   "description": "SEO utilities for Coherent.js applications",
   "type": "module",
   "main": "./dist/index.js",
@@ -20,7 +20,7 @@
   "author": "Coherent.js Team",
   "license": "MIT",
   "peerDependencies": {
-    "@coherent.js/core": "1.0.0-beta.5"
+    "@coherent.js/core": "1.0.0-beta.6"
   },
   "repository": {
     "type": "git",

package/types/index.d.ts

@@ -3,8 +3,164 @@
  * @module @coherent.js/seo
  */
 
-// ===== Meta Builder Types =====
+import type { CoherentNode } from '@coherent.js/core';
 
+// ============================================================================
+// Meta Tag Types
+// ============================================================================
+
+/**
+ * Generic meta tag definition
+ */
+export interface MetaTag {
+  /** Meta name attribute (for standard meta tags) */
+  name?: string;
+  /** Meta property attribute (for Open Graph, etc.) */
+  property?: string;
+  /** Meta content value */
+  content: string;
+  /** HTTP-equiv attribute */
+  httpEquiv?: string;
+}
+
+/**
+ * Open Graph image configuration
+ */
+export interface OpenGraphImage {
+  /** Image URL */
+  url: string;
+  /** Image width in pixels */
+  width?: number;
+  /** Image height in pixels */
+  height?: number;
+  /** Image alt text */
+  alt?: string;
+  /** Image MIME type */
+  type?: string;
+}
+
+/**
+ * Open Graph meta configuration
+ */
+export interface OpenGraphMeta {
+  /** Page title */
+  title: string;
+  /** Page description */
+  description?: string;
+  /** Content type */
+  type?: 'website' | 'article' | 'book' | 'profile' | 'video.movie' | 'video.episode' | 'music.song' | 'music.album';
+  /** Page URL */
+  url?: string;
+  /** Image(s) for sharing */
+  image?: string | OpenGraphImage | (string | OpenGraphImage)[];
+  /** Site name */
+  siteName?: string;
+  /** Locale (e.g., 'en_US') */
+  locale?: string;
+  /** Alternate locales */
+  alternateLocales?: string[];
+  /** Audio URL */
+  audio?: string;
+  /** Video URL */
+  video?: string;
+  /** Determiner (a, an, the, auto, or empty) */
+  determiner?: 'a' | 'an' | 'the' | 'auto' | '';
+}
+
+/**
+ * Twitter Card meta configuration
+ */
+export interface TwitterMeta {
+  /** Card type */
+  card?: 'summary' | 'summary_large_image' | 'app' | 'player';
+  /** Twitter @username of website */
+  site?: string;
+  /** Twitter @username of content creator */
+  creator?: string;
+  /** Card title (defaults to og:title) */
+  title?: string;
+  /** Card description (defaults to og:description) */
+  description?: string;
+  /** Card image (defaults to og:image) */
+  image?: string;
+  /** Image alt text */
+  imageAlt?: string;
+  /** App ID for app cards */
+  appIdIphone?: string;
+  /** App ID for iPad */
+  appIdIpad?: string;
+  /** App ID for Google Play */
+  appIdGooglePlay?: string;
+}
+
+/**
+ * Comprehensive SEO configuration
+ */
+export interface SEOConfig {
+  /** Page title */
+  title: string;
+  /** Title template (e.g., '%s | My Site') */
+  titleTemplate?: string;
+  /** Page description */
+  description?: string;
+  /** Canonical URL */
+  canonical?: string;
+  /** Robots directives (e.g., 'index, follow') */
+  robots?: string;
+  /** Additional meta tags */
+  meta?: MetaTag[];
+  /** Open Graph configuration */
+  openGraph?: OpenGraphMeta;
+  /** Twitter Card configuration */
+  twitter?: TwitterMeta;
+  /** JSON-LD structured data */
+  jsonLd?: Record<string, unknown> | Record<string, unknown>[];
+  /** Keywords (comma-separated or array) */
+  keywords?: string | string[];
+  /** Author name */
+  author?: string;
+  /** Viewport settings */
+  viewport?: string;
+  /** Character set */
+  charset?: string;
+  /** Language code */
+  language?: string;
+  /** Theme color */
+  themeColor?: string;
+}
+
+// ============================================================================
+// SEO Generation Functions
+// ============================================================================
+
+/**
+ * Generate meta tags from SEO configuration
+ * @returns Array of meta element nodes
+ */
+export function generateMeta(config: SEOConfig): CoherentNode[];
+
+/**
+ * Generate JSON-LD script tag from data
+ */
+export function generateJsonLd(data: Record<string, unknown>): CoherentNode;
+
+/**
+ * Create a reusable SEO component from configuration
+ */
+export function createSEOComponent(config: SEOConfig): () => CoherentNode;
+
+/**
+ * Merge multiple SEO configurations (later configs override earlier)
+ */
+export function mergeSEOConfig(...configs: Partial<SEOConfig>[]): SEOConfig;
+
+// ============================================================================
+// Meta Builder
+// ============================================================================
+
+/**
+ * All meta tags in a flat structure
+ */
 export interface MetaTags {
   title?: string;
   description?: string;
@@ -32,41 +188,88 @@ export interface MetaTags {
   twitterDescription?: string;
   twitterImage?: string;
   // Custom meta tags
-  [key: string]: any;
+  [key: string]: unknown;
 }
 
+/**
+ * Fluent builder for meta tags
+ */
 export class MetaBuilder {
   constructor(tags?: MetaTags);
+
+  /** Set page title */
   setTitle(title: string): this;
+
+  /** Set page description */
   setDescription(description: string): this;
+
+  /** Set keywords */
   setKeywords(keywords: string | string[]): this;
+
+  /** Set author */
   setAuthor(author: string): this;
+
+  /** Set robots directive */
   setRobots(robots: string): this;
+
+  /** Set canonical URL */
   setCanonical(url: string): this;
+
+  /** Set viewport */
   setViewport(viewport: string): this;
-  setOpenGraph(tags: Partial<MetaTags>): this;
-  setTwitterCard(tags: Partial<MetaTags>): this;
+
+  /** Set Open Graph properties */
+  setOpenGraph(tags: Partial<OpenGraphMeta>): this;
+
+  /** Set Twitter Card properties */
+  setTwitterCard(tags: Partial<TwitterMeta>): this;
+
+  /** Add a custom meta tag */
   addCustomTag(name: string, content: string, type?: 'name' | 'property'): this;
-  build(): object;
-  render(): object;
+
+  /** Build as CoherentNode */
+  build(): CoherentNode;
+
+  /** Alias for build */
+  render(): CoherentNode;
+
+  /** Convert to HTML string */
   toHTML(): string;
 }
 
+/**
+ * Create a MetaBuilder instance
+ */
 export function createMetaBuilder(tags?: MetaTags): MetaBuilder;
-export function generateMeta(tags: MetaTags): object;
 
-// ===== Sitemap Generator Types =====
+/**
+ * Generate meta nodes from flat tags
+ */
+export function generateMeta(tags: MetaTags): CoherentNode;
 
+// ============================================================================
+// Sitemap Generator
+// ============================================================================
+
+/**
+ * Sitemap entry configuration
+ */
 export interface SitemapEntry {
+  /** Page URL */
   url: string;
+  /** Last modification date */
   lastmod?: string | Date;
+  /** Change frequency */
   changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+  /** Priority (0.0 to 1.0) */
   priority?: number;
+  /** Image entries */
   images?: Array<{
     loc: string;
     title?: string;
     caption?: string;
   }>;
+  /** Video entries */
   videos?: Array<{
     thumbnail_loc: string;
     title: string;
@@ -74,30 +277,69 @@ export interface SitemapEntry {
     content_loc?: string;
     player_loc?: string;
   }>;
+  /** Alternate language versions */
+  alternates?: Array<{
+    hreflang: string;
+    href: string;
+  }>;
 }
 
+/**
+ * Sitemap generator options
+ */
 export interface SitemapOptions {
+  /** Site hostname (e.g., 'https://example.com') */
   hostname: string;
+  /** Cache time in milliseconds */
   cacheTime?: number;
+  /** XML namespaces */
   xmlNs?: Record<string, string>;
+  /** XSL stylesheet URL */
   xslUrl?: string;
 }
 
+/**
+ * Sitemap generator class
+ */
 export class SitemapGenerator {
   constructor(options: SitemapOptions);
+
+  /** Add a URL entry */
   addUrl(entry: SitemapEntry): this;
+
+  /** Add multiple URL entries */
   addUrls(entries: SitemapEntry[]): this;
+
+  /** Remove a URL entry */
   removeUrl(url: string): this;
+
+  /** Generate sitemap XML string */
   generate(): string;
+
+  /** Alias for generate */
   toXML(): string;
+
+  /** Export entries as JSON */
   toJSON(): SitemapEntry[];
 }
 
+/**
+ * Create a sitemap generator
+ */
 export function createSitemapGenerator(options: SitemapOptions): SitemapGenerator;
+
+/**
+ * Generate sitemap XML from entries
+ */
 export function generateSitemap(entries: SitemapEntry[], options: SitemapOptions): string;
 
-// ===== Structured Data Types =====
+// ============================================================================
+// Structured Data (JSON-LD)
+// ============================================================================
 
+/**
+ * Supported structured data types
+ */
 export type StructuredDataType =
   | 'Article'
   | 'BlogPosting'
@@ -115,30 +357,71 @@ export type StructuredDataType =
   | 'FAQPage'
   | 'HowTo'
   | 'VideoObject'
-  | 'ImageObject';
+  | 'ImageObject'
+  | 'SoftwareApplication'
+  | 'Course'
+  | 'JobPosting';
 
+/**
+ * Structured data object
+ */
 export interface StructuredData {
   '@context': string;
   '@type': StructuredDataType | StructuredDataType[];
-  [key: string]: any;
+  [key: string]: unknown;
 }
 
+/**
+ * Fluent builder for structured data
+ */
 export class StructuredDataBuilder {
   constructor(type: StructuredDataType);
+
+  /** Change the schema type */
   setType(type: StructuredDataType): this;
-  setProperty(key: string, value: any): this;
-  setProperties(properties: Record<string, any>): this;
-  addToArray(key: string, value: any): this;
+
+  /** Set a single property */
+  setProperty(key: string, value: unknown): this;
+
+  /** Set multiple properties */
+  setProperties(properties: Record<string, unknown>): this;
+
+  /** Add value to an array property */
+  addToArray(key: string, value: unknown): this;
+
+  /** Build the structured data object */
   build(): StructuredData;
+
+  /** Convert to JSON string */
   toJSON(): string;
-  toJSONLD(): object;
+
+  /** Build as JSON-LD script node */
+  toJSONLD(): CoherentNode;
 }
 
-export function createStructuredData(type: StructuredDataType, properties?: Record<string, any>): StructuredDataBuilder;
-export function generateStructuredData(type: StructuredDataType, properties: Record<string, any>): StructuredData;
+/**
+ * Create a structured data builder
+ */
+export function createStructuredData(
+  type: StructuredDataType,
+  properties?: Record<string, unknown>
+): StructuredDataBuilder;
+
+/**
+ * Generate structured data object
+ */
+export function generateStructuredData(
+  type: StructuredDataType,
+  properties: Record<string, unknown>
+): StructuredData;
 
-// Helper types for common structured data
+// ============================================================================
+// Common Structured Data Types
+// ============================================================================
 
+/**
+ * Article structured data
+ */
 export interface ArticleData {
   headline: string;
   image: string | string[];
@@ -160,6 +443,9 @@ export interface ArticleData {
   mainEntityOfPage?: string;
 }
 
+/**
+ * Product structured data
+ */
 export interface ProductData {
   name: string;
   image: string | string[];
@@ -182,6 +468,9 @@ export interface ProductData {
   };
 }
 
+/**
+ * Breadcrumb structured data
+ */
 export interface BreadcrumbData {
   itemListElement: Array<{
     '@type': 'ListItem';
@@ -190,3 +479,33 @@ export interface BreadcrumbData {
     item?: string;
   }>;
 }
+
+/**
+ * Organization structured data
+ */
+export interface OrganizationData {
+  name: string;
+  url?: string;
+  logo?: string;
+  description?: string;
+  sameAs?: string[];
+  contactPoint?: {
+    '@type': 'ContactPoint';
+    telephone: string;
+    contactType: string;
+  };
+}
+
+/**
+ * FAQ Page structured data
+ */
+export interface FAQPageData {
+  mainEntity: Array<{
+    '@type': 'Question';
+    name: string;
+    acceptedAnswer: {
+      '@type': 'Answer';
+      text: string;
+    };
+  }>;
+}