@sprig-and-prose/sprig-ui-csr 0.1.1 → 0.2.0

package/src/pages/SeriesPage.svelte

@@ -5,9 +5,7 @@
   import ContentsCard from '../lib/components/ContentsCard.svelte';
   import FooterStatus from '../lib/components/FooterStatus.svelte';
   import PageHeader from '../lib/components/PageHeader.svelte';
-  import { linkForPath } from '../lib/references/linkForPath.js';
-  import { linkForRepository } from '../lib/references/linkForRepository.js';
-  import { isWildcardPath } from '../lib/references/isWildcardPath.js';
+  // Reference routing stays internal for series pages
 
   /** @type {{ universe: string, series: string }} */
   export let params;
@@ -21,7 +19,7 @@
 
   /**
    * @typedef {{ raw?:string, normalized?:string, source?:any }} TextBlock
-   * @typedef {{ repository:string, paths:string[]|Array<{path:string, describe?:TextBlock}>, describe?:TextBlock }} ReferenceBlock
+   * @typedef {{ id:string, name:string, kind?:string, title?:string, describe?:TextBlock, note?:TextBlock, urls?:string[], paths?:string[], repositoryRef?:string }} ReferenceModel
    */
 
   $: subtitle = (() => {
@@ -52,133 +50,50 @@
       : `A series in ${params.universe}`;
   })();
 
+  $: referenceItems = ($currentSeries?.references || [])
+    .map((id) => $universeGraph?.references?.[id])
+    .filter(Boolean);
+
   /**
-   * Normalize reference paths to handle both Shape A (strings) and Shape B (objects)
-   * @param {ReferenceBlock} ref
-   * @returns {Array<{path:string, describe?:TextBlock}>}
+   * @param {string} url
+   * @param {string | undefined} label
    */
-  function normalizePaths(ref) {
-    if (!ref.paths || ref.paths.length === 0) return [];
-    
-    // Shape B: paths is array of objects
-    if (typeof ref.paths[0] === 'object' && ref.paths[0] !== null && 'path' in ref.paths[0]) {
-      return ref.paths.map((/** @type {{path:string, describe?:TextBlock}} */ p) => ({
-        path: p.path,
-        describe: p.describe,
-      }));
-    }
-    
-    // Shape A: paths is array of strings
-    return ref.paths.map((/** @type {string} */ p) => ({
-      path: p,
-      describe: undefined, // No per-path describe in Shape A
-    }));
-  }
-
-  // Group references by repository, preserving source order
-  $: groupedReferences = (() => {
-    const refs = $currentSeries?.references || [];
-    if (refs.length === 0) return [];
-
-    const groups = new Map();
-    const order = [];
-
-    for (const ref of refs) {
-      const repo = ref.repository;
-      if (!groups.has(repo)) {
-        groups.set(repo, {
-          referenceGroups: [],
-        });
-        order.push(repo);
-      }
-      
-      const group = groups.get(repo);
-      const normalizedPaths = normalizePaths(ref);
-      const pathEntries = normalizedPaths.map((pathEntry) => ({
-        path: pathEntry.path,
-        perPathDescribe: pathEntry.describe,
-      }));
-      
-      group.referenceGroups.push({
-        paths: pathEntries,
-        groupDescribe: ref.describe?.normalized || undefined,
-      });
-    }
-
-    return order.map((repo) => ({
-      repository: repo,
-      referenceGroups: groups.get(repo).referenceGroups,
-    }));
-  })();
+  function makeLinkLabel(url, label) {
+    return label && label.trim().length > 0 ? label : url;
+  }
 
