sol-components 2.1.0

package/core/edit-placements.js

@@ -0,0 +1,28 @@
+// core/edit-placements.js — activate the `edit="inPlace"` placement.
+//
+// Loaded as part of the `rdf` capability (so an app that does
+// `data-extend-with="rdf"` gets it for free). It walks the page — now and as
+// elements mount — for every editable element whose placement resolves to
+// "inPlace" and attaches an inline edit gear. "collected" elements are left for
+// <sol-settings> to gather. Editability itself comes from the `edit` protocol
+// (a `shape="…"` attribute, a class `static extensionPoints`/`shape`, or a
+// manifest `interop.editable` descriptor); this module only decides PLACEMENT.
+import { observeExtensionPoint } from './extension-points.js';
+import { editPlacement } from './editor.js';
+
+let _on = false;
+/** Begin attaching inline gears to `edit="inPlace"` (or legacy `editor-self`)
+ *  elements. Idempotent. */
+export function activateInlinePlacements() {
+  if (_on || typeof document === 'undefined') return;
+  _on = true;
+  observeExtensionPoint('edit', (el, spec) => {
+    if (spec && spec.self) return;                       // component edits itself
+    if (editPlacement(el, spec) !== 'inPlace') return;   // collected ⇒ sol-settings owns it
+    import('./editor-self.js').then(({ attachEditorSelfGear }) => {
+      try { attachEditorSelfGear(el, spec); } catch (_) { /* no shadowRoot etc. — skip */ }
+    });
+  });
+}
+
+activateInlinePlacements();

package/core/editor-self.js

@@ -0,0 +1,127 @@
+// Inline edit-in-place: page authors opt a component instance into
+// rendering a small gear button by adding the `editor-self` attribute.
+// Clicking the gear opens a <sol-modal> containing a <sol-form> bound
+// to the component's editor (declared via its static `editor` getter)
+// and its current `source` / `from-rdf` subject.
+//
+// Components call attachEditorSelfGear(this) in connectedCallback
+// guarded by `this.hasAttribute('editor-self')`. The helper is a
+// no-op for components that opt out via `editor = { inline: true }`.
+//
+// dk's pages do not exercise this path — every editable component on
+// dk is shared-mode (no `editor-self` attribute), edited from
+// dk-settings. The helper lives in swc because it's a property of
+// the component infrastructure, useful to other consumers.
+
+import { buildEditorElement, resolveEditorSpec } from './editor.js';
+
+const GEAR_CSS = `
+.sol-editor-self-gear {
+  position: absolute;
+  top: 2px;
+  right: 2px;
+  width: 1.4rem;
+  height: 1.4rem;
+  padding: 0;
+  border: 1px solid var(--border, #9e9e9e);
+  border-radius: var(--radius-sm, 4px);
+  background: var(--surface, #fff);
+  color: var(--text-muted, #4d4d4d);
+  font-size: 0.85rem;
+  line-height: 1;
+  cursor: pointer;
+  opacity: 0;
+  transition: opacity 120ms ease;
+  z-index: 1;
+}
+.sol-editor-self-gear:focus,
+:host(:hover) .sol-editor-self-gear,
+.sol-editor-self-gear:hover {
+  opacity: 1;
+}
+.sol-editor-self-gear:focus-visible {
+  outline: 2px solid var(--accent, #1F618D);
+  outline-offset: 1px;
+}
+`;
+
+let _gearSheet = null;
+function gearSheet() {
+  if (_gearSheet) return _gearSheet;
+  _gearSheet = new CSSStyleSheet();
+  _gearSheet.replaceSync(GEAR_CSS);
+  return _gearSheet;
+}
+
+/**
+ * Attach an inline edit gear to a component instance. Idempotent —
+ * calling twice on the same element is a no-op.
+ *
+ * @param {HTMLElement} el - the host component (must have shadowRoot)
+ * @returns {HTMLButtonElement | null} the gear button, or null if
+ *   the component opted out via `editor = { inline: true }` or has
+ *   no editor at all.
+ */
+export function attachEditorSelfGear(el, spec) {
+  // `spec` (from a manifest's interop.editable) lets a FOREIGN element get a
+  // gear even though its class declares no editor; otherwise resolve from class.
+  if (!(spec || resolveEditorSpec(el.constructor, el))) return null;
+  if (el._editorSelfGear) return el._editorSelfGear;
+
+  const root = el.shadowRoot ?? el;
+  // Make the host a positioning context so the absolutely-positioned
+  // gear anchors correctly. Skip if host CSS already established one.
+  if (el.style && !el.style.position) el.style.position = 'relative';
+
+  // Adopt the gear stylesheet into the shadow root (or document for
+  // light-DOM hosts).
+  if (el.shadowRoot && el.shadowRoot.adoptedStyleSheets) {
+    if (!el.shadowRoot.adoptedStyleSheets.includes(gearSheet())) {
+      el.shadowRoot.adoptedStyleSheets = [...el.shadowRoot.adoptedStyleSheets, gearSheet()];
+    }
+  } else if (!document.adoptedStyleSheets.includes(gearSheet())) {
+    document.adoptedStyleSheets = [...document.adoptedStyleSheets, gearSheet()];
+  }
+
+  const btn = document.createElement('button');
+  btn.className = 'sol-editor-self-gear';
+  btn.type = 'button';
+  btn.setAttribute('aria-label', `Edit ${el.localName} settings`);
+  btn.textContent = '⚙';   // ⚙
+  btn.addEventListener('click', (e) => {
+    e.stopPropagation();
+    openEditorModal(el, spec);
+  });
+
+  root.appendChild(btn);
+  el._editorSelfGear = btn;
+  return btn;
+}
+
+/**
+ * Programmatically open the editor modal for any component. Used by
+ * the gear handler above and by external surfaces.
+ *
+ * @param {HTMLElement} el - the component being edited
+ */
+export function openEditorModal(el, spec) {
+  const editor = buildEditorElement(el, spec);
+  if (!editor) return;
+
+  const modal = document.createElement('sol-modal');
+  modal.setAttribute('title', `Edit ${el.localName}`);
+  modal.setAttribute('open', '');
+
+  const close = () => {
+    if (typeof modal.close === 'function') modal.close();
+    else modal.removeAttribute('open');
+  };
+  const onSaved = () => {
+    if (typeof el.reload === 'function') el.reload().catch(() => {});
+    close();
+  };
+  editor.addEventListener('sol-form-save', onSaved);
+
+  modal.appendChild(editor);
+  document.body.appendChild(modal);
+}

