@masters-ws/react-seo 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shammaa
+
+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,138 @@
+# @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.
+
+## 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.
+
+## Installation
+
+```bash
+npm install @masters-ws/react-seo react-helmet-async
+```
+
+## Next.js App Router (SSR - Recommended for News/Malls)
+
+For the best performance and 100% server-side rendering, use the `toNextMetadata` adapter in your `layout.tsx` or `page.tsx`.
+
+```tsx
+// page.tsx (Server Component)
+import { toNextMetadata } from '@shammaa/react-seo';
+
+const config = { name: "My News", url: "https://site.com" };
+
+export async function generateMetadata({ params }) {
+  const post = await getPost(params.id);
+  
+  return toNextMetadata({
+    title: post.title,
+    description: post.excerpt,
+    type: 'article',
+    canonical: `https://site.com/news/${post.slug}`,
+    ogImage: post.image,
+    publishedTime: post.date,
+    readingTime: 5 // Optional: shows in Twitter preview
+  }, config);
+}
+
+export default function Page() {
+  return <article>...</article>;
+}
+```
+
+## React / Next.js Pages Router (Client/SSR)
+
+### 1. Provider Setup
+Wrap your application in `App.tsx` or `_app.tsx`:
+
+```tsx
+import { SEOProvider } from '@shammaa/react-seo';
+
+const siteConfig = {
+  name: "My Site",
+  url: "https://mysite.com",
+  googleAnalyticsId: "G-XXXXXXXXXX",
+  themeColor: "#007bff"
+};
+
+function App({ children }) {
+  return (
+    <SEOProvider config={siteConfig}>
+      {children}
+    </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"
+  }}
+/>
+```
+
+#### 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." }
+  ]}
+/>
+```
+
+## 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/index.d.mts

