@geenius/seo 0.1.0

package/packages/shared/src/__tests__/seo.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from 'vitest'
+import { buildTitle, truncateDescription, articleSchema } from '../index'
+
+describe('buildTitle', () => {
+  it('joins page title and site name with separator', () => {
+    expect(buildTitle('Home', 'Geenius')).toBe('Home | Geenius')
+  })
+
+  it('allows custom separator', () => {
+    expect(buildTitle('Blog', 'Geenius', ' — ')).toBe('Blog — Geenius')
+  })
+
+  it('handles empty page title', () => {
+    expect(buildTitle('', 'Geenius')).toBe(' | Geenius')
+  })
+})
+
+describe('truncateDescription', () => {
+  it('returns short descriptions unchanged', () => {
+    const short = 'A brief description.'
+    expect(truncateDescription(short)).toBe(short)
+  })
+
+  it('truncates to 160 chars by default', () => {
+    const long = 'x'.repeat(200)
+    const result = truncateDescription(long)
+    expect(result.length).toBe(160)
+    expect(result.endsWith('...')).toBe(true)
+  })
+
+  it('respects custom max length', () => {
+    const text = 'x'.repeat(100)
+    const result = truncateDescription(text, 50)
+    expect(result.length).toBe(50)
+    expect(result.endsWith('...')).toBe(true)
+  })
+
+  it('returns exact-length descriptions unchanged', () => {
+    const exact = 'x'.repeat(160)
+    expect(truncateDescription(exact)).toBe(exact)
+  })
+})
+
+describe('articleSchema', () => {
+  it('generates valid JSON-LD structure', () => {
+    const schema = articleSchema({
+      title: 'Test Article',
+      description: 'A test article',
+      author: 'Author',
+      datePublished: '2024-01-01',
+      url: 'https://example.com/test',
+    })
+    expect(schema['@context']).toBe('https://schema.org')
+    expect(schema['@type']).toBe('Article')
+    expect(schema.title).toBe('Test Article')
+    expect(schema.author).toBe('Author')
+  })
+
+  it('includes optional image when provided', () => {
+    const schema = articleSchema({
+      title: 'Test',
+      description: 'Desc',
+      author: 'Author',
+      datePublished: '2024-01-01',
+      url: 'https://example.com',
+      image: 'https://example.com/img.jpg',
+    })
+    expect(schema.image).toBe('https://example.com/img.jpg')
+  })
+})

package/packages/shared/src/config.ts

