@sprig-and-prose/sprig-ui 0.1.0

package/src/lib/data/universeStore.js

@@ -0,0 +1,350 @@
+import { writable, derived, get } from 'svelte/store';
+
+/**
+ * @typedef {{ id:string, name:string, title?:string, kind:string, spelledKind?:string, parent:string|null, children:string[], describe?:{raw:string, normalized:string}, dimension?:string, relationships?:Array<{edge:string, relationship?:string, to:string}> }} NodeModel
+ * @typedef {{ id:string, name:string, root:string }} UniverseModel
+ * @typedef {{ universes:Record<string, UniverseModel>, nodes:Record<string, NodeModel>, relationshipsById:Record<string, any>, relatesById:Record<string, any>, generatedAt?:string, meta?:any }} UniverseGraph
+ */
+
+export const universeGraph = writable(/** @type {UniverseGraph|null} */ (null));
+export const currentUniverseName = writable(/** @type {string|null} */ (null));
+
+const KIND_PRIORITY = ['concept', 'dimension', 'relationship', 'relates'];
+
+function normalizeTextBlock(value) {
+  if (!value) return undefined;
+  if (typeof value === 'string') {
+    return { raw: value, normalized: value };
+  }
+  if (typeof value === 'object' && typeof value.raw === 'string') {
+    return {
+      raw: value.raw,
+      normalized: typeof value.normalized === 'string' ? value.normalized : value.raw,
+    };
+  }
+  return undefined;
+}
+
+function normalizeTitle(value) {
+  if (!value) return undefined;
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+  }
+  if (typeof value === 'object' && typeof value.raw === 'string') {
+    const trimmed = value.raw.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+  }
+  return undefined;
+}
+
+function endpointDisplayName(endpointId, conceptById) {
+  const concept = conceptById?.[endpointId];
+  if (concept?.name) return concept.name;
+  return endpointId;
+}
+
+function formatRelationshipLabel(label) {
+  if (!label) return '';
+  return String(label)
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[_-]+/g, ' ')
+    .toLowerCase()
+    .trim();
+}
+
+function sortByKindAndName(a, b) {
+  const kindDiff = KIND_PRIORITY.indexOf(a.kind) - KIND_PRIORITY.indexOf(b.kind);
+  if (kindDiff !== 0) return kindDiff;
+  return a.name.localeCompare(b.name);
+}
+
+/**
+ * @param {NodeModel[]} children
+ * @returns {{ primary: NodeModel[], other: NodeModel[] }}
+ */
+export function organizeChildren(children) {
+  const valid = children.filter(Boolean);
+  if (valid.length === 0) return { primary: [], other: [] };
+  const primaryKind = valid[0].kind;
+  return {
+    primary: valid.filter((child) => child.kind === primaryKind),
+    other: valid.filter((child) => child.kind !== primaryKind),
+  };
+}
+
+/**
+ * Build a generic parent/child tree by nearest existing id prefix.
+ * @param {Record<string, NodeModel>} nodes
+ * @param {string} universeId
+ */
+function connectTree(nodes, universeId) {
+  const root = nodes[universeId];
+  if (!root) return;
+
+  const ids = Object.keys(nodes);
+  for (const id of ids) {
+    const node = nodes[id];
+    if (!node || id === universeId) continue;
+    const parts = id.split('.');
+    let parentId = universeId;
+    for (let i = parts.length - 1; i > 1; i -= 1) {
+      const candidate = parts.slice(0, i).join('.');
+      if (nodes[candidate]) {
+        parentId = candidate;
+        break;
+      }
+    }
+    node.parent = parentId;
+    nodes[parentId].children.push(id);
+  }
+
+}
+
+/**
+ * @param {Record<string, any>} relationshipsById
+ * @param {string | undefined} relId
+ * @param {string} edge
+ */
+function relationshipLabel(relationshipsById, relId, edge) {
+  const rel = relId ? relationshipsById[relId] : null;
+  if (!rel) return formatRelationshipLabel(edge);
+  if (rel.forward === edge || rel.inverse === edge) {
+    return formatRelationshipLabel(edge);
+  }
+  return formatRelationshipLabel(rel.forward || rel.inverse || edge);
+}
+
+/**
+ * @param {any} manifest
+ * @returns {UniverseGraph}
+ */
+function normalizeLanguageManifest(manifest) {
+  const universeId = manifest?.universe?.id || manifest?.universe?.name;
+  if (!universeId) {
+    throw new Error('Invalid manifest: missing universe.id');
+  }
+
+  /** @type {Record<string, NodeModel>} */
+  const nodes = {};
+  nodes[universeId] = {
+    id: universeId,
+    name: manifest.universe.name || universeId,
+    title: normalizeTitle(manifest.universe.title),
+    kind: 'universe',
+    parent: null,
+    children: [],
+    describe: normalizeTextBlock(manifest.universe.describe),
+  };
+
+  for (const concept of Object.values(manifest?.concepts || {})) {
+    nodes[concept.id] = {
+      id: concept.id,
+      name: concept.name || concept.id,
+      title: normalizeTitle(concept.title),
+      kind: 'concept',
+      spelledKind: concept.dimension ? concept.dimension.split('.').pop() : 'concept',
+      parent: null,
+      children: [],
+      describe: normalizeTextBlock(concept.describe),
+      dimension: concept.dimension,
+      relationships: Array.isArray(concept.relationships) ? concept.relationships : [],
+    };
+  }
+
+  for (const dim of Object.values(manifest?.dimensions || {})) {
+    nodes[dim.id] = {
+      id: dim.id,
+      name: dim.name || dim.id,
+      title: normalizeTitle(dim.title),
+      kind: 'dimension',
+      spelledKind: 'dimension',
+      parent: null,
+      children: [],
+      describe: normalizeTextBlock(dim.describe),
+      relationships: [],
+    };
+  }
+
+  for (const rel of Object.values(manifest?.relationships || {})) {
+    const forward = formatRelationshipLabel(rel.forward || '');
+    const inverse = formatRelationshipLabel(rel.inverse || '');
+    const relationshipName = inverse
+      ? `${forward} and ${inverse}`
+      : forward || rel.id;
+
+    nodes[rel.id] = {
+      id: rel.id,
+      name: relationshipName,
+      title: normalizeTitle(rel.title),
+      kind: 'relationship',
+      spelledKind: 'relationship',
+      parent: null,
+      children: [],
+      describe: normalizeTextBlock(rel.describe),
+      relationships: [],
+    };
+  }
+
+  for (const rel of Object.values(manifest?.relates || {})) {
+    const leftName = endpointDisplayName(rel.left, manifest?.concepts);
+    const rightName = endpointDisplayName(rel.right, manifest?.concepts);
+
+    nodes[rel.id] = {
+      id: rel.id,
+      name: `${leftName} and ${rightName}`,
+      title: normalizeTitle(rel.title),
+      kind: 'relates',
+      spelledKind: 'relates',
+      parent: universeId,
+      children: [],
+      describe: normalizeTextBlock(rel.describe),
+      relationships: Array.isArray(rel.relationships) ? rel.relationships : [],
+    };
+  }
+
+  connectTree(nodes, universeId);
+
+  return {
+    universes: {
+      [universeId]: {
+        id: universeId,
+        name: manifest.universe.name || universeId,
+        root: universeId,
+      },
+    },
+    nodes,
+    relationshipsById: manifest.relationships || {},
+    relatesById: manifest.relates || {},
+    generatedAt: manifest.generatedAt,
+    meta: manifest.meta,
+  };
+}
+
+export const currentUniverse = derived([universeGraph, currentUniverseName], ([$g, $name]) =>
+  $name ? $g?.universes?.[$name] ?? null : null,
+);
+
+export const universeRootNode = derived([universeGraph, currentUniverse], ([$g, $u]) =>
+  $u && $g ? $g.nodes[$u.root] : null,
+);
+
+export const rootChildren = derived([universeGraph, universeRootNode], ([$g, $root]) => {
+  if (!$g || !$root) return { primary: [], other: [] };
+  const children = ($root.children || []).map((id) => $g.nodes[id]).filter(Boolean);
+  return organizeChildren(children);
+});
+
+/**
+ * @param {UniverseGraph | null} graph
+ * @param {string | null} currentNodeId
+ * @returns {Array<{ otherNode: NodeModel, label: string, desc: string | null }>}
+ */
+export function getRelationshipsForNode(graph, currentNodeId) {
+  if (!graph || !currentNodeId) return [];
+  const node = graph.nodes[currentNodeId];
+  if (!node) return [];
+
+  /** @type {Array<{ otherNode: NodeModel, label: string, desc: string | null }>} */
+  const items = [];
+  const seen = new Set();
+
+  /**
+   * @param {string} otherNodeId
+   * @param {string} label
+   * @param {string | null} desc
+   */
+  function pushRelationship(otherNodeId, label, desc) {
+    const otherNode = graph.nodes[otherNodeId];
+    if (!otherNode) return;
+    const key = `${otherNodeId}|${label}|${desc || ''}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    items.push({ otherNode, label, desc });
+  }
+
+  for (const rel of node.relationships || []) {
+    const decl = rel.relationship ? graph.relationshipsById[rel.relationship] : null;
+    pushRelationship(
+      rel.to,
+      relationshipLabel(graph.relationshipsById, rel.relationship, rel.edge),
+      normalizeTextBlock(decl?.describe)?.normalized || null,
+    );
+  }
+
+  for (const rel of Object.values(graph.relatesById || {})) {
+    const isLeft = rel.left === currentNodeId;
+    const isRight = rel.right === currentNodeId;
+    if (!isLeft && !isRight) continue;
+    const otherId = isLeft ? rel.right : rel.left;
+    const otherNode = graph.nodes[otherId];
+    if (!otherNode) continue;
+    const firstRel = Array.isArray(rel.relationships) ? rel.relationships[0] : null;
+    pushRelationship(
+      otherId,
+      formatRelationshipLabel(firstRel?.edge || 'relatesTo'),
+      normalizeTextBlock(rel.describe)?.normalized || null,
+    );
+  }
+
+  return items;
+}
+
+/**
+ * @param {UniverseGraph | null} graph
+ * @param {NodeModel | null} node
+ * @returns {NodeModel[]}
+ */
+export function getAncestorChain(graph, node) {
+  if (!graph || !node?.parent) return [];
+  const ancestors = [];
+  let cursor = node.parent;
+  while (cursor) {
+    const parent = graph.nodes[cursor];
+    if (!parent) break;
+    ancestors.push(parent);
+    cursor = parent.parent;
+  }
+  return ancestors;
+}
+
+/**
+ * @param {NodeModel | null | undefined} node
+ * @returns {string}
+ */
+export function getNodeRoute(node) {
+  if (!node?.id) return '#';
+  const universeId = node.id.split('.')[0];
+  if (!universeId) return '#';
+  return `/universes/${encodeURIComponent(universeId)}/node/${encodeURIComponent(node.id)}`;
+}
+
+/**
+ * @param {UniverseGraph} graph
+ */
+export function autoSelectFirstUniverse(graph) {
+  if (!graph?.universes) return;
+  const universeNames = Object.keys(graph.universes);
+  const currentName = get(currentUniverseName);
+  if (!currentName || !graph.universes[currentName]) {
+    currentUniverseName.set(universeNames[0] || null);
+  }
+}
+
+/**
+ * @param {string} url
+ * @param {typeof fetch} [fetchFn]
+ */
+export async function loadUniverseGraph(url = '/api/manifest', fetchFn = fetch) {
+  const res = await fetchFn(url, {
+    cache: 'no-store',
+    headers: { 'Cache-Control': 'no-cache' },
+  });
+  if (!res.ok) throw new Error(`Failed to load ${url}: ${res.status}`);
+  const raw = await res.json();
+  const data = normalizeLanguageManifest(raw);
+  universeGraph.set(data);
+  const describeRenderMode = res.headers.get('x-describe-render-mode');
+  return { data, describeRenderMode };
+}
+

package/src/lib/format/kind.js

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Helpers for displaying declaration kinds
+ */
+
+/**
+ * @param {{ kind?: string, spelledKind?: string } | null | undefined} node
+ * @returns {string}
+ */
+export function getDisplayKind(node) {
+  if (!node) return '';
+  const spelled = typeof node.spelledKind === 'string' ? node.spelledKind.trim() : '';
+  if (spelled.length > 0) return formatKindLabel(spelled);
+  return typeof node.kind === 'string' ? node.kind : '';
+}
+
+/**
+ * @param {string} label
+ * @returns {string}
+ */
+function formatKindLabel(label) {
+  if (!/[a-z][A-Z]/.test(label)) {
+    return label;
+  }
+  return label.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase();
+}
+

package/src/lib/format/title.js

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview Utility for deriving human-friendly display titles from node identifiers
+ */
+
+/**
+ * Derives a human-friendly display title from a node or identifier string.
+ * 
+ * @param {any} nodeOrId - Node object with optional `title`, `name`, `id`, `slug`, or `identifier` fields, or a string identifier
+ * @param {{}} [options] - Optional configuration (currently unused, reserved for future use)
+ * @returns {string} Human-friendly display title, or empty string if no usable identifier found
+ * 
+ * @example
+ * getDisplayTitle({ title: "Custom Title" }) // "Custom Title"
+ * getDisplayTitle({ name: "CountBasedEffect" }) // "Count Based Effect"
+ * getDisplayTitle({ name: "APIResponse" }) // "API Response"
+ * getDisplayTitle({ name: "effect_type" }) // "Effect Type"
+ * getDisplayTitle("PlayerID") // "Player ID"
+ */
+export function getDisplayTitle(nodeOrId, options = {}) {
+  // Handle explicit title override
+  if (nodeOrId && typeof nodeOrId === 'object' && typeof nodeOrId.title === 'string') {
+    const title = nodeOrId.title.trim();
+    if (title.length > 0) {
+      return title;
+    }
+  }
+
+  // Extract identifier string
+  let identifier = null;
+  
+  if (typeof nodeOrId === 'string') {
+    identifier = nodeOrId;
+  } else if (nodeOrId && typeof nodeOrId === 'object') {
+    // Check in order: name, id, slug, identifier
+    identifier = nodeOrId.name || nodeOrId.id || nodeOrId.slug || nodeOrId.identifier || null;
+  }
+
+  if (!identifier || typeof identifier !== 'string' || identifier.trim().length === 0) {
+    return '';
+  }
+
+  // Derive title from identifier
+  return deriveTitleFromIdentifier(identifier);
+}
+
+/**
+ * Derives a human-friendly title from an identifier string.
+ * Handles PascalCase, camelCase, snake_case, kebab-case, and preserves acronyms.
+ * 
+ * @param {string} identifier - The identifier string to convert
+ * @returns {string} Human-friendly title
+ * 
+ * @private
+ */
+function deriveTitleFromIdentifier(identifier) {
+  // Normalize: replace underscores and hyphens with spaces
+  let normalized = identifier
+    .replace(/[_-]/g, ' ')
+    .trim();
+
+  // Split on case boundaries (PascalCase/camelCase)
+  // This regex finds positions where:
+  // - A lowercase letter is followed by an uppercase letter (camelCase boundary)
+  // - An uppercase letter is followed by an uppercase letter followed by a lowercase letter (PascalCase boundary like "APIResponse")
+  // - A digit is followed by a letter or vice versa
+  normalized = normalized.replace(/([a-z])([A-Z])/g, '$1 $2'); // camelCase: "countBased" -> "count Based"
+  normalized = normalized.replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2'); // PascalCase acronyms: "APIResponse" -> "API Response"
+  normalized = normalized.replace(/([0-9])([A-Za-z])/g, '$1 $2'); // Numbers: "Item2" -> "Item 2"
+  normalized = normalized.replace(/([A-Za-z])([0-9])/g, '$1 $2'); // Numbers: "Item2" -> "Item 2"
+
+  // Split into words and process each
+  const words = normalized
+    .split(/\s+/)
+    .filter(word => word.length > 0)
+    .map(word => {
+      // Detect acronyms: 2+ consecutive uppercase letters
+      // Only preserve as acronym if it's a known common acronym
+      // This handles cases like "APIResponse" -> "API Response" but "SIMPLE" -> "Simple"
+      const isAcronymPattern = word.length >= 2 && word === word.toUpperCase() && /^[A-Z]+$/.test(word);
+      
+      // Common acronyms that should be preserved: API, UUID, ID, HTTP, HTTPS, XML, JSON, etc.
+      const commonAcronyms = ['API', 'UUID', 'ID', 'HTTP', 'HTTPS', 'XML', 'JSON', 'URL', 'URI', 'HTML', 'CSS', 'JS', 'TS', 'AB'];
+      if (isAcronymPattern && commonAcronyms.includes(word)) {
+        // It's a known acronym, preserve as-is
+        return word;
+      }
+      
+      // Title-case the word: first letter uppercase, rest lowercase
+      if (word.length === 0) return word;
+      if (word.length === 1) return word.toUpperCase();
+      return word[0].toUpperCase() + word.slice(1).toLowerCase();
+    });
+
+  // Join words with single spaces and collapse multiple spaces
+  return words.join(' ').replace(/\s+/g, ' ').trim();
+}
+

package/src/lib/router.js

@@ -0,0 +1,39 @@
+/**
+ * Parse a route and extract parameters
+ * @param {string} pathname
+ * @returns {{ route: string, params: Record<string, string> } | null}
+ */
+export function parseRoute(pathname) {
+  const path = pathname.replace(/^\/+|\/+$/g, '');
+
+  if (!path || path === '') {
+    return { route: 'home', params: {} };
+  }
+
+  const nodeMatch = path.match(/^universes\/([^/]+)\/node\/(.+)$/);
+  if (nodeMatch) {
+    return {
+      route: 'node',
+      params: {
+        universe: decodeURIComponent(nodeMatch[1]),
+        id: nodeMatch[2],
+      },
+    };
+  }
+
+  return null;
+}
+
+/**
+ * Get current route from window.location
+ * @returns {{ route: string, params: Record<string, string> } | null}
+ */
+export function getCurrentRoute() {
+  return parseRoute(window.location.pathname);
+}
+
+export function navigate(path) {
+  window.history.pushState({}, '', path);
+  window.dispatchEvent(new PopStateEvent('popstate'));
+}
+

package/src/lib/stores/describeRenderMode.js

@@ -0,0 +1,9 @@
+import { writable } from 'svelte/store';
+
+/**
+ * Store for describe block rendering mode.
+ * Values: 'plain' | 'lists'
+ * Default: 'lists'
+ */
+export const describeRenderMode = writable(/** @type {'plain' | 'lists'} */ ('lists'));
+

package/src/lib/stores/theme.js

@@ -0,0 +1,98 @@
+import { writable } from 'svelte/store';
+
+/**
+ * Get system preference for color scheme
+ * @returns {'light' | 'dark'}
+ */
+function getSystemPreference() {
+  if (typeof window === 'undefined') return 'light';
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+
+/**
+ * Get initial theme: manual preference from localStorage, or system preference
+ * @returns {'light' | 'dark' | 'auto'}
+ */
+function getInitialTheme() {
+  if (typeof localStorage === 'undefined') return 'auto';
+  const stored = localStorage.getItem('theme');
+  if (stored === 'light' || stored === 'dark') return stored;
+  return 'auto'; // 'auto' means use system preference
+}
+
+/**
+ * Get effective theme (resolves 'auto' to system preference)
+ * @param {'light' | 'dark' | 'auto'} theme
+ * @returns {'light' | 'dark'}
+ */
+function getEffectiveTheme(theme) {
+  if (theme === 'auto') {
+    return getSystemPreference();
+  }
+  return theme;
+}
+
+const initial = getInitialTheme();
+export const theme = writable(initial);
+
+// Apply theme to document
+function applyTheme(themeValue) {
+  if (typeof document === 'undefined') return;
+  const effective = getEffectiveTheme(themeValue);
+  document.documentElement.dataset.theme = effective;
+}
+
+// Listen for system preference changes when theme is 'auto'
+let mediaQuery = null;
+let mediaQueryListener = null;
+
+function setupSystemPreferenceListener() {
+  if (typeof window === 'undefined') return;
+  if (mediaQuery) return; // Already set up
+  
+  mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+  mediaQueryListener = () => {
+    // Re-read current theme value and reapply if it's 'auto'
+    const unsubscribe = theme.subscribe((t) => {
+      unsubscribe(); // Immediately unsubscribe to avoid memory leak
+      if (t === 'auto') {
+        applyTheme('auto');
+      }
+    });
+  };
+  mediaQuery.addEventListener('change', mediaQueryListener);
+}
+
+function cleanupSystemPreferenceListener() {
+  if (mediaQuery && mediaQueryListener) {
+    mediaQuery.removeEventListener('change', mediaQueryListener);
+    mediaQuery = null;
+    mediaQueryListener = null;
+  }
+}
+
+// Subscribe to theme changes
+let currentThemeValue = initial;
+theme.subscribe((t) => {
+  currentThemeValue = t;
+  applyTheme(t);
+  if (typeof localStorage !== 'undefined') {
+    localStorage.setItem('theme', t);
+  }
+  
+  // Setup/cleanup system preference listener based on theme
+  if (t === 'auto') {
+    setupSystemPreferenceListener();
+  } else {
+    cleanupSystemPreferenceListener();
+  }
+});
+
+// Initialize: apply theme and setup listener if needed
+if (typeof window !== 'undefined') {
+  applyTheme(initial);
+  if (initial === 'auto') {
+    setupSystemPreferenceListener();
+  }
+}
+