raffel 1.1.11 → 1.1.15

package/dist/docs/ui/assets/raffel-docs.css

@@ -951,6 +951,31 @@
       }
     }
 
+    .docs-pages-group > .tag-group-header {
+      color: var(--text-primary);
+      background: var(--hover-bg);
+      border-left: 3px solid var(--primary-color);
+      padding-left: 9px;
+      margin-bottom: 4px;
+      letter-spacing: 0.01em;
+    }
+
+    .docs-pages-group > .tag-group-header:hover {
+      background: var(--hover-bg);
+      opacity: 0.85;
+    }
+
+    .docs-sidebar-home {
+      display: flex;
+      align-items: center;
+      gap: 6px;
+    }
+
+    .docs-sidebar-home-icon {
+      flex-shrink: 0;
+      opacity: 0.7;
+    }
+
     /* ========== TOC (On this page) — editorial sidenote ========== */
     .toc {
       align-self: start;

package/dist/docs/ui/assets/raffel-docs.js

@@ -908,8 +908,13 @@ function setDocsPage(path, headingId = '') {
     activePagePath = resolveDocsAlias(normalizeDocsPath(path));
     activeHeadingId = headingId;
     win.history?.replaceState?.(null, '', routeToHash(activePagePath, activeHeadingId));
-    if (!activeHeadingId)
-        win.scrollTo?.({ top: 0, behavior: 'smooth' });
+    if (!activeHeadingId) {
+        const appEl = doc.getElementById('docs') ?? doc.querySelector('.app-container');
+        if (appEl)
+            appEl.scrollIntoView({ behavior: 'smooth', block: 'start' });
+        else
+            win.scrollTo?.({ top: 0, behavior: 'smooth' });
+    }
     runVoidHook('onRouteChange', getPluginContext({ pagePath: activePagePath, headingId: activeHeadingId }));
     render();
 }
@@ -1039,8 +1044,30 @@ function renderSidebar() {
 function renderDocsPagesNav(nav) {
     if (sidebarConfig.docsPages === false)
         return;
+    const groupLabel = sidebarConfig.docsPagesGroup;
+    const hasActiveDocPage = Boolean(activePagePath);
+    let target = nav;
+    if (groupLabel) {
+        const allPages = getDocsPageViews();
+        const wrapper = doc.createElement('div');
+        wrapper.className = `tag-group docs-pages-group${hasActiveDocPage || sidebarConfig.expandAll ? '' : ' collapsed'}`;
+        const header = doc.createElement('div');
+        header.className = 'tag-group-header';
+        header.innerHTML = `<span class="tag-group-arrow">▼</span>${esc(groupLabel)}<span class="tag-group-count">${allPages.length}</span>`;
+        const inner = doc.createElement('div');
+        inner.className = 'tag-group-items';
+        inner.style.maxHeight = hasActiveDocPage || sidebarConfig.expandAll ? '9999px' : '0';
+        header.onclick = () => {
+            wrapper.classList.toggle('collapsed');
+            inner.style.maxHeight = wrapper.classList.contains('collapsed') ? '0' : '9999px';
+        };
+        wrapper.appendChild(header);
+        wrapper.appendChild(inner);
+        nav.appendChild(wrapper);
+        target = inner;
+    }
     if (docsSidebar.length > 0 && !searchQuery) {
-        renderDeclarativeDocsSidebar(nav);
+        renderDeclarativeDocsSidebar(target);
         return;
     }
     const pages = getDocsPageViews().filter(page => !searchQuery ||
@@ -1054,9 +1081,10 @@ function renderDocsPagesNav(nav) {
         sections.get(page.section)?.push(page);
     }
     for (const [section, sectionPages] of sections) {
-        appendSidebarGroup(nav, section, sectionPages.map(page => ({
+        appendSidebarGroup(target, section, sectionPages.map(page => ({
             active: page.path === activePagePath,
             label: page.title,
+            path: page.path,
             children: page.path === activePagePath && !searchQuery ? extractSidebarHeadings(page.markdown) : [],
             onClick: () => setDocsPage(page.path),
         })));
@@ -1078,21 +1106,29 @@ function renderDeclarativeDocsSidebar(nav) {
         extractSidebarHeadings,
     });
 }
+const HOME_ICON_SVG = '<svg class="docs-sidebar-home-icon" width="13" height="13" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z"/></svg>';
 function appendSidebarGroup(nav, title, items) {
     const group = doc.createElement('div');
     group.className = 'tag-group';
     const header = doc.createElement('div');
     header.className = 'tag-group-header';
     header.innerHTML = `<span class="tag-group-arrow">▼</span>${esc(title)}<span class="tag-group-count">${items.length}</span>`;
-    header.onclick = () => group.classList.toggle('collapsed');
     const itemContainer = doc.createElement('div');
     itemContainer.className = 'tag-group-items';
     const childCount = items.reduce((count, item) => count + (item.children?.length ?? 0), 0);
-    itemContainer.style.maxHeight = `${items.length * 50 + childCount * 34}px`;
+    const expandedHeight = `${items.length * 50 + childCount * 34}px`;
+    itemContainer.style.maxHeight = expandedHeight;
+    header.onclick = () => {
+        group.classList.toggle('collapsed');
+        itemContainer.style.maxHeight = group.classList.contains('collapsed') ? '0' : expandedHeight;
+    };
     for (const item of items) {
         const el = doc.createElement('div');
         el.className = `nav-item${item.active ? ' active' : ''}`;
-        el.innerHTML = `${item.prefix ? `<span class="nav-item-method method-${esc(item.prefix.toLowerCase())}">${esc(item.prefix)}</span>` : ''}<span class="nav-item-path">${esc(item.label)}</span>`;
+        const isHome = item.path === '/' || item.path === '';
+        el.innerHTML = isHome
+            ? `<span class="docs-sidebar-home">${HOME_ICON_SVG}<span class="nav-item-path">${esc(item.label)}</span></span>`
+            : `${item.prefix ? `<span class="nav-item-method method-${esc(item.prefix.toLowerCase())}">${esc(item.prefix)}</span>` : ''}<span class="nav-item-path">${esc(item.label)}</span>`;
         el.onclick = (event) => {
             event.stopPropagation();
             item.onClick();

package/dist/docs/ui/assets/sidebar-tree.js

@@ -16,10 +16,13 @@ function appendSidebarItem(parent, item, depth, deps) {
         const header = deps.doc.createElement('div');
         header.className = `tag-group-header${active ? ' active' : ''}`;
         header.innerHTML = `<span class="tag-group-arrow">▼</span>${deps.esc(title)}<span class="tag-group-count">${countLeaves(children)}</span>`;
-        header.onclick = () => group.classList.toggle('collapsed');
         const childContainer = deps.doc.createElement('div');
         childContainer.className = 'tag-group-items';
         childContainer.style.maxHeight = expanded ? `${Math.max(1, countRows(children)) * 90}px` : '0';
+        header.onclick = () => {
+            group.classList.toggle('collapsed');
+            childContainer.style.maxHeight = group.classList.contains('collapsed') ? '0' : `${Math.max(1, countRows(children)) * 90}px`;
+        };
         if (itemPath || item.href) {
             childContainer.appendChild(createPageItem(item, title, active, depth, deps));
             if (active && !deps.searchQuery)
@@ -39,7 +42,11 @@ function appendSidebarItem(parent, item, depth, deps) {
 function createPageItem(item, title, active, depth, deps) {
     const element = deps.doc.createElement('div');
     element.className = `nav-item docs-page-nav-item docs-sidebar-page docs-sidebar-depth-${depth}${active ? ' active' : ''}`;
-    element.innerHTML = `<span class="nav-item-text">${deps.esc(title)}</span>`;
+    const normalizedPath = item.path ? deps.normalizeDocsPath(item.path) : '';
+    const isHome = depth === 0 && (normalizedPath === '/' || normalizedPath === '');
+    element.innerHTML = isHome
+        ? `<span class="docs-sidebar-home"><svg class="docs-sidebar-home-icon" width="13" height="13" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z"/></svg><span class="nav-item-text">${deps.esc(title)}</span></span>`
+        : `<span class="nav-item-text">${deps.esc(title)}</span>`;
     element.onclick = (event) => {
         event.stopPropagation();
         if (item.href && !item.path) {

package/dist/docs/ui/html-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"html-builder.d.ts","sourceRoot":"","sources":["../../../src/docs/ui/html-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAA6C,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAkB/F;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CA8IlE;AAmCD;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAYjE"}
+{"version":3,"file":"html-builder.d.ts","sourceRoot":"","sources":["../../../src/docs/ui/html-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAA6C,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAoB/F;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CA0JlE;AAmCD;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,CAYjE"}

package/dist/docs/ui/html-builder.js

@@ -11,6 +11,7 @@
  * 2. All user-visible text is escaped before rendering
  * 3. JSON data is escaped for script embedding to prevent XSS
  */
+const _startupTs = Date.now();
 import { generateStyles } from './styles.js';
 import { escapeHtml, escapeJsonForScript, generateHeroBackgroundCSS } from './utils.js';
 import { generateAppContainer, generateHeroSection, generateIntroductionSection, generateSkipLink, generateTopNavigation, mergeHeroConfig, } from './html-shell.js';
@@ -99,9 +100,21 @@ ${styles}
     });
   })();
   </script>
+  <script type="importmap">
+  {
+    "imports": {
+      "${escapeHtml(assetBasePath)}/-/sidebar-tree.js": "${escapeHtml(assetBasePath)}/-/sidebar-tree.js?v=${_startupTs}",
+      "${escapeHtml(assetBasePath)}/-/marked-renderer.js": "${escapeHtml(assetBasePath)}/-/marked-renderer.js?v=${_startupTs}",
+      "${escapeHtml(assetBasePath)}/-/protocol-console.js": "${escapeHtml(assetBasePath)}/-/protocol-console.js?v=${_startupTs}",
+      "${escapeHtml(assetBasePath)}/-/code-block-toolbar.js": "${escapeHtml(assetBasePath)}/-/code-block-toolbar.js?v=${_startupTs}",
+      "${escapeHtml(assetBasePath)}/-/page-nav.js": "${escapeHtml(assetBasePath)}/-/page-nav.js?v=${_startupTs}",
+      "${escapeHtml(assetBasePath)}/-/search-modal.js": "${escapeHtml(assetBasePath)}/-/search-modal.js?v=${_startupTs}"
+    }
+  }
+  </script>
   <script src="${escapeHtml(assetBasePath)}/-/marked.umd.js"></script>
   <script src="${escapeHtml(assetBasePath)}/-/prism.js"></script>
-  <script type="module" data-raffel-runtime="external" src="${escapeHtml(assetBasePath)}/-/raffel-docs.js"></script>`
+  <script type="module" data-raffel-runtime="external" src="${escapeHtml(assetBasePath)}/-/raffel-docs.js?v=${_startupTs}"></script>`
         : `${generateInlineRuntimeDependencyScripts()}
   <script type="module" data-raffel-runtime="inline">
 ${generateClientRuntimeScript()}

package/dist/docs/ui/html-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"html-builder.js","sourceRoot":"","sources":["../../../src/docs/ui/html-builder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"html-builder.js","sourceRoot":"","sources":["../../../src/docs/ui/html-builder.ts"],"names":[],"mappings":"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"}

package/dist/docs/ui/runtime/index.js

@@ -908,8 +908,13 @@ function setDocsPage(path, headingId = '') {
     activePagePath = resolveDocsAlias(normalizeDocsPath(path));
     activeHeadingId = headingId;
     win.history?.replaceState?.(null, '', routeToHash(activePagePath, activeHeadingId));
-    if (!activeHeadingId)
-        win.scrollTo?.({ top: 0, behavior: 'smooth' });
+    if (!activeHeadingId) {
+        const appEl = doc.getElementById('docs') ?? doc.querySelector('.app-container');
+        if (appEl)
+            appEl.scrollIntoView({ behavior: 'smooth', block: 'start' });
+        else
+            win.scrollTo?.({ top: 0, behavior: 'smooth' });
+    }
     runVoidHook('onRouteChange', getPluginContext({ pagePath: activePagePath, headingId: activeHeadingId }));
     render();
 }
@@ -1039,8 +1044,30 @@ function renderSidebar() {
 function renderDocsPagesNav(nav) {
     if (sidebarConfig.docsPages === false)
         return;
+    const groupLabel = sidebarConfig.docsPagesGroup;
+    const hasActiveDocPage = Boolean(activePagePath);
+    let target = nav;
+    if (groupLabel) {
+        const allPages = getDocsPageViews();
+        const wrapper = doc.createElement('div');
+        wrapper.className = `tag-group docs-pages-group${hasActiveDocPage || sidebarConfig.expandAll ? '' : ' collapsed'}`;
+        const header = doc.createElement('div');
+        header.className = 'tag-group-header';
+        header.innerHTML = `<span class="tag-group-arrow">▼</span>${esc(groupLabel)}<span class="tag-group-count">${allPages.length}</span>`;
+        const inner = doc.createElement('div');
+        inner.className = 'tag-group-items';
+        inner.style.maxHeight = hasActiveDocPage || sidebarConfig.expandAll ? '9999px' : '0';
+        header.onclick = () => {
+            wrapper.classList.toggle('collapsed');
+            inner.style.maxHeight = wrapper.classList.contains('collapsed') ? '0' : '9999px';
+        };
+        wrapper.appendChild(header);
+        wrapper.appendChild(inner);
+        nav.appendChild(wrapper);
+        target = inner;
+    }
     if (docsSidebar.length > 0 && !searchQuery) {
-        renderDeclarativeDocsSidebar(nav);
+        renderDeclarativeDocsSidebar(target);
         return;
     }
     const pages = getDocsPageViews().filter(page => !searchQuery ||
@@ -1054,9 +1081,10 @@ function renderDocsPagesNav(nav) {
         sections.get(page.section)?.push(page);
     }
     for (const [section, sectionPages] of sections) {
-        appendSidebarGroup(nav, section, sectionPages.map(page => ({
+        appendSidebarGroup(target, section, sectionPages.map(page => ({
             active: page.path === activePagePath,
             label: page.title,
+            path: page.path,
             children: page.path === activePagePath && !searchQuery ? extractSidebarHeadings(page.markdown) : [],
             onClick: () => setDocsPage(page.path),
         })));
@@ -1078,21 +1106,29 @@ function renderDeclarativeDocsSidebar(nav) {
         extractSidebarHeadings,
     });
 }
+const HOME_ICON_SVG = '<svg class="docs-sidebar-home-icon" width="13" height="13" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z"/></svg>';
 function appendSidebarGroup(nav, title, items) {
     const group = doc.createElement('div');
     group.className = 'tag-group';
     const header = doc.createElement('div');
     header.className = 'tag-group-header';
     header.innerHTML = `<span class="tag-group-arrow">▼</span>${esc(title)}<span class="tag-group-count">${items.length}</span>`;
-    header.onclick = () => group.classList.toggle('collapsed');
     const itemContainer = doc.createElement('div');
     itemContainer.className = 'tag-group-items';
     const childCount = items.reduce((count, item) => count + (item.children?.length ?? 0), 0);
-    itemContainer.style.maxHeight = `${items.length * 50 + childCount * 34}px`;
+    const expandedHeight = `${items.length * 50 + childCount * 34}px`;
+    itemContainer.style.maxHeight = expandedHeight;
+    header.onclick = () => {
+        group.classList.toggle('collapsed');
+        itemContainer.style.maxHeight = group.classList.contains('collapsed') ? '0' : expandedHeight;
+    };
     for (const item of items) {
         const el = doc.createElement('div');
         el.className = `nav-item${item.active ? ' active' : ''}`;
-        el.innerHTML = `${item.prefix ? `<span class="nav-item-method method-${esc(item.prefix.toLowerCase())}">${esc(item.prefix)}</span>` : ''}<span class="nav-item-path">${esc(item.label)}</span>`;
+        const isHome = item.path === '/' || item.path === '';
+        el.innerHTML = isHome
+            ? `<span class="docs-sidebar-home">${HOME_ICON_SVG}<span class="nav-item-path">${esc(item.label)}</span></span>`
+            : `${item.prefix ? `<span class="nav-item-method method-${esc(item.prefix.toLowerCase())}">${esc(item.prefix)}</span>` : ''}<span class="nav-item-path">${esc(item.label)}</span>`;
         el.onclick = (event) => {
             event.stopPropagation();
             item.onClick();