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

package/components/ZoteroGeoViewer/ZoteroRecordsPreview.tsx

@@ -0,0 +1,185 @@
+import React, { useState, useEffect } from 'react';
+
+// Helper to strip two outermost divs from a HTML string
+function stripWrappingDivs(html: string): string {
+  if (typeof html !== "string") return html;
+  // Remove first <div>...</div>
+  html = html.replace(/^\s*<div[^>]*>([\s\S]*)<\/div>\s*$/, "$1");
+  // Remove next <div>...</div>
+  html = html.replace(/^\s*<div[^>]*>([\s\S]*)<\/div>\s*$/, "$1");
+  return html;
+}
+
+interface ZoteroItem {
+  key: string;
+  bib?: string;
+  data?: {
+    key?: string;
+    title?: string;
+  };
+}
+
+interface ZoteroTag {
+  main: string;
+  alternatives?: string[];
+}
+
+interface ZoteroRecordsPreviewProps {
+  groupId: number;
+  tag: ZoteroTag | null;
+  /** Maximum number of records to fetch/display (default: 1000) */
+  maxItems?: number;
+}
+
+export function ZoteroRecordsPreview({ groupId, tag, maxItems = 1000 }: ZoteroRecordsPreviewProps) {
+  const [records, setRecords] = useState<ZoteroItem[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    if (!tag || !tag.main) {
+      setRecords([]);
+      setError(null);
+      setLoading(false);
+      return;
+    }
+    
+    let cancelled = false;
+
+    async function fetchAllRecords() {
+      if (!tag || !tag.main) return; // Additional null check for TypeScript
+      
+      setLoading(true);
+      setError(null);
+      setRecords([]);
+
+      const allTags = [
+        tag.main,
+        ...(tag.alternatives || [])
+      ].filter(Boolean);
+      const tagsQuery = allTags.map(t => `@${t}`).join(' || ');
+      
+      const baseUrl = `https://api.zotero.org/groups/${groupId}/items`;
+      const limit = 100;
+      const buildUrl = (start = 0) =>
+        `${baseUrl}?sort=date&include=bib&tag=${encodeURIComponent(tagsQuery)}&format=json&limit=${limit}&start=${start}`;
+
+      try {
+        let all: ZoteroItem[] = [];
+        let start = 0;
+        let total: number | null = null;
+        let hasNext = true;
+
+        while (hasNext && all.length < maxItems) {
+          const resp = await fetch(buildUrl(start), {
+            headers: { Accept: "application/json" },
+          });
+          if (!resp.ok)
+            throw new Error(`Zotero API error: ${resp.status} ${resp.statusText}`);
+
+          if (total == null) {
+            const totalHeader = resp.headers.get("Total-Results") || resp.headers.get("total-results");
+            if (totalHeader) {
+              const n = parseInt(totalHeader, 10);
+              if (!Number.isNaN(n)) total = n;
+            }
+          }
+
+          const page = await resp.json();
+          if (cancelled) return;
+
+          all = all.concat(page);
+
+          if (total != null) {
+            hasNext = all.length < total;
+          } else {
+            const link = resp.headers.get("Link") || resp.headers.get("link");
+            if (link && /rel="next"/i.test(link)) {
+              hasNext = true;
+            } else {
+              hasNext = page.length === limit;
+            }
+          }
+          start += page.length;
+
+          // Update progressively so the UI shows results while loading
+          setRecords(all.slice(0, maxItems));
+        }
+
+        if (!cancelled) setRecords(all.slice(0, maxItems));
+      } catch (err) {
+        if (!cancelled) setError(err instanceof Error ? err.message : "Error fetching records");
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    }
+
+    fetchAllRecords();
+    return () => {
+      cancelled = true;
+    };
+  }, [groupId, tag, maxItems]);
+
+  if (!tag || !tag.main) return null;
+  
+  return (
+    <div className="mt-3">
+      <h4 className="h5 fw-semibold">
+        Zotero records for <span className="text-primary">{tag.main}</span>
+        {tag.alternatives && tag.alternatives.length > 0 && (
+          <small className="text-secondary ms-2">{' '}
+            (including: {tag.alternatives.join(", ")})
+          </small>
+        )}
+      </h4>
+      {loading && <div className="text-primary">Loading records...</div>}
+      {error && <div className="text-danger">Error: {error}</div>}
+      {!loading && records && records.length > 0 && (
+        <ol className="mt-3">
+          {records.map(item => {
+            const key = item.key || item.data?.key;
+            const zoteroLink = key
+              ? `https://www.zotero.org/groups/${groupId}/items/${key}`
+              : null;
+            return (
+              <li
+                key={key}
+                className="mb-2 ps-3"
+                style={{  }}
+              >
+                {item.bib ? (
+                  <span
+                    dangerouslySetInnerHTML={{
+                      __html: stripWrappingDivs(item.bib),
+                    }}
+                  />
+                ) : item.data && item.data.title ? (
+                  item.data.title
+                ) : (
+                  JSON.stringify(item)
+                )}
+                {zoteroLink && (
+                  <React.Fragment>
+                    <br />
+                    <a
+                      href={zoteroLink}
+                      target="_blank"
+                      rel="noopener noreferrer"
+                      className="small text-primary text-decoration-underline"
+                      style={{ whiteSpace: "nowrap" }}
+                    >
+                      View in the Zotero Library
+                    </a>
+                  </React.Fragment>
+                )}
+              </li>
+            );
+          })}
+        </ol>
+      )}
+      {!loading && (!records || records.length === 0) && !error && (
+        <div className="text-danger">No records found for this tag.</div>
+      )}
+    </div>
+  );
+}

