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

package/components/Gallery/galleryUtils.ts

@@ -0,0 +1,186 @@
+/**
+ * Utility functions for Gallery component
+ */
+import { z } from 'zod';
+import * as manifest from 'virtual:scms/galleries';
+import type { GalleryImage } from './types';
+
+/**
+ * Extract filename without extension from filepath
+ */
+export function getFileName(filepath: string): string {
+  const parts = filepath.split('/');
+  const filename = parts[parts.length - 1];
+  return filename.replace(/\.[^/.]+$/, '');
+}
+
+/**
+ * Format filename into readable caption
+ * e.g., "my-image-file" -> "My Image File"
+ */
+export function formatFilename(filename: string): string {
+  return filename
+    .split('-')
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+}
+
+/**
+ * Extract base filename without resolution suffix for fuzzy matching
+ * Examples:
+ * - "children-593313_1280.jpg" → "children-593313"
+ * - "coffee-2306471_1920.jpg" → "coffee-2306471"
+ */
+function getBaseFilename(filename: string): string {
+  // Remove extension first
+  const withoutExt = filename.replace(/\.[^.]+$/, '');
+  // Remove resolution suffix (e.g., _1280, _1920, _640x480)
+  return withoutExt.replace(/[_-]\d+(?:x\d+)?$/, '');
+}
+
+/**
+ * Build a caption lookup with multiple keys for fuzzy matching (exact
+ * filename, filename without extension, filename without a resolution
+ * suffix), keyed by the *source* filename as written in captions.json.
+ */
+function buildCaptionLookup(captions: Record<string, string>): Map<string, string> {
+  const lookup = new Map<string, string>();
+  Object.entries(captions).forEach(([key, value]) => {
+    lookup.set(getBaseFilename(key), value);
+    lookup.set(key, value);
+    lookup.set(key.replace(/\.[^.]+$/, ''), value);
+  });
+  return lookup;
+}
+
+/**
+ * Look up a caption for a source filename (exact → no ext → fuzzy base match).
+ *
+ * Must be matched against the *original* source filename (from the
+ * import.meta.glob key), not the Astro-processed `src` — Astro renames
+ * output files to `name.HASH.ext`, which would never match a captions.json
+ * key written against the original filename.
+ */
+function lookupCaption(sourceFilename: string, lookup: Map<string, string>): string | undefined {
+  const noExt = sourceFilename.replace(/\.[^.]+$/, '');
+  const base = getBaseFilename(sourceFilename);
+  return lookup.get(sourceFilename) ?? lookup.get(noExt) ?? lookup.get(base);
+}
+
+/**
+ * Sort images by filename
+ */
+export function sortImages(images: GalleryImage[], reverse: boolean = false): GalleryImage[] {
+  const sorted = [...images].sort((a, b) => {
+    const nameA = getFileName(a.src);
+    const nameB = getFileName(b.src);
+    return nameB.localeCompare(nameA); // DESC by default
+  });
+
+  return reverse ? sorted.reverse() : sorted;
+}
+
+const captionsSchema = z.record(z.string(), z.string());
+
+/**
+ * Validate a raw captions.json payload. Logs a warning and returns undefined
+ * (falling back to filename-based captions) rather than throwing, so a
+ * malformed captions.json degrades gracefully instead of breaking the build.
+ */
+function parseCaptions(raw: unknown, source: string): Record<string, string> | undefined {
+  const result = captionsSchema.safeParse(raw);
+  if (!result.success) {
+    console.warn(`[Gallery] Invalid captions.json at "${source}" — ignoring custom captions.`, result.error.message);
+    return undefined;
+  }
+  return result.data;
+}
+
+function unwrapModule<T>(mod: { default: T } | T): T {
+  return (mod as { default: T }).default ?? (mod as T);
+}
+
+function rawFileName(filepath: string): string {
+  return filepath.split('/').pop() ?? filepath;
+}
+
+function moduleToGalleryImage(
+  filepath: string,
+  mod: { default: { src: string; width: number; height: number } },
+  captionLookup?: Map<string, string>
+): GalleryImage {
+  const img = unwrapModule(mod);
+  const custom = captionLookup ? lookupCaption(rawFileName(filepath), captionLookup) : undefined;
+  const label = custom ?? formatFilename(getFileName(filepath));
+  return {
+    src: img.src,
+    thumb: img.src,
+    width: img.width,
+    height: img.height,
+    alt: label,
+    caption: label,
+  };
+}
+
+const normalizePath = (pathname: string): string => pathname.replace(/\/$/, '');
+
+const COLOCATED_GALLERY_PATTERN = /\/(pages|content)(.+)\/gallery\//;
+const SHARED_GALLERY_PATTERN = /\/galleries\/([^/]+)\//;
+
+export function getColocatedCaptions(pathname: string): Record<string, string> | undefined {
+  const normalized = normalizePath(pathname);
+  const allCaptions = { ...manifest.pagesCaptions, ...manifest.contentCaptions };
+  const entry = Object.entries(allCaptions).find(([filepath]) => {
+    const match = filepath.match(COLOCATED_GALLERY_PATTERN);
+    return !!match && normalized === match[2];
+  });
+  if (!entry) return undefined;
+  const [filepath, mod] = entry;
+  return parseCaptions(unwrapModule(mod), filepath);
+}
+
+export function getSharedCaptions(name: string): Record<string, string> | undefined {
+  const entry = Object.entries(manifest.sharedCaptions).find(([filepath]) => {
+    const match = filepath.match(SHARED_GALLERY_PATTERN);
+    return !!match && match[1] === name;
+  });
+  if (!entry) return undefined;
+  const [filepath, mod] = entry;
+  return parseCaptions(unwrapModule(mod), filepath);
+}
+
+/**
+ * Images from a `gallery/` folder colocated with the current page/content
+ * file, matched by comparing the current URL path against the folder
+ * structure under usr/pages/ or usr/content/. Applies captions.json from
+ * the same folder, if present.
+ *
+ * Known limitation (unchanged from before this redesign): if a content
+ * collection entry overrides its slug, or the site has a non-root `base`,
+ * the URL path diverges from the on-disk folder path and matching silently
+ * finds nothing.
+ */
+export function getColocatedGalleryImages(pathname: string): GalleryImage[] {
+  const normalized = normalizePath(pathname);
+  const allImages = { ...manifest.pagesImages, ...manifest.contentImages };
+  const captions = getColocatedCaptions(pathname);
+  const captionLookup = captions ? buildCaptionLookup(captions) : undefined;
+  return Object.entries(allImages)
+    .filter(([filepath]) => {
+      const match = filepath.match(COLOCATED_GALLERY_PATTERN);
+      return !!match && normalized === match[2];
+    })
+    .map(([filepath, mod]) => moduleToGalleryImage(filepath, mod, captionLookup));
+}
+
+/** Images from a shared gallery at usr/galleries/<name>/. Applies captions.json from the same folder, if present. */
+export function getSharedGalleryImages(name: string): GalleryImage[] {
+  const captions = getSharedCaptions(name);
+  const captionLookup = captions ? buildCaptionLookup(captions) : undefined;
+  return Object.entries(manifest.sharedImages)
+    .filter(([filepath]) => {
+      const match = filepath.match(SHARED_GALLERY_PATTERN);
+      return !!match && match[1] === name;
+    })
+    .map(([filepath, mod]) => moduleToGalleryImage(filepath, mod, captionLookup));
+}