package/core/editor.js

@@ -0,0 +1,162 @@
+// Resolve a component class's editor declaration into a canonical spec
+// consumed by both `core/editor-self.js` (inline gear → modal) and
+// `web/sol-settings.js` (accordion-mounted editors).
+//
+// Declarations a component class may carry:
+//
+//   static get editor()
+//     - { inline: true }                  → opt out (sol-feed)
+//     - "https://…/form.ttl" (string)     → legacy: sol-form with that ui:Form
+//     - { tag, subjectAttr?, attrs? }     → explicit editor (e.g. sol-tree-edit)
+//
+//   static get shape()
+//     - "https://…/shape.shacl"           → implicit sol-form in shape-driven mode
+//
+//   a `shape="…"` ATTRIBUTE on the instance overrides the class shape — so a
+//   generic element (e.g. <sol-default shape="./app-settings.shacl">) is
+//   configurable without any class-level declaration. This is what lets
+//   sol-settings work with anyone's components.
+//
+// `editor` takes precedence over `shape`. When neither is set the
+// component is not editable; resolveEditorSpec returns null.
+
+/**
+ * @param {Function | undefined} Ctor — custom-element class
+ * @param {Element} [el] — the instance, so a per-instance `shape` attribute can
+ *        override the class shape (and make a class-less element editable).
+ * @returns {{tag: string, subjectAttr: string, attrs: object, save: boolean} | null}
+ */
+export function resolveEditorSpec(Ctor, el) {
+  const ed = Ctor && Ctor.editor;
+  if (ed && typeof ed === 'object' && ed.inline) return null;
+
+  if (typeof ed === 'string') {
+    return { tag: 'sol-form', subjectAttr: 'subject', attrs: { source: ed }, save: true };
+  }
+  if (ed && typeof ed === 'object') {
+    const tag = ed.tag || 'sol-form';
+    return {
+      tag,
+      subjectAttr: ed.subjectAttr || 'subject',
+      attrs: { ...(ed.attrs || {}) },
+      save: tag === 'sol-form',
+    };
+  }
+
+  // Instance attribute wins over the class default; either makes it editable.
+  // `data-edit-shape` is the canonical capability attribute; bare `shape` is the
+  // back-compat alias.
+  const shape = (el && el.getAttribute && (el.getAttribute('data-edit-shape') || el.getAttribute('shape'))) ||
+                (Ctor && typeof Ctor.shape === 'string' ? Ctor.shape : null);
+  if (shape) {
+    return { tag: 'sol-form', subjectAttr: 'subject', attrs: { shape }, save: true };
+  }
+  return null;
+}
+
+/**
+ * Normalize a manifest-declared edit spec (from a manifest's
+ * `interop.editable` map) into the canonical editor spec — so a component that
+ * declares NO `static editor`/`shape` (e.g. a foreign library's element) can be
+ * made editable purely from a manifest descriptor. The descriptor distinguishes:
+ *   - shape            (a) ACCESSIBLE: SHACL for auto-generation; absent ⇒ null
+ *   - forms: "self"    (b) the component renders its OWN form; we don't generate
+ *   - present          (c) "inline" (button on the element) | "collected" (sol-settings)
+ *   - subject.attr         which attribute on the element holds the subject URI
+ *   - open                 (self only) how to trigger the component's own editor
+ *
+ * @param {object} decl
+ * @returns {{tag,subjectAttr,attrs,save,subjectFrom?,present?} | {self:true,open,present} | null}
+ */
+export function editorSpecFromDecl(decl) {
+  if (!decl || typeof decl !== 'object') return null;
+  if (decl.forms === 'self') {
+    return { self: true, open: decl.open || null, present: decl.present || 'inPlace' };
+  }
+  if (!decl.shape) return null;   // (a) no shape ⇒ not auto-editable
+  return {
+    tag: 'sol-form',
+    subjectAttr: 'subject',
+    attrs: { shape: decl.shape },
+    save: true,
+    subjectFrom: (decl.subject && decl.subject.attr) || null,
+    present: decl.present || 'collected',
+  };
+}
+
+/**
+ * Resolve the subject URI being edited from a host component instance.
+ * A spec's `subjectFrom` (from a manifest descriptor) wins; otherwise falls
+ * back through `source` → `from-rdf` → empty.
+ */
+export function editorSubjectOf(el, spec) {
+  if (spec && spec.subjectFrom) {
+    const v = el.getAttribute(spec.subjectFrom);
+    if (v) return v;
+  }
+  // `data-subject="…"` (canonical) / `subject="…"` (alias) is the explicit,
+  // foreign-friendly locator (a component whose subject isn't in
+  // `source`/`from-rdf` — e.g. a third party's element — just adds it). Then the
+  // usual fallbacks.
+  return el.getAttribute('data-subject') || el.getAttribute('subject')
+      || el.getAttribute('source') || el.getAttribute('from-rdf') || '';
+}
+
+/**
+ * Where an editable element's form lives:
+ *   "inPlace"   — a gear button ON the element (core/editor-self.js)
+ *   "collected" — gathered into a <sol-settings> panel
+ * The element's `edit="inPlace|collected"` attribute is the canonical control;
+ * the legacy `editor-self` attribute (⇒ inPlace) and a manifest descriptor's
+ * `present` are honored too. Default: "collected".
+ */
+export function editPlacement(el, spec) {
+  const a = ((el && el.getAttribute && (el.getAttribute('data-edit-mode') || el.getAttribute('edit'))) || '').toLowerCase();
+  if (a === 'inplace' || a === 'inline') return 'inPlace';
+  if (a === 'collected') return 'collected';
+  if (el && el.hasAttribute && el.hasAttribute('editor-self')) return 'inPlace';   // legacy alias
+  const p = spec && spec.present && String(spec.present).toLowerCase();
+  if (p) return (p === 'inplace' || p === 'inline') ? 'inPlace' : 'collected';
+  return 'collected';
+}
+
+/**
+ * Create the editor element for a component instance, fully wired with
+ * subject / save-to / additional attributes. Returns null if the
+ * component opts out or has no editor.
+ *
+ * Caller is responsible for inserting the element into the DOM and
+ * listening for `sol-form-save` if it wants to refresh the host.
+ */
+export function buildEditorElement(el, specOverride) {
+  const spec = specOverride || resolveEditorSpec(el.constructor, el);
+  if (!spec || spec.self) return null;   // self-editor: caller triggers via its own UI
+  const subject = editorSubjectOf(el, spec);
+
+  const editorEl = document.createElement(spec.tag);
+  if (subject) {
+    const abs = absolute(subject);
+    editorEl.setAttribute(spec.subjectAttr, abs);
+    if (spec.save) editorEl.setAttribute('save-to', abs);
+  }
+  for (const [k, v] of Object.entries(spec.attrs)) editorEl.setAttribute(k, v);
+  return editorEl;
+}
+
+/**
+ * Trigger a component's OWN editor (forms:"self" in a manifest descriptor),
+ * via the declared `open` hook — a method on the element or an event to
+ * dispatch on it. Returns true if a hook fired.
+ */
+export function triggerSelfEditor(el, spec) {
+  const open = spec && spec.open;
+  if (!open) return false;
+  if (open.method && typeof el[open.method] === 'function') { el[open.method](); return true; }
+  if (open.event) { el.dispatchEvent(new CustomEvent(open.event, { bubbles: true, composed: true })); return true; }
+  return false;
+}
+
+function absolute(uri) {
+  try { return new URL(uri, document.baseURI).href; }
+  catch { return uri; }
+}