package/components/ZoteroGeoViewer/index.ts

@@ -0,0 +1,16 @@
+/**
+ * ZoteroGeoViewer Component
+ * 
+ * Connects to a Zotero group library and visualizes items with geographical coordinates
+ * on a map, providing tag-based filtering and different layout options.
+ */
+
+export { ZoteroGeoViewer } from './ZoteroGeoViewer';
+export { ZoteroRecordsPreview } from './ZoteroRecordsPreview';
+export type { 
+  ZoteroGeoViewerProps, 
+  ZoteroItem, 
+  CoordinateData, 
+  ZoteroGeoData, 
+  LayoutType 
+} from './types';

package/components/ZoteroGeoViewer/types.ts

@@ -0,0 +1,123 @@
+/**
+ * ZoteroGeoViewer Component Types
+ */
+
+export interface ZoteroItem {
+  key: string;
+  version: number;
+  library: {
+    type: string;
+    id: number;
+    name: string;
+    links: {
+      alternate: {
+        href: string;
+        type: string;
+      };
+    };
+  };
+  links: {
+    self: {
+      href: string;
+      type: string;
+    };
+    alternate: {
+      href: string;
+      type: string;
+    };
+  };
+  meta: {
+    parsedDate: string;
+    numChildren: number;
+  };
+  data: {
+    key: string;
+    version: number;
+    itemType: string;
+    title: string;
+    creators: Array<{
+      creatorType: string;
+      firstName: string;
+      lastName: string;
+    }>;
+    abstractNote: string;
+    publicationTitle: string;
+    volume: string;
+    issue: string;
+    pages: string;
+    date: string;
+    series: string;
+    seriesTitle: string;
+    seriesText: string;
+    journalAbbreviation: string;
+    language: string;
+    DOI: string;
+    ISSN: string;
+    shortTitle: string;
+    url: string;
+    accessDate: string;
+    archive: string;
+    archiveLocation: string;
+    libraryCatalog: string;
+    callNumber: string;
+    rights: string;
+    extra: string;
+    tags: Array<{
+      tag: string;
+      type?: number;
+    }>;
+    collections: string[];
+    relations: Record<string, any>;
+    dateAdded: string;
+    dateModified: string;
+  };
+}
+
+export interface CoordinateData {
+  name: string;
+  altLabel?: string | null;
+  id: number;
+  source?: string | null;
+  coordinates: [number, number]; // [longitude, latitude]
+}
+
+export interface ZoteroGeoData extends GeoJSON.FeatureCollection {
+  features: Array<GeoJSON.Feature & {
+    properties: CoordinateData & {
+      zoteroItems?: ZoteroItem[];
+    };
+  }>;
+}
+
+export type LayoutType = 
+  | 'vertical' 
+  | '6x6' 
+  | '8x4' 
+  | '4x8' 
+  | '12x4' 
+  | 'horizontal';
+
+export interface ZoteroGeoViewerProps {
+  /** Zotero group ID (required) */
+  groupId: number;
+  
+  /** Layout configuration for the display */
+  layout?: LayoutType;
+  
+  /** Custom map height */
+  mapHeight?: string;
+  
+  /** Custom map center (lng,lat,zoom) */
+  mapCenter?: string;
+  
+  /** Enable/disable tag autocomplete */
+  tagAutocomplete?: boolean;
+  
+  /** Maximum number of items to display */
+  maxItems?: number;
+}
+
+export interface ZoteroApiResponse {
+  items: ZoteroItem[];
+  totalResults: number;
+}