package/components/Gallery/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Gallery Component Exports
+ */
+
+export { default as Gallery } from './Gallery.astro';
+export type { GalleryProps, GalleryImage } from './types';
+export { sortImages, getFileName, formatFilename } from './galleryUtils';

package/components/Gallery/react-photoswipe-gallery.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Type declarations for react-photoswipe-gallery
+ * Since @types/react-photoswipe-gallery doesn't exist, we provide minimal types
+ */
+
+declare module 'react-photoswipe-gallery' {
+  import { ReactNode } from 'react';
+
+  export interface GalleryProps {
+    children?: ReactNode;
+    options?: any;
+    uiElements?: any[];
+  }
+
+  export interface ItemProps {
+    original: string;
+    thumbnail?: string;
+    width: number | string;
+    height: number | string;
+    caption?: string;
+    children?: (props: { ref: any; open: () => void }) => ReactNode;
+  }
+
+  export const Gallery: React.FC<GalleryProps>;
+  export const Item: React.FC<ItemProps>;
+}

package/components/Gallery/types.ts

@@ -0,0 +1,46 @@
+/**
+ * Type definitions for Gallery component
+ */
+
+export interface GalleryImage {
+  src: string;
+  thumb: string;
+  width: number;
+  height: number;
+  alt: string;
+  caption?: string;
+}
+
+export interface GalleryProps {
+  /**
+   * Name of a shared gallery under usr/galleries/<name>/
+   * If not provided (and `images` isn't either), auto-loads from the
+   * `gallery/` folder colocated with the current page/content file.
+   */
+  name?: string;
+
+  /**
+   * Array of image objects to display
+   * Explicit escape hatch — takes precedence over `name` and auto-loading
+   */
+  images?: GalleryImage[];
+
+  /**
+   * Reverse the default sorting order (DESC by name) of images
+   * When true, images will be sorted in ascending order
+   */
+  reverseSorting?: boolean;
+
+  /**
+   * Grid configuration
+   */
+  columns?: {
+    min?: number;
+    max?: number;
+  };
+
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+}