@@ -0,0 +1,351 @@
+import React from 'react';
+
+interface SiteConfig {
+    name: string;
+    description: string;
+    url: string;
+    logo?: string;
+    publisher?: string;
+    twitterHandle?: string;
+    facebookAppId?: string;
+    language?: string;
+    socialLinks?: string[];
+    googleAnalyticsId?: string;
+    gtmId?: string;
+    facebookPixelId?: string;
+    yandexMetricaId?: string;
+    themeColor?: string;
+    manifest?: string;
+}
+interface SEOData {
+    title?: string;
+    description?: string;
+    image?: string;
+    canonical?: string;
+    type?: 'website' | 'article' | 'product' | 'profile' | 'video' | 'faq';
+    robots?: string;
+    noindex?: boolean;
+    keywords?: string[];
+    prev?: string;
+    next?: string;
+    alternates?: Array<{
+        hreflang: string;
+        href: string;
+    }>;
+    ogTitle?: string;
+    ogDescription?: string;
+    ogImage?: string;
+    ogType?: string;
+    ogLocale?: string;
+    twitterCard?: 'summary' | 'summary_large_image' | 'app' | 'player';
+    twitterTitle?: string;
+    twitterDescription?: string;
+    twitterImage?: string;
+    publishedTime?: string;
+    modifiedTime?: string;
+    author?: {
+        name: string;
+        url?: string;
+        image?: string;
+    };
+    tags?: string[];
+    section?: string;
+    readingTime?: number;
+    product?: {
+        sku?: string;
+        brand?: string;
+        price?: number;
+        currency?: string;
+        availability?: string;
+        rating?: number;
+        reviewCount?: number;
+    };
+    dnsPrefetch?: string[];
+    preconnect?: string[];
+    prefetch?: string[];
+    preload?: Array<{
+        href: string;
+        as: string;
+        type?: string;
+    }>;
+    whatsappImage?: string;
+    whatsappDescription?: string;
+    schema?: any;
+}
+interface BreadcrumbItem {
+    name: string;
+    item: string;
+}
+
+interface SEOProviderProps {
+    config: SiteConfig;
+    children: React.ReactNode;
+    helmetContext?: {};
+}
+declare const SEOProvider: React.FC<SEOProviderProps>;
+declare const useSEOConfig: () => SiteConfig;
+
+interface SEOProps extends SEOData {
+    children?: React.ReactNode;
+}
+declare const SEO: React.FC<SEOProps>;
+
+interface BreadcrumbProps {
+    items: BreadcrumbItem[];
+    className?: string;
+    separator?: React.ReactNode;
+    renderLink?: (item: BreadcrumbItem, isLast: boolean) => React.ReactNode;
+}
+declare const Breadcrumb: React.FC<BreadcrumbProps>;
+
+interface SeoArticleProps extends Omit<SEOProps, 'type'> {
+    article: {
+        title: string;
+        description: string;
+        image: string;
+        publishedAt: string;
+        updatedAt?: string;
+        author: {
+            name: string;
+            url?: string;
+        };
+        category?: string;
+        tags?: string[];
+    };
+}
+declare const SeoArticle: React.FC<SeoArticleProps>;
+
+interface SeoProductProps extends Omit<SEOProps, 'type' | 'product'> {
+    item: {
+        name: string;
+        description: string;
+        image: string;
+        sku?: string;
+        brand?: string;
+        price: number;
+        currency: string;
+        availability?: string;
+        rating?: number;
+        reviewCount?: number;
+    };
+}
+declare const SeoProduct: React.FC<SeoProductProps>;
+
+interface FAQItem {
+    question: string;
+    answer: string;
+}
+interface SeoFAQProps {
+    items: FAQItem[];
+}
+declare const SeoFAQ: React.FC<SeoFAQProps>;
+
+interface SeoVideoProps {
+    video: {
+        name: string;
+        description: string;
+        thumbnailUrl: string[] | string;
+        uploadDate: string;
+        contentUrl?: string;
+        embedUrl?: string;
+        duration?: string;
+        interactionStatistic?: {
+            viewCount?: number;
+        };
+    };
+}
+declare const SeoVideo: React.FC<SeoVideoProps>;
+
+interface SeoEventProps {
+    event: {
+        name: string;
+        description: string;
+        startDate: string;
+        endDate?: string;
+        eventStatus?: 'EventCancelled' | 'EventMovedOnline' | 'EventPostponed' | 'EventRescheduled' | 'EventScheduled';
+        eventAttendanceMode?: 'OfflineEventAttendanceMode' | 'OnlineEventAttendanceMode' | 'MixedEventAttendanceMode';
+        location: {
+            name: string;
+            address?: string;
+            url?: string;
+        };
+        image?: string[] | string;
+        offers?: {
+            price: number;
+            priceCurrency: string;
+            url?: string;
+            availability?: string;
+        };
+        organizer?: {
+            name: string;
+            url?: string;
+        };
+    };
+}
+declare const SeoEvent: React.FC<SeoEventProps>;
+
+interface SeoLocalBusinessProps {
+    business: {
+        type?: string;
+        name: string;
+        image?: string[] | string;
+        description?: string;
+        id?: string;
+        url?: string;
+        telephone?: string;
+        address: {
+            streetAddress: string;
+            addressLocality: string;
+            addressRegion?: string;
+            postalCode?: string;
+            addressCountry: string;
+        };
+        geo?: {
+            latitude: number;
+            longitude: number;
+        };
+        openingHours?: string[] | string;
+        priceRange?: string;
+    };
+}
+declare const SeoLocalBusiness: React.FC<SeoLocalBusinessProps>;
+
+interface SeoCategoryProps extends Omit<SEOProps, 'type'> {
+    category: {
+        name: string;
+        description: string;
+        image?: string;
+        url: string;
+    };
+    page?: number;
+    totalPage?: number;
+}
+declare const SeoCategory: React.FC<SeoCategoryProps>;
+
+interface SeoTagProps extends Omit<SEOProps, 'type'> {
+    tag: {
+        name: string;
+        description?: string;
+        url: string;
+    };
+    page?: number;
+    totalPage?: number;
+}
+declare const SeoTag: React.FC<SeoTagProps>;
+
+interface SeoAuthorProps extends Omit<SEOProps, 'type'> {
+    author: {
+        name: string;
+        description?: string;
+        image?: string;
+        url: string;
+        jobTitle?: string;
+    };
+    page?: number;
+    totalPage?: number;
+}
+declare const SeoAuthor: React.FC<SeoAuthorProps>;
+
+interface HowToStep {
+    name: string;
+    text: string;
+    image?: string;
+    url?: string;
+}
+interface SeoHowToProps {
+    name: string;
+    description?: string;
+    image?: string;
+    steps: HowToStep[] | string[];
+}
+declare const SeoHowTo: React.FC<SeoHowToProps>;
+
+interface SeoReviewProps {
+    itemReviewed: {
+        type: string;
+        name: string;
+        image?: string;
+    };
+    review: {
+        author: string;
+        datePublished?: string;
+        reviewBody: string;
+        ratingValue: number;
+        bestRating?: number;
+        worstRating?: number;
+    };
+}
+declare const SeoReview: React.FC<SeoReviewProps>;
+
+interface SeoCourseProps {
+    course: {
+        name: string;
+        description: string;
+        providerName: string;
+        providerUrl?: string;
+        image?: string;
+    };
+}
+declare const SeoCourse: React.FC<SeoCourseProps>;
+
+interface SeoRecipeProps {
+    recipe: {
+        name: string;
+        description: string;
+        image: string[] | string;
+        author: string;
+        publishedDate?: string;
+        prepTime?: string;
+        cookTime?: string;
+        totalTime?: string;
+        recipeYield?: string;
+        recipeCategory?: string;
+        recipeCuisine?: string;
+        ingredients: string[];
+        instructions: Array<{
+            name?: string;
+            text: string;
+            image?: string;
+        }>;
+    };
+}
+declare const SeoRecipe: React.FC<SeoRecipeProps>;
+
+interface SeoJobPostingProps {
+    job: {
+        title: string;
+        description: string;
+        datePosted: string;
+        validThrough?: string;
+        employmentType?: string | string[];
+        hiringOrganization: {
+            name: string;
+            sameAs?: string;
+            logo?: string;
+        };
+        jobLocation: {
+            streetAddress: string;
+            addressLocality: string;
+            addressRegion?: string;
+            postalCode?: string;
+            addressCountry: string;
+        };
+        baseSalary?: {
+            currency: string;
+            value: number | {
+                minValue: number;
+                maxValue: number;
+            };
+            unitText?: string;
+        };
+    };
+}
+declare const SeoJobPosting: React.FC<SeoJobPostingProps>;
+
+/**
+ * Converts SEOData and SiteConfig to a Next.js compatible Metadata object.
+ * This is designed to be used in Server Components (App Router).
+ */
+declare function toNextMetadata(props: SEOData, config: SiteConfig): any;
+
+export { Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, type FAQItem, type HowToStep, SEO, type SEOData, type SEOProps, SEOProvider, type SEOProviderProps, SeoArticle, type SeoArticleProps, SeoAuthor, type SeoAuthorProps, SeoCategory, type SeoCategoryProps, SeoCourse, type SeoCourseProps, SeoEvent, type SeoEventProps, SeoFAQ, type SeoFAQProps, SeoHowTo, type SeoHowToProps, SeoJobPosting, type SeoJobPostingProps, SeoLocalBusiness, type SeoLocalBusinessProps, SeoProduct, type SeoProductProps, SeoRecipe, type SeoRecipeProps, SeoReview, type SeoReviewProps, SeoTag, type SeoTagProps, SeoVideo, type SeoVideoProps, type SiteConfig, toNextMetadata, useSEOConfig };