sol-components 2.1.0

package/node/sol-query.js

@@ -0,0 +1,116 @@
+// Node.js version of sol-query — same options as the web component,
+// returns plain JS data instead of rendering HTML.
+//
+// Usage:
+//   import { solQuery } from 'sol-components/node';
+//   const data = await solQuery({ endpoint, sparql: 'SELECT ...' });
+//   const data = await solQuery({ endpoint, pattern: '?s foaf:name ?o' });
+//   const data = await solQuery({ endpoint, sparql: 'SELECT ...', vars: { name: 'Alice' } });
+
+import * as rdflib from 'rdflib';
+import { toPlainResults, NativeSparqlAdapter } from '../core/utils.js';
+import {
+  ACCEPT_TYPES,
+  detectFormat,
+  parsePatternParts,
+  patternVarNames,
+  matchStore,
+  isRdfDoc,
+  bindingsToResults,
+  selectVars,
+} from '../core/rdf-core.js';
+import {
+  assertSafeQuery,
+  sanitizeVarValue,
+  substituteVariables,
+} from '../core/sparql-safety.js';
+
+export { assertSafeQuery, sanitizeVarValue, substituteVariables };
+
+// ─── Load & parse RDF from a URL ────────────────────────────────────────────
+async function loadRdfStore(endpoint, fetchFn = globalThis.fetch) {
+  const store = rdflib.graph();
+  let lastError = null;
+
+  for (const accept of ACCEPT_TYPES) {
+    try {
+      const resp = await fetchFn(endpoint, { headers: { Accept: accept } });
+      if (!resp.ok) { lastError = new Error(`HTTP ${resp.status}`); if (resp.status === 405) break; continue; }
+      const text = await resp.text();
+      const ct = (resp.headers.get('content-type') || '').split(';')[0].trim();
+      if (ct.includes('html') || /<html/i.test(text)) { lastError = new Error('Server returned HTML'); continue; }
+      try {
+        rdflib.parse(text, store, endpoint, detectFormat(ct, accept));
+        return store;
+      } catch (parseErr) { lastError = parseErr; }
+    } catch (err) { lastError = err; }
+  }
+
+  // Last resort: no Accept header
+  try {
+    const resp = await fetchFn(endpoint);
+    if (resp.ok) {
+      const text = await resp.text();
+      const ct = (resp.headers.get('content-type') || '').split(';')[0].trim();
+      if (!ct.includes('html') && !/<html/i.test(text)) {
+        rdflib.parse(text, store, endpoint, detectFormat(ct, ''));
+        return store;
+      }
+    }
+  } catch (err) { lastError = err; }
+
+  throw lastError || new Error('Failed to load or parse RDF');
+}
+
+// ─── SPARQL execution (Node) ────────────────────────────────────────────────
+async function _localSparql(queryText, endpoint, fetchFn) {
+  const store  = await loadRdfStore(endpoint, fetchFn);
+  const parsed = rdflib.SPARQLToQuery(queryText, false, store);
+  if (!parsed) throw new Error('Could not parse SPARQL query');
+
+  return new Promise((resolve, reject) => {
+    const bindings = [];
+    try {
+      store.query(
+        parsed,
+        b => bindings.push(b),
+        new rdflib.Fetcher(store),
+        () => resolve(bindingsToResults(bindings, queryText)),
+      );
+    } catch (err) { reject(err); }
+  });
+}
+
+async function execSparql(query, endpoint, fetchFn = globalThis.fetch) {
+  if (isRdfDoc(endpoint)) {
+    return _localSparql(query, endpoint, fetchFn);
+  }
+  return new NativeSparqlAdapter().executeQuery(query, endpoint, fetchFn);
+}
+
+// ─── Main entry point ───────────────────────────────────────────────────────
+export async function solQuery(opts = {}) {
+  const { endpoint, sparql, query, pattern, wanted, vars, columns, fetch: fetchFn } = opts;
+  const pat = pattern || wanted;
+  const queryText = sparql ?? query;
+  if (!endpoint) throw new Error('endpoint is required');
+  if (!queryText && !pat) throw new Error('sparql or pattern is required');
+
+  const _fetch = fetchFn || globalThis.fetch;
+  let data;
+
+  if (queryText) {
+    const processed = substituteVariables(queryText, vars);
+    assertSafeQuery(processed);
+    data = await execSparql(processed, endpoint, _fetch);
+  } else {
+    const store = await loadRdfStore(endpoint, _fetch);
+    const names = patternVarNames(pat);
+    const [s, p, o] = parsePatternParts(pat, rdflib, {}, endpoint);
+    data = matchStore(store, s, p, o, names);
+  }
+
+  return toPlainResults(data, columns);
+}
+
+export default solQuery;