package/core/events.js

@@ -0,0 +1,27 @@
+// core/events.js — the canonical table of cross-component event names.
+//
+// Components coordinate by emitting/observing bubbling+composed CustomEvents on
+// the document; this is the single source of truth for the names so authors use
+// `SolidWebComponents.EVENTS.LOGIN` instead of hardcoding the string. Published
+// onto `window.SolidWebComponents.EVENTS` by core/services.js.
+//
+// (Component-private events — e.g. sol-tab-change, sol-pod-pods-changed — stay
+// local to their component. This table is the *shared* coordination vocabulary
+// a third-party author is expected to emit or observe.)
+
+export const EVENTS = Object.freeze({
+  READY:          'swc:ready',          // loader finished its auto-load
+  CAPABILITY:     'swc:capability',     // a data-extend-with capability finished loading
+  OFFER:          'swc:offer',          // a component announces the extension points it offers
+
+  LOGIN:          'sol-login',          // user authenticated
+  LOGOUT:         'sol-logout',         // user signed out
+  AUTH_NEEDED:    'sol-auth-needed',    // a fetch hit 401; a login listener resolves it
+
+  DEFAULT_CHANGE: 'sol-default-change', // a <sol-default> attribute changed
+  COMMAND:        'sol-command',        // an app-registered command (non-component handler)
+  ERROR:          'sol-error',          // a component/handler load or validation failure
+  FORM_SAVE:      'sol-form-save',      // an editor persisted changes
+});
+
+export default EVENTS;

