@sarimarcus/content-sites-tourism 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All packages in the platform release in lockstep; entries are per release version.
 
+## 0.14.0 (2026-10-01)
+
+- New `./schema`: monument, museum, restaurant, bar, dish, neighborhood and guide item-list builders and the `TourismCity` address policy (SLA-2737).
+
 ## 0.13.0 (2026-10-01)
 
 - No changes; lockstep release with ui (SLA-2819).

package/README.md

@@ -3,7 +3,9 @@
 The city-tourism vertical: city-entity components (monuments, restaurants, hotels, events…), trip-planner
 pieces, tourism page templates and their utilities. Used by the Córdoba and Granada sites.
 
-Named entry points: `cards`, `sections`, `templates` and `types` (`src/internal` is never exported).
+Named entry points: `cards`, `sections`, `templates`, `schema` and `types` (`src/internal` is never exported).
+`schema` holds the city-entity JSON-LD builders (monument, museum, restaurant, bar, dish, neighborhood, guide item
+list) on core `schema`, and the `TourismCity` address policy they share.
 Page templates are rendered by thin route files in each site.
 
 Depends on `@sarimarcus/content-sites-core` and `@sarimarcus/content-sites-ui` (exact lockstep peers).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sarimarcus/content-sites-tourism",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "City-tourism vertical: city-entity components, pages templates and utilities for the tourism sites.",
   "type": "module",
   "license": "MIT",
@@ -29,13 +29,14 @@
     "./cards": "./src/cards/index.ts",
     "./sections": "./src/sections/index.ts",
     "./templates": "./src/templates/index.ts",
+    "./schema": "./src/schema/index.ts",
     "./types": "./src/types/index.ts",
     "./tailwind.css": "./src/tailwind.css"
   },
   "peerDependencies": {
     "astro": "^7.0.6",
     "tailwindcss": "^4.1.18",
-    "@sarimarcus/content-sites-core": "0.13.0",
-    "@sarimarcus/content-sites-ui": "0.13.0"
+    "@sarimarcus/content-sites-core": "0.14.0",
+    "@sarimarcus/content-sites-ui": "0.14.0"
   }
 }

package/src/schema/builders.ts