package/components/Gallery/virtual-gallery.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Type declarations for the virtual module generated by
+ * core/integrations/galleryIntegration.ts. See that file for why this exists.
+ */
+declare module 'virtual:scms/galleries' {
+  type ImageModule = { default: { src: string; width: number; height: number; format?: string } };
+  type CaptionsModule = { default: Record<string, string> } | Record<string, string>;
+
+  export const pagesImages: Record<string, ImageModule>;
+  export const contentImages: Record<string, ImageModule>;
+  export const sharedImages: Record<string, ImageModule>;
+  export const pagesCaptions: Record<string, CaptionsModule>;
+  export const contentCaptions: Record<string, CaptionsModule>;
+  export const sharedCaptions: Record<string, CaptionsModule>;
+}

package/components/Map/LayerControl.tsx

@@ -0,0 +1,368 @@
+import React, { useState, useEffect, useRef, useLayoutEffect } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { createPortal } from 'react-dom';
+import { Layers, Search, X } from 'lucide-react';
+import type { IControl } from 'maplibre-gl';
+import type { BaseLayerConfig, VectorLayerConfig, ControlPosition, SearchInFields, SearchQuery } from './types';
+import { SearchUI } from './Search';
+
+export interface LayerControlProps {
+  baseLayers?: BaseLayerConfig[];
+  activeBaseLayer?: number;
+  onBaseLayerChange?: (index: number) => void;
+  vectorLayers?: Array<VectorLayerConfig & { id: string }>;
+  vectorLayerVisibility?: Record<string, boolean>;
+  onVectorLayerToggle?: (layerId: string) => void;
+  onLayerSearch?: (layerId: string, query: SearchQuery) => void;
+  layerSearchQueries?: Record<string, SearchQuery>;
+  position?: ControlPosition;
+}
+
+// Internal React component for the control UI
+function LayerControlUI({ 
+  baseLayers = [], 
+  activeBaseLayer = 0, 
+  onBaseLayerChange,
+  vectorLayers = [],
+  vectorLayerVisibility = {},
+  onVectorLayerToggle,
+  onLayerSearch,
+  layerSearchQueries = {},
+}: Omit<LayerControlProps, 'position'>) {
+  const [isExpanded, setIsExpanded] = useState(false);
+  const [searchModal, setSearchModal] = useState<{isOpen: boolean, layerId: string, layerName: string, fieldList: SearchInFields, currentQuery?: SearchQuery} | null>(null);
+  const radioGroupId = React.useId();
+  const timeoutRef = React.useRef<NodeJS.Timeout | null>(null);
+
+  const hasContent = baseLayers.length > 0 || vectorLayers.length > 0;
+  if (!hasContent) return null;
+
+  const handleMouseEnter = () => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+    setIsExpanded(true);
+  };
+
+  const handleMouseLeave = () => {
+    timeoutRef.current = setTimeout(() => {
+      setIsExpanded(false);
+    }, 300);
+  };
+
+  const handleSearchClick = (layerId: string, layerName: string, searchInFields: SearchInFields) => {
+    // Prevent layout shift by preserving scrollbar space
+    const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
+    document.body.style.overflow = 'hidden';
+    document.body.style.paddingRight = `${scrollbarWidth}px`;
+    
+    setSearchModal({
+      isOpen: true,
+      layerId,
+      layerName,
+      fieldList: searchInFields,
+      currentQuery: layerSearchQueries[layerId]
+    });
+  };
+
+  const handleSearchClose = () => {
+    setSearchModal(null);
+    
+    // Defer body style restoration until after React re-render
+    setTimeout(() => {
+      document.body.style.overflow = '';
+      document.body.style.paddingRight = '';
+    }, 0);
+  };
+
+  const handleSearch = (query: SearchQuery) => {
+    if (searchModal && onLayerSearch) {
+      onLayerSearch(searchModal.layerId, query);
+    }
+    handleSearchClose();
+  };
+
+  useEffect(() => {
+    return () => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+      }
+      // Cleanup: restore body styles if component unmounts with modal open
+      if (searchModal?.isOpen) {
+        document.body.style.overflow = '';
+        document.body.style.paddingRight = '';
+      }
+    };
+  }, [searchModal?.isOpen]);
+
+  // Prevent re-render position shifts by using useLayoutEffect for immediate cleanup
+  useLayoutEffect(() => {
+    if (!searchModal?.isOpen) {
+      // Ensure body styles are restored immediately after modal closes
+      const timeoutId = setTimeout(() => {
+        if (document.body.style.overflow === 'hidden') {
+          document.body.style.overflow = '';
+          document.body.style.paddingRight = '';
+        }
+      }, 50); // Small delay to let React finish re-rendering
+
+      return () => clearTimeout(timeoutId);
+    }
+  }, [searchModal?.isOpen, layerSearchQueries]);
+
+  return (
+    <div onMouseEnter={handleMouseEnter} onMouseLeave={handleMouseLeave} style={{ position: 'relative' }}>
+      <div 
+        style={{ 
+          padding: '8px', 
+          fontWeight: 600, 
+          userSelect: 'none', 
+          display: 'flex', 
+          alignItems: 'center', 
+          justifyContent: 'center',
+          minHeight: '32px',
+          minWidth: '32px',
+          background: 'white',
+          borderRadius: '4px',
+          position: 'relative',
+          zIndex: 1
+        }}
+      >
+        {!isExpanded && <Layers size={20} />}
+      </div>
+      
+      {isExpanded && (
+        <div style={{ 
+          position: 'absolute',
+          top: 0,
+          right: 0,
+          backgroundColor: 'white',
+          borderRadius: '4px',
+          border: '1px solid rgba(0,0,0,0.1)',
+          boxShadow: '0 2px 10px rgba(0,0,0,0.1)',
+          padding: '8px 12px 12px 12px', 
+          minWidth: 180,
+          maxWidth: 250,
+          zIndex: 1000,
+          whiteSpace: 'nowrap'
+        }}>
+          
+          {/* Vector Layers Section */}
+          {vectorLayers.length > 0 && (
+            <div style={{ marginBottom: 10 }}>
+              {vectorLayers.map((layer) => (
+                <div key={layer.id} style={{ marginBottom: 6, display: 'flex', alignItems: 'center' }}>
+                  <input
+                    type="checkbox"
+                    id={`vector-layer-${layer.id}`}
+                    checked={vectorLayerVisibility[layer.id] !== false}
+                    onChange={() => onVectorLayerToggle?.(layer.id)}
+                    style={{ marginRight: 8, cursor: 'pointer' }}
+                  />
+                  <label 
+                    htmlFor={`vector-layer-${layer.id}`}
+                    style={{ cursor: 'pointer', fontSize: '12px', userSelect: 'none', flex: 1 }}
+                  >
+                    {layer.name}
+                  </label>
+                  {layer.searchInFields && Object.keys(layer.searchInFields).length > 0 && (
+                    <button
+                      type="button"
+                      onClick={() => handleSearchClick(layer.id, layer.name, layer.searchInFields!)}
+                      className={`btn btn-sm p-1 lh-1 border-0 ${
+                        layerSearchQueries[layer.id]?.filters?.length ? 'btn-primary' : 'btn-light'
+                      }`}
+                      title={`Search ${layer.name}${layerSearchQueries[layer.id]?.filters?.length ? ' (Active)' : ''}`}
+                    >
+                      <Search size={14} />
+                    </button>
+                  )}
+                </div>
+              ))}
+              {baseLayers.length > 0 && <hr style={{ margin: '8px 0', borderColor: '#eee' }} />}
+            </div>
+          )}
+
+          {/* Base Layers Section */}
+          {baseLayers.length > 0 && (
+            <div>
+              <div style={{ fontSize: '11px', color: '#666', fontWeight: 600, marginBottom: 4, textTransform: 'uppercase' }}>
+                Base Maps
+              </div>
+              {baseLayers.map((layer, index) => {
+                const isChecked = index === activeBaseLayer;
+                return (
+                  <div key={`${layer.name}-${index}`} style={{ marginBottom: 4, display: 'flex', alignItems: 'center' }}>
+                    <input
+                      type="radio"
+                      id={`base-layer-${radioGroupId}-${index}`}
+                      name={`base-layer-select-${radioGroupId}`}
+                      value={index}
+                      checked={isChecked}
+                      onChange={() => onBaseLayerChange?.(index)}
+                      style={{ 
+                        marginRight: 8, 
+                        cursor: 'pointer',
+                        width: '16px',
+                        height: '16px',
+                        accentColor: '#3b82f6'
+                      }}
+                    />
+                    <label 
+                      htmlFor={`base-layer-${radioGroupId}-${index}`}
+                      style={{ cursor: 'pointer', fontSize: '12px', userSelect: 'none' }}
+                    >
+                      {layer.name}
+                    </label>
+                  </div>
+                );
+              })}
+            </div>
+          )}
+        </div>
+      )}
+      
+      {/* Search Modal */}
+      {searchModal?.isOpen && createPortal(
+        <div 
+          style={{
+            position: 'fixed',
+            top: 0,
+            left: 0,
+            right: 0,
+            bottom: 0,
+            backgroundColor: 'rgba(0, 0, 0, 0.5)',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            zIndex: 10000,
+            overflowY: 'auto'
+          }}
+          onClick={handleSearchClose}
+        >
+          <div
+            className="bg-white rounded shadow"
+            style={{ maxHeight: 'calc(100vh - 4rem)', width: '500px', maxWidth: '90vw', margin: '2rem 1rem' }}
+            onClick={(e) => e.stopPropagation()}
+          >
+            <div className="d-flex justify-content-between align-items-center p-3 border-bottom">
+              <h3 className="h5 fw-semibold mb-0 d-flex align-items-center gap-2 flex-grow-1 pe-2">
+                <Search size={18} />
+                Search {searchModal.layerName}
+              </h3>
+              <button
+                onClick={handleSearchClose}
+                className="btn btn-sm btn-light flex-shrink-0"
+                aria-label="Close modal"
+              >
+                <X size={18} />
+              </button>
+            </div>
+            
+            <div className="p-3" style={{ overflowY: 'auto' }}>
+              <SearchUI
+                fieldList={searchModal.fieldList}
+                onSearch={handleSearch}
+                currentQuery={searchModal.currentQuery}
+              />
+            </div>
+          </div>
+        </div>,
+        document.body
+      )}
+    </div>
+  );
+}
+
+// MapLibre IControl wrapper
+export class LayerControlClass implements IControl {
+  private container: HTMLDivElement | undefined;
+  private root: Root | undefined;
+  private props: Omit<LayerControlProps, 'position'>;
+  private isAddedToMap: boolean = false;
+
+  constructor(props: Omit<LayerControlProps, 'position'>) {
+    this.props = props;
+  }
+
+  onAdd(): HTMLElement {
+    this.container = document.createElement('div');
+    this.container.className = 'maplibregl-ctrl maplibregl-ctrl-group';
+    
+    this.root = createRoot(this.container);
+    this.root.render(<LayerControlUI {...this.props} />);
+    this.isAddedToMap = true;
+    
+    return this.container;
+  }
+
+  onRemove(): void {
+    if (this.root) {
+      this.root.unmount();
+      this.root = undefined;
+    }
+    if (this.container) {
+      this.container.remove();
+    }
+    this.container = undefined;
+    this.isAddedToMap = false;
+  }
+
+  updateProps(newProps: Omit<LayerControlProps, 'position'>): void {
+    // Only update if the control is actually added to the map and props have changed
+    if (!this.isAddedToMap || !this.root) {
+      this.props = newProps;
+      return;
+    }
+
+    // Compare props to avoid unnecessary re-renders
+    const hasChanged = 
+      JSON.stringify(this.props.layerSearchQueries) !== JSON.stringify(newProps.layerSearchQueries) ||
+      JSON.stringify(this.props.vectorLayerVisibility) !== JSON.stringify(newProps.vectorLayerVisibility) ||
+      this.props.activeBaseLayer !== newProps.activeBaseLayer;
+
+    if (hasChanged) {
+      this.props = newProps;
+      // Use requestAnimationFrame to ensure the update happens after current execution
+      requestAnimationFrame(() => {
+        if (this.root && this.isAddedToMap) {
+          this.root.render(<LayerControlUI {...this.props} />);
+        }
+      });
+    }
+  }
+}
+
+// React component wrapper for use in @vis.gl/react-maplibre
+export function LayerControl(props: LayerControlProps) {
+  const controlRef = useRef<LayerControlClass | null>(null);
+  const previousPropsRef = useRef<LayerControlProps | undefined>(undefined);
+
+  // Only update if props have actually changed
+  useEffect(() => {
+    if (controlRef.current && previousPropsRef.current) {
+      const { position, ...restProps } = props;
+      const { position: prevPosition, ...prevRestProps } = previousPropsRef.current;
+      
+      // Only call updateProps if relevant props changed
+      if (JSON.stringify(restProps) !== JSON.stringify(prevRestProps)) {
+        controlRef.current.updateProps(restProps);
+      }
+    }
+    previousPropsRef.current = props;
+  }, [props.layerSearchQueries, props.vectorLayerVisibility, props.activeBaseLayer]);
+
+  // Create control instance only once
+  if (!controlRef.current) {
+    const { position, ...restProps } = props;
+    controlRef.current = new LayerControlClass(restProps);
+  }
+
+  // Return a placeholder that react-maplibre can recognize
+  // The actual control is added via map.addControl in Map.tsx
+  return null;
+}
+
+// Export the control class for direct use
+export { LayerControlClass as LayerControlIControl };