@lad-sapienza/scms-core 0.1.0-alpha.0

package/integrations/galleryIntegration.ts

@@ -0,0 +1,78 @@
+/**
+ * galleryIntegration
+ *
+ * Registers the virtual module `virtual:scms/galleries`, which holds the
+ * import.meta.glob() calls the Gallery component needs to auto-load images.
+ *
+ * Vite requires import.meta.glob patterns to be static string literals in the
+ * file that calls them — a plain relative pattern shipped inside a
+ * node_modules/ package would resolve against the package's own folder, never
+ * the consumer project's. Because this module's source is generated here
+ * (not shipped verbatim as part of the component), the literal lives in code
+ * Vite parses fresh in the consumer's own build, satisfying that requirement.
+ * Verified empirically (2026-08-22): a generated virtual module's glob still
+ * goes through Astro's image pipeline (hashed src + width/height), not just
+ * raw strings — see project memory for the prototype that confirmed this.
+ */
+import type { AstroIntegration } from 'astro';
+
+export const GALLERY_VIRTUAL_MODULE_ID = 'virtual:scms/galleries';
+const RESOLVED_VIRTUAL_MODULE_ID = '\0' + GALLERY_VIRTUAL_MODULE_ID;
+
+const IMAGE_EXTENSIONS = '{jpg,jpeg,png,gif,webp,avif,JPG,JPEG,PNG,GIF,WEBP,AVIF}';
+
+export interface GalleryIntegrationOptions {
+  /** Path to page files, relative to the project root. Defaults to 'usr/pages'. */
+  pagesDir?: string;
+  /** Path to content collections, relative to the project root. Defaults to 'usr/content'. */
+  contentDir?: string;
+  /** Path to shared galleries, relative to the project root. Defaults to 'usr/galleries'. */
+  galleriesDir?: string;
+}
+
+/** Normalize a directory segment into a Vite root-relative glob prefix, e.g. 'usr/pages' -> '/usr/pages'. */
+function toRootGlobPrefix(dir: string): string {
+  return '/' + dir.replace(/^\/+|\/+$/g, '');
+}
+
+export function buildGalleryVirtualModuleSource(options: GalleryIntegrationOptions = {}): string {
+  const pages = toRootGlobPrefix(options.pagesDir ?? 'usr/pages');
+  const content = toRootGlobPrefix(options.contentDir ?? 'usr/content');
+  const galleries = toRootGlobPrefix(options.galleriesDir ?? 'usr/galleries');
+
+  return `
+export const pagesImages = import.meta.glob('${pages}/**/gallery/*.${IMAGE_EXTENSIONS}', { eager: true });
+export const contentImages = import.meta.glob('${content}/**/gallery/*.${IMAGE_EXTENSIONS}', { eager: true });
+export const sharedImages = import.meta.glob('${galleries}/*/*.${IMAGE_EXTENSIONS}', { eager: true });
+export const pagesCaptions = import.meta.glob('${pages}/**/gallery/captions.json', { eager: true });
+export const contentCaptions = import.meta.glob('${content}/**/gallery/captions.json', { eager: true });
+export const sharedCaptions = import.meta.glob('${galleries}/*/captions.json', { eager: true });
+`;
+}
+
+export function galleryIntegration(options: GalleryIntegrationOptions = {}): AstroIntegration {
+  const virtualModuleSource = buildGalleryVirtualModuleSource(options);
+
+  return {
+    name: 'scms-gallery',
+    hooks: {
+      'astro:config:setup': ({ updateConfig }) => {
+        updateConfig({
+          vite: {
+            plugins: [
+              {
+                name: 'scms-gallery-virtual-module',
+                resolveId(id: string) {
+                  if (id === GALLERY_VIRTUAL_MODULE_ID) return RESOLVED_VIRTUAL_MODULE_ID;
+                },
+                load(id: string) {
+                  if (id === RESOLVED_VIRTUAL_MODULE_ID) return virtualModuleSource;
+                },
+              },
+            ],
+          },
+        });
+      },
+    },
+  };
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@lad-sapienza/scms-core",
+  "version": "0.1.0-alpha.0",
+  "description": "Framework components and Astro integrations for s:CMS — DataTb, Gallery, Map, ZoteroGeoViewer, Record.",
+  "type": "module",
+  "license": "BSD-0-Clause",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lad-sapienza/scms-core.git"
+  },
+  "author": "Julian Bogdani <julian.bogdani@uniroma1.it>",
+  "main": "./index.ts",
+  "files": [
+    "index.ts",
+    "scms.ts",
+    "components",
+    "integrations",
+    "utils",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "astro": "^7.2.4",
+    "maplibre-gl": "^5.21.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4"
+  },
+  "dependencies": {
+    "@astrojs/mdx": "^7.0.7",
+    "@astrojs/react": "^6.0.4",
+    "@astrojs/sitemap": "^3.7.3",
+    "@directus/sdk": "^21.2.0",
+    "@expressive-code/plugin-line-numbers": "^0.44.1",
+    "@tanstack/react-table": "^8.21.3",
+    "@types/geojson": "^7946.0.16",
+    "@types/papaparse": "^5.5.2",
+    "@vis.gl/react-maplibre": "^8.1.0",
+    "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",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11"
+  }
+}