package/index.ts

@@ -0,0 +1,26 @@
+// Core package exports
+export { Gallery } from './components/Gallery';
+export { default as TableOfContents } from './components/TableOfContents/TableOfContents.astro';
+
+// DataTb (recommended table component)
+export { DataTb, CsvSource, JsonSource, DirectusSource, ApiSource } from './components/DataTb';
+
+// Map components
+export { Map as MapComponent } from './components/Map';
+export { SearchUI, SearchUISimple, SearchUIAdvanced } from './components/Map/Search';
+
+// ZoteroGeoViewer component
+export { ZoteroGeoViewer } from './components/ZoteroGeoViewer';
+export type { ZoteroGeoViewerProps, ZoteroItem, CoordinateData, LayoutType } from './components/ZoteroGeoViewer';
+
+// Record helpers
+export { RecordProvider, Field, Image, RecordFetcher, useRecordFetcher, getValueByDotPath } from './components/Record';
+export type { RecordProviderProps, FieldProps, ImageProps, RecordFetcherProps, UseRecordFetcherOptions, UseRecordFetcherResult } from './components/Record';
+
+// Utils
+export * from './utils/record-fetcher';
+// Note: content utils not exported to prevent astro:content in client components
+export * from './utils/directus-config';
+
+// Types
+export type * from './components/Map/types';

package/integrations/__tests__/galleryIntegration.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect, vi } from 'vitest';
+import { galleryIntegration, GALLERY_VIRTUAL_MODULE_ID, buildGalleryVirtualModuleSource } from '../galleryIntegration';
+
+function getVitePlugin(options?: Parameters<typeof galleryIntegration>[0]) {
+  let capturedConfig: any;
+  const updateConfig = vi.fn((config: any) => {
+    capturedConfig = config;
+  });
+
+  const integration = galleryIntegration(options);
+  const setupHook = integration.hooks?.['astro:config:setup'];
+  expect(setupHook).toBeTypeOf('function');
+
+  // @ts-expect-error - minimal fake hook params, only what the hook uses
+  setupHook({ updateConfig });
+
+  const plugin = capturedConfig.vite.plugins[0];
+  return plugin;
+}
+
+describe('galleryIntegration', () => {
+  it('registers a resolveId/load pair for the virtual module id', () => {
+    const plugin = getVitePlugin();
+    const resolved = plugin.resolveId(GALLERY_VIRTUAL_MODULE_ID);
+    expect(resolved).toBe('\0' + GALLERY_VIRTUAL_MODULE_ID);
+    expect(plugin.resolveId('some/other/id')).toBeUndefined();
+  });
+
+  it('generates a virtual module with one static glob per source root, using the default usr/ paths', () => {
+    const plugin = getVitePlugin();
+    const resolvedId = plugin.resolveId(GALLERY_VIRTUAL_MODULE_ID);
+    const source = plugin.load(resolvedId);
+
+    expect(source).toContain("import.meta.glob('/usr/pages/**/gallery/*.");
+    expect(source).toContain("import.meta.glob('/usr/content/**/gallery/*.");
+    expect(source).toContain("import.meta.glob('/usr/galleries/*/*.");
+    expect(source).toContain("import.meta.glob('/usr/pages/**/gallery/captions.json'");
+    expect(source).toContain("import.meta.glob('/usr/content/**/gallery/captions.json'");
+    expect(source).toContain("import.meta.glob('/usr/galleries/*/captions.json'");
+
+    // Every glob call must use { eager: true } — a lazy glob would return
+    // dynamic import() functions instead of already-resolved image metadata.
+    const globCallCount = (source.match(/import\.meta\.glob/g) || []).length;
+    const eagerCount = (source.match(/\{\s*eager:\s*true\s*\}/g) || []).length;
+    expect(eagerCount).toBe(globCallCount);
+  });
+
+  it('returns undefined for any id it does not own', () => {
+    const plugin = getVitePlugin();
+    expect(plugin.load('/some/unrelated/module.js')).toBeUndefined();
+  });
+
+  it('honors custom directory options', () => {
+    const plugin = getVitePlugin({ pagesDir: 'src/pages', contentDir: 'src/content', galleriesDir: 'src/galleries' });
+    const source = plugin.load(plugin.resolveId(GALLERY_VIRTUAL_MODULE_ID));
+
+    expect(source).toContain("import.meta.glob('/src/pages/**/gallery/*.");
+    expect(source).toContain("import.meta.glob('/src/content/**/gallery/*.");
+    expect(source).toContain("import.meta.glob('/src/galleries/*/*.");
+    expect(source).not.toContain('/usr/');
+  });
+});
+
+describe('buildGalleryVirtualModuleSource', () => {
+  it('strips leading/trailing slashes from a configured directory before building the glob prefix', () => {
+    const source = buildGalleryVirtualModuleSource({ pagesDir: '/src/pages/' });
+    expect(source).toContain("import.meta.glob('/src/pages/**/gallery/*.");
+    expect(source).not.toContain('//src/pages');
+  });
+});

