@lad-sapienza/scms-core 0.1.0-alpha.8 → 0.1.0

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.
@@ -199,3 +228,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.8",
+  "version": "0.1.0",
   "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

@@ -64,22 +64,31 @@ 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` — required for consumers that render <Map> with
+              // `client:load`/`client:visible` (server pass) rather than
+              // `client:only`. MapLibre's own Astro guidance calls for this.
+              noExternal: ['maplibre-gl'],
             },
           },
         });

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",