package/scms.ts

@@ -0,0 +1,95 @@
+/**
+ * scms
+ *
+ * Bundles every integration sCMS's components need, plus the Vite config
+ * (React/@tanstack dedupe, optimizeDeps) they depend on, into one function.
+ *
+ * Why the dedupe/optimizeDeps live here rather than in the consumer's own
+ * astro.config.mjs: confirmed empirically (2026-08-22, npm-packaging
+ * prototype — see project memory) that without an explicit Vite `dedupe`
+ * entry, React and @tanstack/react-table can resolve to two different
+ * physical module copies in the same render tree, crashing with "Invalid
+ * hook call" in dev mode specifically (a production build can look fine and
+ * still be broken in dev). Registering it from the integration itself means
+ * every consumer gets the fix automatically, instead of needing to
+ * hand-configure Vite themselves.
+ *
+ * This file has no path-alias dependency, by design — it's consumed
+ * directly as the `@lad-sapienza/scms-core` npm package (`import { scms }
+ * from '@lad-sapienza/scms-core'`), not via a path alias into a sibling
+ * folder. Any `@user`/`@components`/etc. aliases a consuming site defines
+ * for its own content are that site's own astro.config.mjs concern.
+ */
+import type { AstroIntegration } from 'astro';
+import mdx from '@astrojs/mdx';
+import react from '@astrojs/react';
+import sitemap from '@astrojs/sitemap';
+import expressiveCode from 'astro-expressive-code';
+import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers';
+import { contentAssetsIntegration } from './integrations/contentAssetsIntegration';
+import { galleryIntegration } from './integrations/galleryIntegration';
+
+export interface ScmsOptions {
+  /** Path to the content directory, relative to the project root. Defaults to 'usr/content'. */
+  contentDir?: string;
+  /** Path to page files, relative to the project root. Defaults to 'usr/pages'. */
+  pagesDir?: string;
+  /** Path to shared galleries, relative to the project root. Defaults to 'usr/galleries'. */
+  galleriesDir?: string;
+}
+
+/** react, react-dom, and any library that calls hooks internally (@tanstack/react-table) — see file doc comment. */
+const HOOK_LIBRARIES = ['react', 'react-dom', 'react-dom/client', 'react/jsx-runtime', 'react/jsx-dev-runtime', 'scheduler', '@tanstack/react-table'];
+
+function scmsViteConfigIntegration(): AstroIntegration {
+  return {
+    name: 'scms-vite-config',
+    hooks: {
+      'astro:config:setup': ({ updateConfig }) => {
+        updateConfig({
+          vite: {
+            resolve: {
+              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'],
+            },
+          },
+        });
+      },
+    },
+  };
+}
+
+export function scms(options: ScmsOptions = {}): AstroIntegration[] {
+  const { contentDir, pagesDir, galleriesDir } = options;
+
+  return [
+    contentAssetsIntegration({ contentDir }),
+    galleryIntegration({ pagesDir, contentDir, galleriesDir }),
+    expressiveCode({
+      themes: ['github-dark'],
+      plugins: [pluginLineNumbers()],
+      defaultProps: { showLineNumbers: true },
+    }),
+    mdx(),
+    react(),
+    sitemap(),
+    scmsViteConfigIntegration(),
+  ];
+}

package/utils/content.ts