@@ -0,0 +1,297 @@
+/**
+ * SEO configuration and utilities
+ */
+
+import type { SEOConfig, SEOMeta, OGMeta, TwitterMeta } from './index'
+
+/**
+ * SEO configuration builder for type-safe setup
+ *
+ * @example
+ * ```ts
+ * const seoConfig = createSEOConfig()
+ *   .withSiteName('My Site')
+ *   .withSiteUrl('https://example.com')
+ *   .withDefaultImage('https://example.com/og-image.jpg')
+ *   .withTwitterHandle('@mysite')
+ * ```
+ */
+export class SEOConfigBuilder {
+  private config: SEOConfig = {
+    siteName: '',
+    siteUrl: '',
+  }
+
+  /**
+   * Sets the site name
+   */
+  withSiteName(name: string): this {
+    this.config.siteName = name
+    return this
+  }
+
+  /**
+   * Sets the site URL
+   */
+  withSiteUrl(url: string): this {
+    this.config.siteUrl = url
+    return this
+  }
+
+  /**
+   * Sets default OG image
+   */
+  withDefaultImage(url: string): this {
+    this.config.defaultImage = url
+    return this
+  }
+
+  /**
+   * Sets Twitter handle
+   */
+  withTwitterHandle(handle: string): this {
+    this.config.twitterHandle = handle
+    return this
+  }
+
+  /**
+   * Sets default locale
+   */
+  withLocale(locale: string): this {
+    this.config.locale = locale
+    return this
+  }
+
+  /**
+   * Sets Google Analytics ID
+   */
+  withGoogleAnalyticsId(id: string): this {
+    this.config.googleAnalyticsId = id
+    return this
+  }
+
+  /**
+   * Sets Google Tag Manager ID
+   */
+  withGoogleTagManagerId(id: string): this {
+    this.config.googleTagManagerId = id
+    return this
+  }
+
+  /**
+   * Builds the configuration
+   */
+  build(): SEOConfig {
+    if (!this.config.siteName || !this.config.siteUrl) {
+      throw new Error('SEO config requires siteName and siteUrl')
+    }
+    return this.config
+  }
+}
+
+/**
+ * Creates a new SEO configuration builder
+ */
+export function createSEOConfig(): SEOConfigBuilder {
+  return new SEOConfigBuilder()
+}
+
+/**
+ * Meta tags builder for individual pages
+ *
+ * @example
+ * ```ts
+ * const meta = createPageMeta({
+ *   title: 'Home',
+ *   description: 'Welcome to my site'
+ * })
+ *   .withKeywords(['web', 'development'])
+ *   .withImage('https://example.com/image.jpg')
+ * ```
+ */
+export class PageMetaBuilder {
+  private meta: Partial<SEOMeta> = {
+    og: {} as OGMeta,
+    twitter: {} as TwitterMeta,
+  }
+
+  constructor(private config: SEOConfig, title: string, description: string) {
+    this.meta.title = title
+    this.meta.description = description
+    this.meta.og = {
+      title,
+      description,
+      type: 'website',
+      url: config.siteUrl,
+      siteName: config.siteName,
+      image: config.defaultImage,
+    }
+    this.meta.twitter = {
+      card: 'summary_large_image',
+      title,
+      description,
+      image: config.defaultImage,
+      creator: config.twitterHandle,
+    }
+  }
+
+  /**
+   * Adds keywords
+   */
+  withKeywords(keywords: string[]): this {
+    this.meta.keywords = keywords
+    return this
+  }
+
+  /**
+   * Sets canonical URL
+   */
+  withCanonical(url: string): this {
+    this.meta.canonical = url
+    return this
+  }
+
+  /**
+   * Sets OG image
+   */
+  withImage(url: string, alt?: string): this {
+    if (this.meta.og) {
+      this.meta.og.image = url
+      if (alt) this.meta.og.imageAlt = alt
+    }
+    if (this.meta.twitter) {
+      this.meta.twitter.image = url
+    }
+    return this
+  }
+
+  /**
+   * Sets OG type
+   */
+  withType(type: 'website' | 'article' | 'product'): this {
+    if (this.meta.og) {
+      this.meta.og.type = type
+    }
+    return this
+  }
+
+  /**
+   * Adds JSON-LD schema
+   */
+  withJsonLd(schema: Record<string, unknown>): this {
+    if (!this.meta.jsonLd) {
+      this.meta.jsonLd = []
+    }
+    this.meta.jsonLd.push(schema)
+    return this
+  }
+
+  /**
+   * Sets robots meta
+   */
+  withRobots(robots: string): this {
+    this.meta.robots = robots
+    return this
+  }
+
+  /**
+   * Adds alternate language links
+   */
+  withAlternates(alternates: Record<string, string>): this {
+    this.meta.alternates = alternates
+    return this
+  }
+
+  /**
+   * Builds the meta tags
+   */
+  build(): SEOMeta {
+    return {
+      title: this.meta.title || '',
+      description: this.meta.description || '',
+      keywords: this.meta.keywords || [],
+      canonical: this.meta.canonical,
+      og: this.meta.og || ({ type: 'website', title: '', description: '', url: '' } as OGMeta),
+      twitter: this.meta.twitter || ({ card: 'summary', title: '', description: '' } as TwitterMeta),
+      robots: this.meta.robots,
+      alternates: this.meta.alternates,
+      jsonLd: this.meta.jsonLd,
+    }
+  }
+}
+
+/**
+ * Creates page-specific meta tags
+ */
+export function createPageMeta(config: SEOConfig, title: string, description: string): PageMetaBuilder {
+  return new PageMetaBuilder(config, title, description)
+}
+
+/**
+ * Validates SEO meta configuration
+ */
+export function validateSEOMeta(meta: SEOMeta): { valid: boolean; errors: string[] } {
+  const errors: string[] = []
+
+  if (!meta.title || meta.title.length === 0) {
+    errors.push('Title is required')
+  }
+  if (meta.title && meta.title.length > 60) {
+    errors.push('Title should be under 60 characters')
+  }
+
+  if (!meta.description || meta.description.length === 0) {
+    errors.push('Description is required')
+  }
+  if (meta.description && meta.description.length > 160) {
+    errors.push('Description should be under 160 characters')
+  }
+
+  if (!meta.og?.image && !meta.twitter?.image) {
+    errors.push('At least one image (OG or Twitter) is recommended')
+  }
+
+  if (!meta.keywords || meta.keywords.length === 0) {
+    errors.push('At least one keyword is recommended')
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  }
+}
+
+/**
+ * Presets for common SEO configurations
+ */
+export const seoPresets = {
+  /**
+   * Blog article preset
+   */
+  article: (config: SEOConfig): Partial<SEOMeta> => ({
+    og: { type: 'article', ...config },
+    robots: 'index, follow',
+  }),
+
+  /**
+   * E-commerce product preset
+   */
+  product: (config: SEOConfig): Partial<SEOMeta> => ({
+    og: { type: 'product', ...config },
+    robots: 'index, follow',
+  }),
+
+  /**
+   * Service/company page preset
+   */
+  business: (config: SEOConfig): Partial<SEOMeta> => ({
+    robots: 'index, follow',
+  }),
+
+  /**
+   * Private/unlisted page preset
+   */
+  private: (): Partial<SEOMeta> => ({
+    robots: 'noindex, nofollow',
+  }),
+}

