@masters-ws/react-seo 1.0.0 → 1.2.0

package/README.md

@@ -1,138 +1,189 @@
 # @masters-ws/react-seo
 
-Professional high-performance SEO package for React and Next.js. **1:1 Feature Parity with the powerful Laravel SEO package.** Designed for high-traffic news sites, e-marketplaces, and professional blog platforms where speed and indexing are critical.
+Professional high-performance SEO package for React and Next.js. **Zero-dependency core** for Next.js App Router + optional Helmet components for universal React support.
 
 ## Key Features
 
-- ✅ **Hybrid Implementation** - Works with `react-helmet-async` for Client/Pages Router and native `Metadata API` for Next.js App Router.
-- ✅ **Full Metadata Support** - Title, Description, Keywords, Robots, Canonical.
-- ✅ **Intelligent Pagination** - Automatic `rel="prev"` and `rel="next"` handling with clean URL logic.
-- ✅ **Advanced Social Meta** - OpenGraph (Facebook/LinkedIn), Twitter Cards, and WhatsApp/Telegram optimization.
-- ✅ **JSON-LD Schema.org (25+ Types)** - Dedicated components for `NewsArticle`, `Product`, `FAQPage`, `BreadcrumbList`, `Organization`, `WebSite`, `Event`, `HowTo`, `Recipe`, etc.
-- ✅ **Performance & Security** - Support for DNS Prefetch, Preconnect, Preload, and CSP.
-- ✅ **Multilingual Support** - Easy `hreflang` management.
-- ✅ **Mobile Optimized** - Theme color, Apple mobile web app capability, and manifest support.
-- ✅ **Analytics Integration** - Built-in hooks for GA4, GTM, and Facebook Pixel.
+- ✅ **Zero-Dependency Core** - Pure functions for Next.js (no react-helmet-async needed!)
+- ✅ **Hybrid Architecture** - Use functions OR components based on your needs
+- ✅ **Full Metadata Support** - Title, Description, Keywords, Robots, Canonical
+- ✅ **Intelligent Pagination** - Automatic `rel="prev"` and `rel="next"` handling
+- ✅ **25+ Schema Types** - Article, Product, FAQ, Event, LocalBusiness, Video, Recipe, etc.
+- ✅ **Multilingual Support** - Easy `hreflang` management
+- ✅ **Performance Optimized** - DNS Prefetch, Preconnect, Preload support
 
 ## Installation
 
+### For Next.js App Router (Zero Dependencies):
+```bash
+npm install @masters-ws/react-seo
+```
+
+### For React / Next.js Pages Router (With Components):
 ```bash
 npm install @masters-ws/react-seo react-helmet-async
 ```
 
-## Next.js App Router (SSR - Recommended for News/Malls)
+---
+
+## Usage: Next.js App Router (Recommended)
 
-For the best performance and 100% server-side rendering, use the `toNextMetadata` adapter in your `layout.tsx` or `page.tsx`.
+Use the **core functions** directly in your Server Components. No Helmet needed!
 
 ```tsx
-// page.tsx (Server Component)
-import { toNextMetadata } from '@shammaa/react-seo';
+// app/news/[slug]/page.tsx
+import { toNextMetadata, generateArticleSchema } from '@masters-ws/react-seo';
 
-const config = { name: "My News", url: "https://site.com" };
+const siteConfig = {
+  name: "My News Site",
+  url: "https://mysite.com"
+};
 
+// This runs on the server - instant SEO!
 export async function generateMetadata({ params }) {
-  const post = await getPost(params.id);
+  const post = await getPost(params.slug);
   
   return toNextMetadata({
     title: post.title,
     description: post.excerpt,
+    image: post.cover,
     type: 'article',
-    canonical: `https://site.com/news/${post.slug}`,
-    ogImage: post.image,
-    publishedTime: post.date,
-    readingTime: 5 // Optional: shows in Twitter preview
-  }, config);
+    publishedTime: post.date
+  }, siteConfig);
 }
 
