sol-pod: gear-icon attr, dropdown scheme-strip, select min-width:0; add sol-solidos help

jeff-zucker · claude · jeff-zucker · commit d287fb4a257d · 2026-05-25T19:07:51.000-07:00
- sol-pod: new gear-icon attribute on the per-item action button.
  Treated as a URL when it contains "/" or ends in svg/png/jpg/gif/webp
  (rendered as &lt;img&gt;); otherwise used as text. Defaults to ⚙.
- sol-pod: strip http(s):// from the pod dropdown options for
  display compactness; option .value still carries the full URL so
  selection/fetch are unchanged.
- sol-pod-css: .item-gear img { display:block; width:1.1em; height:1.1em; pointer-events:none }
  and .pod-header select { min-width: 0 } so the login + settings
  buttons stay in the row in narrow sidebars (long URLs ellipsis-
  truncate inside the select).
- help/sol-pod-demo: document all attributes including gear-icon
  and the new dropdown behavior; demo now passes
  gear-icon="../web/styles/solid-logo.svg".
- help/sol-solidos-help (new): covers attributes, mashlib runtime
  deps, the known empty-window.Mashlib quirk (entry-point exports
  initMainPage via window.panes), and a panes-only embedding
  pattern that skips sol-solidos's duplicate DOM scaffolding.
- home.html: surface sol-solidos as a visible row in the components
  table.
- dist/sol-pod.umd.min.js, dist/podz-extras.bundle.min.js rebuilt.

Co-Authored-By: Claude Opus 4.7 &lt;noreply@anthropic.com&gt;
diff --git a/dist/podz-extras.bundle.min.js b/dist/podz-extras.bundle.min.js
diff --git a/dist/sol-pod.umd.min.js b/dist/sol-pod.umd.min.js
diff --git a/help/sol-pod-demo.html b/help/sol-pod-demo.html
@@ -12,10 +12,30 @@ <h1> sol-pod component </h1>
 
   <!-- No `source` — sol-pod discovers pods from the current origin
        (and again on login). Discovery only finds pods when this page is
-       served from a Solid origin. -->
-  <sol-pod></sol-pod>
+       served from a Solid origin.
+       `gear-icon` swaps the default ⚙ for an image; here we use this
+       project's Solid logo. If you omit the attribute you get the ⚙.
+       If you give it a short string (like a single emoji) it's used
+       as text. If it contains a slash or ends in svg/png/jpg/gif/webp
+       it's rendered as <img>. -->
+  <sol-pod gear-icon="../web/styles/solid-logo.svg"></sol-pod>
   <div id="results"></div>
 
+  <h3>Attributes</h3>
+  <ul>
+    <li><code>source</code> — pod storage URL or comma/space-separated list. Omit to auto-discover from the current origin / WebID.</li>
+    <li><code>login</code> — CSS selector for an external <code>&lt;sol-login&gt;</code>. Omit to use the built-in one in the header.</li>
+    <li><code>login-mode</code>, <code>login-callback</code>, <code>issuers</code>, <code>side</code> — forwarded to the built-in <code>&lt;sol-login&gt;</code>.</li>
+    <li><code>pod-click-action</code> — function (assigned via JS property) or named handler. Receives <code>(item, podEl)</code> when the user clicks the per-item icon, presses Enter, or double-clicks. Item carries <code>{ url, name, displayName, isContainer, contentType }</code>.</li>
+    <li><code>handler</code> — alias for <code>pod-click-action</code>.</li>
+    <li><code>gear-icon</code> — replaces the default <code>⚙</code> per-item button. URL (contains <code>/</code> or ends in svg/png/jpg/gif/webp) → renders as <code>&lt;img&gt;</code>; otherwise used as text.</li>
+    <li><code>pods-group</code> — shared pod-list scope across multiple <code>&lt;sol-pod&gt;</code>s on the page. Absent = default shared group; <code>'none'</code> = standalone registry.</li>
+  </ul>
+
+  <h3>Pod selector display</h3>
+  <p>The pod dropdown strips the <code>http://</code> / <code>https://</code> prefix from each option for compactness — <code>https://alice.solidcommunity.net/</code> shows as <code>alice.solidcommunity.net/</code>. The option's <code>value</code> stays the full URL so selection / fetch are unchanged.</p>
+  <p>The selector also has <code>min-width: 0</code> in flex layouts so the login + settings buttons stay visible even in narrow sidebars; long URLs ellipsis-truncate inside the select.</p>
+
   <script src="../dist/vendor/rdflib.umd.js"></script>
   <script src="../dist/sol-pod.umd.min.js?v=7"></script>
   <script>
