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

package/components/Map/types.ts

@@ -0,0 +1,179 @@
+/**
+ * Map Component Types
+ */
+
+import type { SourceConfig } from '../../utils/data-fetcher';
+import type { BasemapKey } from './defaultBasemaps';
+import type { FilterObject } from './utils';
+import type { DirectusShorthand } from '../../utils/directus-config';
+
+/**
+ * Search field configuration
+ * Can be a simple label string or an object with label and predefined values
+ */
+export type SearchFieldConfig = 
+  | string 
+  | { 
+      label: string; 
+      values?: string[]; 
+      operator?: string; 
+    };
+
+/**
+ * Search fields configuration for vector layers
+ * Maps field names to their search configuration
+ */
+export type SearchInFields = Record<string, SearchFieldConfig>;
+
+/**
+ * Search operators supported by the search interface
+ */
+export interface SearchOperators {
+  _eq: string;
+  _neq: string;
+  _lt: string;
+  _lte: string;
+  _gt: string;
+  _gte: string;
+  _null: string;
+  _nnull: string;
+  _contains: string;
+  _icontains: string;
+  _ncontains: string;
+  _starts_with: string;
+  _istarts_with: string;
+  _nstarts_with: string;
+  _ends_with: string;
+  _iends_with: string;
+  _nends_with: string;
+}
+
+/**
+ * Search filter triplet: field, operator, value
+ */
+export interface SearchFilter {
+  field: string;
+  operator: string;
+  value: any;
+}
+
+/**
+ * Search query structure
+ */
+export interface SearchQuery {
+  connector: '_and' | '_or';
+  filters: SearchFilter[];
+}
+
+export type ControlPosition = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
+
+export interface BaseLayerConfig {
+  name: string;
+  url: string;
+  attribution?: string;
+}
+
+export interface VectorLayerConfig {
+  /** Layer name/ID */
+  name: string;
+  
+  /** Data source configuration */
+  source: SourceConfig;
+  
+  /** Layer style (MapLibre paint/layout properties) */
+  style?: any;
+  
+  /** Popup template string (e.g., "<b>${Title}</b>: ${Description}") */
+  popupTemplate?: string;
+  
+  /** Initial visibility */
+  visible?: boolean;
+  
+  /** Fit map bounds to layer content */
+  fitToContent?: boolean;
+
+  /** Optional client-side filter for features */
+  filter?: FilterObject | ((feature: any) => boolean);
+  
+  /** Search configuration - defines which fields are searchable */
+  searchInFields?: SearchInFields;
+}
+
+export interface MapProps {
+  /** Map height (CSS string) */
+  height?: string;
+  
+  /** Initial center [lng, lat, zoom] as string "lng,lat,zoom" */
+  center?: string;
+  
+  /** MapLibre style object or URL (for full style specification) */
+  mapStyle?: string | object;
+  
+  /** Overrides/expansions for mapStyle layers */
+  styleOverrides?: {
+    [layerId: string]: {
+      /** Override layer paint properties */
+      paint?: any;
+      /** Override layer layout properties */
+      layout?: any;
+      /** Add popup template (expanded feature) */
+      popupTemplate?: string;
+      /** Fit map to layer bounds (expanded feature) */
+      fitToContent?: boolean;
+      /** Initial visibility (expanded feature) */
+      visible?: boolean;
+    };
+  };
+  
+  /** Base layers configuration (can be array of configs or array of basemap keys) */
+  baseLayers?: BaseLayerConfig[] | BasemapKey[];
+  
+  /** Vector layers configuration (alternative to children for hydration-safe usage) */
+  vectorLayers?: VectorLayerConfig[];
+  
+  /** Controls positions (null/undefined to hide) */
+  geolocateControl?: ControlPosition;
+  fullscreenControl?: ControlPosition;
+  navigationControl?: ControlPosition;
+  scaleControl?: ControlPosition;
+  
+  /** Show layer control for basemap switching (default: true) */
+  layerControl?: boolean | ControlPosition;
+  
+  /** Optional sprite URL */
+  sprite?: string;
+  
+  /** GeoJSON shorthand - for simple single-layer maps */
+  geojson?: string | object | {
+    path: string;
+    name?: string;
+    style?: any;
+    popup?: string;
+    fitToContent?: boolean;
+    filter?: FilterObject | ((feature: any) => boolean);
+  };
+  
+  /** CSV shorthand - for simple single-layer maps */
+  csv?: string | {
+    path: string;
+    lng: string;
+    lat: string;
+    name?: string;
+    style?: any;
+    popup?: string;
+    fitToContent?: boolean;
+    filter?: FilterObject | ((row: any) => boolean);
+  };
+  
+  /** JSON shorthand - for simple single-layer maps */
+  json?: any[] | string;
+  
+  /** Directus shorthand - for simple single-layer maps */
+  directus?: DirectusShorthand & {
+    geoField?: string;
+    name?: string;
+    style?: any;
+    popup?: string;
+    fitToContent?: boolean;
+  };
+}

