@flightdev/seo 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Flight Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,403 @@
+# @flight-framework/seo
+
+Native SEO and head management for Flight Framework. Zero dependencies, framework-agnostic, SSR-first.
+
+## Features
+
+- **Head Management** - Tag deduplication, ordering, and efficient rendering
+- **Meta Tags** - Basic meta, robots, verification, viewport
+- **Open Graph** - Full OG protocol support including article, product, profile
+- **Twitter Cards** - Summary, large image, app, and player cards
+- **JSON-LD** - Type-safe structured data for rich results
+- **Sitemap Generation** - XML sitemaps with image, video, and news support
+- **robots.txt** - Configurable crawler directives
+- **Framework Integrations** - React, Vue, Solid, Svelte
+
+## Installation
+
+```bash
+npm install @flight-framework/seo
+```
+
+## Quick Start
+
+### Core API
+
+```typescript
+import { createSEO, defineMeta } from '@flight-framework/seo';
+
+const seo = createSEO({
+    baseUrl: 'https://example.com',
+    titleTemplate: '%s | My Site',
+    defaultTitle: 'My Site',
+});
+
+const metadata = defineMeta({
+    title: 'About Us',
+    description: 'Learn more about our company',
+    canonical: '/about',
+    openGraph: {
+        type: 'website',
+        images: [{ url: '/og.jpg', width: 1200, height: 630 }],
+    },
+    twitter: {
+        card: 'summary_large_image',
+    },
+});
+
+const { html, tags } = seo.render(metadata);
+// Insert `html` into your document head
+```
+
+### React
+
+```tsx
+import { SEO, JsonLd } from '@flight-framework/seo/react';
+
+export default function ProductPage({ product }) {
+    return (
+        <>
+            <SEO
+                title={product.name}
+                description={product.description}
+                openGraph={{
+                    type: 'product',
+                    images: [{ url: product.image }],
+                }}
+            />
+            <JsonLd
+                data={{
+                    '@type': 'Product',
+                    name: product.name,
+                    offers: {
+                        '@type': 'Offer',
+                        price: product.price,
+                        priceCurrency: 'USD',
+                    },
+                }}
+            />
+            <main>{/* Page content */}</main>
+        </>
+    );
+}
+```
+
+### Vue
+
+```vue
+<script setup>
+import { useSEO, useJsonLd } from '@flight-framework/seo/vue';
+
+const product = defineProps(['product']);
+
+useSEO({
+    title: product.name,
+    description: product.description,
+    openGraph: {
+        type: 'product',
+        images: [{ url: product.image }],
+    },
+});
+
+useJsonLd({
+    '@type': 'Product',
+    name: product.name,
+    offers: {
+        '@type': 'Offer',
+        price: product.price,
+        priceCurrency: 'USD',
+    },
+});
+</script>
+```
+
+### Solid
+
+```tsx
+import { SEO, JsonLd } from '@flight-framework/seo/solid';
+
+export default function ProductPage(props) {
+    return (
+        <>
+            <SEO
+                title={props.product.name}
+                description={props.product.description}
+            />
+            <JsonLd data={{ '@type': 'Product', name: props.product.name }} />
+            <main>...</main>
+        </>
+    );
+}
+```
+
+### Svelte
+
+```svelte
+<script>
+    import { generateMetadataHtml, createJsonLdScript } from '@flight-framework/seo/svelte';
+
+    export let product;
+</script>
+
+<svelte:head>
+    {@html generateMetadataHtml({
+        title: product.name,
+        description: product.description,
+        openGraph: { type: 'product' }
+    })}
+    {@html createJsonLdScript({
+        '@type': 'Product',
+        name: product.name
+    })}
+</svelte:head>
+```
+
+## API Reference
+
+### createSEO(config?)
+
+Create an SEO service instance.
+
+```typescript
+const seo = createSEO({
+    baseUrl: 'https://example.com',
+    titleTemplate: '%s | My Site',
+    defaultTitle: 'My Site',
+    defaultOpenGraph: {
+        siteName: 'My Site',
+        locale: 'en_US',
+    },
+    defaultTwitter: {
+        site: '@mysite',
+    },
+});
+```
+
+### defineMeta(metadata)
+
+Type-safe metadata definition.
+
+```typescript
+const metadata = defineMeta({
+    title: 'Page Title',
+    description: 'Page description',
+    keywords: ['keyword1', 'keyword2'],
+    author: 'Author Name',
+    canonical: 'https://example.com/page',
+    robots: { index: true, follow: true },
+    openGraph: { /* ... */ },
+    twitter: { /* ... */ },
+});
+```
+
+### Metadata Types
+
+```typescript
+interface Metadata {
+    // Basic
+    title?: string;
+    titleTemplate?: string;
+    description?: string;
+    keywords?: string | string[];
+    author?: string;
+    canonical?: string;
+
+    // Robots
+    robots?: RobotsMeta | string;
+    googleBot?: RobotsMeta | string;
+
+    // Open Graph
+    openGraph?: {
+        type?: 'website' | 'article' | 'product' | ...;
+        title?: string;
+        description?: string;
+        url?: string;
+        siteName?: string;
+        locale?: string;
+        images?: OpenGraphImage[];
+        article?: OpenGraphArticle;
+        product?: OpenGraphProduct;
+    };
+
+    // Twitter
+    twitter?: {
+        card?: 'summary' | 'summary_large_image' | 'app' | 'player';
+        title?: string;
+        description?: string;
+        site?: string;
+        creator?: string;
+        image?: TwitterCardImage | string;
+    };
+}
+```
+
+## JSON-LD Structured Data
+
+```typescript
+import {
+    createJsonLd,
+    articleJsonLd,
+    productJsonLd,
+    breadcrumbJsonLd,
+    faqJsonLd,
+} from '@flight-framework/seo/json-ld';
+
+// Generic
+const jsonLd = createJsonLd({
+    '@type': 'Organization',
+    name: 'My Company',
+    url: 'https://example.com',
+});
+
+// Article
+const article = articleJsonLd({
+    headline: 'Article Title',
+    datePublished: '2026-01-10',
+    author: { '@type': 'Person', name: 'Author' },
+    publisher: { '@type': 'Organization', name: 'Publisher' },
+});
+
+// Product
+const product = productJsonLd({
+    name: 'Widget',
+    description: 'A great widget',
+    offers: {
+        '@type': 'Offer',
+        price: 9.99,
+        priceCurrency: 'USD',
+        availability: 'InStock',
+    },
+});
+
+// Breadcrumb
+const breadcrumb = breadcrumbJsonLd([
+    { name: 'Home', url: '/' },
+    { name: 'Products', url: '/products' },
+    { name: 'Widget' },
+]);
+
+// FAQ
+const faq = faqJsonLd([
+    { question: 'What is this?', answer: 'A great product.' },
+    { question: 'How much?', answer: '$9.99' },
+]);
+```
+
+## Sitemap Generation
+
+```typescript
+import { createSitemap, createSitemapIndex } from '@flight-framework/seo/sitemap';
+
+const sitemap = createSitemap({
+    baseUrl: 'https://example.com',
+    pretty: true,
+});
+
+// Add URLs
+sitemap.add('/', { priority: 1.0, changefreq: 'daily' });
+sitemap.add('/about', { priority: 0.8 });
+sitemap.add('/products/widget', {
+    lastmod: new Date(),
+    priority: 0.7,
+    images: [{ loc: '/images/widget.jpg', title: 'Widget' }],
+});
+
+// Generate XML
+const xml = sitemap.generate();
+
+// For large sites, use sitemap index
+const index = createSitemapIndex();
+index.add('https://example.com/sitemap-1.xml');
+index.add('https://example.com/sitemap-2.xml');
+const indexXml = index.generate();
+```
+
+## robots.txt Generation
+
+```typescript
+import { createRobots, standardRobots } from '@flight-framework/seo/robots';
+
+// Custom
+const robots = createRobots();
+robots.allow('*', '/');
+robots.disallow('*', '/admin');
+robots.disallow('*', '/api');
+robots.addSitemap('https://example.com/sitemap.xml');
+const txt = robots.generate();
+
+// Standard preset
+const standard = standardRobots({
+    sitemapUrl: 'https://example.com/sitemap.xml',
+    blockPaths: ['/private'],
+});
+```
+
+## SSR Integration
+
+```typescript
+// In your server entry
+import { createSEO, createHeadManager } from '@flight-framework/seo';
+
+const seo = createSEO({ baseUrl: 'https://example.com' });
+
+export function render(url: string, metadata: Metadata): string {
+    const { html: headHtml } = seo.render(metadata);
+
+    return `
+<!DOCTYPE html>
+<html>
+<head>
+    ${headHtml}
+</head>
+<body>
+    <!-- app content -->
+</body>
+</html>
+    `;
+}
+```
+
+## Dynamic Metadata
+
+```typescript
+// src/routes/products/[id].page.tsx
+import { defineMeta } from '@flight-framework/seo';
+
+export async function generateMetadata({ params }) {
+    const product = await getProduct(params.id);
+
+    return defineMeta({
+        title: product.name,
+        description: product.description,
+        openGraph: {
+            type: 'product',
+            images: [{ url: product.image }],
+        },
+    });
+}
+
+export default function ProductPage({ product }) {
+    return <main>{/* content */}</main>;
+}
+```
+
+## Best Practices
+
+1. **Always set title and description** - These are essential for SEO
+2. **Use canonical URLs** - Prevent duplicate content issues
+3. **Provide Open Graph images** - 1200x630px recommended for social sharing
+4. **Add structured data** - Improves rich results in search
+5. **Generate sitemaps** - Help search engines discover your pages
+6. **Configure robots.txt** - Control crawler access
+
+## Related
+
+- [Flight Framework](https://github.com/flight-framework/flight)
+- [Open Graph Protocol](https://ogp.me/)
+- [Twitter Cards](https://developer.twitter.com/en/docs/twitter-for-websites/cards)
+- [Schema.org](https://schema.org/)
+- [Google Rich Results](https://search.google.com/test/rich-results)
+
+## License
+
+MIT License

package/dist/index.d.ts

@@ -0,0 +1,282 @@
+import { H as HtmlTag, R as RenderedHead, M as Metadata, V as VerificationMeta, O as OpenGraphMeta, T as TwitterCardMeta, S as SEOConfig, a as SEOService } from './types-BBIMJIqz.js';
+export { A as AlternateLink, I as IconMeta, h as OpenGraphArticle, g as OpenGraphAudio, j as OpenGraphBook, e as OpenGraphImage, k as OpenGraphProduct, i as OpenGraphProfile, d as OpenGraphType, f as OpenGraphVideo, b as ResolvedMetadata, c as RobotsMeta, o as TwitterCardApp, m as TwitterCardImage, n as TwitterCardPlayer, l as TwitterCardType } from './types-BBIMJIqz.js';
+
+/**
+ * @flightdev/seo - Head Manager
+ *
+ * Server-side head management with tag deduplication,
+ * ordering, and efficient rendering.
+ *
+ * Designed for SSR-first with O(1) deduplication.
+ */
+
+/**
+ * Head Manager for SSR
+ *
+ * Manages head tags with:
+ * - O(1) deduplication using Map
+ * - Deterministic ordering
+ * - Efficient string concatenation
+ */
+declare class HeadManager {
+    private tags;
+    private frozen;
+    /**
+     * Add a tag to the head
+     */
+    addTag(tag: HtmlTag): this;
+    /**
+     * Add multiple tags
+     */
+    addTags(tags: HtmlTag[]): this;
+    /**
+     * Remove a tag by key
+     */
+    removeTag(key: string): this;
+    /**
+     * Check if a tag exists
+     */
+    hasTag(key: string): boolean;
+    /**
+     * Get a tag by key
+     */
+    getTag(key: string): HtmlTag | undefined;
+    /**
+     * Get all tags
+     */
+    getTags(): HtmlTag[];
+    /**
+     * Clear all tags
+     */
+    clear(): this;
+    /**
+     * Freeze the manager (no more modifications)
+     */
+    freeze(): this;
+    /**
+     * Check if frozen
+     */
+    isFrozen(): boolean;
+    /**
+     * Render all tags to HTML
+     */
+    render(): RenderedHead;
+}
+/**
+ * Render a single tag to HTML
+ */
+declare function renderTag(tag: HtmlTag): string;
+/**
+ * Render multiple tags to HTML
+ */
+declare function renderTags(tags: HtmlTag[]): string;
+/**
+ * Create a new HeadManager instance
+ */
+declare function createHeadManager(): HeadManager;
+/**
+ * SSR head context for passing data between components
+ */
+interface HeadContext {
+    manager: HeadManager;
+    metadata: Metadata;
+}
+/**
+ * Set the current head context (call at request start)
+ */
+declare function setHeadContext(context: HeadContext): void;
+/**
+ * Get the current head context
+ */
+declare function getHeadContext(): HeadContext | null;
+/**
+ * Clear the current head context (call at request end)
+ */
+declare function clearHeadContext(): void;
+/**
+ * Run a function with a head context
+ */
+declare function withHeadContext<T>(context: HeadContext, fn: () => T): T;
+
+/**
+ * @flightdev/seo - Meta Tag Generation
+ *
+ * Generates meta tags from Metadata configuration.
+ * Handles basic meta, robots, viewport, and verification tags.
+ */
+
+/**
+ * Generate title tag
+ */
+declare function generateTitleTag(title: string | undefined, template?: string, defaultTitle?: string): HtmlTag | null;
+/**
+ * Generate charset meta tag
+ */
+declare function generateCharsetTag(charset?: string): HtmlTag;
+/**
+ * Generate viewport meta tag
+ */
+declare function generateViewportTag(viewport: Metadata['viewport']): HtmlTag | null;
+/**
+ * Generate description meta tag
+ */
+declare function generateDescriptionTag(description: string | undefined): HtmlTag | null;
+/**
+ * Generate keywords meta tag
+ */
+declare function generateKeywordsTag(keywords: string | string[] | undefined): HtmlTag | null;
+/**
+ * Generate author meta tag
+ */
+declare function generateAuthorTag(author: string | undefined): HtmlTag | null;
+/**
+ * Generate theme-color meta tag(s)
+ */
+declare function generateThemeColorTags(themeColor: Metadata['themeColor']): HtmlTag[];
+/**
+ * Generate robots meta tag
+ */
+declare function generateRobotsTag(robots: Metadata['robots']): HtmlTag | null;
+/**
+ * Generate googlebot meta tag
+ */
+declare function generateGooglebotTag(googleBot: Metadata['googleBot']): HtmlTag | null;
+/**
+ * Generate verification meta tags
+ */
+declare function generateVerificationTags(verification: VerificationMeta | undefined): HtmlTag[];
+/**
+ * Generate canonical link tag
+ */
+declare function generateCanonicalTag(canonical: string | undefined): HtmlTag | null;
+/**
+ * Generate alternate link tags
+ */
+declare function generateAlternateTags(alternates: Metadata['alternates']): HtmlTag[];
+/**
+ * Generate all basic meta tags from Metadata
+ */
+declare function generateMetaTags(metadata: Metadata, options?: {
+    titleTemplate?: string;
+    defaultTitle?: string;
+}): HtmlTag[];
+
+/**
+ * @flightdev/seo - Open Graph Tags
+ *
+ * Generates Open Graph protocol meta tags for rich social sharing.
+ * Supports all OG types: website, article, product, profile, etc.
+ */
+
+/**
+ * Generate all Open Graph meta tags
+ */
+declare function generateOpenGraphTags(og: OpenGraphMeta | undefined): HtmlTag[];
+/**
+ * Generate minimal Open Graph tags (for fallback from metadata)
+ */
+declare function generateOpenGraphFallback(title: string | undefined, description: string | undefined, url: string | undefined): HtmlTag[];
+
+/**
+ * @flightdev/seo - Twitter Card Tags
+ *
+ * Generates Twitter Card meta tags for rich Twitter sharing.
+ * Supports summary, summary_large_image, app, and player cards.
+ */
+
+/**
+ * Generate all Twitter Card meta tags
+ */
+declare function generateTwitterTags(twitter: TwitterCardMeta | undefined): HtmlTag[];
+/**
+ * Generate minimal Twitter Card tags (for fallback)
+ */
+declare function generateTwitterFallback(title: string | undefined, description: string | undefined, image: string | undefined, cardType?: TwitterCardMeta['card']): HtmlTag[];
+
+/**
+ * @flightdev/seo
+ *
+ * Native SEO and head management for Flight Framework.
+ * Zero dependencies, framework-agnostic, SSR-first.
+ *
+ * Features:
+ * - Head management with deduplication
+ * - Meta tags (basic, robots, verification)
+ * - Open Graph protocol
+ * - Twitter Cards
+ * - JSON-LD structured data
+ * - Sitemap generation
+ * - robots.txt generation
+ *
+ * @example
+ * ```typescript
+ * import { createSEO, defineMeta } from '@flightdev/seo';
+ *
+ * const seo = createSEO({ baseUrl: 'https://example.com' });
+ *
+ * const metadata = defineMeta({
+ *   title: 'My Page',
+ *   description: 'Page description',
+ *   openGraph: {
+ *     type: 'website',
+ *     images: [{ url: '/og.jpg', width: 1200, height: 630 }],
+ *   },
+ * });
+ *
+ * const { html } = seo.render(metadata);
+ * ```
+ */
+
+/**
+ * Create an SEO service
+ *
+ * @example
+ * ```typescript
+ * const seo = createSEO({
+ *   baseUrl: 'https://example.com',
+ *   titleTemplate: '%s | My Site',
+ *   defaultTitle: 'My Site',
+ * });
+ *
+ * const { html } = seo.render({
+ *   title: 'About Us',
+ *   description: 'Learn more about us',
+ * });
+ * ```
+ */
+declare function createSEO(config?: SEOConfig): SEOService;
+/**
+ * Define metadata with type safety
+ *
+ * @example
+ * ```typescript
+ * const metadata = defineMeta({
+ *   title: 'Product Name',
+ *   description: 'Product description',
+ *   openGraph: {
+ *     type: 'product',
+ *     images: [{ url: '/product.jpg' }],
+ *   },
+ * });
+ * ```
+ */
+declare function defineMeta(metadata: Metadata): Metadata;
+/**
+ * Merge parent and child metadata
+ * Child values override parent values
+ * Arrays are replaced, not merged
+ */
+declare function mergeMetadata(parent: Metadata, child: Metadata): Metadata;
+/**
+ * Type for async metadata generation function
+ */
+type GenerateMetadataFn<TParams = Record<string, string>> = (context: {
+    params: TParams;
+    searchParams?: Record<string, string | string[]>;
+}) => Metadata | Promise<Metadata>;
+/**
+ * Version constant
+ */
+declare const VERSION = "0.1.0";
+
+export { type GenerateMetadataFn, type HeadContext, HeadManager, HtmlTag, Metadata, OpenGraphMeta, RenderedHead, SEOConfig, SEOService, TwitterCardMeta, VERSION, VerificationMeta, clearHeadContext, createHeadManager, createSEO, defineMeta, generateAlternateTags, generateAuthorTag, generateCanonicalTag, generateCharsetTag, generateDescriptionTag, generateGooglebotTag, generateKeywordsTag, generateMetaTags, generateOpenGraphFallback, generateOpenGraphTags, generateRobotsTag, generateThemeColorTags, generateTitleTag, generateTwitterFallback, generateTwitterTags, generateVerificationTags, generateViewportTag, getHeadContext, mergeMetadata, renderTag, renderTags, setHeadContext, withHeadContext };