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

package/components/DataTb/utils.ts

@@ -0,0 +1,186 @@
+/**
+ * DataTb Utility Functions
+ * 
+ * Helper functions for data transformation, column generation, and formatting
+ */
+
+import type { ColumnDef } from '@tanstack/react-table';
+import type { DataRow, ColumnConfig } from './types';
+
+/**
+ * Auto-detect columns from data
+ */
+export function autoDetectColumns(data: DataRow[]): ColumnConfig[] {
+  if (!data || data.length === 0) return [];
+  
+  const firstRow = data[0];
+  const keys = Object.keys(firstRow);
+  
+  return keys.map(key => ({
+    key,
+    header: formatHeader(key),
+    sortable: true,
+  }));
+}
+
+/**
+ * Convert snake_case or camelCase to Title Case
+ */
+export function formatHeader(key: string): string {
+  return key
+    .replace(/([A-Z])/g, ' $1') // camelCase to words
+    .replace(/_/g, ' ') // snake_case to words
+    .replace(/\b\w/g, (l) => l.toUpperCase()) // capitalize first letter
+    .trim();
+}
+
+/**
+ * Format value based on format type
+ */
+export function formatValue(value: any, format?: string): string {
+  if (value === null || value === undefined) return '';
+  
+  switch (format) {
+    case 'date':
+      return formatDate(value);
+    case 'number':
+      return formatNumber(value);
+    case 'currency':
+      return formatCurrency(value);
+    case 'percent':
+      return formatPercent(value);
+    default:
+      return String(value);
+  }
+}
+
+/**
+ * Format date value
+ */
+export function formatDate(value: any): string {
+  try {
+    if (!value) return '';
+    const date = new Date(value);
+    if (isNaN(date.getTime())) return String(value);
+    
+    return new Intl.DateTimeFormat('en-US', {
+      year: 'numeric',
+      month: 'short',
+      day: 'numeric',
+    }).format(date);
+  } catch {
+    return String(value);
+  }
+}
+
+/**
+ * Format number value
+ */
+export function formatNumber(value: any): string {
+  const num = Number(value);
+  if (isNaN(num)) return String(value);
+  
+  return new Intl.NumberFormat('en-US').format(num);
+}
+
+/**
+ * Format currency value (USD by default)
+ */
+export function formatCurrency(value: any, currency: string = 'USD'): string {
+  const num = Number(value);
+  if (isNaN(num)) return String(value);
+  
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency,
+  }).format(num);
+}
+
+/**
+ * Format percentage value
+ */
+export function formatPercent(value: any): string {
+  const num = Number(value);
+  if (isNaN(num)) return String(value);
+  
+  return new Intl.NumberFormat('en-US', {
+    style: 'percent',
+    minimumFractionDigits: 0,
+    maximumFractionDigits: 2,
+  }).format(num);
+}
+
+/**
+ * Convert ColumnConfig to TanStack ColumnDef
+ */
+export function columnConfigToColumnDef(config: ColumnConfig): ColumnDef<DataRow> {
+  return {
+    id: config.key,
+    accessorKey: config.key,
+    header: config.header,
+    enableSorting: config.sortable ?? true,
+    meta: { width: config.width },
+    cell: (info) => {
+      const value = info.getValue();
+      const row = info.row.original;
+      
+      // Use custom render if provided
+      if (config.render) {
+        return config.render(value, row);
+      }
+      
+      // Use labels map if provided
+      if (config.labels) {
+        const key = String(value);
+        if (config.labels[key]) {
+          return config.labels[key];
+        }
+      }
+      
+      // Apply format if specified
+      return formatValue(value, config.format);
+    },
+  };
+}
+
+/**
+ * Merge auto-detected columns with user-provided overrides
+ */
+export function mergeColumns(
+  autoColumns: ColumnConfig[],
+  userColumns?: ColumnConfig[]
+): ColumnConfig[] {
+  // If no user columns, use all auto-detected columns
+  if (!userColumns || userColumns.length === 0) {
+    return autoColumns;
+  }
+  
+  // Exclusive Mode:
+  // Return ONLY user columns, but enrich them with auto-detected defaults (like headers) if available
+  return userColumns.map(userCol => {
+    const autoCol = autoColumns.find(ac => ac.key === userCol.key);
+    // If we found a match, merge defaults from autoCol, but let userCol override
+    if (autoCol) {
+      return { ...autoCol, ...userCol };
+    }
+    // If no match (computed column or non-existent key), return userCol as is
+    return userCol;
+  });
+}
+
+/**
+ * Global filter function for searchable tables
+ */
+export function globalFilterFn(
+  row: any,
+  columnId: string,
+  filterValue: string
+): boolean {
+  const value = row.getValue(columnId);
+  
+  if (value === null || value === undefined) return false;
+  
+  return String(value)
+    .toLowerCase()
+    .includes(String(filterValue).toLowerCase());
+}

