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

package/LICENSE

@@ -0,0 +1,14 @@
+BSD Zero Clause License
+
+Copyright (c) 2026 LAD: Laboratorio di Archeologia Digitale alla Sapienza
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# @lad-sapienza/scms-core
+
+Framework components and Astro integrations for [s:CMS](https://github.com/lad-sapienza/sCMS) — the static-site CMS built by [LAD @Sapienza](https://lad.saras.uniroma1.it/).
+
+This package supplies the `core/` framework layer that used to live inside the sCMS template repo itself. A site built with sCMS depends on this package from `node_modules` instead of vendoring/syncing it via git, so updates are ordinary `npm update`s.
+
+## Install
+
+```bash
+npm install @lad-sapienza/scms-core
+```
+
+Peer dependencies (install alongside): `astro`, `react`, `react-dom`, `maplibre-gl`, `@types/react`, `@types/react-dom`.
+
+## Usage
+
+Register the integration in `astro.config.mjs`:
+
+```js
+import { defineConfig } from 'astro/config';
+import { scms } from '@lad-sapienza/scms-core';
+
+export default defineConfig({
+  integrations: [
+    ...scms({
+      // all optional, default to the paths below
+      contentDir: 'usr/content',
+      pagesDir: 'usr/pages',
+      galleriesDir: 'usr/galleries',
+    }),
+  ],
+});
+```
+
+`scms()` bundles content-asset serving, the Gallery virtual module, Expressive Code, MDX, React, and sitemap integrations into one call, and self-registers the Vite `dedupe`/`optimizeDeps` config React and `@tanstack/react-table` need to avoid duplicate-module "Invalid hook call" errors — no extra Vite config required in the consumer.
+
+Import components from the package root in any `.mdx` file:
+
+```mdx
+import { DataTb, Map, Gallery } from '@lad-sapienza/scms-core';
+```
+
+| Component | Description |
+|---|---|
+| `DataTb` | Sortable, filterable, paginated data table |
+| `MapComponent` (`Map`) | Interactive map with MapLibre GL JS |
+| `Gallery` | Responsive image gallery with lightbox |
+| `TableOfContents` | Auto-generated TOC from headings |
+| `ZoteroGeoViewer` | Zotero library visualised on a map |
+| `RecordProvider`, `Field`, `Image`, `RecordFetcher`, `useRecordFetcher` | Build single-record detail pages against Directus |
+| `SearchUI`, `SearchUISimple`, `SearchUIAdvanced` | Field/operator/value search UI (used by `Map`'s `searchInFields`) |
+
+A few components are reachable only via subpath import, not the root barrel — this mirrors the internal layout, no bundler config or `exports` map restricts it:
+
+```js
+import SEO from '@lad-sapienza/scms-core/components/SEO/SEO.astro';
+import BSNavbar from '@lad-sapienza/scms-core/components/BSNavbar';
+import { directusLoader } from '@lad-sapienza/scms-core/integrations/directusLoader';
+```
+
+See each component folder's own `README.md` (`components/DataTb`, `components/Gallery`, `components/ZoteroGeoViewer`, `components/`) for detailed API docs and examples.
+
+## Development
+
+```bash
+npm install
+npm run test        # vitest
+npm run typecheck    # tsc --noEmit
+```
+
+## License
+
+BSD-0-Clause

package/components/BSNavbar.tsx

@@ -0,0 +1,264 @@
+import React, { useState, useRef, useEffect } from "react";
+import { Menu, X, ChevronRight } from "lucide-react";
+
+/**
+ * A single navigation link entry.
+ *
+ * - `href`  — URL the link points to. Optional for parent items that only open a dropdown.
+ * - `label` — visible text.
+ * - `match` — optional path prefix used for active detection (falls back to `href`).
+ *   Useful when a parent item has no `href` but should be highlighted for a subtree,
+ *   e.g. `match: "/docs"` highlights the "Docs" entry for any `/docs/*` page.
+ * - `children` — nested items, enabling up to 3 levels of dropdown menus.
+ */
+interface MenuItem {
+  href?: string;
+  label: string;
+  match?: string;
+  children?: MenuItem[];
+}
+
+/** Brand / logo configuration for the navbar. */
+interface BrandProps {
+  /** Text displayed as the brand name. */
+  text: string;
+  /** URL the brand name links to. */
+  link: string;
+  /** Additional CSS classes applied to the brand anchor. */
+  cssClasses?: string;
+}
+
+/** Optional CSS class overrides for individual navbar elements. */
+interface CssClasses {
+  /** Classes applied to the `<nav>` element. */
+  nav?: string;
+  /** Classes applied to the `<ul>` list. */
+  ul?: string;
+  /** Classes applied to each `<li>` item. */
+  li?: string;
+}
+
+/**
+ * Bootstrap-compatible responsive navbar with a React-controlled toggle.
+ * Active state is computed internally from `currentPath` — no need to set
+ * `isActive` on individual menu items.
+ *
+ * Menu data can be loaded from a YAML file (e.g. `usr/content/data/menu.yaml`)
+ * and passed straight to `menuItems`.
+ *
+ * Must be hydrated with `client:load` when used inside an Astro component.
+ *
+ * @example
+ * ```astro
+ * ---
+ * import { getEntry } from 'astro:content';
+ * const menuEntry = await getEntry('menu', 'menu');
+ * ---
+ * <BSNavbar
+ *   client:load
+ *   menuItems={menuEntry?.data ?? []}
+ *   currentPath={Astro.url.pathname}
+ *   cssClasses={{ nav: "sticky-top shadow-sm", ul: "ms-auto" }}
+ *   brand={{ text: "My Site", link: "/" }}
+ * />
+ * ```
+ *
+ * @example YAML menu structure (`usr/content/data/menu.yaml`)
+ * ```yaml
+ * - href: /
+ *   label: Home
+ * - label: Docs
+ *   match: /docs
+ *   children:
+ *     - href: /docs/guides/getting-started
+ *       label: Getting Started
+ *     - label: Components
+ *       children:
+ *         - href: /docs/components/datatb
+ *           label: DataTb
+ * ```
+ */
+interface BSNavbarProps {
+  /** Array of navigation items to render in the menu. */
+  menuItems: MenuItem[];
+  /**
+   * Current page path (e.g. `Astro.url.pathname`).
+   * Used internally to compute which items are active.
+   */
+  currentPath?: string;
+  /** Optional CSS class overrides for navbar sub-elements. */
+  cssClasses?: CssClasses;
+  /** Optional brand / logo configuration. Omit to hide the brand area. */
+  brand?: BrandProps;
+}
+
+// ---------------------------------------------------------------------------
+// Active detection
+// ---------------------------------------------------------------------------
+
+/** Returns true when `item` (or any descendant) matches `currentPath`. */
+function isItemActive(item: MenuItem, currentPath: string): boolean {
+  const target = item.match ?? item.href;
+  if (target) {
+    const active = target === "/" ? currentPath === "/" : currentPath.startsWith(target);
+    if (active) return true;
+  }
+  return item.children?.some(child => isItemActive(child, currentPath)) ?? false;
+}
+
+// ---------------------------------------------------------------------------
+// DropdownItem — item inside a dropdown (level ≥ 2)
+// ---------------------------------------------------------------------------
+const DropdownItem: React.FC<{ item: MenuItem; currentPath: string }> = ({ item, currentPath }) => {
+  const [isOpen, setIsOpen] = useState(false);
+  const [openLeft, setOpenLeft] = useState(false);
+  const ref = useRef<HTMLLIElement>(null);
+  const hasChildren = !!item.children?.length;
+  const active = isItemActive(item, currentPath);
+
+  useEffect(() => {
+    if (!isOpen) return;
+    const close = (e: MouseEvent) => {
+      if (ref.current && !ref.current.contains(e.target as Node)) setIsOpen(false);
+    };
+    document.addEventListener("mousedown", close);
+    return () => document.removeEventListener("mousedown", close);
+  }, [isOpen]);
+
+  const handleToggle = () => {
+    if (!isOpen && ref.current) {
+      const rect = ref.current.getBoundingClientRect();
+      setOpenLeft(rect.left > window.innerWidth / 2);
+    }
+    setIsOpen(p => !p);
+  };
+
+  if (!hasChildren) {
+    return (
+      <li>
+        <a
+          className={`dropdown-item${active ? " active" : ""}`}
+          href={item.href ?? "#"}
+        >
+          {item.label}
+        </a>
+      </li>
+    );
+  }
+
+  return (
+    <li ref={ref} style={{ position: "relative" }}>
+      <button
+        type="button"
+        className={`dropdown-item d-flex justify-content-between align-items-center${active ? " active" : ""}`}
+        onClick={handleToggle}
+        aria-expanded={isOpen}
+      >
+        {item.label}
+        <ChevronRight size={14} className="ms-2 flex-shrink-0" />
+      </button>
+      {isOpen && (
+        <ul
+          className="dropdown-menu show"
+          style={openLeft
+            ? { position: "absolute", right: "100%", left: "auto", top: 0, minWidth: "12rem" }
+            : { position: "absolute", left: "100%", top: 0, minWidth: "12rem" }
+          }
+        >
+          {item.children!.map((child, i) => (
+            <DropdownItem key={child.href ?? i} item={child} currentPath={currentPath} />
+          ))}
+        </ul>
+      )}
+    </li>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// NavItem — top-level nav entry (level 1)
+// ---------------------------------------------------------------------------
+const NavItem: React.FC<{ item: MenuItem; currentPath: string; liClass?: string }> = ({ item, currentPath, liClass }) => {
+  const [isOpen, setIsOpen] = useState(false);
+  const ref = useRef<HTMLLIElement>(null);
+  const hasChildren = !!item.children?.length;
+  const active = isItemActive(item, currentPath);
+
+  useEffect(() => {
+    if (!isOpen) return;
+    const close = (e: MouseEvent) => {
+      if (ref.current && !ref.current.contains(e.target as Node)) setIsOpen(false);
+    };
+    document.addEventListener("mousedown", close);
+    return () => document.removeEventListener("mousedown", close);
+  }, [isOpen]);
+
+  const liBase = `nav-item${hasChildren ? " dropdown" : ""}${active ? " active" : ""}${liClass ? ` ${liClass}` : ""}`;
+
+  if (!hasChildren) {
+    return (
+      <li className={liBase} ref={ref}>
+        <a className={`nav-link${active ? " active" : ""}`} href={item.href ?? "#"}>
+          {item.label}
+        </a>
+      </li>
+    );
+  }
+
+  return (
+    <li className={liBase} ref={ref}>
+      <button
+        type="button"
+        className={`nav-link dropdown-toggle${active ? " active" : ""}`}
+        onClick={() => setIsOpen(p => !p)}
+        aria-expanded={isOpen}
+      >
+        {item.label}
+      </button>
+      {isOpen && (
+        <ul className="dropdown-menu show">
+          {item.children!.map((child, i) => (
+            <DropdownItem key={child.href ?? i} item={child} currentPath={currentPath} />
+          ))}
+        </ul>
+      )}
+    </li>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// BSNavbar — root component
+// ---------------------------------------------------------------------------
+const BSNavbar: React.FC<BSNavbarProps> = ({ menuItems, currentPath = "/", cssClasses = {}, brand }) => {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <nav className={`navbar navbar-expand-md ${cssClasses.nav ?? ""}`}>
+      <div className="container">
+        {brand && (
+          <a className={`navbar-brand ${brand.cssClasses ?? ""}`} href={brand.link}>
+            {brand.text}
+          </a>
+        )}
+        <button
+          className="navbar-toggler border-0 p-2"
+          type="button"
+          onClick={() => setIsOpen(prev => !prev)}
+          aria-controls="navbarCollapse"
+          aria-expanded={isOpen}
+          aria-label="Toggle navigation"
+        >
+          {isOpen ? <X size={24} className="text-dark" /> : <Menu size={24} className="text-dark" />}
+        </button>
+        <div className={`collapse navbar-collapse${isOpen ? " show" : ""}`} id="navbarCollapse">
+          <ul className={`navbar-nav ${cssClasses.ul ?? ""}`}>
+            {menuItems.map((item, i) => (
+              <NavItem key={item.href ?? i} item={item} currentPath={currentPath} liClass={cssClasses.li} />
+            ))}
+          </ul>
+        </div>
+      </div>
+    </nav>
+  );
+};
+
+export default BSNavbar;

package/components/DataTb/DataTb.astro

@@ -0,0 +1,33 @@
+---
+/**
+ * DataTb Astro Wrapper
+ *
+ * Astro component that wraps the React DataTb component
+ * This file exists for documentation and re-export purposes.
+ * In MDX files, import the React component directly with a hydration directive.
+ *
+ * Example usage in MDX:
+ * ```jsx
+ * import { DataTb } from '@lad-sapienza/scms-core/components/DataTb';
+ *
+ * <DataTb csv="/data.csv" searchable pagination client:idle />
+ * ```
+ *
+ * CsvSource / JsonSource / DirectusSource / ApiSource are also exported, but as
+ * headless data-loaders (they render nothing; they call onDataLoad/onLoadingChange/
+ * onError) for building a fully custom table UI — they are not children of
+ * <DataTb>, which has no children/composition API. See the "Headless Source
+ * Components" section of usr/content/docs/components/datatb.mdx.
+ */
+
+// Re-export for convenience. `DataTb` itself is deliberately not re-exported
+// here — a named export called `DataTb` in DataTb.astro's own frontmatter
+// collides with Astro's implicit type for the file (same name as the file),
+// producing a "Duplicate identifier 'DataTb'" build error. Nothing in this
+// project imports DataTb from this file (use `@lad-sapienza/scms-core` or
+// `@lad-sapienza/scms-core/components/DataTb` instead), so this only affects the unused path.
+export { CsvSource, JsonSource, DirectusSource, ApiSource } from './index';
+export type * from './types';
+---
+
+<slot />