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

package/README.md

@@ -10,7 +10,20 @@ This package supplies the `core/` framework layer that used to live inside the s
 npm install @lad-sapienza/scms-core
 ```
 
-Peer dependencies (install alongside): `astro`, `react`, `react-dom`, `maplibre-gl`, `@types/react`, `@types/react-dom`.
+Peer dependencies (install alongside): `astro`, `react`, `react-dom`, `maplibre-gl` (v6+), `@types/react`, `@types/react-dom`.
+
+### Requirements
+
+scms-core is an **Astro** package. It ships TypeScript, React and `.astro` sources
+that the host site's Astro/Vite pipeline compiles; it is not usable from plain
+Node, or from tooling that doesn't understand `.astro` and `.tsx`. Astro is a
+requirement of the package, not an optional extra.
+
+| Dependency | Minimum |
+|---|---|
+| `astro` | 7.2.4 |
+| `react`, `react-dom` | 19.2.4 |
+| `maplibre-gl` | 6.7.0 (needs WebGL2) |
 
 ## Usage
 
@@ -37,7 +50,7 @@ export default defineConfig({
 });
 ```
 
-`scms()` bundles content-asset serving, the Gallery virtual module, Expressive Code, MDX, React, and sitemap integrations into one call, and self-registers the Vite `dedupe`/`optimizeDeps` config React and `@tanstack/react-table` need to avoid duplicate-module "Invalid hook call" errors — no extra Vite config required in the consumer.
+`scms()` bundles content-asset serving, the Gallery virtual module, Expressive Code, MDX, React, and sitemap integrations into one call, and self-registers the Vite config the components need — `dedupe`/`optimizeDeps` for React and `@tanstack/react-table` (avoids duplicate-module "Invalid hook call" errors) and `ssr.noExternal` for `maplibre-gl` (so the `Map` component's MapLibre v6 worker import resolves in the SSR pass). No extra Vite config required in the consumer.
 
 Import components from the package root in any `.mdx` file:
 
@@ -48,7 +61,7 @@ import { DataTb, Map, Gallery } from '@lad-sapienza/scms-core';
 | Component | Description |
 |---|---|
 | `DataTb` | Sortable, filterable, paginated data table |
-| `MapComponent` (`Map`) | Interactive map with MapLibre GL JS |
+| `Map` | Interactive map with MapLibre GL JS |
 | `Gallery` | Responsive image gallery with lightbox |
 | `TableOfContents` | Auto-generated TOC from headings |
 | `RedirectPage` | Static client-side redirect stub (meta-refresh + JS fallback) for static hosts |
@@ -56,7 +69,27 @@ import { DataTb, Map, Gallery } from '@lad-sapienza/scms-core';
 | `RecordProvider`, `Field`, `Image`, `RecordFetcher`, `useRecordFetcher` | Build single-record detail pages against Directus |
 | `SearchUI`, `SearchUISimple`, `SearchUIAdvanced` | Field/operator/value search UI (used by `Map`'s `searchInFields`) |
 
-A few components are reachable only via subpath import, not the root barrel — this mirrors the internal layout, no bundler config or `exports` map restricts it:
+Only the entry points below are public API: the package declares an
+[`exports`](https://nodejs.org/api/packages.html#exports) map, and importing any
+other path (e.g. `.../utils/...`, `.../components/DataTb/DataTbMdx`) fails to
+resolve. Everything is also available from the root barrel except the `.astro`
+components and the ones listed here:
+
+| Import path | Provides |
+|---|---|
+| `@lad-sapienza/scms-core` | root barrel — `DataTb`, `Map`, `Gallery`, `Record*`, `RedirectPage`, `ZoteroGeoViewer`, i18n helpers |
+| `@lad-sapienza/scms-core/scms` | `scms()` — use this (not the root) in `astro.config.mjs` |
+| `.../components/Map` | `Map`, map types, `defaultBasemaps` |
+| `.../components/DataTb`, `.../components/DataTb/types` | `DataTb` and the source components; table types |
+| `.../components/Gallery`, `.../components/Gallery/Gallery.astro` | `Gallery` (named export / `.astro` default) |
+| `.../components/Record` | `RecordProvider`, `Field`, `Image`, `RecordFetcher`, `useRecordFetcher` |
+| `.../components/ZoteroGeoViewer` | `ZoteroGeoViewer` |
+| `.../components/TableOfContents/TableOfContents.astro` | `TableOfContents` |
+| `.../components/SEO/SEO.astro` | `SEO` |
+| `.../components/BSNavbar`, `.../components/LocaleSwitcher`, `.../components/ThemeToggle` | layout components (default exports) |
+| `.../components/RedirectPage/RedirectPage.astro` | `RedirectPage` |
+| `.../components/i18n`, `.../components/i18n/I18nInit.astro` | translation helpers; `I18nInit` |
+| `.../integrations/directusLoader` | `directusLoader` for `content.config.ts` |
 
 ```js
 import SEO from '@lad-sapienza/scms-core/components/SEO/SEO.astro';
@@ -87,6 +120,98 @@ npx scms-add-content      # add a new content file to an existing collection
 
 A consuming site typically wires these up as `npm run add-collection` / `npm run add-content` in its own `package.json` (this is what `scms-create` sets up automatically).
 
+Both commands are multilingual-aware. `scms-add-collection` optionally takes a list of locale codes and scaffolds one sample per `src/content/<name>/<locale>/` folder; `scms-add-content` detects those language folders (every sub-folder is a locale code, nothing loose at the collection root) and asks which language the new file belongs in — a single locale, a comma-separated subset, or `all`.
+
+## Image optimization
+
+`scms-optimize-images` is a maintenance command (also a `bin`, run from the site's project root) that keeps the images in your content light: it converts every JPG/JPEG/PNG under the content folder to WebP, scales them down to a maximum size, deletes the originals and rewrites every reference to them in your `.md`/`.mdx` files. It uses [sharp](https://sharp.pixelplumbing.com/), so nothing else needs to be installed on the machine.
+
+```bash
+npx scms-optimize-images              # convert, delete the originals, rewrite references
+npx scms-optimize-images --dry-run    # print the estimated savings, touch nothing
+npx scms-optimize-images --check      # touch nothing; exit 1 if something is left to do
+npx scms-optimize-images --only a.jpg b.png   # limit the work to these files
+```
+
+Wire it up in the site's `package.json`:
+
+```json
+{
+  "scripts": {
+    "images": "scms-optimize-images",
+    "prebuild": "scms-optimize-images --check"
+  }
+}
+```
+
+`--check` never changes anything — the build must not modify or delete source files. It exits with a non-zero code (and lists the offenders) if it finds a JPG/PNG that could be converted, a WebP larger than the maximum size, or a stale reference from code (see below), so a forgotten image fails the build or the CI instead of being published at 5 MB. Fix it locally with `npm run images`, review the diff, commit.
+
+### What it does
+
+- **Resize**: the long side is limited to `maxSize` (2000 px); images are only ever scaled down. EXIF orientation is applied and metadata stripped.
+- **JPG → lossy WebP** at quality 82. **PNG → lossless WebP**; if the result is still larger than 50% of the original *and* the original is over 500 KB, it falls back to lossy WebP (quality 85, alpha quality 100).
+- **Not lighter, not converted**: when the WebP would not be smaller than the original, the original is left as it is. The verdict is stored (file hash + settings) in `.scms-optimize-images.json` at the project root — **commit it** — so such images are neither re-encoded on every run nor reported again by `--check`. Replace the file, or change a setting, and it is evaluated again.
+- **References** in `.md`/`.mdx` files (frontmatter such as `img:`, `![](…)`, relative and absolute paths) are rewritten. Absolute paths are rooted at the content folder, as in `contentAssetsIntegration`. `%20` is decoded and names are compared case-insensitively.
+- **Languages**: pages in a non-default language usually have no assets of their own and reuse those of the default-language twin (`blog/en/post/index.md` citing `a.jpg` that lives in `blog/it/post/`). Such references are resolved by swapping the language folder for the default one — using the languages declared in `userConfig.i18n` (below), not fixed codes.
+- **Name conflicts**: `bdus.jpg` + `bdus.png` would both become `bdus.webp`. The one cited by a `.md`/`.mdx` in the same folder (or its twin in another language) is kept, the other is deleted; if that does not single one out, both are skipped and reported.
+- **WebP already larger than `maxSize`** are scaled down in place (lossless stays lossless, lossy is re-encoded at `quality`), and reported by `--check`.
+- **Idempotent**: a second run changes nothing (and takes a fraction of a second).
+- The report lists converted files, skipped ones (with the reason), deleted duplicates and converted WebP that nothing cites (images in `gallery/` folders are not expected to be cited).
+
+### References in code
+
+Only `.md`/`.mdx` files are rewritten. Images can also be referenced from `.astro`, `.jsx`, `.tsx`, `.ts`, `.js` and `.mjs` files under `src/` (`<img src="/didattica/cover.jpg">`, `import x from '@content/…'`): those are **never rewritten** — every one that points at an image that is, or was, converted is reported with file and line, and the command exits with an error:
+
+```
+src/pages/[locale]/didattica/index.astro:22  /didattica/cover.jpg is now broken: the image was converted → use /didattica/cover.webp
+```
+
+The report keeps coming back (also from `--check`) until the code is fixed, so a broken link cannot slip through silently. Paths are resolved from the content folder (`/…`), from the file (`./…`, `../…`) and through the `@content/` and `@user/` aliases.
+
+### Configuration
+
+All optional; defaults shown. In `src/user.config.mjs`:
+
+```js
+export const userConfig = {
+  // Languages of the site. Pages in a language other than defaultLocale may reuse
+  // the images of the defaultLocale twin. Omit for a monolingual site.
+  i18n: {
+    defaultLocale: 'it',
+    locales: ['it', 'en'],
+  },
+
+  images: {
+    contentDir: 'src/content',  // scanned for images and .md/.mdx files
+    srcDir: 'src',              // scanned for references from code
+    maxSize: 2000,              // px, long side
+    quality: 82,                // WebP quality for JPGs (and for re-encoded lossy WebP)
+    pngLossyRatio: 0.5,         // PNG: go lossy if lossless WebP > this fraction of the original...
+    pngLossyMinSize: 500,       // ...and the original is larger than this many KB
+    pngLossyQuality: 85,        // quality of that lossy fallback
+    exclude: [],                // folders left alone: paths relative to contentDir, or plain folder names
+  },
+};
+```
+
+Keep `i18n` in sync with the site's own locale list (e.g. `LOCALES`/`DEFAULT_LOCALE` in `src/utils/i18n.ts`). Images outside the content folder (e.g. `public/`) are never touched.
+
+### Optional: pre-commit hook
+
+Nothing is installed automatically. If you want images checked at commit time, add `.git/hooks/pre-commit` (or the equivalent in husky/lefthook) and make it executable. It only looks at the images staged in the commit:
+
+```sh
+#!/bin/sh
+# Block the commit if a staged image is not optimized
+git diff --cached --name-only --diff-filter=AM -z -- '*.jpg' '*.jpeg' '*.png' '*.JPG' '*.JPEG' '*.PNG' '*.webp' \
+  | xargs -0 npx scms-optimize-images --check --only || {
+    echo "Run 'npm run images', review the changes and stage them." >&2
+    exit 1
+  }
+```
+
+An empty list is fine: `--only` with no files does nothing and exits 0. To convert instead of just blocking, run `npx scms-optimize-images --only <files>` and then `git add` the converted `.webp` files and the rewritten `.md`/`.mdx` — the command never stages anything itself.
+
 ## Development
 
 ```bash

package/bin/add-collection.mjs

@@ -468,6 +468,27 @@ async function main() {
   const typeRaw = (await ask('Choose type [1/2/3] (default: 3): ')).trim() || '3';
   const colType = typeRaw === '1' ? 'blog' : typeRaw === '2' ? 'docs' : 'generic';
   ok(`Type: ${colType}`);
+
+  // ─── Prompt: language folders (multilingual collection) ──────────────────
+  // A site can organise a collection's content per language, as
+  // src/content/<col>/<locale>/… — s:CMS's i18n layer is structural, it keys
+  // off those folders existing rather than a config flag. Ask up front so the
+  // sample file(s) land in the right place. (The page templates written below
+  // are single-language starting points regardless — see the closing notes.)
+  console.log('');
+  console.log(`${B}Language folders${X} — for a multilingual collection, list the locale`);
+  console.log(`  codes to scaffold (e.g. ${B}en, it${X}). Leave blank for a single-language collection.`);
+  let locales = [];
+  while (true) {
+    const raw = (await ask('  Locale codes [blank = none]: ')).trim();
+    if (!raw) break;
+    const parsed = raw.split(',').map(s => s.trim().toLowerCase()).filter(Boolean);
+    const bad = parsed.filter(p => !/^[a-z]{2}(?:[-_][a-z0-9]{2,4})?$/i.test(p));
+    if (bad.length) { warn(`Not a locale code: ${bad.join(', ')} (expected e.g. en, it, pt-BR)`); continue; }
+    locales = [...new Set(parsed)];
+    break;
+  }
+  if (locales.length) ok(`Language folders: ${locales.join(', ')}`);
   rl.close();
 
   // ─── 1. Update src/content.config.ts ──────────────────────────────────────
@@ -505,10 +526,9 @@ async function main() {
   writeFileSync(CONFIG_FILE, before + after, 'utf8');
   ok('src/content.config.ts updated');
 
-  // ─── 2. Sample content file ───────────────────────────────────────────────
+  // ─── 2. Sample content file(s) ───────────────────────────────────────────
   const today      = new Date().toISOString().slice(0, 10);
   const contentDir = join(ROOT_DIR, 'src', 'content', colName);
-  mkdirSync(contentDir, { recursive: true });
 
   const SAMPLE_NAME = { blog: 'sample-post.md', docs: 'sample-doc.md', generic: 'sample.md' };
   const SAMPLE_BODY = {
@@ -529,9 +549,16 @@ async function main() {
       `# Sample Entry\n\nThis is a sample entry. Replace this file with real content.\n`,
   };
 
-  const samplePath = join(contentDir, SAMPLE_NAME[colType]);
-  writeFileSync(samplePath, SAMPLE_BODY[colType], 'utf8');
-  ok(relative(ROOT_DIR, samplePath));
+  // One sample per language folder for a multilingual collection, otherwise a
+  // single sample in the collection root. The copies are identical starting
+  // points — translations get written by hand afterwards.
+  const sampleDirs = locales.length ? locales.map(loc => join(contentDir, loc)) : [contentDir];
+  for (const dir of sampleDirs) {
+    mkdirSync(dir, { recursive: true });
+    const samplePath = join(dir, SAMPLE_NAME[colType]);
+    writeFileSync(samplePath, SAMPLE_BODY[colType], 'utf8');
+    ok(relative(ROOT_DIR, samplePath));
+  }
 
   // ─── 3. Page templates ────────────────────────────────────────────────────
   const pagesDir = join(ROOT_DIR, 'src', 'pages', colName);
@@ -553,7 +580,11 @@ async function main() {
   console.log(`  ${B}Next steps:${X}`);
   console.log(`    1. Open ${B}src/content.config.ts${X} and review the schema for '${colName}'`);
   console.log(`    2. Edit the page files in ${B}src/pages/${colName}/${X} to customise the UI`);
-  console.log(`    3. Replace the sample file in ${B}src/content/${colName}/${X} with real content`);
+  if (locales.length) {
+    console.log(`       ${Y}These render a single language — adapt them to your locale`);
+    console.log(`       routing (e.g. move them under src/pages/[locale]/${colName}/).${X}`);
+  }
+  console.log(`    3. Replace the sample file${locales.length ? 's' : ''} in ${B}src/content/${colName}/${X} with real content`);
   console.log(`    4. Run ${B}npm run dev${X} and visit ${B}/${colName}${X}`);
   console.log('');
 }

package/bin/add-content.mjs

@@ -75,6 +75,36 @@ function hasMdx(dir) {
   } catch { return false; }
 }
 
+/** True if any .md/.mdx file sits directly in dir (not in a sub-folder) */
+function hasRootContentFiles(dir) {
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+      .some(d => d.isFile() && /\.mdx?$/.test(d.name));
+  } catch { return false; }
+}
+
+/**
+ * Locale-code sub-directories directly inside a collection dir — e.g.
+ * `en`, `it`, `pt-BR`. Their presence is how a site opts a collection in to
+ * per-language content: there is no config flag (s:CMS's i18n layer is
+ * structural — it keys off these folders existing). The pattern is a
+ * 2-letter base with an optional region/script suffix (`pt-BR`, `zh-Hans`),
+ * and — to keep ordinary topic folders (`api`, `guides`) from being taken
+ * for languages — this returns nothing unless *every* sub-folder matches.
+ * Sorted, for a stable prompt order.
+ */
+function detectLocaleDirs(dir) {
+  let subdirs;
+  try {
+    subdirs = readdirSync(dir, { withFileTypes: true })
+      .filter(d => d.isDirectory())
+      .map(d => d.name);
+  } catch { return []; }
+  if (subdirs.length === 0) return [];
+  const locales = subdirs.filter(n => /^[a-z]{2}(?:[-_][a-z0-9]{2,4})?$/i.test(n));
+  return locales.length === subdirs.length ? locales.sort() : [];
+}
+
 /** Extract z.object field lines for a named collection from config.ts */
 function parseSchemaFields(src, colName) {
   const pat = new RegExp(
@@ -163,9 +193,37 @@ async function main() {
   }
   ok(`Collection: ${collection}`);
 
+  const colDir = join(CONTENT_BASE, collection);
+
+  // ─── Prompt: language folder (multilingual collections only) ─────────────
+  // A collection counts as multilingual purely by its layout: content split
+  // into locale-named sub-folders (src/content/<col>/<locale>/…) with nothing
+  // loose at the collection root. When that's the case, ask which locale
+  // folder(s) the new file belongs in — one, a comma-separated subset, or
+  // `all`. Collections that aren't organised this way skip the step entirely
+  // and behave exactly as before.
+  const localeDirs = hasRootContentFiles(colDir) ? [] : detectLocaleDirs(colDir);
+  let targetLocales = ['']; // '' → straight into the collection root (single-language)
+  if (localeDirs.length > 0) {
+    console.log('');
+    console.log(`  This collection is organised by language folder: ${B}${localeDirs.join(', ')}${X}`);
+    console.log('  Enter one language, a comma-separated list, or "all".');
+    console.log('');
+    while (true) {
+      const raw = (await ask(`${B}Language${X} [${[...localeDirs, 'all'].join(' / ')}]: `)).trim().toLowerCase();
+      if (!raw) { warn('Please choose a language (or "all").'); continue; }
+      if (raw === 'all') { targetLocales = [...localeDirs]; break; }
+      const picked  = raw.split(',').map(s => s.trim()).filter(Boolean);
+      const unknown = picked.filter(p => !localeDirs.includes(p));
+      if (unknown.length) { warn(`Not an available language: ${unknown.join(', ')}`); continue; }
+      targetLocales = [...new Set(picked)];
+      break;
+    }
+    ok(`Language: ${targetLocales.join(', ')}`);
+  }
+
   // ─── Prompt: file format ─────────────────────────────────────────────────
-  const colDir     = join(CONTENT_BASE, collection);
-  const defaultExt = hasMdx(colDir) ? 'mdx' : 'md';
+  const defaultExt = targetLocales.some(loc => hasMdx(join(colDir, loc))) ? 'mdx' : 'md';
   console.log('');
   const extRaw = (await ask(`${B}File format${X} [md/mdx] (default: ${defaultExt}): `)).trim() || defaultExt;
   const ext    = (extRaw === 'md' || extRaw === 'mdx') ? extRaw : defaultExt;
@@ -183,8 +241,9 @@ async function main() {
       warn('Slug must contain only lowercase letters, numbers, hyphens, underscores, and forward slashes.');
       continue;
     }
-    if (existsSync(join(colDir, raw, `index.${ext}`))) {
-      warn(`File already exists: src/content/${collection}/${raw}/index.${ext}`);
+    const clash = targetLocales.find(loc => existsSync(join(colDir, loc, raw, `index.${ext}`)));
+    if (clash !== undefined) {
+      warn(`File already exists: ${relative(ROOT_DIR, join(colDir, clash, raw, `index.${ext}`))}`);
       continue;
     }
     slug = raw;
@@ -234,11 +293,7 @@ async function main() {
 
   rl.close();
 
-  // ─── Write file ───────────────────────────────────────────────────────────
-  const targetDir  = join(colDir, slug);
-  const targetPath = join(targetDir, `index.${ext}`);
-  mkdirSync(targetDir, { recursive: true });
-
+  // ─── Write file(s) ────────────────────────────────────────────────────────
   const content = [
     '---',
     ...fmLines,
@@ -250,19 +305,39 @@ async function main() {
     '',
   ].join('\n');
 
-  writeFileSync(targetPath, content, 'utf8');
+  // One copy per chosen language folder (just one entry, '', for a
+  // single-language collection). Each copy is an identical starting point —
+  // the per-locale translations are written afterwards, by hand.
+  const created = [];
+  for (const loc of targetLocales) {
+    const targetDir  = join(colDir, loc, slug);
+    const targetPath = join(targetDir, `index.${ext}`);
+    mkdirSync(targetDir, { recursive: true });
+    writeFileSync(targetPath, content, 'utf8');
+    created.push(relative(ROOT_DIR, targetPath));
+  }
 
   console.log('');
-  ok(`Created: ${relative(ROOT_DIR, targetPath)}`);
+  for (const p of created) ok(`Created: ${p}`);
 
   // ─── Summary ──────────────────────────────────────────────────────────────
+  const multilingual = targetLocales.some(Boolean);
   console.log('');
   console.log(`${G}${B}Done!${X}`);
   console.log('');
   console.log(`  ${B}Next steps:${X}`);
-  console.log(`    1. Open ${B}src/content/${collection}/${slug}/index.${ext}${X} and write your content`);
+  if (multilingual) {
+    console.log(`    1. Open the new file${created.length > 1 ? 's' : ''} and write ${created.length > 1 ? 'each translation' : 'your content'}:`);
+    for (const p of created) console.log(`         ${B}${p}${X}`);
+  } else {
+    console.log(`    1. Open ${B}${created[0]}${X} and write your content`);
+  }
   console.log(`    2. Set ${B}draft: false${X} when the content is ready to publish`);
-  console.log(`    3. Run ${B}npm run dev${X} and visit ${B}/${collection}/${slug}${X}`);
+  if (multilingual) {
+    console.log(`    3. Run ${B}npm run dev${X} and visit the new page (e.g. ${B}/${targetLocales[0]}/${collection}/${slug}${X}, depending on your locale routing)`);
+  } else {
+    console.log(`    3. Run ${B}npm run dev${X} and visit ${B}/${collection}/${slug}${X}`);
+  }
   console.log('');
 }
 

package/bin/create.mjs

@@ -115,7 +115,7 @@ async function main() {
     __ASTRO_VERSION__: bareVersion(peers.astro ?? '7.0.0'),
     __REACT_VERSION__: bareVersion(peers.react ?? '19.0.0'),
     __REACT_DOM_VERSION__: bareVersion(peers['react-dom'] ?? '19.0.0'),
-    __MAPLIBRE_VERSION__: bareVersion(peers['maplibre-gl'] ?? '5.0.0'),
+    __MAPLIBRE_VERSION__: bareVersion(peers['maplibre-gl'] ?? '6.0.0'),
     __TYPES_REACT_VERSION__: bareVersion(peers['@types/react'] ?? '19.0.0'),
     __TYPES_REACT_DOM_VERSION__: bareVersion(peers['@types/react-dom'] ?? '19.0.0'),
   };