@@ -0,0 +1,88 @@
+/**
+ * Content Utility Functions
+ * Helper functions for working with Astro Content Collections
+ */
+
+import { getCollection } from 'astro:content';
+import Papa from 'papaparse';
+
+/**
+ * Get all entries from a collection sorted by a field (agnostic to collection name)
+ */
+export async function getSortedCollection(
+  collectionName: string,
+  sortField: string = 'date',
+  order: 'asc' | 'desc' = 'desc'
+) {
+  const entries = await getCollection(collectionName as any);
+  return entries.sort((a: any, b: any) => {
+    // Type guard: ensure a and b are objects with a 'data' property
+    if (
+      typeof a !== 'object' || a === null || !('data' in a) ||
+      typeof b !== 'object' || b === null || !('data' in b)
+    ) {
+      return 0;
+    }
+    const aData = (a as { data: Record<string, any> }).data;
+    const bData = (b as { data: Record<string, any> }).data;
+    const aValue = aData[sortField];
+    const bValue = bData[sortField];
+    if (aValue === undefined || bValue === undefined) return 0;
+    // Date comparison
+    if (
+      Object.prototype.toString.call(aValue) === '[object Date]' &&
+      Object.prototype.toString.call(bValue) === '[object Date]'
+    ) {
+      const aTime = (aValue as unknown as Date).getTime();
+      const bTime = (bValue as unknown as Date).getTime();
+      return order === 'desc' ? bTime - aTime : aTime - bTime;
+    }
+    // Number comparison
+    if (typeof aValue === 'number' && typeof bValue === 'number') {
+      return order === 'desc' ? bValue - aValue : aValue - bValue;
+    }
+    // String comparison
+    if (typeof aValue === 'string' && typeof bValue === 'string') {
+      return order === 'desc' ? bValue.localeCompare(aValue) : aValue.localeCompare(bValue);
+    }
+    return 0;
+  });
+}
+
+// Menu extraction logic should be implemented in user code (usr/), not in core.
+
+/**
+ * Parse CSV string to JSON
+ */
+export async function parseCSV(csvText: string): Promise<any[]> {
+  const { data } = Papa.parse(csvText, {
+    header: true,
+    skipEmptyLines: true,
+    dynamicTyping: true,
+  });
+  return data as any[];
+}
+
+/**
+ * Fetch and parse remote data
+ */
+export async function fetchRemoteData(url: string): Promise<any> {
+  const response = await fetch(url);
+  
+  if (!response.ok) {
+    throw new Error(`Failed to fetch ${url}: ${response.statusText}`);
+  }
+
+  const contentType = response.headers.get('content-type');
+  
+  if (contentType?.includes('application/json')) {
+    return await response.json();
+  }
+  
+  if (contentType?.includes('text/csv') || url.endsWith('.csv')) {
+    const text = await response.text();
+    return await parseCSV(text);
+  }
+  
+  return await response.text();
+}

package/utils/data-fetcher.ts