package/core/extension-points.js

@@ -0,0 +1,189 @@
+// core/extension-points.js — the general "a capability discovers & enhances any
+// component that offers a named point" protocol. Generalizes the editor/shape
+// contract (core/editor.js + sol-settings discovery) so it's no longer just
+// about editing.
+//
+// A COMPONENT author offers points, import-free, with one static getter:
+//
+//   class AcmeMap extends HTMLElement {
+//     static get extensionPoints() {
+//       return {
+//         edit:     { shape: 'https://acme/map.shacl' }, // the editing capability
+//         annotate: { vocab: 'https://acme/notes#' },    // some other capability
+//       };
+//     }
+//   }
+//
+// A CAPABILITY author (a module loaded via data-extend-with) finds and enhances
+// every component offering its point — now or whenever one mounts later:
+//
+//   observeExtensionPoint('annotate', (el, spec) => enhance(el, spec));
+//
+// Neither side imports the other; they meet in the DOM. `edit` is special: it
+// delegates to core/editor.js so the existing `static get editor()` /
+// `static get shape()` / `shape=` attribute all keep working as sugar for it.
+
+import { resolveEditorSpec, editorSpecFromDecl } from './editor.js';
+
+function own(o, k) { return Object.prototype.hasOwnProperty.call(o, k); }
+function safe(fn) { try { return fn(); } catch (_) { return null; } }
+
+// ── externally-registered points ───────────────────────────────────────────
+// A component declares points with a `static get extensionPoints()`. But a
+// FOREIGN component (another library's element) can't — so a manifest's
+// `interop.editable` map lets a host register points for elements matching a
+// CSS selector, with no class change and no library patch. findExtensionPoints
+// consults this registry alongside class statics, so sol-form/sol-settings
+// enhance those elements through the unchanged `edit` protocol.
+const _registered = [];   // [{ selector, points }]
+
+/** Register extension points for every element matching `selector`. `points`
+ *  is the same shape a class returns from `extensionPoints` (e.g.
+ *  `{ edit: { shape, subject:{attr}, forms, present, open } }`). */
+export function registerExtensionPoints(selector, points) {
+  if (!selector || !points) return;
+  _registered.push({ selector: String(selector), points });
+  // nudge live observers to re-scan (late registration / already-mounted els)
+  if (typeof document !== 'undefined') {
+    document.dispatchEvent(new CustomEvent('swc:offer', { bubbles: true, composed: true, detail: { selector, points } }));
+  }
+}
+
+// The raw registered declaration for one point on `el`, or null.
+function registeredPoint(el, point) {
+  if (!el || typeof el.matches !== 'function') return null;
+  for (const r of _registered) {
+    if (own(r.points, point) && safe(() => el.matches(r.selector))) return r.points[point];
+  }
+  return null;
+}
+
+// The component's declared point map (guarded — a class getter may throw).
+function pointsMap(Ctor) {
+  const m = safe(() => (Ctor && Ctor.extensionPoints) || null);
+  return (m && typeof m === 'object') ? m : {};
+}
+
+// The `edit` point: legacy editor/shape/shape= (editor.js owns the rules), then
+// extensionPoints.edit fed back through editor.js so a map-only component works.
+function editPoint(Ctor, el) {
+  const legacy = safe(() => resolveEditorSpec(Ctor, el));
+  if (legacy) return legacy;
+  const e = pointsMap(Ctor).edit;
+  if (e != null) {
+    const synthetic = (typeof e === 'string') ? { editor: e }
+      : (e.shape ? { shape: e.shape } : { editor: e });
+    const spec = safe(() => resolveEditorSpec(synthetic, el));
+    if (spec) return spec;
+  }
+  // Finally, a manifest-registered edit descriptor for this element.
+  return editorSpecFromDecl(registeredPoint(el, 'edit'));
+}
+
+/** The spec a component offers for ONE point, or null. */
+export function resolveExtensionPoint(Ctor, el, point) {
+  if (point === 'edit') return editPoint(Ctor, el);
+  const raw = pointsMap(Ctor);
+  if (own(raw, point)) return raw[point];
+  return registeredPoint(el, point);
+}
+
+/** Every point a component offers, as { [point]: spec }. `edit` (if any) is the
+ *  editor.js canonical spec; other points are their raw declarations. */
+export function resolveExtensionPoints(Ctor, el) {
+  const out = {};
+  const raw = pointsMap(Ctor);
+  for (const k in raw) if (own(raw, k) && k !== 'edit') out[k] = raw[k];
+  // manifest-registered non-edit points for this element (class statics win)
+  for (const r of _registered) {
+    if (!safe(() => el && el.matches && el.matches(r.selector))) continue;
+    for (const k in r.points) if (own(r.points, k) && k !== 'edit' && !own(out, k)) out[k] = r.points[k];
+  }
+  const edit = editPoint(Ctor, el);
+  if (edit) out.edit = edit;
+  return out;
+}
+
+/** Walk the document (crossing shadow roots) for every element offering `point`.
+ *  Returns [{ el, spec }]. opts.root (default document), opts.skipAttr (an
+ *  attribute that opts an element out; default 'data-swc-skip'). */
+export function findExtensionPoints(point, opts) {
+  opts = opts || {};
+  const skipAttr = opts.skipAttr || 'data-swc-skip';
+  const out = [];
+  const seen = new WeakSet();
+  const visit = (r) => {
+    if (!r || !r.querySelectorAll) return;
+    for (const el of r.querySelectorAll('*')) {
+      if (seen.has(el)) continue;
+      seen.add(el);
+      if (el.hasAttribute && el.hasAttribute(skipAttr)) { if (el.shadowRoot) visit(el.shadowRoot); continue; }
+      // Resolve against the class statics AND the manifest registry (the latter
+      // works even for foreign elements whose ctor declares nothing).
+      const ctor = customElements.get(el.localName);
+      const spec = safe(() => resolveExtensionPoint(ctor, el, point));
+      if (spec) out.push({ el, spec });
+      if (el.shadowRoot) visit(el.shadowRoot);
+    }
+  };
+  visit(opts.root || document);
+  return out;
+}
+
+/** Call onMatch(el, spec) once for every element offering `point` — now and as
+ *  components mount later (debounced MutationObserver) or announce via
+ *  `swc:offer`. Returns an unsubscribe function. */
+export function observeExtensionPoint(point, onMatch, opts) {
+  opts = opts || {};
+  const matched = new WeakSet();
+  const scan = () => {
+    for (const { el, spec } of findExtensionPoints(point, opts)) {
+      if (matched.has(el)) continue;
+      matched.add(el);
+      safe(() => onMatch(el, spec));
+    }
+  };
+  scan();
+  let timer = null;
+  const debounced = () => { clearTimeout(timer); timer = setTimeout(scan, 50); };
+  const target = (opts.root && opts.root.documentElement) || document.documentElement || document;
+  const mo = new MutationObserver(debounced);
+  mo.observe(target, { childList: true, subtree: true });
+  document.addEventListener('swc:offer', debounced);
+  return () => { mo.disconnect(); clearTimeout(timer); document.removeEventListener('swc:offer', debounced); };
+}
+
+/** Announce, for a component that can't declare statically (created dynamically),
+ *  the points it offers — capabilities observing those points re-scan. */
+export function offerExtensionPoint(el, points) {
+  el.dispatchEvent(new CustomEvent('swc:offer', {
+    bubbles: true, composed: true, detail: { el, points },
+  }));
+}
+
+/** Register every `interop.editable` entry the loader collected from the page's
+ *  manifests, so a manifest can make any component (its own or a foreign
+ *  library's) editable with no class change. Each entry is keyed by CSS
+ *  selector → an edit descriptor `{ shape, subject:{attr}, forms, present, open }`.
+ *  Idempotent (a one-shot guard avoids double-registering on re-import). */
+export function registerInteropEditables() {
+  if (typeof window === 'undefined') return;
+  const api = window.SolidWebComponents;
+  const libs = (api && Array.isArray(api.interop)) ? api.interop : [];
+  for (const lib of libs) {
+    const editable = lib && lib.interop && lib.interop.editable;
+    if (!editable || typeof editable !== 'object') continue;
+    const seen = (lib._editableSeen = lib._editableSeen || {});
+    for (const selector in editable) {
+      if (!own(editable, selector) || seen[selector]) continue;
+      seen[selector] = true;
+      registerExtensionPoints(selector, { edit: editable[selector] });
+    }
+  }
+  // Inline placement (edit="inPlace" / present:"inPlace") is activated by
+  // core/edit-placements.js, loaded with the rdf capability.
+}
+
+// Run on import: the rdf capability (sol-form/sol-settings → this module) loads
+// after the loader has parsed manifests, so api.interop is already populated.
+registerInteropEditables();