package/components/Map/utils.ts

@@ -0,0 +1,367 @@
+/**
+ * Map Utilities
+ */
+
+import type { DataRow } from '../../utils/data-fetcher';
+import type { FeatureCollection, Feature, Geometry } from 'geojson';
+
+/**
+ * Tries to identify latitude and longitude fields from a data row
+ */
+export function getGeoFields(row: DataRow): { latField: string; lngField: string } | null {
+  const keys = Object.keys(row);
+  
+  const latField = keys.find(k => /^(lat|latitude|y)$/i.test(k));
+  const lngField = keys.find(k => /^(lng|long|longitude|x)$/i.test(k));
+  
+  if (latField && lngField) {
+    return { latField, lngField };
+  }
+  
+  return null;
+}
+
+/**
+ * Converts generic data rows to GeoJSON FeatureCollection
+ * Handles both coordinate-based data and data already containing geometry
+ */
+export function dataToGeoJson(
+  data: DataRow[],
+  customLngField?: string,
+  customLatField?: string,
+  geoField?: string
+): FeatureCollection {
+  const features: Feature[] = [];
+  
+  if (data.length === 0) {
+    return { type: 'FeatureCollection', features: [] };
+  }
+  
+  // Check if data already has geometry (from GeoJSON source)
+  if (data[0]._geometry) {
+    data.forEach((row, index) => {
+      features.push({
+        type: 'Feature',
+        id: row._id || row.id || index,
+        geometry: row._geometry,
+        properties: { ...row, _geometry: undefined, _id: undefined }
+      });
+    });
+    return { type: 'FeatureCollection', features };
+  }
+  
+  // Check if geoField is provided (from Directus or other sources)
+  if (geoField && data[0][geoField]) {
+    data.forEach((row, index) => {
+      let geometry = row[geoField];
+      
+      // Parse geometry if it's a string (JSON)
+      if (typeof geometry === 'string') {
+        try {
+          geometry = JSON.parse(geometry);
+        } catch (e) {
+          console.warn(`Failed to parse geometry field "${geoField}" for row ${index}:`, e);
+          return;
+        }
+      }
+      
+      // Validate geometry object
+      if (geometry && typeof geometry === 'object' && geometry.type && geometry.coordinates) {
+        features.push({
+          type: 'Feature',
+          id: row.id || index,
+          geometry: geometry as Geometry,
+          properties: { ...row, [geoField]: undefined }
+        });
+      }
+    });
+    return { type: 'FeatureCollection', features };
+  }
+  
+  // If custom fields provided, use them
+  let latField = customLatField;
+  let lngField = customLngField;
+  
+  // Otherwise, try to detect lat/lng fields
+  if (!latField || !lngField) {
+    const geoFields = getGeoFields(data[0]);
+    if (!geoFields) {
+      console.warn('Map: Could not auto-detect simple lat/lng fields in data. GeoJSON conversion failed.');
+      return { type: 'FeatureCollection', features: [] };
+    }
+    latField = latField || geoFields.latField;
+    lngField = lngField || geoFields.lngField;
+  }
+  
+  data.forEach((row, index) => {
+    const lat = Number(row[latField!]);
+    const lng = Number(row[lngField!]);
+    
+    if (!isNaN(lat) && !isNaN(lng)) {
+      features.push({
+        type: 'Feature',
+        id: row.id || index,
+        geometry: {
+          type: 'Point',
+          coordinates: [lng, lat]
+        },
+        properties: row
+      });
+    }
+  });
+  
+  return {
+    type: 'FeatureCollection',
+    features
+  };
+}
+
+/**
+ * Escapes a string for safe interpolation into HTML markup/attributes.
+ */
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/**
+ * Parses simple string templates with ${variable} syntax.
+ *
+ * The template itself is treated as trusted markup (it's author-supplied,
+ * e.g. `popupTemplate: '<b>${Title}</b>'`), but each interpolated value comes
+ * from feature/row data — which may be third-party or user-submitted content
+ * (CSV, GeoJSON, Directus) — and is HTML-escaped before substitution, since
+ * the result is rendered via dangerouslySetInnerHTML.
+ */
+export function parseStringTemplate(template: string, data: Record<string, any>): string {
+  return template.replace(/\$\{([^}]+)\}/g, (_, key) => {
+    return data[key] !== undefined ? escapeHtml(String(data[key])) : '';
+  });
+}
+
+/**
+ * Filter object syntax type (similar to Directus filtering)
+ * 
+ * Example:
+ * { field: { _eq: 'value' } }
+ * { field: { _neq: 'value' } }
+ * { field: { _in: ['value1', 'value2'] } }
+ * { field: { _contains: 'substring' } }
+ * { field: { _gt: 100 }, field2: { _eq: 'value' } } // Multiple conditions (AND)
+ */
+export type FilterObject = {
+  [field: string]: {
+    _eq?: any;
+    _neq?: any;
+    _in?: any[];
+    _nin?: any[];
+    _contains?: string;
+    _ncontains?: string;
+    _gt?: number;
+    _gte?: number;
+    _lt?: number;
+    _lte?: number;
+    _null?: boolean;
+    _nnull?: boolean;
+  };
+};
+
+/**
+ * Converts a Directus-like filter object to a JavaScript predicate function
+ * Supports both GeoJSON features and CSV rows
+ */
+export function filterObjectToPredicate(
+  filterObj: FilterObject
+): (item: Feature | DataRow) => boolean {
+  return (item: Feature | DataRow) => {
+    // Get properties (for GeoJSON features) or use item directly (for CSV rows)
+    const properties = 'properties' in item ? item.properties : item;
+    
+    // Check all field conditions (AND logic)
+    for (const [field, conditions] of Object.entries(filterObj)) {
+      const value = properties?.[field];
+      
+      // Check each operator
+      for (const [operator, expected] of Object.entries(conditions)) {
+        switch (operator) {
+          case '_eq':
+            if (value != expected) return false; // Loose equality
+            break;
+          case '_neq':
+            if (value == expected) return false;
+            break;
+          case '_in':
+            if (!Array.isArray(expected) || !expected.includes(value)) return false;
+            break;
+          case '_nin':
+            if (!Array.isArray(expected) || expected.includes(value)) return false;
+            break;
+          case '_contains':
+            if (typeof value !== 'string' || !value.includes(String(expected))) return false;
+            break;
+          case '_ncontains':
+            if (typeof value !== 'string' || value.includes(String(expected))) return false;
+            break;
+          case '_gt':
+            if (Number(value) <= Number(expected)) return false;
+            break;
+          case '_gte':
+            if (Number(value) < Number(expected)) return false;
+            break;
+          case '_lt':
+            if (Number(value) >= Number(expected)) return false;
+            break;
+          case '_lte':
+            if (Number(value) > Number(expected)) return false;
+            break;
+          case '_null':
+            if (expected === true && value != null) return false;
+            if (expected === false && value == null) return false;
+            break;
+          case '_nnull':
+            if (expected === true && value == null) return false;
+            if (expected === false && value != null) return false;
+            break;
+        }
+      }
+    }
+    
+    return true;
+  };
+}
+
+/**
+ * Converts a search query to a MapLibre filter expression
+ * This provides better performance than client-side filtering for large datasets
+ */
+export function searchQueryToMapLibreFilter(query: import('./types').SearchQuery): any[] | null {
+  if (!query.filters || query.filters.length === 0) {
+    return null; // No filter
+  }
+
+  const filters = query.filters.map(filter => {
+    const { field, operator, value } = filter;
+    
+    switch (operator) {
+      case '_eq':
+        return ['==', ['get', field], value];
+      case '_neq':
+        return ['!=', ['get', field], value];
+      case '_gt':
+        return ['>', ['get', field], value];
+      case '_gte':
+        return ['>=', ['get', field], value];
+      case '_lt':
+        return ['<', ['get', field], value];
+      case '_lte':
+        return ['<=', ['get', field], value];
+      case '_contains':
+        return ['in', value, ['get', field]];
+      case '_icontains':
+        // Case-insensitive contains using downcase for both field value and search value
+        return ['in', ['downcase', value], ['downcase', ['get', field]]];
+      case '_ncontains':
+        return ['!', ['in', value, ['get', field]]];
+      case '_starts_with':
+        return ['==', ['slice', ['get', field], 0, value.length], value];
+      case '_istarts_with':
+        // Case-insensitive starts with using downcase
+        return ['==', ['slice', ['downcase', ['get', field]], 0, value.length], ['downcase', value]];
+      case '_nstarts_with':
+        return ['!=', ['slice', ['get', field], 0, value.length], value];
+      case '_ends_with':
+        return ['==', ['slice', ['get', field], ['-', ['length', ['get', field]], value.length]], value];
+      case '_iends_with':
+        // Case-insensitive ends with using downcase
+        return ['==', ['slice', ['downcase', ['get', field]], ['-', ['length', ['get', field]], value.length]], ['downcase', value]];
+      case '_nends_with':
+        return ['!=', ['slice', ['get', field], ['-', ['length', ['get', field]], value.length]], value];
+      case '_null':
+        return ['==', ['get', field], null];
+      case '_nnull':
+        return ['!=', ['get', field], null];
+      default:
+        console.warn(`Unsupported search operator for MapLibre filter: ${operator}`);
+        return ['==', ['get', field], value];
+    }
+  });
+
+  // Combine filters with the specified connector
+  if (filters.length === 1) {
+    return filters[0];
+  }
+
+  if (query.connector === '_and') {
+    return ['all', ...filters];
+  } else {
+    return ['any', ...filters];
+  }
+}
+
+/**
+ * Converts a search query to a client-side predicate function
+ * Fallback when MapLibre filtering is not suitable or for complex operations
+ */
+export function searchQueryToPredicate(query: import('./types').SearchQuery): (item: Feature | DataRow) => boolean {
+  if (!query.filters || query.filters.length === 0) {
+    return () => true; // No filter, match all
+  }
+
+  return (item: Feature | DataRow) => {
+    const properties = 'properties' in item ? item.properties : item;
+    
+    const results = query.filters.map(filter => {
+      const { field, operator, value } = filter;
+      const fieldValue = properties?.[field];
+      
+      switch (operator) {
+        case '_eq':
+          return fieldValue == value;
+        case '_neq':
+          return fieldValue != value;
+        case '_gt':
+          return Number(fieldValue) > Number(value);
+        case '_gte':
+          return Number(fieldValue) >= Number(value);
+        case '_lt':
+          return Number(fieldValue) < Number(value);
+        case '_lte':
+          return Number(fieldValue) <= Number(value);
+        case '_contains':
+          return typeof fieldValue === 'string' && fieldValue.includes(String(value));
+        case '_icontains':
+          return typeof fieldValue === 'string' && fieldValue.toLowerCase().includes(String(value).toLowerCase());
+        case '_ncontains':
+          return typeof fieldValue === 'string' && !fieldValue.includes(String(value));
+        case '_starts_with':
+          return typeof fieldValue === 'string' && fieldValue.startsWith(String(value));
+        case '_istarts_with':
+          return typeof fieldValue === 'string' && fieldValue.toLowerCase().startsWith(String(value).toLowerCase());
+        case '_nstarts_with':
+          return typeof fieldValue === 'string' && !fieldValue.startsWith(String(value));
+        case '_ends_with':
+          return typeof fieldValue === 'string' && fieldValue.endsWith(String(value));
+        case '_iends_with':
+          return typeof fieldValue === 'string' && fieldValue.toLowerCase().endsWith(String(value).toLowerCase());
+        case '_nends_with':
+          return typeof fieldValue === 'string' && !fieldValue.endsWith(String(value));
+        case '_null':
+          return fieldValue == null;
+        case '_nnull':
+          return fieldValue != null;
+        default:
+          console.warn(`Unsupported search operator: ${operator}`);
+          return true;
+      }
+    });
+    
+    // Apply connector logic
+    return query.connector === '_and' 
+      ? results.every(Boolean)
+      : results.some(Boolean);
+  };
+}