package/components/Gallery/Gallery.astro

@@ -0,0 +1,65 @@
+---
+/**
+ * Gallery Component
+ *
+ * Renders a responsive image grid with a PhotoSwipe lightbox. Usable from
+ * both .astro files and MDX content bodies (see core/integrations/galleryIntegration.ts
+ * for how auto-loading works without each caller needing its own glob).
+ *
+ * <Gallery />                     colocated: ./gallery/ next to this page/content file
+ * <Gallery name="scavi-2024" />   shared: usr/galleries/scavi-2024/
+ * <Gallery images={[...]} />      explicit: pass images directly (remote, custom order, ...)
+ */
+import { Gallery as GalleryClient } from './Gallery';
+import { getColocatedGalleryImages, getSharedGalleryImages, sortImages } from './galleryUtils';
+import type { GalleryProps } from './types';
+
+const { name, images: explicitImages, reverseSorting = false, columns = { min: 200, max: 1 }, className } = Astro.props as GalleryProps;
+
+// Auto-loaded images (colocated/shared) are always sorted by filename —
+// DESC by default, ASC when reverseSorting is set. Explicit `images` are
+// left in exactly the order the caller gave them, since a custom order is
+// one of the reasons to use that escape hatch in the first place.
+let finalImages;
+
+if (explicitImages && explicitImages.length > 0) {
+  finalImages = explicitImages;
+} else if (name) {
+  finalImages = sortImages(getSharedGalleryImages(name), reverseSorting);
+} else {
+  finalImages = sortImages(getColocatedGalleryImages(Astro.url.pathname), reverseSorting);
+}
+---
+
+{finalImages.length > 0 ? (
+  <GalleryClient
+    images={finalImages}
+    columns={columns}
+    className={className}
+    client:idle
+  />
+) : (
+  <p class="gallery-empty">
+    No images found{name && <> for gallery "<code>{name}</code>"</>}.
+    {!name && !explicitImages && (
+      <> Add images to a <code>gallery/</code> folder next to this page.</>
+    )}
+  </p>
+)}
+
+<style>
+  .gallery-empty {
+    padding: 2rem;
+    background: #f5f5f5;
+    border-radius: 8px;
+    text-align: center;
+    color: #666;
+  }
+
+  .gallery-empty code {
+    background: #e0e0e0;
+    padding: 2px 6px;
+    border-radius: 3px;
+    font-family: monospace;
+  }
+</style>

package/components/Gallery/Gallery.tsx

@@ -0,0 +1,136 @@
+/**
+ * Gallery Component
+ * 
+ * React component for displaying image gallery with PhotoSwipe lightbox
+ */
+
+
+import { Gallery as PhotoSwipeGallery, Item } from 'react-photoswipe-gallery';
+import type { GalleryImage } from './types';
+import 'photoswipe/dist/photoswipe.css';
+
+interface Props {
+  images?: GalleryImage[];
+  columns?: {
+    min?: number;
+    max?: number;
+  };
+  className?: string;
+}
+
+const captionStyle = `
+  .pswp__custom-caption {
+    background: rgba(0, 0, 0, 0.75);
+    font-size: 16px;
+    color: #fff;
+    width: 100%;
+    max-width: 100%;
+    padding: 12px 16px;
+    border-radius: 0;
+    position: absolute;
+    left: 0;
+    bottom: 0;
+    text-align: center;
+  }
+  .pswp__custom-caption a {
+    color: #fff;
+    text-decoration: underline;
+  }
+`;
+
+export function Gallery({
+  images = [],
+  columns = { min: 200, max: 1 },
+  className = '',
+}: Props) {
+  if (images.length === 0) {
+    return null;
+  }
+
+  // Ensure defaults for columns
+  const minWidth = columns?.min ?? 200;
+  const maxWidth = columns?.max ?? 1;
+
+  return (
+    <>
+      <style>{captionStyle}</style>
+      <PhotoSwipeGallery
+        options={{
+          showHideAnimationType: 'fade',
+          showAnimationDuration: 0,
+          hideAnimationDuration: 0,
+        }}
+        uiElements={[
+          {
+            name: 'custom-caption',
+            order: 9,
+            isButton: false,
+            appendTo: 'root',
+            html: '',
+            onInit: (el: any, pswpInstance: any) => {
+              el.classList.add('pswp__custom-caption');
+              
+              pswpInstance.on('change', () => {
+                const currSlideElement = pswpInstance.currSlide?.data?.element;
+                // Captions are plain text (from captions.json or a filename) — use
+                // textContent, not innerHTML, so caption text can never be parsed as markup.
+                el.textContent = currSlideElement?.getAttribute('data-caption') || '';
+              });
+            },
+          },
+        ]}
+      >
+        <div
+          className={`gallery-grid ${className}`}
+          style={{
+            display: 'grid',
+            gridTemplateColumns: `repeat(auto-fill, minmax(${minWidth}px, ${maxWidth}fr))`,
+            gap: '8px',
+            padding: 0,
+          }}
+        >
+          {images.map((image, index) => (
+            <Item
+              key={index}
+              original={image.src}
+              thumbnail={image.thumb}
+              width={image.width}
+              height={image.height}
+              caption={image.caption || image.alt}
+            >
+              {({ ref, open }: any) => (
+                <div
+                  ref={ref}
+                  onClick={open}
+                  onKeyDown={(e) => {
+                    if (e.key === 'Enter' || e.key === ' ') {
+                      e.preventDefault();
+                      open();
+                    }
+                  }}
+                  role="button"
+                  tabIndex={0}
+                  style={{ cursor: 'pointer', overflow: 'hidden', borderRadius: '4px' }}
+                  data-caption={image.caption || image.alt}
+                  aria-label={`Open image: ${image.alt}`}
+                >
+                  <img
+                    src={image.thumb}
+                    alt={image.alt}
+                    style={{
+                      width: '100%',
+                      height: '100%',
+                      objectFit: 'cover',
+                      aspectRatio: '1',
+                      display: 'block',
+                    }}
+                  />
+                </div>
+              )}
+            </Item>
+          ))}
+        </div>
+      </PhotoSwipeGallery>
+    </>
+  );
+}

