Структуровані дані Schema.org та JSON-LD в React SPA

+-------------------------------------------------------------------------+
|                  АРХІТЕКТУРА СЕМАНТИЧНОГО ГРАФА JSON-LD В SPA           |
+-------------------------------------------------------------------------+

 [ React SPA Компонент ]
        |
        | 1. Дані сутності з API (Типізований DTO)
        v
 +-----------------------------------------------------------------------+
 | Конструктор схеми Schema.org (schema-dts)                             |
 | - Валідація структури: @type: "TechArticle" | "Product" | "FAQPage"   |
 | - Вкладені графи: Author (Person), Publisher (Organization)           |
 +-----------------------------------------------------------------------+
        |
        | 2. Безпечна санітизація (Екранування </script>, <, >, &)
        v
 +-----------------------------------------------------------------------+
 | <script type="application/ld+json" id="jsonld-primary">               |
 |   {                                                                   |
 |     "@context": "https://schema.org",                                 |
 |     "@type": "Product",                                               |
 |     "name": "Mechanical Keyboard",                                    |
 |     "offers": { "@type": "Offer", "price": "149.00" }                 |
 |   }                                                                   |
 | </script>                                                             |
 +-----------------------------------------------------------------------+
        |
        | 3. Індексація WRS / Googlebot / LLM Parser
        v
 +-----------------------------------------------------------------------+
 | Пошукова видача: Розширений сніпет (Rich Snippet / AI Overview)       |
 | ★★★★★ 4.9 (128 відгуків) | В наявності | 149.00 USD                   |
 +-----------------------------------------------------------------------+

/**
 * Безпечно серіалізує об'єкт даних у рядок JSON для вставки в HTML-тег <script>.
 * Нейтралізує символи <, >, & та рядкові термінатори JavaScript,
 * запобігаючи вразливостям типу Cross-Site Scripting (XSS).
 */
export function serializeSafeJsonLd(data: unknown): string {
  const jsonString = JSON.stringify(data, null, process.env.NODE_ENV === 'development' ? 2 : 0);

  if (!jsonString) {
    return '{}';
  }

  // Екрануємо спецсимволи за специфікацією HTML5/W3C
  return jsonString
    .replace(/</g, '\\u003c')
    .replace(/>/g, '\\u003e')
    .replace(/&/g, '\\u0026')
    .replace(/\u2028/g, '\\u2028') // Line Separator
    .replace(/\u2029/g, '\\u2029'); // Paragraph Separator
}

import React from 'react';
import type { Thing, WithContext } from 'schema-dts';
import { serializeSafeJsonLd } from '@/utils/safe-json-ld';

export interface JsonLdProps<T extends Thing> {
  schema: WithContext<T>;
  id?: string;
}

/**
 * Універсальний компонент ін'єкції JSON-LD структурованих даних.
 * Гарантує 100% сувору типізацію Schema.org та захист від XSS.
 */
export function JsonLd<T extends Thing>({ schema, id }: JsonLdProps<T>) {
  const scriptId = id || `jsonld-${schema['@type'] ? String(schema['@type']).toLowerCase() : 'schema'}`;

  return (
    <script
      id={scriptId}
      type="application/ld+json"
      dangerouslySetInnerHTML={{ __html: serializeSafeJsonLd(schema) }}
    />
  );
}

import React from 'react';
import type { Product, BreadcrumbList, WithContext } from 'schema-dts';
import { JsonLd } from '@/components/seo/JsonLd';

interface ProductItem {
  id: string;
  name: string;
  sku: string;
  description: string;
  brand: string;
  price: number;
  currency: string;
  ratingValue: number;
  reviewCount: number;
  imageUrl: string;
}

interface ProductDetailsProps {
  product: ProductItem;
}

export const ProductDetailsPage: React.FC<ProductDetailsProps> = ({ product }) => {
  // 1. Формуємо схему Product
  const productSchema: WithContext<Product> = {
    '@context': 'https://schema.org',
    '@type': 'Product',
    name: product.name,
    image: product.imageUrl,
    description: product.description,
    sku: product.sku,
    brand: {
      '@type': 'Brand',
      name: product.brand,
    },
    offers: {
      '@type': 'Offer',
      url: `https://agenticlab.dev/products/${product.sku}`,
      priceCurrency: product.currency,
      price: product.price.toFixed(2),
      availability: 'https://schema.org/InStock',
      itemCondition: 'https://schema.org/NewCondition',
    },
    aggregateRating: {
      '@type': 'AggregateRating',
      ratingValue: product.ratingValue.toString(),
      reviewCount: product.reviewCount.toString(),
      bestRating: '5',
      worstRating: '1',
    },
  };

  // 2. Формуємо схему BreadcrumbList
  const breadcrumbSchema: WithContext<BreadcrumbList> = {
    '@context': 'https://schema.org',
    '@type': 'BreadcrumbList',
    itemListElement: [
      {
        '@type': 'ListItem',
        position: 1,
        name: 'Головна',
        item: 'https://agenticlab.dev',
      },
      {
        '@type': 'ListItem',
        position: 2,
        name: 'Каталог',
        item: 'https://agenticlab.dev/products',
      },
      {
        '@type': 'ListItem',
        position: 3,
        name: product.name,
        item: `https://agenticlab.dev/products/${product.sku}`,
      },
    ],
  };

  return (
    <main className="container mx-auto p-6">
      {/* Впровадження структурованих даних */}
      <JsonLd schema={productSchema} id="product-jsonld" />
      <JsonLd schema={breadcrumbSchema} id="breadcrumbs-jsonld" />

      <h1 className="text-2xl font-bold">{product.name}</h1>
      <p className="text-gray-600">{product.description}</p>
      <div className="price-tag text-xl font-semibold mt-4">
        {product.price} {product.currency}
      </div>
    </main>
  );
};

import { chromium } from 'playwright';

export async function validateJsonLdOnPage(url: string): Promise<void> {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  await page.goto(url, { waitUntil: 'networkidle' });

  // Витягуємо всі блоки JSON-LD з відрендереного DOM
  const jsonLdScripts = await page.locator('script[type="application/ld+json"]').allInnerTexts();

  if (jsonLdScripts.length === 0) {
    throw new Error(`[Schema Error]: На сторінці ${url} відсутні блоки JSON-LD`);
  }

  for (const scriptContent of jsonLdScripts) {
    try {
      const parsed = JSON.parse(scriptContent) as Record<string, unknown>;
      if (!parsed['@context'] || !parsed['@type']) {
        throw new Error(`[Schema Error]: Відсутні обов'язкові ключі @context або @type`);
      }
      console.info(`[Schema Valid]: Успішно спарсено @type: ${String(parsed['@type'])}`);
    } catch (err: unknown) {
      throw new Error(`[Schema Error]: Невалідний JSON: ${err instanceof Error ? err.message : 'Unknown'}`);
    }
  }

  await browser.close();
}