package/package.json

@@ -0,0 +1,133 @@
+{
+  "name": "sol-components",
+  "version": "2.1.0",
+  "description": "Web components and Node.js tools for querying, including, and editing RDF/Linked Data on Solid Pods",
+  "type": "module",
+  "exports": {
+    ".": {
+      "node": "./node/sol-query.js",
+      "default": "./web/sol-query.js"
+    },
+    "./query": {
+      "node": "./node/sol-query.js",
+      "default": "./web/sol-query.js"
+    },
+    "./include": {
+      "node": "./node/sol-include.js",
+      "default": "./web/sol-include.js"
+    },
+    "./form": {
+      "node": "./node/sol-form.js",
+      "default": "./web/sol-form.js"
+    },
+    "./login": {
+      "node": "./node/sol-login.js",
+      "default": "./web/sol-login.js"
+    },
+    "./menu": {
+      "node": "./node/sol-menu.js",
+      "default": "./web/sol-menu.js"
+    },
+    "./web": "./web/sol-full.js",
+    "./web/*": "./web/*",
+    "./node/*": "./node/*",
+    "./core/*": "./core/*",
+    "./dist/*": "./dist/*"
+  },
+  "bin": {
+    "sol-menu-cli": "./node/sol-menu.js"
+  },
+  "files": [
+    "core/",
+    "web/",
+    "node/",
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --experimental-vm-modules node_modules/.bin/jest --coverage",
+    "test:ci": "node --experimental-vm-modules node_modules/.bin/jest",
+    "build:importmaps": "node tools/build-importmaps.mjs",
+    "build:vendor": "node tools/vendor.mjs",
+    "build": "npm run build:importmaps && npm run build:vendor",
+    "lint": "eslint .",
+    "docs": "jsdoc -c jsdoc.config.json"
+  },
+  "dependencies": {
+    "dompurify": "^3.4.0",
+    "ical.js": "^2.2.1",
+    "marked": "^18.0.0",
+    "rdflib": "^2.3.6"
+  },
+  "peerDependencies": {
+    "@comunica/query-sparql": "^5.1.3",
+    "@inrupt/solid-client-authn-browser": "^4.0.0",
+    "@inrupt/solid-client-authn-node": "^3.0.0",
+    "jsdom": "^26.1.0",
+    "openid-client": "^5.0.0",
+    "solid-ui": "^3.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@comunica/query-sparql": {
+      "optional": true
+    },
+    "@inrupt/solid-client-authn-browser": {
+      "optional": true
+    },
+    "@inrupt/solid-client-authn-node": {
+      "optional": true
+    },
+    "openid-client": {
+      "optional": true
+    },
+    "solid-ui": {
+      "optional": true
+    },
+    "jsdom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@babel/core": "^7.24.0",
+    "@babel/preset-env": "^7.24.0",
+    "@eslint/js": "^8.57.1",
+    "@rdfjs/dataset": "^2.0.2",
+    "@rdfjs/namespace": "^2.0.1",
+    "@rollup/plugin-commonjs": "^29.0.2",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^15.2.3",
+    "@rollup/plugin-terser": "^0.4.4",
+    "babel-jest": "^29.7.0",
+    "clownface": "^2.0.3",
+    "esbuild": "^0.28.0",
+    "eslint": "^9.39.4",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "jsdoc": "^4.0.5",
+    "n3": "^2.0.3",
+    "rdf-ext": "^2.6.0",
+    "rdf-validate-shacl": "^0.6.5",
+    "rollup": "^4.13.0"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "transform": {
+      "^.+\\.js$": "babel-jest"
+    },
+    "moduleNameMapper": {
+      "^rdflib$": "<rootDir>/tests/__mocks__/rdflib-esm.js",
+      "^https://esm\\.sh/rdflib@2$": "<rootDir>/tests/__mocks__/rdflib-esm.js",
+      "^@inrupt/solid-client-authn-node$": "<rootDir>/tests/__mocks__/solid-client-authn-node.js",
+      "^openid-client$": "<rootDir>/tests/__mocks__/openid-client.js",
+      "^dompurify$": "<rootDir>/tests/__mocks__/dompurify.js",
+      "^marked$": "<rootDir>/tests/__mocks__/marked.js"
+    },
+    "setupFiles": [
+      "<rootDir>/tests/setup.js"
+    ],
+    "testMatch": [
+      "**/tests/**/*.test.js"
+    ]
+  }
+}