@@ -0,0 +1,128 @@
+import Papa from 'papaparse';
+import { createDirectus, rest, staticToken, readItems, readItem } from '@directus/sdk';
+import type { SourceConfig } from '../components/DataTb/types';
+
+export type { SourceConfig } from '../components/DataTb/types';
+export type DataRow = Record<string, any>;
+
+/**
+ * Fetches data from a configured source
+ */
+export async function fetchData(source: SourceConfig): Promise<DataRow[]> {
+  let fetchedData: DataRow[] = [];
+
+  switch (source.type) {
+    case 'csv':
+      await new Promise<void>((resolve, reject) => {
+        Papa.parse(source.url, {
+          download: true,
+          header: true,
+          delimiter: source.delimiter || ',',
+          skipEmptyLines: true,
+          dynamicTyping: true,
+          complete: (results) => {
+            fetchedData = source.skipRows && source.skipRows > 0
+              ? (results.data as DataRow[]).slice(source.skipRows)
+              : (results.data as DataRow[]);
+            resolve();
+          },
+          error: (error) => {
+            reject(error);
+          },
+        });
+      });
+      break;
+
+    case 'json':
+      if (source.data) {
+        fetchedData = source.data;
+      } else if (source.url) {
+        const response = await fetch(source.url);
+        if (!response.ok) throw new Error(`HTTP error! status: ${response.status}`);
+        const jsonData = await response.json();
+        fetchedData = Array.isArray(jsonData) ? jsonData : [jsonData];
+      }
+      break;
+
+    case 'directus':
+      if (!source.config) throw new Error('Directus configuration required');
+      const client = createDirectus(source.config.url)
+        .with(staticToken(source.config.token))
+        .with(rest());
+
+      // Handle single item request vs collection query
+      if (source.itemId !== undefined) {
+        // Fetch single item by ID (more efficient)
+        const queryOptions: any = {};
+        if (source.fields) queryOptions.fields = source.fields;
+        
+        const item = await client.request(readItem(source.collection, source.itemId, queryOptions));
+        fetchedData = item ? [item] : [];
+      } else {
+        // Query collection with filters
+        const queryOptions: any = {};
+        if (source.filter) queryOptions.filter = source.filter;
+        if (source.fields) queryOptions.fields = source.fields;
+        if (source.sort) queryOptions.sort = source.sort;
+        if (source.limit) queryOptions.limit = source.limit;
+
+        const items = await client.request(readItems(source.collection, queryOptions));
+        fetchedData = items as any[];
+      }
+      break;
+
+    case 'geojson':
+      if (source.data) {
+        // Direct GeoJSON object - extract features as data rows
+        const geojsonData = source.data;
+        fetchedData = geojsonData.features ? geojsonData.features.map((f: any) => ({
+          ...f.properties,
+          _geometry: f.geometry,
+          _id: f.id
+        })) : [];
+      } else if (source.url) {
+        const geoResponse = await fetch(source.url);
+        if (!geoResponse.ok) throw new Error(`HTTP error! status: ${geoResponse.status}`);
+        const geojsonData = await geoResponse.json();
+        fetchedData = geojsonData.features ? geojsonData.features.map((f: any) => ({
+          ...f.properties,
+          _geometry: f.geometry,
+          _id: f.id
+        })) : [];
+      }
+      break;
+
+    case 'api':
+      const apiOptions: RequestInit = {
+        method: source.method || 'GET',
+        headers: {
+          'Content-Type': 'application/json',
+          ...source.headers,
+        },
+      };
+      if (source.body && source.method === 'POST') {
+        apiOptions.body = JSON.stringify(source.body);
+      }
+      const apiResponse = await fetch(source.url, apiOptions);
+      if (!apiResponse.ok) throw new Error(`HTTP error! status: ${apiResponse.status}`);
+      const apiData = await apiResponse.json();
+
+      if (source.transformer) {
+        fetchedData = source.transformer(apiData);
+      } else if (Array.isArray(apiData)) {
+        fetchedData = apiData;
+      } else if (apiData.data && Array.isArray(apiData.data)) {
+        fetchedData = apiData.data;
+      } else {
+        fetchedData = [apiData];
+      }
+      break;
+
+    default:
+      // e.g. 'vector' (MapLibre vector tile sources) — these are rendered
+      // directly by MapLibre from tiles, not fetched/converted to rows here.
+      throw new Error(`fetchData: unsupported source type "${(source as SourceConfig).type}"`);
+  }
+
+  return fetchedData;
+}

package/utils/directus-config.ts