package/components/Gallery/README.md

@@ -0,0 +1,118 @@
+# Gallery Component
+
+A responsive image gallery component with PhotoSwipe lightbox integration. One component, usable the same way from `.astro` files and MDX content — no `import.meta.glob` needed in your own page or content file.
+
+## Features
+
+- 📸 **PhotoSwipe Lightbox**: Full-screen image viewing with zoom and navigation
+- 🎨 **Responsive Grid**: Auto-adjusting columns based on screen size
+- 🔄 **Auto-loading**: automatically discovers images in a `gallery/` folder colocated with the current page/content file
+- 🔗 **Shared galleries**: reference one set of images by name from `usr/galleries/<name>/`
+- 🔍 **Custom Captions**: via `captions.json`, or auto-generated from filenames
+- ⌨️ **Keyboard Navigation**: Arrow keys and ESC support
+- ♿ **Accessible**: Proper ARIA labels and keyboard support
+
+## How auto-loading works
+
+`Gallery.astro` doesn't glob its own files — a separate integration
+(`core/integrations/galleryIntegration.ts`, bundled into `core/scms.ts` and wired into `astro.config.mjs`)
+generates a Vite virtual module (`virtual:scms/galleries`) containing the
+`import.meta.glob()` calls, at project build time. `Gallery.astro` just reads
+from that virtual module and matches by URL path. This exists so the component
+can move into an npm package later without losing auto-loading (a component
+shipped in `node_modules/` can't statically glob a consumer project's files;
+the integration generating the glob call at the consumer's own build time
+can). See `core/integrations/galleryIntegration.ts`'s own doc comment for
+details, and `core/components/Gallery/galleryUtils.ts` for the matching logic.
+
+## Usage
+
+### Colocated (default) — auto-loads from a sibling `gallery/` folder
+
+```
+usr/content/blog/my-post/
+  index.mdx
+  gallery/
+    photo1.jpg
+    photo2.jpg
+    captions.json      ← optional
+```
+
+```mdx
+import { Gallery } from '@lad-sapienza/scms-core/components/Gallery';
+
+<Gallery />
+```
+
+Matching is based on the current page's URL path against the folder
+structure on disk. **Known limitation**: if a content collection entry
+overrides its slug, or the site is deployed under a non-root `base`, the URL
+path can diverge from the on-disk folder path and the match silently finds
+nothing. Use `name` (below) or `images` as a workaround in that case.
+
+### Shared — referenced by name from any page
+
+```
+usr/galleries/
+  scavi-2024/
+    photo1.jpg
+    photo2.jpg
+    captions.json      ← optional
+```
+
+```mdx
+<Gallery name="scavi-2024" />
+```
+
+### Explicit — pass images directly
+
+Escape hatch for remote images, a Directus-backed source, or a custom order.
+Takes precedence over both `name` and auto-loading.
+
+```jsx
+<Gallery
+  images={[
+    { src: '/photos/img1.jpg', thumb: '/photos/img1.jpg', width: 1200, height: 800, alt: 'Description', caption: 'My custom caption' },
+  ]}
+/>
+```
+
+## Custom Captions
+
+By default, captions are generated from filenames (e.g., `my-photo.jpg` → "My Photo"). Place a `captions.json` file in the same `gallery/` folder (colocated) or shared-gallery folder to override them:
+
+```json
+{
+  "photo1.jpg": "A beautiful sunset over the mountains",
+  "photo2.jpg": "Morning coffee with a view"
+}
+```
+
+Keys can be filenames with or without extensions, and can use a different
+resolution suffix than the actual file (`_1280`, `_1920`, etc.) — matching is
+fuzzy on the base filename. A malformed `captions.json` (not a flat
+string-to-string map) is ignored with a console warning rather than breaking
+the build.
+
+## Props API
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `name` | `string` | — | Load a shared gallery from `usr/galleries/<name>/` |
+| `images` | `GalleryImage[]` | — | Explicit images — takes precedence over `name` and auto-loading |
+| `reverseSorting` | `boolean` | `false` | Reverse the default alphabetical sort |
+| `columns` | `{ min?: number, max?: number }` | `{ min: 200, max: 1 }` | `min` = minimum item width in px; `max` = maximum column count |
+| `className` | `string` | — | Additional CSS classes |
+
+### GalleryImage Type
+
+```typescript
+interface GalleryImage {
+  src: string;       // Full-size image URL
+  thumb: string;     // Thumbnail URL
+  width: number;
+  height: number;
+  alt: string;
+  caption?: string;
+}
+```