package/web/menu-from-rdf.js

@@ -0,0 +1,23 @@
+/**
+ * menu-from-rdf.js — opt-in add-on: switch on `from-rdf` for the menu family.
+ *
+ * Importing this module IS the activation. It is the only place in the menu
+ * family (sol-tabs, sol-menu, sol-dropdown-button) that pulls in rdflib — via
+ * core/menu-rdf.js → core/rdf.js. Without it, those components are declarative-
+ * only (light-DOM <a> / <menu> children) and rdflib never enters their graph.
+ *
+ *   <script type="module" src="…/sol-tabs.js"></script>        <!-- declarative, no rdflib -->
+ *   <script type="module" src="…/menu-from-rdf.js"></script>   <!-- + from-rdf, pulls rdflib -->
+ *   <sol-tabs from-rdf="./tabs.ttl#Tabs"></sol-tabs>
+ *
+ * This layer carries no component definitions — load the components themselves
+ * (individually, or via an aggregator like sol-full / sol-basic) however you
+ * already do. installFromRdfLoader() wires every menu consumer that is or
+ * becomes registered, in any import order (see core/menu-consumer.js).
+ * sol-dropdown-button inherits the loader from SolMenu via the static prototype
+ * chain.
+ */
+import { installFromRdfLoader } from '../core/menu-consumer.js';
+import { loadMenuFromUri } from '../core/menu-rdf.js';
+
+installFromRdfLoader(loadMenuFromUri);

package/web/scripts/prefs.js

@@ -0,0 +1,25 @@
+(function () {
+  var THEME_KEY = 'swc-theme';
+  var FONT_KEY  = 'swc-font-size';
+
+  function apply(theme, fontSize) {
+    if (theme)    document.documentElement.setAttribute('data-theme', theme);
+    if (fontSize) document.documentElement.style.setProperty('--font-size', fontSize);
+  }
+
+  try {
+    apply(
+      localStorage.getItem(THEME_KEY) || 'light',
+      localStorage.getItem(FONT_KEY)  || '20px'
+    );
+  } catch (e) {}
+
+  window.addEventListener('message', function (ev) {
+    var d = ev.data;
+    if (d && d.type === 'swc-prefs') apply(d.theme, d.fontSize);
+  });
+
+  if (window.parent !== window) {
+    try { window.parent.postMessage({ type: 'swc-ready' }, '*'); } catch (e) {}
+  }
+})();

package/web/sol-accordion.js

