@lad-sapienza/scms-core 0.1.0-alpha.9 → 0.1.1

package/components/Map/README.md

@@ -1,11 +1,16 @@
 # Map Component
 
-Interactive map built on [MapLibre GL JS](https://maplibre.org/) (via
+Interactive map built on [MapLibre GL JS](https://maplibre.org/) **v6** (via
 `@vis.gl/react-maplibre`). Renders a raster basemap, any number of toggleable
 overlay layers pulled from heterogeneous data sources (GeoJSON, CSV, JSON,
 Directus, a generic API, or raster XYZ/WMS tiles), and a built-in layer
 control for switching basemaps and toggling overlays.
 
+MapLibre v6 requires **WebGL2** (universally supported by current browsers) and
+no longer auto-loads its Web Worker — `Map.tsx` wires the worker up itself with
+a Vite `?worker&url` import, so consuming sites need no bundler/worker config.
+The `maplibre-gl` peer dependency is `^6`.
+
 ## Basic usage
 
 ```mdx
@@ -26,6 +31,30 @@ touching `overlayLayers` directly:
 <Map directus={{ table: 'sites', geoField: 'location' }} />
 ```
 
+For one or a few hand-placed points (e.g. the location of a single site) use
+`markers` — no data file needed. The map fits to them automatically; a lone
+marker is centred at a regional zoom (≥ 12) rather than zoomed to the max:
+
+```mdx
+<Map markers={{ lng: 12.4964, lat: 41.9028, label: 'Roma' }} />
+
+<Map markers={[
+  { lng: 12.49, lat: 41.90, label: 'Site A' },
+  { lng: 12.51, lat: 41.88, label: 'Site B' },
+]} />
+```
+
+`label` is optional (shown in a popup as plain text). Markers are an extra
+overlay layer and combine with any of the shorthands below.
+
+`markersZoom` fixes the zoom: the map is centred on the markers at that level
+instead of being fitted to their extent — useful to give a single site the
+same geographic context on every page:
+
+```mdx
+<Map markers={{ lng: 12.4964, lat: 41.9028, label: 'Roma' }} markersZoom={9} />
+```
+
 `geojson`/`csv`/`json`/`directus` each accept either a bare string (path/URL)
 or an object with `name`, `style`, `popup`, `fitToContent`, `filter` — see
 `MapProps` in [`types.ts`](./types.ts) for the exact shape of each.
@@ -148,6 +177,32 @@ add `popupTemplate`/`fitToContent`/`visible` (properties the style spec
 itself has no room for). See `MapProps` in [`types.ts`](./types.ts) for the
 exact shape.
 
+## Styles (MapLibre CSS)
+
+`Map.tsx` imports `maplibre-gl/dist/maplibre-gl.css` itself, so you do not need
+to import it yourself: it styles the layer control, zoom/compass buttons,
+attribution and popups. Without it the map still renders, but those controls
+and popups appear unstyled.
+
+That import is not always linked from the page in production builds (`astro
+dev` is unaffected). It is missed when `<Map>` is imported from an MDX
+content-collection entry whose `render()`ed `Content` is passed as a prop to
+another component (e.g. `<ArticlePage Content={Content} />`): Astro emits the
+CSS file but no page links it. This happens with every client directive
+(`client:load` and `client:only="react"` alike).
+
+`scms()` works around this by linking the stylesheet from every page. If you
+are on a version that predates that fix, or you set `scms({ mapCss: false })`
+(e.g. because the site has no maps, or to avoid the stylesheet on pages
+without one), import it once in your layout instead:
+
+```astro
+---
+// src/layouts/BaseLayout.astro
+import 'maplibre-gl/dist/maplibre-gl.css';
+---
+```
+
 ## Props
 
 ### `Map`
@@ -199,3 +254,10 @@ exact shape.
   only two functions that build tile URL templates — both `baseLayers` and
   raster `overlayLayers` go through them, so there's one place to fix or
   extend tile-URL construction.
+- MapLibre GL JS v6 dropped the automatic worker bootstrap, so `Map.tsx`
+  imports `maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url` and calls
+  `setWorkerUrl()` at module load, before `@vis.gl/react-maplibre` constructs
+  any map. `?worker&url` (not `?url`) routes the worker through Vite's worker
+  pipeline so its `maplibre-gl-shared.mjs` sibling is bundled in. `scms.ts`
+  adds `ssr.noExternal: ['maplibre-gl']` so that import also resolves in the
+  SSR pass for consumers rendering `<Map client:load>`.

package/components/Map/index.ts

@@ -1,5 +1,4 @@
 export { Map } from './MapMdx';
-export { Map as MapCore } from './Map';
 export { defaultBasemaps, getBasemap, getBasemaps } from './defaultBasemaps';
 export type { BasemapKey } from './defaultBasemaps';
 export type { OverlayLayerConfig } from './types';

package/components/Map/types.ts

@@ -124,6 +124,12 @@ export interface OverlayLayerConfig {
   /** Fit map bounds to layer content */
   fitToContent?: boolean;
 
+  /**
+   * With `fitToContent`: centre on the content's bounds at this fixed zoom
+   * instead of fitting them (used by the `markers` shorthand).
+   */
+  fitZoom?: number;
+
   /** Optional client-side filter for features */
   filter?: FilterObject | ((feature: any) => boolean);
 
@@ -131,6 +137,17 @@ export interface OverlayLayerConfig {
   searchInFields?: SearchInFields;
 }
 
+/**
+ * A single point marker for the `markers` shorthand — for maps with one or a
+ * few hand-placed points, no data file needed.
+ */
+export interface MarkerConfig {
+  lng: number;
+  lat: number;
+  /** Text shown in the popup on hover/click (plain text, HTML-escaped) */
+  label?: string;
+}
+
 export interface MapProps {
   /** Map height (CSS string) */
   height?: string;
@@ -197,6 +214,19 @@ export interface MapProps {
     filter?: FilterObject | ((row: any) => boolean);
   };
   
+  /**
+   * Inline markers - one or a few hand-placed points, e.g. to give the
+   * geographic context of a single site. Rendered as an extra overlay layer
+   * and, by default, the map is fitted to them.
+   */
+  markers?: MarkerConfig | MarkerConfig[];
+
+  /**
+   * Fixed zoom for the `markers`: the map is centred on them at this zoom
+   * instead of being fitted to their extent. Handy for a single site.
+   */
+  markersZoom?: number;
+
   /** JSON shorthand - for simple single-layer maps */
   json?: any[] | string;
   

package/components/Map/utils.ts

@@ -4,7 +4,7 @@
 
 import type { DataRow } from '../../utils/data-fetcher';
 import type { FeatureCollection, Feature, Geometry } from 'geojson';
-import type { WmsSourceConfig } from './types';
+import type { WmsSourceConfig, MarkerConfig } from './types';
 
 /**
  * Tries to identify latitude and longitude fields from a data row
@@ -117,6 +117,24 @@ export function dataToGeoJson(
   };
 }
 
+/**
+ * Converts the `markers` shorthand to a GeoJSON FeatureCollection of points,
+ * dropping entries whose coordinates aren't finite numbers. The label ends up
+ * in the `label` property, which the markers layer's popup template reads.
+ */
+export function markersToGeoJson(markers: MarkerConfig | MarkerConfig[]): FeatureCollection {
+  const list = Array.isArray(markers) ? markers : [markers];
+  const features: Feature[] = list
+    .filter(m => m && m.lng != null && m.lat != null
+      && Number.isFinite(Number(m.lng)) && Number.isFinite(Number(m.lat)))
+    .map(m => ({
+      type: 'Feature',
+      geometry: { type: 'Point', coordinates: [Number(m.lng), Number(m.lat)] },
+      properties: { label: m.label ?? '' }
+    }));
+  return { type: 'FeatureCollection', features };
+}
+
 /**
  * Expands an XYZ tile URL template's {s} subdomain placeholder into the
  * standard a/b/c rotation (as Leaflet does natively). Returns the url

package/components/Record/RecordFetcher.tsx

@@ -49,7 +49,7 @@ function DefaultError({ table, id }: { table: string; id: string }) {
  * **Usage in an Astro page:**
  * ```astro
  * ---
- * import RecordFetcher from '@lad-sapienza/scms-core/components/Record/RecordFetcher.tsx';
+ * import { RecordFetcher } from '@lad-sapienza/scms-core/components/Record';
  * import MyLayout from '@components/MyRecordLayout.tsx';
  * ---
  * <RecordFetcher Layout={MyLayout} client:load />

package/components/Record/useRecordFetcher.ts

@@ -32,7 +32,7 @@ export interface UseRecordFetcherResult {
  * @example
  * ```tsx
  * // src/components/RecordView.tsx
- * import { useRecordFetcher } from '@lad-sapienza/scms-core/components/Record/useRecordFetcher';
+ * import { useRecordFetcher } from '@lad-sapienza/scms-core/components/Record';
  *
  * export default function RecordView() {
  *   const { record, loading, error, table, id } = useRecordFetcher();

package/components/i18n/builtinDictionary.ts

@@ -28,6 +28,7 @@ export const BUILTIN_DICTIONARY: Dictionary = {
   },
   map: {
     defaultLayerName: 'Default Layer',
+    markers: 'Markers',
     baseMaps: 'Base Maps',
     searchLayer: 'Search {name}',
     active: '(Active)',

package/index.ts

@@ -8,7 +8,7 @@ export { default as ThemeToggle } from './components/ThemeToggle';
 export { DataTb, CsvSource, JsonSource, DirectusSource, ApiSource } from './components/DataTb';
 
 // Map components
-export { Map as MapComponent } from './components/Map';
+export { Map } from './components/Map';
 export { SearchUI, SearchUISimple, SearchUIAdvanced } from './components/Map/Search';
 
 // ZoteroGeoViewer component

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lad-sapienza/scms-core",
-  "version": "0.1.0-alpha.9",
+  "version": "0.1.1",
   "description": "Framework components and Astro integrations for s:CMS — DataTb, Gallery, Map, ZoteroGeoViewer, Record.",
   "type": "module",
   "license": "BSD-0-Clause",
@@ -10,10 +10,32 @@
   },
   "author": "Julian Bogdani <julian.bogdani@uniroma1.it>",
   "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts",
+    "./scms": "./scms.ts",
+    "./components/Map": "./components/Map/index.ts",
+    "./components/DataTb": "./components/DataTb/index.ts",
+    "./components/DataTb/types": "./components/DataTb/types.ts",
+    "./components/Gallery": "./components/Gallery/index.ts",
+    "./components/Gallery/Gallery.astro": "./components/Gallery/Gallery.astro",
+    "./components/Record": "./components/Record/index.ts",
+    "./components/ZoteroGeoViewer": "./components/ZoteroGeoViewer/index.ts",
+    "./components/TableOfContents/TableOfContents.astro": "./components/TableOfContents/TableOfContents.astro",
+    "./components/SEO/SEO.astro": "./components/SEO/SEO.astro",
+    "./components/BSNavbar": "./components/BSNavbar.tsx",
+    "./components/LocaleSwitcher": "./components/LocaleSwitcher.tsx",
+    "./components/ThemeToggle": "./components/ThemeToggle.tsx",
+    "./components/RedirectPage/RedirectPage.astro": "./components/RedirectPage/RedirectPage.astro",
+    "./components/i18n": "./components/i18n/index.ts",
+    "./components/i18n/I18nInit.astro": "./components/i18n/I18nInit.astro",
+    "./integrations/directusLoader": "./integrations/directusLoader.ts",
+    "./package.json": "./package.json"
+  },
   "bin": {
     "scms-add-collection": "./bin/add-collection.mjs",
     "scms-add-content": "./bin/add-content.mjs",
-    "scms-create": "./bin/create.mjs"
+    "scms-create": "./bin/create.mjs",
+    "scms-optimize-images": "./bin/optimize-images.mjs"
   },
   "files": [
     "index.ts",
@@ -35,7 +57,7 @@
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "astro": "^7.2.4",
-    "maplibre-gl": "^5.21.0",
+    "maplibre-gl": "^6.7.0",
     "react": "^19.2.4",
     "react-dom": "^19.2.4"
   },
@@ -48,12 +70,13 @@
     "@tanstack/react-table": "^8.21.3",
     "@types/geojson": "^7946.0.16",
     "@types/papaparse": "^5.5.2",
-    "@vis.gl/react-maplibre": "^8.1.0",
+    "@vis.gl/react-maplibre": "^8.1.3",
     "astro-expressive-code": "^0.44.1",
     "lucide-react": "^1.8.0",
     "papaparse": "^5.5.3",
     "photoswipe": "^5.4.4",
     "react-photoswipe-gallery": "^4.0.0",
+    "sharp": "^0.35.3",
     "zod": "^4.3.6"
   },
   "devDependencies": {

package/scms.ts

@@ -36,6 +36,13 @@ export interface ScmsOptions {
   pagesDir?: string;
   /** Path to shared galleries, relative to the project root. Defaults to 'src/galleries'. */
   galleriesDir?: string;
+  /**
+   * Link MapLibre's stylesheet (`maplibre-gl/dist/maplibre-gl.css`, ~83 KB /
+   * ~11 KB gzipped) from every page — see `scmsMapCssIntegration`. Defaults to
+   * `true`. Set `false` for sites that never render `<Map>`, or that import the
+   * stylesheet themselves.
+   */
+  mapCss?: boolean;
 }
 
 /** react, react-dom, and any library that calls hooks internally (@tanstack/react-table) — see file doc comment. */
@@ -64,22 +71,34 @@ function scmsViteConfigIntegration(): AstroIntegration {
               dedupe: HOOK_LIBRARIES,
             },
             optimizeDeps: {
-              // papaparse is CommonJS-only (no `module`/`exports` field), and
-              // maplibre-gl's `dist/maplibre-gl.js` is a UMD bundle despite
-              // declaring `"type": "module"` in its own package.json (verified:
-              // it's a `(function(global, factory) {...})` UMD wrapper with zero
-              // `export` statements). When their importers (CsvSource.tsx,
-              // Map.tsx via @vis.gl/react-maplibre's dynamic `import('maplibre-gl')`)
-              // lived inside this project's own source tree, Vite's dev-time
-              // dependency scanner discovered and pre-bundled them automatically,
-              // performing the CJS/UMD→ESM interop conversion. Now that the
-              // importers live in node_modules (this package), Vite's default
-              // scanning no longer picks them up on its own, and the browser gets
-              // served the raw file as if it already were ESM — resulting in
-              // "does not provide an export named 'default'" for papaparse and
-              // an empty module namespace (silently breaking `'Map' in module`)
-              // for maplibre-gl. Both must be pre-bundled explicitly.
-              include: ['react', 'react-dom', 'react-dom/client', 'react/jsx-runtime', 'react/jsx-dev-runtime', 'papaparse', 'maplibre-gl'],
+              // papaparse is CommonJS-only (no `module`/`exports` field). Its
+              // importer (CsvSource.tsx) lives in node_modules once this is a
+              // published package, so Vite's dev-time dependency scanner no
+              // longer discovers it on its own and pre-bundles the CJS→ESM
+              // interop — without this entry the browser is served the raw CJS
+              // file and crashes with "does not provide an export named
+              // 'default'". Must stay explicit.
+              //
+              // maplibre-gl used to need the same treatment because v5 shipped a
+              // UMD `dist/maplibre-gl.js`; v6 is real ESM (`dist/maplibre-gl.mjs`,
+              // `"exports"` map, no UMD), so Vite handles it with no interop
+              // shim and no explicit entry here. Map.tsx's `?worker&url` worker
+              // chunk is a separate, self-contained module and does not go
+              // through this pre-bundle.
+              include: ['react', 'react-dom', 'react-dom/client', 'react/jsx-runtime', 'react/jsx-dev-runtime', 'papaparse'],
+            },
+            ssr: {
+              // MapLibre GL JS v6's worker is wired up in Map.tsx via a
+              // `maplibre-gl/dist/...?worker&url` import (see that file). Vite's
+              // worker plugin can only resolve that specifier when maplibre-gl
+              // is bundled for SSR rather than externalised to a raw Node
+              // `import`. MapLibre's own Astro guidance calls for this.
+              //
+              // This is about the worker only. It has no bearing on whether the
+              // stylesheet reaches the page — that is a separate problem, with
+              // the same symptom under every client directive (`client:load`
+              // and `client:only` alike); see `scmsMapCssIntegration`.
+              noExternal: ['maplibre-gl'],
             },
           },
         });