@@ -0,0 +1,234 @@
+import {
+  aggregateRating, createPersonSchema, generateOpeningHours, geoCoordinates,
+  normalizeHotelPriceRange, normalizePriceRange, parseHoursString, postalAddress, postalCodeOf, withAuthorPersonSchema,
+} from '@sarimarcus/content-sites-core/schema';
+import type { JsonLdNode, SchemaBuilder } from '@sarimarcus/content-sites-core/schema';
+import { cityAddressPolicy, type TourismCity } from './city.ts';
+
+const isFree = (data: Record<string, any>) => data.tags?.includes('free') || data.fees?.toLowerCase().includes('free');
+
+export interface MonumentOptions {
+  city: TourismCity;
+  touristType?: string;
+}
+
+/** TouristAttraction at route `monument`; hours from the free-text `hours` line. */
+export function monumentBuilder(options: MonumentOptions): SchemaBuilder {
+  const address = cityAddressPolicy(options.city);
+  const touristType = options.touristType ?? 'Cultural';
+  return (data, ctx) => withAuthorPersonSchema(ctx, {
+    '@type': 'TouristAttraction',
+    name: data.name,
+    description: data.description,
+    image: ctx.resolveImageUrl(data.image, data.slug),
+    address: postalAddress(address, data, { street: data.address, postalCode: postalCodeOf(data) }),
+    geo: geoCoordinates(data.coordinates),
+    openingHoursSpecification: parseHoursString(data.hours),
+    isAccessibleForFree: isFree(data),
+    touristType,
+    mainEntityOfPage: { '@id': ctx.pageUrl },
+    url: ctx.route('monument', data.slug),
+  }, data.author);
+}
+
+/** Museum at route `museum`; hours from the free-text `hours` line. */
+export function museumBuilder(options: { city: TourismCity }): SchemaBuilder {
+  const address = cityAddressPolicy(options.city);
+  return (data, ctx) => withAuthorPersonSchema(ctx, {
+    '@type': 'Museum',
+    name: data.name,
+    description: data.description,
+    image: ctx.resolveImageUrl(data.image, data.slug),
+    address: postalAddress(address, data, { street: data.address, postalCode: postalCodeOf(data) }),
+    geo: geoCoordinates(data.coordinates),
+    openingHoursSpecification: parseHoursString(data.hours),
+    isAccessibleForFree: isFree(data),
+    mainEntityOfPage: { '@id': ctx.pageUrl },
+    url: ctx.route('museum', data.slug),
+  }, data.author);
+}
+
+const menu = (sectionName: string, items: string[] | undefined): JsonLdNode | undefined =>
+  ((items?.length ?? 0) > 0 ? {
+    '@type': 'Menu',
+    hasMenuSection: {
+      '@type': 'MenuSection',
+      name: sectionName,
+      hasMenuItem: items!.map((name) => ({ '@type': 'MenuItem', name })),
+    },
+  } : undefined);
+
+export interface RestaurantOptions {
+  city: TourismCity;
+  menuSectionName?: string;
+}
+
+/** Restaurant at route `restaurant`; `specialties` become its menu. */
+export function restaurantBuilder(options: RestaurantOptions): SchemaBuilder {
+  const address = cityAddressPolicy(options.city);
+  const sectionName = options.menuSectionName ?? 'Specialties';
+  return (data, ctx) => withAuthorPersonSchema(ctx, {
+    '@type': 'Restaurant',
+    name: data.name,
+    description: data.description,
+    image: ctx.resolveImageUrl(data.image, data.slug),
+    address: postalAddress(address, data, { street: data.address, postalCode: postalCodeOf(data) }),
+    servesCuisine: data.cuisine,
+    priceRange: normalizePriceRange(data.averagePrice, data.priceFrom),
+    openingHoursSpecification: generateOpeningHours(data.openingHours),
+    telephone: data.phone,
+    aggregateRating: aggregateRating(data),
+    geo: geoCoordinates(data.coordinates),
+    sameAs: data.website ? [data.website] : undefined,
+    hasMenu: menu(sectionName, data.specialties),
+    mainEntityOfPage: { '@id': ctx.pageUrl },
+    url: ctx.route('restaurant', data.slug),
+  }, data.author);
+}
+
+export interface BarOptions {
+  city: TourismCity;
+  menuSectionName?: string;
+  /** `servesCuisine` for a bar whose `category` is `tapas`. */
+  tapasCuisine?: string;
+}
+
+/** BarOrPub at route `bar`; `specialties` become its drinks menu. */
+export function barBuilder(options: BarOptions): SchemaBuilder {
+  const address = cityAddressPolicy(options.city);
+  const sectionName = options.menuSectionName ?? 'Signature Drinks';
+  const tapas = options.tapasCuisine ?? 'Tapas';
+  return (data, ctx) => withAuthorPersonSchema(ctx, {
+    '@type': 'BarOrPub',
+    name: data.name,
+    description: data.description,
+    image: ctx.resolveImageUrl(data.image, data.slug),
+    address: postalAddress(address, data, { street: data.address, postalCode: postalCodeOf(data) }),
+    geo: geoCoordinates(data.coordinates),
+    priceRange: normalizePriceRange(data.averagePrice, data.priceFrom),
+    aggregateRating: aggregateRating(data),
+    sameAs: data.website ? [data.website] : undefined,
+    servesCuisine: data.category === 'tapas' ? tapas : undefined,
+    hasMenu: menu(sectionName, data.specialties),
+    openingHoursSpecification: generateOpeningHours(data.openingHours),
+    telephone: data.phone,
+    mainEntityOfPage: { '@id': ctx.pageUrl },
+    url: ctx.route('bar', data.slug),
+  }, data.author);
+}
+
+export interface DishOptions {
+  articleSection?: string;
+  inLanguage?: string;
+}
+
+/** A dish page as an Article at route `dish`, dated by `dateModified` (now when absent). */
+export function dishBuilder(options: DishOptions = {}): SchemaBuilder {
+  const { articleSection = 'Gastronomy', inLanguage = 'en' } = options;
+  return (data, ctx) => {
+    const author = ctx.resolveAuthor(data.author);
+    const node: JsonLdNode = {
+      '@type': 'Article',
+      headline: data.name,
+      description: data.description,
+      image: ctx.resolveImageUrl(data.image, data.slug),
+      author: author ? { '@id': author.id } : undefined,
+      publisher: ctx.publisherFor(data.author),
+      mainEntityOfPage: { '@id': ctx.pageUrl },
+      datePublished: ctx.formatDate(data.dateModified, true),
+      dateModified: ctx.formatDate(data.dateModified, true),
+      keywords: data.tags?.join(', ') || '',
+      articleSection,
+      inLanguage,
+      url: ctx.route('dish', data.slug),
+    };
+    return author ? [createPersonSchema(author), node] : node;
+  };
+}
+
+/** Place at route `neighborhood`, inside the city; pinned to the city when it has no coordinates. */
+export function neighborhoodBuilder(options: { city: TourismCity }): SchemaBuilder {
+  const { city } = options;
+  const address = cityAddressPolicy(city);
+  return (data, ctx) => withAuthorPersonSchema(ctx, {
+    '@type': 'Place',
+    name: data.name,
+    description: data.description,
+    image: ctx.resolveImageUrl(data.image, data.slug),
+    address: postalAddress(address, data),
+    geo: geoCoordinates(data.coordinates || city.geo),
+    containedInPlace: {
+      '@type': 'City',
+      name: city.locality,
+      address: { '@type': 'PostalAddress', addressRegion: city.region, addressCountry: city.country },
+    },
+    mainEntityOfPage: { '@id': ctx.pageUrl },
+    url: ctx.route('neighborhood', data.slug),
+  }, data.author);
+}
+
+/** Guide item `type` (a plural collection name) → schema type (SLA-2468). */
+export const GUIDE_ITEM_TYPES: Record<string, string> = {
+  restaurants: 'Restaurant',
+  hotels: 'LodgingBusiness',
+  monuments: 'TouristAttraction',
+  museums: 'Museum',
+  activities: 'TouristAttraction',
+  bars: 'BarOrPub',
+  dishes: 'MenuItem',
+  events: 'Event',
+  neighborhoods: 'Place',
+  walks: 'TouristTrip',
+};
+
+/**
+ * A ranked guide as an ItemList of mixed-type nested entities. Event nests address and geo under `location`;
+ * TouristTrip carries no `geo`; hotels carry a price range and no hours.
+ */
+export function guideItemListBuilder(options: { city: TourismCity; itemTypes?: Record<string, string> }): SchemaBuilder {
+  const policy = cityAddressPolicy(options.city);
+  const itemTypes = options.itemTypes ?? GUIDE_ITEM_TYPES;
+  return (data, ctx) => {
+    const nested = (item: any): JsonLdNode => {
+      const schemaType = itemTypes[item.type] ?? 'WebPage';
+      const entity: JsonLdNode = {
+        '@type': schemaType,
+        name: item.name,
+        url: ctx.absOrHttp(item.url),
+        image: ctx.resolveImageUrl(item.image, item.slug),
+      };
+      const addressNode = (item.type !== 'dishes' && item.type !== 'neighborhoods' && item.address)
+        ? postalAddress(policy, item, { street: item.address, postalCode: item.address?.match(/(\d{5})/)?.[1] })
+        : undefined;
+      const geoNode = geoCoordinates(item.coordinates);
+      if (schemaType === 'Event') {
+        if (addressNode || geoNode) {
+          entity.location = { '@type': 'Place', name: item.name, ...(addressNode && { address: addressNode }), ...(geoNode && { geo: geoNode }) };
+        }
+      } else {
+        if (addressNode) entity.address = addressNode;
+        if (geoNode && schemaType !== 'TouristTrip') entity.geo = geoNode;
+      }
+      if (item.type === 'restaurants' || item.type === 'bars') {
+        entity.priceRange = normalizePriceRange(item.averagePrice, item.priceFrom);
+        if (item.type === 'restaurants' && item.cuisine) entity.servesCuisine = item.cuisine;
+        const hours = generateOpeningHours(item.openingHours);
+        if (hours) entity.openingHoursSpecification = hours;
+      } else if (item.type === 'monuments' || item.type === 'museums') {
+        const hours = parseHoursString(item.hours);
+        if (hours) entity.openingHoursSpecification = hours;
+      }
+      if (item.type === 'hotels' && item.priceRange) entity.priceRange = normalizeHotelPriceRange(item.priceRange);
+      return entity;
+    };
+    return {
+      '@type': 'ItemList',
+      name: data.name,
+      description: data.description,
+      url: data.url,
+      numberOfItems: data.items?.length || 0,
+      itemListElement: (data.items || []).map((item: any) => ({ '@type': 'ListItem', position: item.rank, item: nested(item) })),
+    };
+  };
+}
+