@@ -0,0 +1,114 @@
+/**
+ * <sol-accordion> — Accordion (collapsible sections) web component.
+ *
+ * Wraps child `<div>` elements into `<details>`/`<summary>` pairs.
+ * Each child div should contain two inner divs: the first becomes the
+ * summary (header), the second becomes the collapsible content.
+ * Only one section is open at a time (exclusive mode via `<details name>`).
+ *
+ * The first panel opens by default. Add `start-closed` to start with
+ * every panel collapsed instead.
+ *
+ * @element sol-accordion
+ * @attr {boolean} start-closed - leave every panel collapsed on first render
+ *
+ * @example
+ * <sol-accordion>
+ *   <div><div>Section 1</div><div>Content 1</div></div>
+ *   <div><div>Section 2</div><div>Content 2</div></div>
+ * </sol-accordion>
+ */
+import { ensureDocStyle } from '../core/adopt.js';
+import { CSS as ACCORDION_CSS } from './styles/sol-accordion-css.js';
+import { define } from '../core/define.js';
+
+/**
+ * Accordion (collapsible sections) web component.
+ *
+ * Wraps child `<div>` elements into `<details>`/`<summary>` pairs.
+ * Only one section is open at a time.
+ *
+ * @class SolAccordion
+ * @extends HTMLElement
+ */
+class SolAccordion extends HTMLElement {
+  connectedCallback() {
+    const groupName = `sol-accordion-${Math.random().toString(36).slice(2, 9)}`;
+    const startClosed = this.hasAttribute('start-closed');
+
+    const authorDivs = Array.from(this.children).filter(el => el.tagName === 'DIV');
+
+    if (!authorDivs.length) {
+      this.textContent = 'No accordion panels found';
+      return;
+    }
+
+    const wrapper = document.createElement('div');
+    wrapper.className = 'sol-accordion-wrapper';
+    wrapper.setAttribute('role', 'region');
+    wrapper.setAttribute('aria-label', 'Accordion');
+
+    authorDivs.forEach((srcDiv, i) => {
+      const childDivs = Array.from(srcDiv.children).filter(el => el.tagName === 'DIV');
+
+      const openInitial = !startClosed && i === 0;
+      const det = document.createElement('details');
+      det.name = groupName;
+      if (openInitial) det.open = true;
+
+      const sum = document.createElement('summary');
+      sum.setAttribute('role', 'button');
+      sum.setAttribute('aria-expanded', openInitial ? 'true' : 'false');
+      sum.setAttribute('tabindex', '0');
+      sum.id = `panel-${i}-summary`;
+      
+      if (childDivs.length >= 2) {
+        sum.textContent = childDivs[0].textContent.trim() || `Panel ${i + 1}`;
+        
+        const body = document.createElement('div');
+        body.className = 'accordion-body';
+        body.setAttribute('role', 'region');
+        body.setAttribute('aria-labelledby', `panel-${i}-summary`);
+        
+        for (let j = 1; j < childDivs.length; j++) {
+          const contentDiv = document.createElement('div');
+          contentDiv.className = 'accordion-content-section';
+          const clone = childDivs[j].cloneNode(true);
+          while (clone.firstChild) contentDiv.appendChild(clone.firstChild);
+          body.appendChild(contentDiv);
+        }
+        
+        det.appendChild(sum);
+        det.appendChild(body);
+      } else {
+        sum.textContent = srcDiv.textContent.trim() || `Panel ${i + 1}`;
+        const body = document.createElement('div');
+        body.className = 'accordion-body';
+        body.textContent = 'No content';
+        det.appendChild(sum);
+        det.appendChild(body);
+      }
+
+      det.addEventListener('toggle', () => {
+        sum.setAttribute('aria-expanded', det.open ? 'true' : 'false');
+      });
+
+      sum.addEventListener('keypress', e => {
+        if (e.key === 'Enter' || e.key === ' ') {
+          e.preventDefault();
+          det.open = !det.open;
+        }
+      });
+
+      wrapper.appendChild(det);
+    });
+
+    this.innerHTML = '';
+    ensureDocStyle(this.getRootNode(), 'sol-accordion-styles', ACCORDION_CSS);
+    this.appendChild(wrapper);
+  }
+
+
+}
+
+define('sol-accordion', SolAccordion);