-export default function Page() {
-  return <article>...</article>;
+export default function ArticlePage({ params }) {
+  const post = await getPost(params.slug);
+  
+  // Add JSON-LD Schema using core function
+  const articleSchema = generateArticleSchema({
+    title: post.title,
+    description: post.excerpt,
+    publishedTime: post.date,
+    author: { name: post.author }
+  }, siteConfig);
+
+  return (
+    <>
+      <script
+        type="application/ld+json"
+        dangerouslySetInnerHTML={{ __html: JSON.stringify(articleSchema) }}
+      />
+      <article>...</article>
+    </>
+  );
 }
 ```
 
-## React / Next.js Pages Router (Client/SSR)
+---
 
-### 1. Provider Setup
-Wrap your application in `App.tsx` or `_app.tsx`:
+## Usage: React / Pages Router (With Components)
+
+If you prefer the component approach or are using React without Next.js:
 
 ```tsx
-import { SEOProvider } from '@shammaa/react-seo';
+// _app.tsx
+import { SEOProvider } from '@masters-ws/react-seo';
 
-const siteConfig = {
-  name: "My Site",
-  url: "https://mysite.com",
-  googleAnalyticsId: "G-XXXXXXXXXX",
-  themeColor: "#007bff"
-};
+const config = { name: "My Site", url: "https://mysite.com" };
 
-function App({ children }) {
+export default function App({ Component, pageProps }) {
   return (
-    <SEOProvider config={siteConfig}>
-      {children}
+    <SEOProvider config={config}>
+      <Component {...pageProps} />
     </SEOProvider>
   );
 }
 ```
 
-### 2. Specialized Components
-
-#### News Article
 ```tsx
-import { SeoArticle } from '@shammaa/react-seo';
-
-<SeoArticle 
-  article={{
-    title: "Article Title",
-    description: "Short excerpt...",
-    image: "/cover.jpg",
-    publishedAt: "2024-02-01T10:00:00Z",
-    author: { name: "John Doe" },
-    category: "Tech"
-  }}
-/>
+// pages/article.tsx
+import { SeoArticle } from '@masters-ws/react-seo';
+
+export default function ArticlePage({ post }) {
+  return (
+    <>
+      <SeoArticle article={{
+        title: post.title,
+        description: post.excerpt,
+        image: post.cover,
+        publishedAt: post.date
+      }} />
+      <article>...</article>
+    </>
+  );
+}
 ```
 
-#### FAQ Page
-```tsx
-import { SeoFAQ } from '@shammaa/react-seo';
-
-<SeoFAQ 
-  questions={[
-    { q: "Is it free?", a: "Yes, it is!" },
-    { q: "How to install?", a: "Use npm install." }
-  ]}
-/>
+---
+
+## Core Functions Reference
+
+All functions are pure (no side effects) and work in any environment:
+
+| Function | Description |
+| :--- | :--- |
+| `toNextMetadata(data, config)` | Converts SEO data to Next.js Metadata object |
+| `generateArticleSchema(data, config)` | Creates NewsArticle JSON-LD |
+| `generateProductSchema(data)` | Creates Product JSON-LD with offers |
+| `generateFAQSchema(questions)` | Creates FAQPage JSON-LD |
+| `generateBreadcrumbSchema(items)` | Creates BreadcrumbList JSON-LD |
+| `generateVideoSchema(data)` | Creates VideoObject JSON-LD |
+| `generateEventSchema(data)` | Creates Event JSON-LD |
+| `generateLocalBusinessSchema(data)` | Creates LocalBusiness JSON-LD |
+| `generatePaginationLinks(url, page, total)` | Returns prev/next/canonical URLs |
+| `generateOrganizationSchema(config)` | Creates Organization JSON-LD |
+| `generateWebSiteSchema(config)` | Creates WebSite JSON-LD with SearchAction |
+
+---
+
+## Components Reference (Requires react-helmet-async)
+
+| Component | Description |
+| :--- | :--- |
+| `<SEO />` | Main component for meta tags and schemas |
+| `<SeoArticle />` | For news articles and blog posts |
+| `<SeoProduct />` | For e-commerce products |
+| `<SeoFAQ />` | For FAQ pages |
+| `<SeoVideo />` | For video content |
+| `<SeoEvent />` | For events and conferences |
+| `<SeoLocalBusiness />` | For physical business locations |
+| `<SeoCategory />` | For category pages with pagination |
+| `<SeoTag />` | For tag pages with pagination |
+| `<SeoAuthor />` | For author profile pages |
+| `<Breadcrumb />` | For breadcrumb navigation with schema |
+
+---
+
+## Configuration Options
+
+### SiteConfig
+```typescript
+{
+  name: string;           // Site name
+  url: string;            // Base URL
+  logo?: string;          // Logo URL
+  language?: string;      // Default: 'ar'
+  twitterHandle?: string; // @username
+  themeColor?: string;    // Mobile theme color
+}
+```
+
+### SEOData
+```typescript
+{
+  title?: string;
+  description?: string;
+  image?: string;
+  canonical?: string;
+  noindex?: boolean;      // Sets robots to noindex
+  type?: 'website' | 'article' | 'product';
+  alternates?: Array<{ hreflang: string; href: string }>;
+  // ... and more
+}
 ```
 
-## Detailed Configuration Reference
-
-### SiteConfig Props
-| Prop | Type | Description |
-| :--- | :--- | :--- |
-| `name` | `string` | Site name (used in titles and schemas) |
-| `url` | `string` | Base URL of the site |
-| `logo` | `string` | URL to the site logo |
-| `language` | `string` | Main language (e.g., 'ar', 'en') |
-| `googleAnalyticsId`| `string` | GA4 Measurement ID |
-| `themeColor` | `string` | Browser theme color (mobile) |
-
-### SEOData Props (Common)
-| Prop | Type | Description |
-| :--- | :--- | :--- |
-| `title` | `string` | Page title (auto-appends Site name) |
-| `noindex` | `boolean` | Sets robots to noindex and removes canonical |
-| `alternates` | `Array` | List of `{hreflang, href}` for multilingual |
-| `dnsPrefetch` | `string[]` | List of domains to prefetch |
-| `readingTime` | `number` | Reading time in minutes for Twitter Cards |
-
-## Advanced Schemas List
-Use these components for specific SEO needs:
-- `<SeoVideo />` - For video content.
-- `<SeoEvent />` - For conferences/events.
-- `<SeoLocalBusiness />` - For physical stores.
-- `<SeoHowTo />` - For tutorials.
-- `<SeoReview />` - For product ratings.
-- `<SeoJobPosting />` - For hiring.
-- `<SeoRecipe />` - For cooking sites.
+---
 
 ## License
 MIT

package/dist/chunk-AAN7NRZE.mjs

@@ -0,0 +1,235 @@
+// src/core/schemas.ts
+function generateOrganizationSchema(config) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "Organization",
+    "name": config.name,
+    "url": config.url,
+    "logo": config.logo,
+    "sameAs": config.socialLinks || []
+  };
+}
+function generateWebSiteSchema(config) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "WebSite",
+    "name": config.name,
+    "url": config.url,
+    "potentialAction": {
+      "@type": "SearchAction",
+      "target": `${config.url}/search?q={search_term_string}`,
+      "query-input": "required name=search_term_string"
+    }
+  };
+}
+function generateArticleSchema(data, config) {
+  const org = generateOrganizationSchema(config);
+  return {
+    "@context": "https://schema.org",
+    "@type": "NewsArticle",
+    "headline": data.title,
+    "description": data.description,
+    "image": data.image || config.logo,
+    "datePublished": data.publishedTime,
+    "dateModified": data.modifiedTime || data.publishedTime,
+    "mainEntityOfPage": data.url,
+    "author": data.author ? {
+      "@type": "Person",
+      "name": data.author.name,
+      "url": data.author.url
+    } : org,
+    "publisher": org
+  };
+}
+function generateProductSchema(data) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "Product",
+    "name": data.name,
+    "description": data.description,
+    "image": data.image,
+    "sku": data.sku,
+    "brand": data.brand ? { "@type": "Brand", "name": data.brand } : void 0,
+    "offers": {
+      "@type": "Offer",
+      "url": data.url,
+      "priceCurrency": data.currency || "USD",
+      "price": data.price,
+      "availability": data.availability || "https://schema.org/InStock"
+    },
+    "aggregateRating": data.rating ? {
+      "@type": "AggregateRating",
+      "ratingValue": data.rating,
+      "reviewCount": data.reviewCount || 1
+    } : void 0
+  };
+}
+function generateFAQSchema(questions) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "FAQPage",
+    "mainEntity": questions.map((item) => ({
+      "@type": "Question",
+      "name": item.q,
+      "acceptedAnswer": {
+        "@type": "Answer",
+        "text": item.a
+      }
+    }))
+  };
+}
+function generateBreadcrumbSchema(items) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "BreadcrumbList",
+    "itemListElement": items.map((item, index) => ({
+      "@type": "ListItem",
+      "position": index + 1,
+      "name": item.name,
+      "item": item.item
+    }))
+  };
+}
+function generateVideoSchema(data) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "VideoObject",
+    "name": data.name,
+    "description": data.description,
+    "thumbnailUrl": data.thumbnailUrl,
+    "uploadDate": data.uploadDate,
+    "duration": data.duration,
+    "contentUrl": data.contentUrl,
+    "embedUrl": data.embedUrl
+  };
+}
+function generateEventSchema(data) {
+  const isOnline = data.location && "url" in data.location;
+  return {
+    "@context": "https://schema.org",
+    "@type": "Event",
+    "name": data.name,
+    "description": data.description,
+    "startDate": data.startDate,
+    "endDate": data.endDate,
+    "eventAttendanceMode": isOnline ? "https://schema.org/OnlineEventAttendanceMode" : "https://schema.org/OfflineEventAttendanceMode",
+    "location": isOnline ? {
+      "@type": "VirtualLocation",
+      "url": data.location.url
+    } : data.location ? {
+      "@type": "Place",
+      "name": data.location.name,
+      "address": data.location.address
+    } : void 0,
+    "image": data.image,
+    "offers": data.offers ? {
+      "@type": "Offer",
+      "price": data.offers.price,
+      "priceCurrency": data.offers.currency,
+      "url": data.offers.url
+    } : void 0
+  };
+}
+function generateLocalBusinessSchema(data) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "LocalBusiness",
+    "name": data.name,
+    "description": data.description,
+    "image": data.image,
+    "telephone": data.telephone,
+    "address": {
+      "@type": "PostalAddress",
+      "streetAddress": data.address.street,
+      "addressLocality": data.address.city,
+      "addressRegion": data.address.region,
+      "postalCode": data.address.postalCode,
+      "addressCountry": data.address.country
+    },
+    "geo": data.geo ? {
+      "@type": "GeoCoordinates",
+      "latitude": data.geo.lat,
+      "longitude": data.geo.lng
+    } : void 0,
+    "openingHours": data.openingHours,
+    "priceRange": data.priceRange
+  };
+}
+
+// src/core/metadata.ts
+function toNextMetadata(props, config) {
+  const title = props.title ? `${props.title} | ${config.name}` : config.name;
+  const description = props.description || config.description;
+  const url = props.canonical || config.url;
+  const image = props.image || config.logo;
+  const metadata = {
+    title,
+    description,
+    keywords: props.keywords,
+    robots: props.noindex ? "noindex, nofollow" : props.robots || "index, follow",
+    alternates: {
+      canonical: props.noindex ? void 0 : url
+    },
+    openGraph: {
+      title: props.ogTitle || title,
+      description: props.ogDescription || description,
+      url,
+      siteName: config.name,
+      images: props.ogImage || image ? [{ url: props.ogImage || image }] : [],
+      type: props.ogType || (props.type === "article" ? "article" : "website"),
+      locale: props.ogLocale || config.language || "ar_SA"
+    },
+    twitter: {
+      card: props.twitterCard || "summary_large_image",
+      title: props.twitterTitle || title,
+      description: props.twitterDescription || description,
+      images: props.twitterImage || image ? [props.twitterImage || image] : [],
+      site: config.twitterHandle,
+      creator: config.twitterHandle
+    },
+    other: {}
+  };
+  if (props.alternates && props.alternates.length > 0) {
+    const languages = {};
+    props.alternates.forEach((alt) => {
+      languages[alt.hreflang] = alt.href;
+    });
+    metadata.alternates.languages = languages;
+  }
+  metadata.appleWebApp = {
+    capable: true,
+    title: config.name,
+    statusBarStyle: "default"
+  };
+  if (config.themeColor) metadata.themeColor = config.themeColor;
+  if (config.manifest) metadata.manifest = config.manifest;
+  return metadata;
+}
+function generatePaginationLinks(baseUrl, currentPage, totalPages) {
+  const hasNext = currentPage < totalPages;
+  const hasPrev = currentPage > 1;
+  const cleanBase = baseUrl.split("?")[0];
+  return {
+    next: hasNext ? `${cleanBase}?page=${currentPage + 1}` : void 0,
+    prev: hasPrev ? currentPage === 2 ? cleanBase : `${cleanBase}?page=${currentPage - 1}` : void 0,
+    canonical: currentPage === 1 ? cleanBase : `${cleanBase}?page=${currentPage}`
+  };
+}
+function generatePaginatedTitle(title, page, suffix = "\u0635\u0641\u062D\u0629") {
+  return page > 1 ? `${title} - ${suffix} ${page}` : title;
+}
+
+export {
+  generateOrganizationSchema,
+  generateWebSiteSchema,
+  generateArticleSchema,
+  generateProductSchema,
+  generateFAQSchema,
+  generateBreadcrumbSchema,
+  generateVideoSchema,
+  generateEventSchema,
+  generateLocalBusinessSchema,
+  toNextMetadata,
+  generatePaginationLinks,
+  generatePaginatedTitle
+};