package/src/schema/city.ts

@@ -0,0 +1,42 @@
+import { geoCoordinates } from '@sarimarcus/content-sites-core/schema';
+import type { AddressPolicy, TouristDestinationFields } from '@sarimarcus/content-sites-core/schema';
+
+/** The city a tourism site covers: every entity's PostalAddress and the default pin come from here. */
+export interface TourismCity {
+  locality: string;
+  region: string;
+  /** ISO 3166-1 alpha-2. */
+  country: string;
+  /** Postal code for an item with none of its own. Leave unset rather than invent one. */
+  postalFallback?: string;
+  geo: { lat: number; lng: number };
+}
+
+/** Fixed locality/region/country from the city; an empty street is kept as `""`. */
+export function cityAddressPolicy(city: TourismCity): AddressPolicy {
+  return {
+    locality: () => city.locality,
+    region: () => city.region,
+    country: () => city.country,
+    postalFallback: city.postalFallback,
+  };
+}
+
+/** The site-level TouristDestination for a city guide: the city, its region and its pin. */
+export function cityDestinationFields(
+  city: TourismCity,
+  copy: { name: string; description: string; touristType?: string },
+): TouristDestinationFields {
+  return {
+    name: copy.name,
+    description: copy.description,
+    address: { '@type': 'PostalAddress', addressLocality: city.locality, addressRegion: city.region, addressCountry: city.country },
+    containedInPlace: {
+      '@type': 'AdministrativeArea',
+      name: city.region,
+      address: { '@type': 'PostalAddress', addressCountry: city.country },
+    },
+    geo: geoCoordinates(city.geo),
+    touristType: copy.touristType ?? 'Cultural',
+  };
+}

package/src/schema/index.ts

@@ -0,0 +1,8 @@
+// Public surface of @sarimarcus/content-sites-tourism/schema: city-entity JSON-LD builders on core `schema`.
+export { cityAddressPolicy, cityDestinationFields } from './city.ts';
+export type { TourismCity } from './city.ts';
+export {
+  monumentBuilder, museumBuilder, restaurantBuilder, barBuilder, dishBuilder, neighborhoodBuilder,
+  guideItemListBuilder, GUIDE_ITEM_TYPES,
+} from './builders.ts';
+export type { MonumentOptions, RestaurantOptions, BarOptions, DishOptions } from './builders.ts';