package/web/sol-basic.js

@@ -0,0 +1,50 @@
+/**
+ * sol-basic.js — bundle entry: the no-RDF, html-first tier.
+ *
+ * Registers the everyday UI primitives that work from plain HTML and never
+ * need the RDF / Solid stack at runtime:
+ *   sol-button, sol-dropdown-button, sol-include, sol-menu, sol-tabs,
+ *   sol-accordion, sol-rolodex
+ * …plus the registered-by-tag helpers these conjure / instantiate at runtime:
+ *   sol-default     — singleton holding shared non-CSS defaults (proxy, region…)
+ *   sol-modal       — the "modal" display surface + the editor-self gear popup
+ *   sol-window      — the "floating" display surface
+ * The author-facing surface for the conjured ones is the region KEYWORD
+ * (region="modal" / "floating"), not the tag — see core/display-target.js.
+ *
+ * sol-menu's EDITOR (sol-tree-edit + sol-breadcrumb) is NOT here: editing a
+ * menu reads/writes it as RDF (SHACL + Turtle), so it's part of the solid-ui
+ * editing stack — loaded via sol-loader's `rdf` capability (or the importmap +
+ * module recipe). sol-menu conjures sol-tree-edit by tag when it's present.
+ *
+ * Deliberately NOT here (they need the RDF / Solid stack):
+ *   sol-login, sol-form, sol-settings, sol-query, sol-solidos.
+ * Also NOT here: `menu-from-rdf` — driving the menu family from RDF is the
+ * opt-in add-on that pulls rdflib; import the `menu-from-rdf` module (it
+ * resolves via the importmap) when a page wants `from-rdf`. Keeping it out is
+ * what keeps this tier truly dependency-free.
+ *
+ * dompurify and marked (sol-include's sanitiser / Markdown renderer) are the
+ * only third-party code, and they're bundled IN. There is no rdflib peer.
+ */
+
+import './sol-include.js';
+import './sol-button.js';
+import './sol-dropdown-button.js';
+import './sol-menu.js';
+import './sol-tabs.js';
+import './sol-accordion.js';
+import './sol-rolodex.js';
+
+// Registered-by-tag helpers the primitives conjure / instantiate at runtime:
+import './sol-default.js';    // singleton holding shared non-CSS defaults (proxy, region…)
+import './sol-modal.js';      // modal display surface + editor-self gear popup
+import './sol-window.js';     // floating-window display surface
+
+// Surface the JS API on `window.SolBasic.*` for hosts that need the class
+// symbols, not just the registered custom-element tags.
+export { SolButton } from './sol-button.js';
+export { SolDropdownButton } from './sol-dropdown-button.js';
+export { SolInclude } from './sol-include.js';
+export { SolMenu } from './sol-menu.js';
+export { SolTabs } from './sol-tabs.js';

package/web/sol-breadcrumb.js