@@ -0,0 +1,160 @@
+/**
+ * Shared Directus Configuration Utilities
+ * 
+ * Provides consistent Directus connection handling across components
+ */
+
+/**
+ * Simple Directus configuration interface
+ * Used by Map and DataTb components for a consistent API
+ */
+export interface DirectusShorthand {
+  /** Table/collection name in Directus */
+  table: string;
+  
+  /** Directus query string (e.g., "filter[status][_eq]=published&limit=10") */
+  queryString?: string;
+  
+  /** Optional: Override Directus URL (defaults to PUBLIC_DIRECTUS_URL env var) */
+  url?: string;
+  
+  /** Optional: Override Directus token (defaults to PUBLIC_DIRECTUS_TOKEN env var) */
+  token?: string;
+}
+
+/**
+ * Full Directus source configuration (internal format used by data-fetcher)
+ */
+export interface DirectusSourceConfig {
+  type: 'directus';
+  collection: string;
+  config: {
+    url: string;
+    token: string;
+  };
+  /** Optional: Fetch single item by ID instead of querying collection */
+  itemId?: string | number;
+  filter?: Record<string, any>;
+  fields?: string[];
+  sort?: string[];
+  limit?: number;
+  offset?: number;
+  /** GeoJSON field name (for map conversion) - Directus stores GeoJSON as JSON field */
+  geoField?: string;
+}
+
+/**
+ * Parse Directus query string into filter object and other parameters
+ * Supports Directus API query syntax: filter[field][operator]=value
+ */
+export function parseDirectusQueryString(queryString: string): {
+  filter?: Record<string, any>;
+  fields?: string[];
+  sort?: string[];
+  limit?: number;
+  offset?: number;
+} {
+  const params = new URLSearchParams(queryString);
+  const filter: any = {};
+  const fields: string[] = [];
+  const sort: string[] = [];
+  let limit: number | undefined;
+  let offset: number | undefined;
+  
+  params.forEach((value, key) => {
+    // Parse filter syntax: filter[field][operator]=value
+    const filterMatch = key.match(/^filter\[([^\]]+)\]\[([^\]]+)\]$/);
+    if (filterMatch) {
+      const [, field, operator] = filterMatch;
+      if (!filter[field]) filter[field] = {};
+      // Convert string booleans to actual booleans
+      filter[field][operator] = value === 'true' ? true : value === 'false' ? false : value;
+    } 
+    // Parse fields: fields[]=field1&fields[]=field2 or fields=field1,field2
+    else if (key === 'fields[]' || key === 'fields') {
+      if (value.includes(',')) {
+        fields.push(...value.split(',').map(f => f.trim()));
+      } else {
+        fields.push(value);
+      }
+    }
+    // Parse sort: sort[]=field1&sort[]=-field2 or sort=field1,-field2
+    else if (key === 'sort[]' || key === 'sort') {
+      if (value.includes(',')) {
+        sort.push(...value.split(',').map(s => s.trim()));
+      } else {
+        sort.push(value);
+      }
+    }
+    // Parse limit and offset
+    else if (key === 'limit') {
+      limit = parseInt(value, 10);
+    } else if (key === 'offset') {
+      offset = parseInt(value, 10);
+    }
+  });
+  
+  const result: any = {};
+  if (Object.keys(filter).length > 0) result.filter = filter;
+  if (fields.length > 0) result.fields = fields;
+  if (sort.length > 0) result.sort = sort;
+  if (limit !== undefined) result.limit = limit;
+  if (offset !== undefined) result.offset = offset;
+  
+  return result;
+}
+
+/**
+ * Convert simplified Directus shorthand to full source config
+ * Handles environment variables and query string parsing
+ */
+export function directusShorthandToConfig(directus: DirectusShorthand): DirectusSourceConfig | null {
+  const directusUrl = directus.url || import.meta.env.PUBLIC_DIRECTUS_URL;
+  const directusToken = directus.token || import.meta.env.PUBLIC_DIRECTUS_TOKEN;
+  
+  if (!directusUrl) {
+    console.error('Directus URL is not configured. Please provide it via the directus.url prop or set PUBLIC_DIRECTUS_URL environment variable.');
+    return null;
+  }
+  
+  const sourceConfig: DirectusSourceConfig = {
+    type: 'directus',
+    collection: directus.table,
+    config: {
+      url: directusUrl,
+      token: directusToken || ''
+    }
+  };
+  
+  // Parse query string if provided
+  if (directus.queryString) {
+    const parsed = parseDirectusQueryString(directus.queryString);
+    Object.assign(sourceConfig, parsed);
+  }
+  
+  // Default to no limit if not specified
+  if (sourceConfig.limit === undefined) {
+    sourceConfig.limit = -1;
+  }
+  
+  return sourceConfig;
+}
+
+/**
+ * Get Directus connection config from environment or props
+ * Returns null if configuration is incomplete
+ */
+export function getDirectusConfig(url?: string, token?: string): { url: string; token: string } | null {
+  const directusUrl = url || import.meta.env.PUBLIC_DIRECTUS_URL;
+  const directusToken = token || import.meta.env.PUBLIC_DIRECTUS_TOKEN;
+  
+  if (!directusUrl) {
+    console.error('Directus URL is not configured. Set PUBLIC_DIRECTUS_URL environment variable or pass url prop.');
+    return null;
+  }
+  
+  return {
+    url: directusUrl,
+    token: directusToken || ''
+  };
+}