package/components/Gallery/__tests__/galleryUtils.test.ts

@@ -0,0 +1,178 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+const manifest = {
+  pagesImages: {
+    '/usr/pages/my-page/gallery/photo1.jpg': { default: { src: '/_astro/photo1.abc123.jpg', width: 1200, height: 800 } },
+  },
+  contentImages: {
+    '/usr/content/blog/my-article/gallery/photo2.jpg': { default: { src: '/_astro/photo2.def456.jpg', width: 1000, height: 600 } },
+    '/usr/content/blog/other-article/gallery/photo3.jpg': { default: { src: '/_astro/photo3.ghi789.jpg', width: 900, height: 500 } },
+  },
+  sharedImages: {
+    '/usr/galleries/scavi-2024/site-a.jpg': { default: { src: '/_astro/site-a.jkl000.jpg', width: 800, height: 600 } },
+    '/usr/galleries/scavi-2024/site-b_1920.jpg': { default: { src: '/_astro/site-b_1920.mno111.jpg', width: 800, height: 600 } },
+    '/usr/galleries/other-name/site-c.jpg': { default: { src: '/_astro/site-c.pqr222.jpg', width: 800, height: 600 } },
+  },
+  pagesCaptions: {},
+  contentCaptions: {
+    '/usr/content/blog/my-article/gallery/captions.json': { default: { 'photo2.jpg': 'A custom caption' } },
+  },
+  sharedCaptions: {
+    '/usr/galleries/scavi-2024/captions.json': {
+      default: {
+        'site-a.jpg': 'Exact match caption',
+        // Deliberately a different resolution suffix than the real file
+        // (site-b_1920.jpg vs the real site-b_1920.jpg above uses the same
+        // base name so this also verifies base-filename fuzzy matching).
+        'site-b_1280.jpg': 'Fuzzy match caption',
+      },
+    },
+  },
+};
+
+vi.mock('virtual:scms/galleries', () => manifest);
+
+const {
+  getColocatedGalleryImages,
+  getColocatedCaptions,
+  getSharedGalleryImages,
+  getSharedCaptions,
+  sortImages,
+  formatFilename,
+  getFileName,
+} = await import('../galleryUtils');
+
+describe('getColocatedGalleryImages', () => {
+  it('matches a page-colocated gallery by URL path', () => {
+    const images = getColocatedGalleryImages('/my-page/');
+    expect(images).toHaveLength(1);
+    expect(images[0].src).toBe('/_astro/photo1.abc123.jpg');
+    expect(images[0].width).toBe(1200);
+  });
+
+  it('matches a content-colocated gallery by URL path', () => {
+    const images = getColocatedGalleryImages('/blog/my-article');
+    expect(images).toHaveLength(1);
+    expect(images[0].src).toBe('/_astro/photo2.def456.jpg');
+  });
+
+  it('handles a trailing slash the same as without one', () => {
+    const withSlash = getColocatedGalleryImages('/blog/my-article/');
+    const withoutSlash = getColocatedGalleryImages('/blog/my-article');
+    expect(withSlash).toEqual(withoutSlash);
+  });
+
+  it('returns an empty array when no gallery matches the path', () => {
+    expect(getColocatedGalleryImages('/no/such/page')).toEqual([]);
+  });
+
+  it('derives alt/caption from the filename when no captions.json applies', () => {
+    const [image] = getColocatedGalleryImages('/my-page/');
+    expect(image.alt).toBe('Photo1');
+    expect(image.caption).toBe('Photo1');
+  });
+
+  it('applies a matching captions.json caption instead of the filename fallback', () => {
+    const [image] = getColocatedGalleryImages('/blog/my-article');
+    expect(image.caption).toBe('A custom caption');
+    expect(image.alt).toBe('A custom caption');
+  });
+});
+
+describe('getColocatedCaptions', () => {
+  it('returns the parsed captions for a matching path', () => {
+    expect(getColocatedCaptions('/blog/my-article')).toEqual({ 'photo2.jpg': 'A custom caption' });
+  });
+
+  it('returns undefined when there is no captions.json for the path', () => {
+    expect(getColocatedCaptions('/my-page/')).toBeUndefined();
+  });
+});
+
+describe('getSharedGalleryImages', () => {
+  it('returns only images under the matching shared gallery name', () => {
+    const images = getSharedGalleryImages('scavi-2024');
+    expect(images).toHaveLength(2);
+    expect(images.map((i) => i.src).sort()).toEqual(['/_astro/site-a.jkl000.jpg', '/_astro/site-b_1920.mno111.jpg']);
+  });
+
+  it('returns an empty array for an unknown gallery name', () => {
+    expect(getSharedGalleryImages('does-not-exist')).toEqual([]);
+  });
+
+  it('applies an exact-filename caption match', () => {
+    const images = getSharedGalleryImages('scavi-2024');
+    const siteA = images.find((i) => i.src.includes('site-a'));
+    expect(siteA?.caption).toBe('Exact match caption');
+  });
+
+  it('fuzzy-matches a caption across a different resolution suffix than the real file', () => {
+    const images = getSharedGalleryImages('scavi-2024');
+    const siteB = images.find((i) => i.src.includes('site-b'));
+    expect(siteB?.caption).toBe('Fuzzy match caption');
+  });
+
+  it('falls back to the filename when no gallery-wide captions.json exists', () => {
+    const images = getSharedGalleryImages('other-name');
+    expect(images[0].caption).toBe('Site C');
+  });
+});
+
+describe('getSharedCaptions', () => {
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warnSpy.mockRestore();
+  });
+
+  it('logs a warning and returns undefined for a malformed captions.json', () => {
+    const result = parseMalformedFixture();
+    expect(result).toBeUndefined();
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Invalid captions.json'),
+      expect.anything()
+    );
+  });
+
+  it('returns undefined for an unknown gallery name, without warning', () => {
+    expect(getSharedCaptions('does-not-exist')).toBeUndefined();
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  function parseMalformedFixture() {
+    // Reuses the real function against a manifest entry shaped like a
+    // malformed captions.json (nested object instead of Record<string,string>).
+    (manifest.sharedCaptions as any)['/usr/galleries/broken/captions.json'] = { default: { nested: { not: 'a string' } } };
+    return getSharedCaptions('broken');
+  }
+});
+
+describe('sortImages', () => {
+  const images = [
+    { src: 'a.jpg', thumb: '', width: 1, height: 1, alt: '', caption: '' },
+    { src: 'c.jpg', thumb: '', width: 1, height: 1, alt: '', caption: '' },
+    { src: 'b.jpg', thumb: '', width: 1, height: 1, alt: '', caption: '' },
+  ];
+
+  it('sorts descending by filename by default', () => {
+    expect(sortImages(images).map((i) => i.src)).toEqual(['c.jpg', 'b.jpg', 'a.jpg']);
+  });
+
+  it('sorts ascending when reverse is true', () => {
+    expect(sortImages(images, true).map((i) => i.src)).toEqual(['a.jpg', 'b.jpg', 'c.jpg']);
+  });
+});
+
+describe('formatFilename / getFileName', () => {
+  it('extracts a filename without its extension', () => {
+    expect(getFileName('/a/b/my-photo.jpg')).toBe('my-photo');
+  });
+
+  it('formats a hyphenated filename into title case', () => {
+    expect(formatFilename('my-photo-file')).toBe('My Photo File');
+  });
+});