package/packages/shared/src/index.ts

@@ -0,0 +1,207 @@
+// ─── SEO Metadata Interfaces ─────────────────────────────────────
+
+export interface OGMeta {
+  title: string
+  description: string
+  image?: string
+  imageAlt?: string
+  type: 'website' | 'article' | 'product'
+  url: string
+  siteName?: string
+}
+
+export interface TwitterMeta {
+  card: 'summary' | 'summary_large_image'
+  title: string
+  description: string
+  image?: string
+  creator?: string
+}
+
+export interface SEOMeta {
+  title: string
+  description: string
+  keywords: string[]
+  canonical?: string
+  og: OGMeta
+  twitter: TwitterMeta
+  robots?: string
+  alternates?: Record<string, string>
+  jsonLd?: Record<string, unknown>[]
+}
+
+export interface SitemapEntry {
+  url: string
+  lastmod?: string
+  changefreq?: string
+  priority?: number
+}
+
+export interface RobotsTxt {
+  allow: string[]
+  disallow: string[]
+  sitemap?: string
+}
+
+export interface SEOConfig {
+  siteName: string
+  siteUrl: string
+  defaultImage?: string
+  twitterHandle?: string
+  locale?: string
+  googleAnalyticsId?: string
+  googleTagManagerId?: string
+}
+
+// ─── Utility Functions ──────────────────────────────────────────
+
+export function buildTitle(pageTitle: string, siteName: string, sep = ' | '): string {
+  return `${pageTitle}${sep}${siteName}`
+}
+
+export function truncateDescription(desc: string, max = 160): string {
+  if (desc.length <= max) return desc
+  return desc.slice(0, max - 3) + '...'
+}
+
+// ─── JSON-LD Schema Builders ────────────────────────────────────
+
+export function articleSchema(data: {
+  title: string
+  description: string
+  author: string
+  datePublished: string
+  url: string
+  image?: string
+}): Record<string, unknown> {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'Article',
+    ...data,
+  }
+}
+
+export function productSchema(data: {
+  name: string
+  description: string
+  price: number
+  currency: string
+  url: string
+  image?: string
+}): Record<string, unknown> {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'Product',
+    name: data.name,
+    description: data.description,
+    url: data.url,
+    image: data.image,
+    offers: {
+      '@type': 'Offer',
+      price: data.price,
+      priceCurrency: data.currency,
+    },
+  }
+}
+
+export function orgSchema(data: {
+  name: string
+  url: string
+  logo?: string
+  sameAs?: string[]
+}): Record<string, unknown> {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'Organization',
+    ...data,
+  }
+}
+
+export function breadcrumbSchema(items: {
+  name: string
+  url: string
+}[]): Record<string, unknown> {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BreadcrumbList',
+    itemListElement: items.map((item, i) => ({
+      '@type': 'ListItem',
+      position: i + 1,
+      name: item.name,
+      item: item.url,
+    })),
+  }
+}
+
+export function faqSchema(items: {
+  question: string
+  answer: string
+}[]): Record<string, unknown> {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'FAQPage',
+    mainEntity: items.map((q) => ({
+      '@type': 'Question',
+      name: q.question,
+      acceptedAnswer: {
+        '@type': 'Answer',
+        text: q.answer,
+      },
+    })),
+  }
+}
+
+export function buildCanonical(path: string, baseUrl: string): string {
+  return `${baseUrl.replace(/\/$/, '')}/${path.replace(/^\//, '')}`
+}
+
+export function buildAlternates(
+  locales: string[],
+  baseUrl: string,
+  path: string,
+): Record<string, string> {
+  return Object.fromEntries(locales.map((l) => [l, `${baseUrl}/${l}${path}`]))
+}
+
+export function generateRobotsTxt(config: RobotsTxt): string {
+  const lines = ['User-agent: *']
+  config.allow.forEach((p) => lines.push(`Allow: ${p}`))
+  config.disallow.forEach((p) => lines.push(`Disallow: ${p}`))
+  if (config.sitemap) lines.push(`Sitemap: ${config.sitemap}`)
+  return lines.join('\n')
+}
+
+export function generateSitemapXml(entries: SitemapEntry[]): string {
+  const urls = entries
+    .map(
+      (e) =>
+        `  <url>\n    <loc>${e.url}</loc>${e.lastmod ? `\n    <lastmod>${e.lastmod}</lastmod>` : ''}${e.changefreq ? `\n    <changefreq>${e.changefreq}</changefreq>` : ''}${e.priority !== undefined ? `\n    <priority>${e.priority}</priority>` : ''}\n  </url>`,
+    )
+    .join('\n')
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls}\n</urlset>`
+}
+
+export function estimateReadingTime(content: string): number {
+  return Math.ceil(content.split(/\s+/).length / 200)
+}
+
+export function calcSEOScore(meta: SEOMeta): {
+  score: number
+  issues: string[]
+} {
+  const issues: string[] = []
+
+  if (!meta.title || meta.title.length < 10) issues.push('Title too short (< 10 chars)')
+  if (meta.title && meta.title.length > 60) issues.push('Title too long (> 60 chars)')
+  if (!meta.description || meta.description.length < 50)
+    issues.push('Description too short (< 50 chars)')
+  if (meta.description && meta.description.length > 160)
+    issues.push('Description too long (> 160 chars)')
+  if (!meta.keywords || meta.keywords.length === 0) issues.push('No keywords specified')
+  if (!meta.canonical) issues.push('No canonical URL')
+  if (!meta.og.image) issues.push('No OG image')
+  if (!meta.twitter.image) issues.push('No Twitter image')
+
+  const score = Math.max(0, 100 - issues.length * 12)
+  return { score, issues }
+}

package/packages/shared/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler"
+  },
+  "include": [
+    "src"
+  ]
+}

package/packages/shared/tsup.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+    entry: { index: 'src/index.ts' },
+    outDir: 'dist',
+    format: ['esm'],
+    dts: true,
+    sourcemap: true,
+    clean: true,
+    treeshake: true,
+})

package/packages/shared/vitest.config.ts

@@ -0,0 +1,4 @@
+import { defineConfig } from 'vitest/config'
+export default defineConfig({
+  test: { globals: true, environment: 'node' },
+})

package/packages/solidjs/README.md

@@ -0,0 +1 @@
+# ✦ @geenius-seo/solidjs\n\n> Geenius Seo — SolidJS components & primitives\n\n---\n\n## Overview\nBuilt with Steve Jobs-level minimalism and Jony Ive-level craftsmanship, this package is designed to deliver unparalleled developer experience (DX) and rock-solid performance.\n\n## Installation\n\n```bash\npnpm add @geenius-seo/solidjs\n```\n\n## Usage\n\n```typescript\nimport { init } from '@geenius-seo/solidjs';\n\n// Initialize the module with absolute precision\ninit({\n  mode: 'premium',\n});\n```\n\n## Architecture\n- **Zero-config**: It just works.\n- **Strictly Typed**: Fully written in TypeScript for flawless IntelliSense.\n- **Framework Agnostic**: seamlessly integrates into the Geenius ecosystem.\n\n---\n\n*Designed by Antigravity HQ*\n