-  // Expand/collapse state per repository group
-  let expandedGroups = new Set();
-
-  // Reactive repository URLs and path link generator - need to read from store reactively
-  $: repositoryUrls = (() => {
-    const graph = $universeGraph;
-    if (!graph?.repositories) return {};
-    const urls = {};
-    for (const [repoName, repoConfig] of Object.entries(graph.repositories)) {
-      const { kind, options } = repoConfig;
-      if (kind === 'sprig-repository-github') {
-        if (options?.url) {
-          urls[repoName] = options.url.endsWith('/') ? options.url.slice(0, -1) : options.url;
-        } else if (options?.owner && options?.repo) {
-          urls[repoName] = `https://github.com/${options.owner}/${options.repo}`;
+  /**
+   * @param {ReferenceModel} ref
+   */
+  function getRepositoryForReference(ref) {
+    if (!ref.repositoryRef || !$universeGraph?.repositories) return null;
+    return $universeGraph.repositories[ref.repositoryRef] || null;
+  }
+
+  $: referenceGroups = (() => {
+    /** @type {Array<{ repo: any | null, refs: ReferenceModel[] }>} */
+    const groups = [];
+    const byRepo = new Map();
+
+    for (const ref of referenceItems) {
+      if (!ref) continue;
+      if (ref.repositoryRef) {
+        let group = byRepo.get(ref.repositoryRef);
+        if (!group) {
+          const repo = getRepositoryForReference(ref);
+          group = { repo, refs: [] };
+          byRepo.set(ref.repositoryRef, group);
+          groups.push(group);
         }
-      }
-    }
-    return urls;
-  })();
-
-  // Helper function to generate path URLs reactively
-  function getPathUrl(repository, path) {
-    const graph = $universeGraph;
-    if (!graph?.repositories) return null;
-    const repoConfig = graph.repositories[repository];
-    if (!repoConfig) return null;
-    const { kind, options } = repoConfig;
-    const defaultBranch = options?.defaultBranch || 'main';
-    
-    if (kind === 'sprig-repository-github') {
-      let baseUrl;
-      if (options?.url) {
-        baseUrl = options.url;
-      } else if (options?.owner && options?.repo) {
-        baseUrl = `https://github.com/${options.owner}/${options.repo}`;
+        group.refs.push(ref);
       } else {
-        return null;
+        groups.push({ repo: null, refs: [ref] });
       }
-      const normalizedBaseUrl = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
-      const normalizedPath = path.startsWith('/') ? path : `/${path}`;
-      
-      if (isWildcardPath(path)) {
-        const lastSlashIndex = normalizedPath.lastIndexOf('/');
-        if (lastSlashIndex > 0) {
-          const folderPath = normalizedPath.slice(0, lastSlashIndex);
-          return `${normalizedBaseUrl}/tree/${defaultBranch}${folderPath}`;
-        }
-        return `${normalizedBaseUrl}/tree/${defaultBranch}`;
-      }
-      return `${normalizedBaseUrl}/blob/${defaultBranch}${normalizedPath}`;
     }
-    return null;
-  }
 
-  /**
-   * @param {string} repository
-   */
-  function toggleGroup(repository) {
-    if (expandedGroups.has(repository)) {
-      expandedGroups.delete(repository);
-    } else {
-      expandedGroups.add(repository);
-    }
-    expandedGroups = expandedGroups; // Trigger reactivity
-  }
+    return groups;
+  })();
 
-  const DEFAULT_VISIBLE_PATHS = 3;
 
   /**
    * Get the anthology node for a series, if it belongs to one
@@ -270,100 +185,68 @@
     </section>
   {/if}
 
-  {#if groupedReferences.length > 0}
+  {#if referenceItems.length > 0}
     <section class="references">
       <h2 class="references-title">References</h2>
       <p class="references-subtitle">Where this concept appears in code and docs.</p>
 
-      {#each groupedReferences as group}
-        {@const repoUrl = repositoryUrls[group.repository] || null}
-        {@const allPaths = group.referenceGroups.flatMap(rg => rg.paths)}
-        {@const isExpanded = expandedGroups.has(group.repository)}
-        {@const visibleRefGroups = (() => {
-          if (isExpanded) return group.referenceGroups;
-          let pathCount = 0;
-          const visible = [];
-          for (const refGroup of group.referenceGroups) {
-            if (pathCount + refGroup.paths.length <= DEFAULT_VISIBLE_PATHS) {
-              visible.push(refGroup);
-              pathCount += refGroup.paths.length;
-            } else {
-              break;
-            }
-          }
-          return visible;
-        })()}
-        {@const hiddenCount = allPaths.length - visibleRefGroups.reduce((sum, rg) => sum + rg.paths.length, 0)}
-
-        <div class="reference-group">
-          {#if repoUrl}
-            <a class="reference-repo-pill" href={repoUrl} target="_blank" rel="noopener noreferrer">
-              <span class="reference-repo-label">repo</span>
-              <span class="reference-repo-name">{group.repository}</span>
-            </a>
-          {:else}
-            <div class="reference-repo-pill reference-repo-pill--no-link">
-              <span class="reference-repo-label">repo</span>
-              <span class="reference-repo-name">{group.repository}</span>
-            </div>
-          {/if}
-          
-          <ul class="reference-paths-list">
-            {#each visibleRefGroups as refGroup, refGroupIndex}
-              {#each refGroup.paths as pathEntry, pathIndex}
-                {@const path = pathEntry.path}
-                {@const url = getPathUrl(group.repository, path)}
-                {@const isWildcard = isWildcardPath(path)}
-                {@const isLastInRefGroup = pathIndex === refGroup.paths.length - 1}
-                {@const isFirstInRefGroup = pathIndex === 0}
-                {@const isFirstRefGroup = refGroupIndex === 0}
-                <li class="reference-path-item" class:reference-path-item--tight={!isLastInRefGroup} class:reference-path-item--spaced={isFirstInRefGroup && !isFirstRefGroup}>
-                  {#if url}
-                    <a class="reference-path-link sprig-link sprig-link--quiet" href={url} target="_blank" rel="noopener noreferrer">
-                      <span class="reference-path-text">{path}</span>
-                      {#if isWildcard}
-                        <span class="reference-path-wildcard">(pattern)</span>
-                      {/if}
-                    </a>
-                  {:else}
-                    <span class="reference-path-text">{path}</span>
-                    {#if isWildcard}
-                      <span class="reference-path-wildcard">(pattern)</span>
+      <ul class="reference-list">
+        {#each referenceGroups as group}
+          <li class="reference-item">
+            {#if group.repo}
+              <a
+                class="reference-repo-pill sprig-link"
+                href={group.repo.url}
+                target="_blank"
+                rel="noopener noreferrer"
+              >
+                {group.repo.title || group.repo.name}
+              </a>
+            {/if}
+            <ul class="reference-group-list">
+              {#each group.refs as ref}
+                <li class="reference-group-item">
+                  {#if ref.urls && ref.urls.length > 0}
+                    {#if ref.urls.length === 1}
+                      {@const label = makeLinkLabel(ref.urls[0], ref.paths?.[0])}
+                      <div class="reference-row">
+                        <a class="reference-path-link sprig-link" href={ref.urls[0]} target="_blank" rel="noopener noreferrer">
+                          {label}
+                        </a>
+                        {#if ref.kind}
+                          <span class="reference-kind">{ref.kind}</span>
+                        {/if}
+                      </div>
+                    {:else}
+                      <ul class="reference-links-list">
+                        {#each ref.urls as url, index}
+                          {@const label = makeLinkLabel(url, ref.paths?.[index])}
+                          <li class="reference-links-item">
+                            <div class="reference-row">
+                              <a class="reference-path-link sprig-link" href={url} target="_blank" rel="noopener noreferrer">
+                                {label}
+                              </a>
+                              {#if ref.kind && index === 0}
+                                <span class="reference-kind">{ref.kind}</span>
+                              {/if}
+                            </div>
+                          </li>
+                        {/each}
+                      </ul>
                     {/if}
                   {/if}
-                  {#if pathEntry.perPathDescribe?.normalized}
-                    <p class="reference-description reference-description--per-path">{pathEntry.perPathDescribe.normalized}</p>
+                  {#if ref.describe?.normalized}
+                    <p class="reference-description">{ref.describe.normalized}</p>
+                  {/if}
+                  {#if ref.note?.normalized}
+                    <p class="reference-note">{ref.note.normalized}</p>
                   {/if}
                 </li>
               {/each}
-              {#if refGroup.groupDescribe}
-                <li class="reference-path-item reference-path-item--describe">
-                  <p class="reference-description reference-description--group">{refGroup.groupDescribe}</p>
-                </li>
-              {/if}
-            {/each}
-          </ul>
-          
-          {#if hiddenCount > 0 && !isExpanded}
-            <button
-              class="reference-expand-button"
-              on:click={() => toggleGroup(group.repository)}
-              type="button"
-            >
-              + {hiddenCount} more path{hiddenCount === 1 ? '' : 's'}
-            </button>
-          {/if}
-          {#if isExpanded && hiddenCount > 0}
-            <button
-              class="reference-expand-button"
-              on:click={() => toggleGroup(group.repository)}
-              type="button"
-            >
-              Show less
-            </button>
-          {/if}
-        </div>
-      {/each}
+            </ul>
+          </li>
+        {/each}
+      </ul>
     </section>
   {/if}
 
@@ -450,13 +333,13 @@
 
   .relationship-label {
     font-family: var(--font-ui);
-    font-size: var(--sp-font-tiny);
+    font-size: var(--sp-font-small);
     color: var(--text-secondary);
   }
 
   .relationship-separator {
     font-family: var(--font-ui);
-    font-size: var(--sp-font-tiny);
+    font-size: var(--sp-font-small);
     color: var(--text-tertiary);
     opacity: 0.6;
   }
@@ -510,101 +393,59 @@
     margin: 0 0 1.5rem 0;
   }
 
-  .reference-group {
+  .reference-list {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+  }
+
+  .reference-item {
     margin-bottom: 2rem;
   }
 
-  .reference-group:last-child {
+  .reference-item:last-child {
     margin-bottom: 0;
   }
 
+
   .reference-repo-pill {
     display: inline-flex;
     align-items: center;
     gap: 6px;
-    padding: 4px 10px;
-    background: var(--card-bg);
-    border-radius: 6px;
-    text-decoration: none;
-    color: inherit;
-    margin-bottom: 0.75rem;
-    transition: opacity 0.2s;
-  }
-
-  .reference-repo-pill:hover {
-    opacity: 0.8;
-  }
-
-  .reference-repo-pill--no-link {
-    cursor: default;
-  }
-
-  .reference-repo-pill--no-link:hover {
-    opacity: 1;
-  }
-
-  .reference-repo-label {
+    padding: 2px 10px;
+    border-radius: 999px;
     font-family: var(--font-ui);
-    font-size: var(--sp-font-tiny);
-    letter-spacing: 0.05em;
+    font-size: var(--sp-font-small);
     text-transform: lowercase;
     color: var(--text-tertiary);
-    font-weight: 400;
-  }
-
-  .reference-repo-name {
-    font-family: var(--font-ui);
-    font-size: var(--sp-font-tiny);
-    color: var(--text-secondary);
-    font-weight: 400;
-  }
-
-  .reference-paths-list {
-    list-style: none;
-    padding: 0;
-    margin: 0;
-  }
-
-  .reference-path-item {
-    margin-bottom: 0.75rem;
-  }
-
-  .reference-path-item:last-child {
-    margin-bottom: 0;
-  }
-
-  .reference-path-item--tight {
-    margin-bottom: 0.25rem;
-  }
-
-  .reference-path-item--spaced {
-    margin-top: 0.75rem;
-  }
-
-  .reference-path-item--describe {
-    margin-top: 0.5rem;
-    margin-bottom: 0.75rem;
+    border: 1px solid var(--hairline);
+    margin-bottom: 1rem;
+    text-decoration: none;
   }
 
   .reference-path-link {
     display: block;
-    padding: 4px 0;
-  }
-
-  .reference-path-text {
+    margin-top: 2px;
     font-family: ui-monospace, 'SF Mono', Monaco, 'Cascadia Code', 'Roboto Mono', Consolas, 'Courier New', monospace;
     font-size: var(--sp-font-body);
     color: inherit;
-    font-variant-numeric: tabular-nums;
-    letter-spacing: 0.01em;
+    text-decoration: underline;
+    text-decoration-thickness: 1px;
+    text-underline-offset: 0.1875rem;
+    text-decoration-color: var(--sprig-link-underline);
   }
 
-  .reference-path-wildcard {
+  .reference-row {
+    display: flex;
+    align-items: baseline;
+    gap: 8px;
+  }
+
+  .reference-kind {
+    margin-left: auto;
     font-family: var(--font-ui);
-    font-size: var(--sp-font-tiny);
+    font-size: var(--sp-font-small);
     color: var(--text-tertiary);
-    margin-left: 4px;
-    font-weight: 400;
   }
 
   .reference-description {
@@ -616,29 +457,37 @@
     max-width: 70ch;
   }
 
-  .reference-description--per-path {
-    margin-top: 6px;
+  .reference-note {
+    margin: 6px 0 0 0;
+    font-family: var(--font-prose);
+    font-size: var(--sp-font-body);
+    color: var(--text-secondary);
+    line-height: 1.5;
+    max-width: 70ch;
+  }
+
+  .reference-links-list {
+    list-style: none;
+    padding: 0;
+    margin: 8px 0 0 0;
   }
 
-  .reference-description--group {
+  .reference-group-list {
+    list-style: none;
+    padding: 0;
     margin: 0;
   }
 
-  .reference-expand-button {
-    background: none;
-    border: none;
-    color: var(--text-tertiary);
-    font-family: var(--font-ui);
-    font-size: var(--sp-font-tiny);
-    padding: 4px 0;
-    margin-top: 0.5rem;
-    cursor: pointer;
-    text-decoration: underline;
-    text-underline-offset: 2px;
+  .reference-group-item + .reference-group-item {
+    margin-top: 2rem;
   }
 
-  .reference-expand-button:hover {
-    opacity: 0.8;
+  .reference-links-item {
+    margin-bottom: 6px;
+  }
+
+  .reference-links-item:last-child {
+    margin-bottom: 0;
   }
 
   @media (max-width: 768px) {
@@ -655,3 +504,4 @@
   }
 </style>
 
+

package/src/lib/references/isWildcardPath.js

@@ -1,9 +0,0 @@
-/**
- * Checks if a path contains a wildcard pattern
- * @param {string} path - File path to check
- * @returns {boolean} - True if path contains '*'
- */
-export function isWildcardPath(path) {
-  return typeof path === 'string' && path.includes('*');
-}
-

package/src/lib/references/linkForPath.js

@@ -1,65 +0,0 @@
-import { get } from 'svelte/store';
-import { universeGraph } from '../data/universeStore.js';
-import { isWildcardPath } from './isWildcardPath.js';
-
-/**
- * Builds a URL for a file path in a repository
- * @param {string} repository - Repository key (e.g., "amaranthine")
- * @param {string} path - File path (e.g., "/backends/api/src/routers/players.js" or "/data/actions/*.yaml")
- * @returns {string | null} - Full URL to the file/folder, or null if repository is unconfigured
- */
-export function linkForPath(repository, path) {
-  const graph = get(universeGraph);
-  if (!graph?.repositories) {
-    return null;
-  }
-
-  const repoConfig = graph.repositories[repository];
-  if (!repoConfig) {
-    return null;
-  }
-
-  const { kind, options } = repoConfig;
-  const defaultBranch = options?.defaultBranch || 'main';
-
-  // Handle GitHub repositories
-  if (kind === 'sprig-repository-github') {
-    // Prefer url if available, otherwise build from owner/repo
-    let baseUrl;
-    if (options?.url) {
-      baseUrl = options.url;
-    } else {
-      const owner = options?.owner;
-      const repo = options?.repo;
-      if (!owner || !repo) {
-        return null;
-      }
-      baseUrl = `https://github.com/${owner}/${repo}`;
-    }
-
-    const normalizedBaseUrl = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
-
-    // Ensure path begins with /
-    const normalizedPath = path.startsWith('/') ? path : `/${path}`;
-
-    // Handle wildcard paths - link to folder view
-    if (isWildcardPath(path)) {
-      // Derive folder by taking everything up to the last '/'
-      // e.g., "/data/actions/*.yaml" -> "/data/actions"
-      const lastSlashIndex = normalizedPath.lastIndexOf('/');
-      if (lastSlashIndex > 0) {
-        const folderPath = normalizedPath.slice(0, lastSlashIndex);
-        // Build GitHub tree URL: baseUrl/tree/branch/folder
-        return `${normalizedBaseUrl}/tree/${defaultBranch}${folderPath}`;
-      }
-      // Fallback: if no slash, link to repo root
-      return `${normalizedBaseUrl}/tree/${defaultBranch}`;
-    }
-
-    // Build GitHub blob URL: baseUrl/blob/branch/path
-    return `${normalizedBaseUrl}/blob/${defaultBranch}${normalizedPath}`;
-  }
-
-  return null;
-}
-

package/src/lib/references/linkForRepository.js

@@ -1,42 +0,0 @@
-import { get } from 'svelte/store';
-import { universeGraph } from '../data/universeStore.js';
-
-/**
- * Builds a URL for a repository root
- * @param {string} repository - Repository key (e.g., "amaranthine")
- * @returns {string | null} - Full URL to the repository root, or null if repository is unconfigured
- */
-export function linkForRepository(repository) {
-  const graph = get(universeGraph);
-  if (!graph?.repositories) {
-    return null;
-  }
-
-  const repoConfig = graph.repositories[repository];
-  if (!repoConfig) {
-    return null;
-  }
-
-  const { kind, options } = repoConfig;
-
-  // Handle GitHub repositories
-  if (kind === 'sprig-repository-github') {
-    // Prefer url if available, otherwise build from owner/repo
-    if (options?.url) {
-      const baseUrl = options.url;
-      // Remove trailing slash if present
-      return baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
-    }
-    
-    const owner = options?.owner;
-    const repo = options?.repo;
-    if (owner && repo) {
-      const baseUrl = `https://github.com/${owner}/${repo}`;
-      // Remove trailing slash if present
-      return baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
-    }
-  }
-
-  return null;
-}
-