@@ -0,0 +1,131 @@
+/**
+ * <sol-breadcrumb> — clickable path-strip primitive.
+ *
+ * Pure UI component. Knows nothing about RDF, navigation, or routing.
+ * Wraps declarative `<span data-key="...">` children into a breadcrumb
+ * with `>` separators. Earlier segments are clickable; the last is the
+ * current location and is shown in a non-clickable style.
+ *
+ * Click emits a bubbling, composed `sol-breadcrumb-navigate` event
+ * with `detail: { key, index, label }`. The host decides what
+ * "navigate" means — sol-tree-edit pops its breadcrumb stack;
+ * podz might swap a path display; a router might call pushState.
+ *
+ * @element sol-breadcrumb
+ *
+ * @fires sol-breadcrumb-navigate — detail: { key, index, label }
+ *
+ * @example
+ *   <sol-breadcrumb>
+ *     <span data-key="root">Main Menu</span>
+ *     <span data-key="notes">Notes</span>
+ *     <span data-key="daily">Daily</span>
+ *   </sol-breadcrumb>
+ *
+ * Children mutate freely; an attached MutationObserver re-renders so
+ * the host can push/pop segments by `element.append()` / `.removeChild()`.
+ */
+
+import { define } from '../core/define.js';
+import { ensureDocStyle } from '../core/adopt.js';
+
+const CSS = `
+sol-breadcrumb {
+  display: flex;
+  align-items: baseline;
+  flex-wrap: wrap;
+  gap: 0.35rem 0.55rem;
+  font-family: var(--font-ui, system-ui, sans-serif);
+  font-size: 0.92rem;
+  line-height: 1.5;
+}
+sol-breadcrumb .sol-breadcrumb-segment {
+  cursor: pointer;
+  color: var(--accent, #1F618D);
+  background: none;
+  border: 0;
+  padding: 0;
+  font: inherit;
+  text-decoration: none;
+  border-radius: 2px;
+}
+sol-breadcrumb .sol-breadcrumb-segment:hover,
+sol-breadcrumb .sol-breadcrumb-segment:focus-visible {
+  text-decoration: underline;
+  outline: none;
+}
+sol-breadcrumb .sol-breadcrumb-current {
+  color: var(--text, #2c3e50);
+  font-weight: 600;
+  cursor: default;
+}
+sol-breadcrumb .sol-breadcrumb-sep {
+  color: var(--text-muted, #8a8a8a);
+  user-select: none;
+}
+sol-breadcrumb [data-key] {
+  display: none;
+}
+`;
+
+class SolBreadcrumb extends HTMLElement {
+  connectedCallback() {
+    ensureDocStyle(this.getRootNode(), 'sol-breadcrumb-styles', CSS);
+    this._render();
+    // Watch for children being added/removed so callers can mutate
+    // the path declaratively (push by appendChild, pop by remove).
+    if (!this._observer) {
+      this._observer = new MutationObserver(() => this._render());
+      this._observer.observe(this, { childList: true, characterData: true, subtree: true });
+    }
+  }
+
+  disconnectedCallback() {
+    if (this._observer) { this._observer.disconnect(); this._observer = null; }
+  }
+
+  _render() {
+    // Pull the data-key segments declared by the author; ignore the
+    // rendered chrome we add ourselves.
+    const segments = Array.from(this.querySelectorAll(':scope > [data-key]'));
+    // Remove any previously-rendered chrome.
+    for (const el of Array.from(this.children)) {
+      if (!el.hasAttribute('data-key')) el.remove();
+    }
+    if (segments.length === 0) return;
+
+    const lastIdx = segments.length - 1;
+    segments.forEach((seg, i) => {
+      const key   = seg.dataset.key;
+      const label = seg.textContent.trim();
+      let node;
+      if (i === lastIdx) {
+        node = document.createElement('span');
+        node.className = 'sol-breadcrumb-current';
+        node.setAttribute('aria-current', 'page');
+        node.textContent = label;
+      } else {
+        node = document.createElement('button');
+        node.type = 'button';
+        node.className = 'sol-breadcrumb-segment';
+        node.textContent = label;
+        node.addEventListener('click', () => {
+          this.dispatchEvent(new CustomEvent('sol-breadcrumb-navigate', {
+            bubbles: true, composed: true,
+            detail: { key, index: i, label },
+          }));
+        });
+      }
+      this.appendChild(node);
+      if (i !== lastIdx) {
+        const sep = document.createElement('span');
+        sep.className = 'sol-breadcrumb-sep';
+        sep.setAttribute('aria-hidden', 'true');
+        sep.textContent = '›';
+        this.appendChild(sep);
+      }
+    });
+  }
+}
+
+define('sol-breadcrumb', SolBreadcrumb);