@@ -100,8 +119,40 @@ function scmsThemeInitIntegration(): AstroIntegration {
   };
 }
 
+/**
+ * Links MapLibre's stylesheet from every page.
+ *
+ * `Map.tsx` imports `maplibre-gl/dist/maplibre-gl.css` itself, which is enough
+ * when `<Map>` is imported straight into a page or layout. It is NOT enough
+ * for a `<Map>` imported from an MDX content-collection entry whose
+ * `render()`ed `Content` is handed down as a prop to another component (e.g.
+ * `<ArticlePage Content={Content} />`, which then renders `<Content />` inside
+ * a layout): Astro still emits the stylesheet but never links it from the
+ * page's HTML, so the layer control, zoom buttons and popups render unstyled
+ * in production builds. `astro dev` is unaffected (Vite injects CSS at
+ * runtime), which is why it only shows up after `astro build`. Reproduced on
+ * Astro 7.2.4 with `client:load` and `client:only="react"`.
+ *
+ * Importing the stylesheet from `page-ssr` puts it in every page's own module
+ * graph, so it is linked regardless of how the MDX is rendered. Costs: one
+ * cached, render-blocking ~11 KB (gzipped) request on pages that have no map —
+ * hence the `mapCss` opt-out — and, for a `<Map client:only>` imported
+ * directly into a page, a second identical-content file (Astro emits the
+ * island's copy separately), which is redundant but harmless.
+ */
+function scmsMapCssIntegration(): AstroIntegration {
+  return {
+    name: 'scms-map-css',
+    hooks: {
+      'astro:config:setup': ({ injectScript }) => {
+        injectScript('page-ssr', "import 'maplibre-gl/dist/maplibre-gl.css';");
+      },
+    },
+  };
+}
+
 export function scms(options: ScmsOptions = {}): AstroIntegration[] {
-  const { contentDir, pagesDir, galleriesDir } = options;
+  const { contentDir, pagesDir, galleriesDir, mapCss = true } = options;
 
   return [
     contentAssetsIntegration({ contentDir }),
@@ -116,5 +167,6 @@ export function scms(options: ScmsOptions = {}): AstroIntegration[] {
     sitemap(),
     scmsViteConfigIntegration(),
     scmsThemeInitIntegration(),
+    ...(mapCss ? [scmsMapCssIntegration()] : []),
   ];
 }

package/template/README.md.tmpl

@@ -14,6 +14,19 @@ Built with [s:CMS](https://github.com/lad-sapienza/scms-core), on top of [Astro]
 | `npm run preview` | Preview the production build locally |
 | `npm run add-collection` | Scaffold a new content collection |
 | `npm run add-content` | Add a new content file to an existing collection |
+| `npm run images` | Convert content images to WebP (max 2000 px) and rewrite their references |
+
+## Optimizing images
+
+Drop JPG/PNG images next to your content as usual, then run `npm run images`: they are converted to WebP, scaled down to 2000 px, the originals are deleted and the `.md`/`.mdx` references are rewritten (`--dry-run` shows the savings without touching anything). References from `.astro`/`.tsx` files are only reported — update them by hand.
+
+To make the build fail when an unoptimized image slips in, add a check to `package.json`; it never modifies any file:
+
+```json
+"prebuild": "scms-optimize-images --check"
+```
+
+Limits, quality and the site languages are configured in `src/user.config.mjs` (`userConfig.images`, `userConfig.i18n`); see the [scms-core README](https://github.com/lad-sapienza/scms-core#image-optimization) for all the options, including an optional pre-commit hook. Commit the `.scms-optimize-images.json` file it may create.
 
 ## Updating the framework
 

package/template/package.json.tmpl

@@ -10,7 +10,8 @@
     "preview": "astro preview",
     "astro": "astro",
     "add-collection": "scms-add-collection",
-    "add-content": "scms-add-content"
+    "add-content": "scms-add-content",
+    "images": "scms-optimize-images"
   },
   "dependencies": {
     "@astrojs/check": "^0.9.10",