package/integrations/contentAssetsIntegration.ts

@@ -0,0 +1,132 @@
+/**
+ * contentAssetsIntegration
+ *
+ * Astro integration that serves static assets (images, PDFs, etc.) co-located
+ * in the content directory (usr/content/ by default) without requiring a
+ * manual copy step.
+ *
+ * - Dev server: a Vite middleware intercepts requests for static file extensions
+ *   and serves them directly from the content directory, mapping URL paths 1:1
+ *   (e.g. /blog/post/image.jpg → usr/content/blog/post/image.jpg).
+ *
+ * - Production build: assets are copied from the content directory into dist/
+ *   with the same relative path structure, so they are available at the
+ *   expected URLs.
+ *
+ * This replaces the scripts/copy-content-images.js pre-build script for
+ * content-colocated assets.
+ */
+
+import type { AstroIntegration } from 'astro';
+import { resolve, join, relative, extname, dirname } from 'node:path';
+import { existsSync, statSync, mkdirSync, copyFileSync, readdirSync, createReadStream } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+export interface ContentAssetsOptions {
+  /** Path to the content directory, relative to the project root. Defaults to 'usr/content'. */
+  contentDir?: string;
+}
+
+/** File extensions treated as static assets. */
+const STATIC_EXTENSIONS = /\.(jpe?g|png|gif|svg|webp|pdf|avif|mp4|mp3|woff2?|ttf|ico)$/i;
+
+const MIME_TYPES: Record<string, string> = {
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  png: 'image/png',
+  gif: 'image/gif',
+  svg: 'image/svg+xml',
+  webp: 'image/webp',
+  avif: 'image/avif',
+  pdf: 'application/pdf',
+  mp4: 'video/mp4',
+  mp3: 'audio/mpeg',
+  woff: 'font/woff',
+  woff2: 'font/woff2',
+  ttf: 'font/ttf',
+  ico: 'image/x-icon',
+};
+
+function collectAssets(dir: string, results: string[] = []): string[] {
+  for (const item of readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = join(dir, item.name);
+    if (item.isDirectory()) {
+      collectAssets(fullPath, results);
+    } else if (STATIC_EXTENSIONS.test(item.name)) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+export function contentAssetsIntegration(options: ContentAssetsOptions = {}): AstroIntegration {
+  const contentDirSegment = options.contentDir ?? join('usr', 'content');
+  // Resolved from Astro's own config root in astro:config:setup below, rather
+  // than assumed from process.cwd() — more portable if the process is ever
+  // invoked from somewhere other than the project root.
+  let projectRoot = process.cwd();
+
+  return {
+    name: 'content-assets',
+    hooks: {
+      'astro:config:setup': ({ config }) => {
+        projectRoot = fileURLToPath(config.root);
+      },
+
+      /**
+       * Dev server: add a Connect middleware that serves static assets directly
+       * from the content directory without requiring them to be copied to
+       * usr/public/.
+       */
+      'astro:server:setup': ({ server, logger }) => {
+        const contentDir = resolve(projectRoot, contentDirSegment);
+
+        server.middlewares.use((req, res, next) => {
+          const url = req.url?.split('?')[0];
+          if (!url || !STATIC_EXTENSIONS.test(url)) return next();
+
+          // Security: prevent path traversal
+          const filePath = resolve(join(contentDir, url));
+          if (!filePath.startsWith(contentDir + '/')) return next();
+
+          if (!existsSync(filePath) || statSync(filePath).isDirectory()) return next();
+
+          const mime = MIME_TYPES[extname(filePath).slice(1).toLowerCase()] ?? 'application/octet-stream';
+          res.setHeader('Content-Type', mime);
+          createReadStream(filePath).pipe(res as NodeJS.WritableStream);
+        });
+
+        logger.info(`Serving content assets directly from ${contentDirSegment}/`);
+      },
+
+      /**
+       * Production build: copy all static assets from the content directory
+       * into the dist/ output directory, preserving the relative path structure.
+       */
+      'astro:build:done': ({ dir, logger }) => {
+        const contentDir = resolve(projectRoot, contentDirSegment);
+        const distDir = fileURLToPath(dir);
+
+        if (!existsSync(contentDir)) {
+          logger.warn(`${contentDirSegment}/ not found – skipping content asset copy`);
+          return;
+        }
+
+        const assets = collectAssets(contentDir);
+        let count = 0;
+
+        for (const assetPath of assets) {
+          const relPath = relative(contentDir, assetPath);
+          const destPath = join(distDir, relPath);
+          mkdirSync(dirname(destPath), { recursive: true });
+          copyFileSync(assetPath, destPath);
+          count++;
+        }
+
+        if (count > 0) {
+          logger.info(`Copied ${count} content asset(s) to dist/`);
+        }
+      },
+    },
+  };
+}

package/integrations/directusLoader.ts

@@ -0,0 +1,98 @@
+/**
+ * Directus Content Loader for Astro Content Collections
+ * 
+ * This loader fetches data from a Directus API and makes it available
+ * as an Astro Content Collection.
+ */
+
+import type { Loader } from 'astro/loaders';
+
+export interface DirectusLoaderOptions {
+  endpoint?: string;
+  token?: string;
+  table: string;
+  fields?: string[];
+  filter?: Record<string, any>;
+  sort?: string[];
+  limit?: number;
+}
+
+export function directusLoader(options: DirectusLoaderOptions): Loader {
+  return {
+    name: 'directus-loader',
+    load: async ({ store, logger }) => {
+      const endpoint = options.endpoint || process.env.DIRECTUS_URL;
+      const token = options.token || process.env.DIRECTUS_TOKEN;
+
+      if (!endpoint) {
+        throw new Error(
+          'Directus endpoint not configured. Set DIRECTUS_URL in .env or provide endpoint option.'
+        );
+      }
+
+      // Build URL
+      let url = `${endpoint}/items/${options.table}`;
+      const params = new URLSearchParams();
+
+      if (options.fields) {
+        params.append('fields', options.fields.join(','));
+      }
+
+      if (options.filter) {
+        Object.entries(options.filter).forEach(([key, value]) => {
+          params.append(`filter[${key}]`, String(value));
+        });
+      }
+
+      if (options.sort) {
+        params.append('sort', options.sort.join(','));
+      }
+
+      if (options.limit) {
+        params.append('limit', String(options.limit));
+      }
+
+      const queryString = params.toString();
+      if (queryString) {
+        url += `?${queryString}`;
+      }
+
+      logger.info(`Fetching from Directus: ${url}`);
+
+      // Fetch data
+      const headers: HeadersInit = {
+        'Content-Type': 'application/json',
+      };
+
+      if (token) {
+        headers['Authorization'] = `Bearer ${token}`;
+      }
+
+      try {
+        const response = await fetch(url, { headers });
+
+        if (!response.ok) {
+          throw new Error(`Directus API error: ${response.statusText}`);
+        }
+
+        const result = await response.json();
+        const items = Array.isArray(result.data) ? result.data : [result.data];
+
+        logger.info(`Loaded ${items.length} items from Directus table: ${options.table}`);
+
+        // Store items in the collection
+        store.clear();
+        
+        for (const item of items) {
+          store.set({
+            id: String(item.id),
+            data: item,
+          });
+        }
+      } catch (error) {
+        logger.error(`Failed to load from Directus: ${error}`);
+        throw error;
+      }
+    },
+  };
+}