package/components/README.md

@@ -0,0 +1,62 @@
+# Core Components
+
+This directory contains reusable, framework-level components that provide essential functionality for the s:CMS system.
+
+## Components
+
+### SEO.astro
+
+Comprehensive SEO component that generates meta tags and structured data for search engines and social media.
+
+**Usage:**
+
+```astro
+---
+import SEO from '@lad-sapienza/scms-core/components/SEO/SEO.astro';
+---
+
+<head>
+  <SEO 
+    title="Page Title"
+    description="Page description"
+    image="/images/og-image.jpg"
+    author="Author Name"
+    isArticle={true}
+    datePublished="2026-01-14"
+    tags={['tag1', 'tag2']}
+  />
+</head>
+```
+
+**Props:**
+- `title` (string, optional) - Page title
+- `description` (string, optional) - Page description
+- `image` (string, optional) - Social media image URL
+- `author` (string, optional) - Content author name
+- `isArticle` (boolean, optional) - Whether this is an article (adds Article schema)
+- `datePublished` (string|Date, optional) - Publication date
+- `dateModified` (string|Date, optional) - Last modification date
+- `tags` (string[], optional) - Article tags
+- `canonical` (string, optional) - Canonical URL override
+
+**Features:**
+- Open Graph meta tags for Facebook/LinkedIn
+- Twitter Card meta tags
+- JSON-LD structured data for articles
+- Automatic canonical URL generation
+- Image URL resolution
+
+## Extending Core
+
+Core components should be:
+1. **Framework-level**: Provide essential, reusable functionality
+2. **Well-documented**: Include usage examples and prop descriptions
+3. **Tested**: Ensure they work across different use cases
+4. **Minimal dependencies**: Keep external dependencies to a minimum
+
+## User Customization
+
+Users should **not** edit core components directly. Instead:
+- Override behavior in `usr/layouts/`
+- Create custom components in `usr/components/`
+- Extend layouts with slots and composition

package/components/Record/Field.tsx

@@ -0,0 +1,35 @@
+import React, { useContext } from 'react';
+import { RecordContext } from './context';
+import { getValueByDotPath } from './utils';
+
+export interface FieldProps {
+  name: string;
+  transformer?: (value: any) => React.ReactNode;
+  fallback?: React.ReactNode;
+  record?: any;
+}
+
+export function Field({ name, transformer, fallback = null, record }: FieldProps) {
+  const contextRecord = useContext(RecordContext);
+  const sourceRecord = record ?? contextRecord;
+
+  if (!sourceRecord) return <>{fallback}</>;
+
+  const value = getValueByDotPath(sourceRecord, name);
+
+  if (value === undefined || value === null || value === '') {
+    return <>{fallback}</>;
+  }
+
+  if (transformer) {
+    return <>{transformer(value)}</>;
+  }
+
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+    return <>{String(value)}</>;
+  }
+
+  return <>{JSON.stringify(value, null, 2)}</>;
+}
+
+export default Field;