diff --git a/help/sol-solidos-help.html b/help/sol-solidos-help.html
@@ -0,0 +1,108 @@
+<!DOCTYPE html><html lang="en"><head>
+  <meta charset="utf-8">
+  <title>sol-solidos</title>
+  <script src="../web/scripts/prefs.js"></script>
+  <link rel="stylesheet" href="../web/styles/root.css">
+  <link rel="stylesheet" href="../web/styles/sol-query-help.css">
+  <link rel="stylesheet" href="../web/styles/help.css">
+</head><body>
+
+<div class="container">
+  <h1>sol-solidos</h1>
+
+  <p>A custom element that mounts the
+     <a href="https://github.com/SolidOS/mashlib">SolidOS</a> data
+     browser inside its light DOM. Setting the <code>source</code>
+     attribute drives <code>outliner.GotoSubject(...)</code> so the
+     panes navigate to that resource.</p>
+
+  <h2>Attributes</h2>
+  <ul>
+    <li><code>source</code> — URL of the Solid resource to display.
+        Setting it after the element is connected triggers a
+        navigation. If unset on first mount, the panes initialise
+        with <code>window.location.href</code> as the subject.</li>
+  </ul>
+
+  <h2>Runtime dependencies (bring-your-own)</h2>
+  <p>sol-solidos relies on mashlib + solid-panes (a substantial
+     dependency tree — RDF store, panes, login UI, theme module).
+     These are <em>not</em> in the all-in-one
+     <code>solid-web-components.bundle.min.js</code> or in
+     <code>podz-extras.bundle.min.js</code>. You must load mashlib
+     separately so that <code>window.panes</code>,
+     <code>window.SolidLogic</code>, and <code>window.Mashlib</code>
+     are populated before sol-solidos's <code>connectedCallback</code>
+     runs.</p>
+
+  <pre><code>&lt;script src="dist/vendor/rdflib.umd.js"&gt;&lt;/script&gt;
+&lt;script src="dist/vendor/@inrupt-solid-client-authn-browser.umd.js"&gt;&lt;/script&gt;
+&lt;link rel="stylesheet" href="node_modules/mashlib/dist/mash.css"&gt;
+&lt;script src="node_modules/mashlib/dist/mashlib.min.js"&gt;&lt;/script&gt;
+&lt;script src="dist/sol-solidos.umd.min.js"&gt;&lt;/script&gt;
+
+&lt;sol-solidos source="https://your.pod/some/resource"&gt;&lt;/sol-solidos&gt;</code></pre>
+
+  <h2>Known mashlib quirk: empty <code>window.Mashlib</code></h2>
+  <p>mashlib's UMD wrapper sets <code>window.Mashlib</code> to its
+     entry-point exports — and its entry point
+     (<code>./src/index.ts</code>) is pure side-effects with no
+     exports. So <code>window.Mashlib</code> ends up an empty
+     <code>{}</code>. sol-solidos's <code>getMashlib()</code> looks
+     for <code>Mashlib.initMainPage</code>, which is actually exposed
+     on <code>window.panes</code>. Patch it before mounting
+     sol-solidos:</p>
+
+  <pre><code>&lt;script&gt;
+  if (window.Mashlib &amp;&amp; window.panes &amp;&amp; window.panes.initMainPage) {
+    window.Mashlib.initMainPage = window.panes.initMainPage;
+  }
+&lt;/script&gt;
+&lt;sol-solidos&gt;&lt;/sol-solidos&gt;</code></pre>
+
+  <h2>Embedding alternative: skip sol-solidos, use panes directly</h2>
+  <p>sol-solidos creates its own DOM scaffolding
+     (<code>&lt;header id="PageHeader"&gt;</code>,
+     <code>&lt;main id="mainContent"&gt;</code>,
+     <code>&lt;footer id="PageFooter"&gt;</code>) and then calls
+     <code>initMainPage</code>, which creates a parallel set of
+     SolidOS-shell elements
+     (<code>#mainSolidUiHeader</code>, <code>#MainContent</code>,
+     <code>#PageFooter</code>) at the document body. If you want the
+     SolidOS chrome (banner + side menu + footer) and the outline
+     <em>without</em> the duplicate IDs, skip sol-solidos and use
+     mashlib's lower-level API directly:</p>
+
+  <pre><code>&lt;body id="PageBody"&gt;
+  &lt;solid-ui-header id="mainSolidUiHeader"&gt;&lt;span slot="title"&gt;&lt;/span&gt;&lt;/solid-ui-header&gt;
+  &lt;main id="MainContent" role="main"&gt;
+    &lt;div class="app-shell"&gt;
+      &lt;aside id="NavMenu" class="app-nav" hidden&gt;&lt;div id="NavMenuContent"&gt;&lt;/div&gt;&lt;/aside&gt;
+      &lt;div class="app-view"&gt;&lt;table id="OutlineView" class="outline-view"&gt;&lt;/table&gt;&lt;/div&gt;
+    &lt;/div&gt;
+  &lt;/main&gt;
+  &lt;footer id="PageFooter"&gt;&lt;/footer&gt;
+  &lt;script&gt;
+    const store = window.SolidLogic.solidLogicSingleton.store;
+    window.panes.initMainPage(store, 'https://your.pod/foo');
+  &lt;/script&gt;
+&lt;/body&gt;</code></pre>
+
+  <p>This is the structure
+     <a href="../../node_modules/mashlib/dist/databrowser.html">mashlib's
+     <code>databrowser.html</code></a> uses; <code>initMainPage</code>
+     fills the existing elements instead of creating new ones. For
+     navigation after the initial render, hold the outliner and call
+     it directly:</p>
+
+  <pre><code>const outliner = window.panes.getOutliner(document);
+outliner.GotoSubject(window.$rdf.sym(newUrl), true, undefined, true, undefined);</code></pre>
+
+  <h2>Working embedded example</h2>
+  <p>See <a href="https://github.com/jeff-zucker/data-kitchen">data-kitchen</a>
+     for an integration that hosts SolidOS inside a same-origin iframe
+     (so its CSS / globals / theme handling stay contained) and drives
+     it from a sidebar <code>&lt;sol-pod&gt;</code>.</p>
+
+</div>
+</body></html>
diff --git a/home.html b/home.html
@@ -70,6 +70,10 @@ <h3>Access Solid and Linked Data resources using HTML custom elements</h3>
    <span class="cell name" role="cell"><a href="help/sol-form-help.html">sol-form</a></span>
    <span class="cell" role="cell">Auto-saving editable forms bound to RDF. Two paths: <b>shape-driven</b> &mdash; point at a SHACL shape + data document and sol-form generates the inputs from the shape; <b>form-driven</b> &mdash; supply a hand-authored <code>ui:Form</code> TTL and solid-ui renders it. Includes a live SHACL-to-form demo on the help page.</span>
  </article>
+ <article class="row" role="row">
+   <span class="cell name" role="cell"><a href="help/sol-solidos-help.html">sol-solidos</a></span>
+   <span class="cell" role="cell">Mount the SolidOS data browser (mashlib panes) inside a custom element; set <code>source</code> to navigate. Requires loading <code>mashlib</code> separately as a UMD &mdash; not in the all-in-one bundle. Help page covers the standard wiring, the known empty-<code>window.Mashlib</code> quirk, and a panes-only embedding pattern for hosts (like an iframe) that just want the outline.</span>
+ </article>
  <article class="row" role="row">
    <span class="cell name" role="cell"><b>dashboard</b></span>
    <span class="cell" role="cell">A worked-example page combining <a href="help/sol-weather-help.html">sol-weather</a>, <a href="help/sol-time-help.html">sol-time</a>, <a href="help/sol-calendar-help.html">sol-calendar</a>, and <a href="help/sol-feed-help.html">sol-feed</a> into a single dashboard layout. Open <a href="dashboard.html">dashboard.html</a> in the repo root to see them all working together.</span>
diff --git a/web/sol-pod.js b/web/sol-pod.js
@@ -44,6 +44,9 @@ import './sol-login.js';   // built-in login button in the pod header
  * @attr {string} side - auth session tag; also forwarded to the built-in sol-login as its `side`
  * @attr {string} pod-click-action - callback when an item is activated (gear / Enter / double-click)
  * @attr {string} handler - default sol-* component for file viewing
+ * @attr {string} gear-icon - icon for the per-item action button. Treated as
+ *                 a URL when it contains '/' or ends in svg/png/jpg/gif/webp;
+ *                 otherwise used as text (emoji). Defaults to '⚙'.
  * @attr {string} pods-group - shared pod-list scope; absent = the default shared
  *                 group, 'none' = a standalone unshared registry
  * @property {Object} login - SolLogin element reference (external if given, else the built-in one)
@@ -488,7 +491,10 @@ class SolPod extends HTMLElement {
     } else {
       storages.forEach(url => {
         const opt = document.createElement('option');
-        opt.value = url; opt.textContent = url;
+        opt.value = url;
+        // Strip the scheme for display; the value still carries the
+        // full URL so selection / fetch keep working.
+        opt.textContent = url.replace(/^https?:\/\//, '');
         sel.appendChild(opt);
       });
     }
@@ -733,8 +739,17 @@ class SolPod extends HTMLElement {
     };
 
     const gear = document.createElement('button');
-    gear.className = 'item-gear'; gear.textContent = '\u2699';
+    gear.className = 'item-gear';
     gear.title = 'Actions';
+    const iconAttr = this.getAttribute('gear-icon');
+    if (iconAttr && /\/|\.(svg|png|jpe?g|gif|webp)$/i.test(iconAttr)) {
+      const img = document.createElement('img');
+      img.src = iconAttr;
+      img.alt = '';
+      gear.appendChild(img);
+    } else {
+      gear.textContent = iconAttr || '\u2699';
+    }
     gear.onclick = openItemAction;
     li.appendChild(gear);
 
diff --git a/web/styles/sol-pod-css.js b/web/styles/sol-pod-css.js
@@ -33,6 +33,10 @@ export const CSS = BTN_CSS + `
   }
   .pod-header select {
     flex: 1; padding: 6px 10px;
+    /* Without min-width:0 a flex <select> reserves the width of its
+       widest option, pushing the login + settings buttons out of the
+       sidebar in narrow panels. */
+    min-width: 0;
     border: 1px solid var(--border, #e0e0e0); border-radius: 4px;
     font-size: 0.9em;
     background: var(--surface, #fff); color: var(--text, #212121);
@@ -129,6 +133,8 @@ export const CSS = BTN_CSS + `
     transition: color 0.15s;
   }
   .item-gear:hover { color: var(--accent-dark, #1976d2); background: var(--focus-bg, #e3f2fd); }
+  /* When gear-icon attribute is a URL, the button holds an <img>. */
+  .item-gear img { display: block; width: 1.1em; height: 1.1em; pointer-events: none; }
 
   .file-tree .folder { font-weight: 500; color: var(--folder-color, var(--accent-dark, #1976d2)); }
   .file-tree .file   { color: var(--file-color, #424242); }