package/packages/solidjs/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@geenius-seo/solidjs",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Geenius Seo — SolidJS components & primitives",
+  "author": "Antigravity HQ",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "pnpm clean && pnpm build"
+  },
+  "dependencies": {
+    "@geenius-seo/shared": "workspace:*"
+  },
+  "devDependencies": {
+    "solid-js": "^1.9.0",
+    "tsup": "^8.5.1",
+    "typescript": "~6.0.2"
+  },
+  "peerDependencies": {
+    "solid-js": "^1.8.0 || ^1.9.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/packages/solidjs/src/components/ArticleJsonLd.tsx

@@ -0,0 +1,35 @@
+import { createEffect } from 'solid-js'
+import { articleSchema } from '@geenius-seo/shared'
+
+interface ArticleJsonLdProps {
+  title: string
+  description: string
+  author: string
+  datePublished: string
+  url: string
+  image?: string
+}
+
+export function ArticleJsonLd(props: ArticleJsonLdProps) {
+  createEffect(() => {
+    const script = document.createElement('script')
+    script.type = 'application/ld+json'
+    script.textContent = JSON.stringify(
+      articleSchema({
+        title: props.title,
+        description: props.description,
+        author: props.author,
+        datePublished: props.datePublished,
+        url: props.url,
+        image: props.image,
+      }),
+    )
+    document.head.appendChild(script)
+
+    return () => {
+      document.head.removeChild(script)
+    }
+  })
+
+  return null
+}