@emeryld/rrroutes-contract 2.7.3 → 2.7.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@emeryld/rrroutes-contract",
   "description": "TypeScript contract definitions for RRRoutes",
-  "version": "2.7.3",
+  "version": "2.7.4",
   "private": false,
   "type": "module",
   "main": "dist/index.cjs",

package/tools/finalized-leaves-viewer.html

@@ -6,14 +6,15 @@
     <title>Finalized Leaves Viewer</title>
     <style>
       :root {
-        --bg: #f5f7fb;
+        --bg: #f6f8fc;
         --surface: #ffffff;
-        --surface-2: #f8faff;
-        --border: #d6ddea;
-        --text: #172033;
-        --muted: #5b6680;
+        --surface-2: #f1f4f9;
+        --border: #d9e0eb;
+        --text: #182033;
+        --muted: #64708b;
         --accent: #1858c6;
         --ok: #1f8f4e;
+        --danger: #d12b2b;
       }
 
       * {
@@ -24,8 +25,7 @@
         margin: 0;
         font-family: 'Iosevka Web', 'SFMono-Regular', Menlo, Consolas, monospace;
         color: var(--text);
-        background: radial-gradient(circle at top right, #eaf0ff, transparent 45%),
-          linear-gradient(180deg, var(--bg), #eef2fa);
+        background: var(--bg);
       }
 
       mark {
@@ -43,9 +43,9 @@
 
       .card {
         background: var(--surface);
-        border: 1px solid var(--border);
-        border-radius: 12px;
-        padding: 14px;
+        border: 1px solid #e7ecf4;
+        border-radius: 6px;
+        padding: 12px;
       }
 
       .controls {
@@ -59,22 +59,41 @@
         gap: 8px;
       }
 
+      .field-actions {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 8px;
+      }
+
       .field-item {
         display: inline-flex;
         align-items: center;
         gap: 6px;
-        padding: 4px 8px;
-        border: 1px solid var(--border);
-        border-radius: 8px;
-        background: var(--surface-2);
+        padding: 3px 0;
       }
 
-      input[type='text'] {
+      input[type='text'],
+      select {
         width: 100%;
         border: 1px solid var(--border);
-        border-radius: 8px;
-        padding: 10px 12px;
+        border-radius: 4px;
+        padding: 8px 10px;
+        font: inherit;
+        background: #fff;
+      }
+
+      button {
+        border: 1px solid var(--border);
+        border-radius: 4px;
+        padding: 7px 10px;
         font: inherit;
+        background: #fff;
+        color: var(--text);
+        cursor: pointer;
+      }
+
+      button:hover {
+        background: var(--surface-2);
       }
 
       .meta {
@@ -85,14 +104,12 @@
       #results {
         margin-top: 14px;
         display: grid;
-        gap: 10px;
+        gap: 0;
       }
 
       details.leaf {
-        background: var(--surface);
-        border: 1px solid var(--border);
-        border-radius: 10px;
-        padding: 8px 10px;
+        border-top: 1px solid var(--border);
+        padding: 10px 2px;
       }
 
       summary {
@@ -103,15 +120,13 @@
 
       .leaf-content {
         display: grid;
-        gap: 10px;
+        gap: 4px;
         margin-top: 10px;
       }
 
       .section {
-        border: 1px solid var(--border);
-        border-radius: 8px;
-        padding: 10px;
-        background: #fbfcff;
+        border-top: 1px solid #e8edf5;
+        padding: 10px 0 2px;
       }
 
       .section h3 {
@@ -121,15 +136,13 @@
 
       .grid-2 {
         display: grid;
-        gap: 8px;
+        gap: 6px;
         grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
       }
 
       .kv {
-        border: 1px solid var(--border);
-        border-radius: 6px;
-        padding: 6px 8px;
-        background: white;
+        border-bottom: 1px dashed #e2e8f2;
+        padding: 4px 0 6px;
       }
 
       .kv .k {
@@ -148,12 +161,16 @@
         flex-wrap: wrap;
       }
 
+      .chips.filters {
+        margin-top: 2px;
+      }
+
       .chip {
-        border: 1px solid var(--border);
-        border-radius: 999px;
-        padding: 2px 8px;
+        border: 1px solid #e0e6f0;
+        border-radius: 4px;
+        padding: 2px 6px;
         font-size: 12px;
-        background: #fff;
+        background: #f6f8fc;
       }
 
       .chip.ok {
@@ -171,11 +188,9 @@
       }
 
       .schema-block {
-        border: 1px solid var(--border);
-        border-radius: 8px;
-        padding: 8px;
-        margin-bottom: 8px;
-        background: white;
+        border-top: 1px solid #e8edf5;
+        padding: 8px 0 2px;
+        margin-bottom: 6px;
       }
 
       .schema-block:last-child {
@@ -189,29 +204,45 @@
 
       .schema-tree details {
         margin-left: 12px;
-        border-left: 1px dashed var(--border);
+        border-left: 1px solid #e8edf5;
         padding-left: 8px;
       }
 
       .tree-row {
         display: grid;
-        grid-template-columns: 1fr auto auto auto;
+        grid-template-columns: 1fr auto;
         gap: 8px;
         padding: 3px 0;
         align-items: center;
       }
 
+      .schema-tree summary .tree-row {
+        display: inline-grid;
+        vertical-align: middle;
+      }
+
+      .tree-name {
+        display: inline-flex;
+        align-items: baseline;
+        gap: 2px;
+      }
+
       .tree-col-muted {
         color: var(--muted);
         font-size: 12px;
       }
 
+      .required-star {
+        color: var(--danger);
+        font-weight: 700;
+      }
+
       .tree-pill {
-        border: 1px solid var(--border);
-        border-radius: 999px;
+        border: 1px solid #e0e6f0;
+        border-radius: 4px;
         padding: 1px 6px;
         font-size: 11px;
-        background: #f9fbff;
+        background: #f2f5fa;
       }
     </style>
   </head>
@@ -229,6 +260,11 @@
           <input id="searchInput" type="text" placeholder="Type to search..." />
         </label>
 
+        <label>
+          Type filter:
+          <input id="typeFilterInput" type="text" placeholder='Type/kind/enum (e.g. "paid")' />
+        </label>
+
         <div class="field-row">
           <label class="field-item">
             <input id="caseSensitive" type="checkbox" />
@@ -238,9 +274,28 @@
             <input id="regexSearch" type="checkbox" />
             <span>regex</span>
           </label>
+          <label class="field-item">
+            <input id="hasEnumOnly" type="checkbox" />
+            <span>has enum only</span>
+          </label>
+          <label class="field-item">
+            <span>type match</span>
+            <select id="typeMatchMode">
+              <option value="contains" selected>contains</option>
+              <option value="exact">exact</option>
+            </select>
+          </label>
         </div>
 
         <div id="fieldCheckboxes" class="field-row"></div>
+        <div class="field-actions">
+          <button id="selectAllFields" type="button">Select all</button>
+          <button id="clearAllFields" type="button">Clear all</button>
+          <button id="schemasOnlyFields" type="button">Schemas only</button>
+          <button id="metadataOnlyFields" type="button">Metadata only</button>
+          <button id="resetFilters" type="button">Reset filters</button>
+        </div>
+        <div id="activeFilterChips" class="chips filters"></div>
 
         <div id="status" class="meta">Load a JSON export to begin.</div>
       </div>
@@ -264,26 +319,60 @@
         { id: 'tags', label: 'tags', get: (leaf) => leaf.cfg?.tags || [] },
         { id: 'stability', label: 'stability', get: (leaf) => [leaf.cfg?.stability] },
         { id: 'docsMeta', label: 'docsMeta', get: (leaf) => [leaf.cfg?.docsMeta] },
-        { id: 'schemas', label: 'schemas', get: (leaf) => [leaf.cfg?.schemas] },
         {
-          id: 'flatSchema',
-          label: 'flatSchema',
-          get: (leaf, schemaFlatByLeaf) => [schemaFlatByLeaf?.[leaf.key]],
+          id: 'params',
+          label: 'params',
+          get: (leaf, schemaFlatByLeaf) =>
+            schemaSectionToSearchTokens(schemaFlatByLeaf?.[leaf.key], 'params'),
+        },
+        {
+          id: 'query',
+          label: 'query',
+          get: (leaf, schemaFlatByLeaf) =>
+            schemaSectionToSearchTokens(schemaFlatByLeaf?.[leaf.key], 'query'),
+        },
+        {
+          id: 'body',
+          label: 'body',
+          get: (leaf, schemaFlatByLeaf) =>
+            schemaSectionToSearchTokens(schemaFlatByLeaf?.[leaf.key], 'body'),
+        },
+        {
+          id: 'output',
+          label: 'output',
+          get: (leaf, schemaFlatByLeaf) =>
+            schemaSectionToSearchTokens(schemaFlatByLeaf?.[leaf.key], 'output'),
         },
       ]
 
       const SCHEMA_SECTIONS = ['params', 'query', 'body', 'output']
+      const SCHEMA_FIELD_IDS = new Set(SCHEMA_SECTIONS)
+      const METADATA_FIELD_IDS = new Set(
+        SEARCH_FIELDS.map((field) => field.id).filter((id) => !SCHEMA_FIELD_IDS.has(id)),
+      )
 
       const state = { payload: null, leaves: [] }
 
       const fileInput = document.getElementById('fileInput')
       const searchInput = document.getElementById('searchInput')
+      const typeFilterInput = document.getElementById('typeFilterInput')
       const caseSensitiveInput = document.getElementById('caseSensitive')
       const regexSearchInput = document.getElementById('regexSearch')
+      const hasEnumOnlyInput = document.getElementById('hasEnumOnly')
+      const typeMatchModeInput = document.getElementById('typeMatchMode')
       const fieldCheckboxes = document.getElementById('fieldCheckboxes')
+      const activeFilterChips = document.getElementById('activeFilterChips')
+      const selectAllFieldsBtn = document.getElementById('selectAllFields')
+      const clearAllFieldsBtn = document.getElementById('clearAllFields')
+      const schemasOnlyFieldsBtn = document.getElementById('schemasOnlyFields')
+      const metadataOnlyFieldsBtn = document.getElementById('metadataOnlyFields')
+      const resetFiltersBtn = document.getElementById('resetFilters')
       const statusEl = document.getElementById('status')
       const resultsEl = document.getElementById('results')
 
+      const URL_PARAM_KEY = 'filters'
+      let isHydratingFromUrl = false
+
       function escapeHtml(value) {
         return String(value)
           .replace(/&/g, '&amp;')
@@ -370,6 +459,65 @@
         return []
       }
 
+      function flatSchemaToSearchTokens(flatSchema) {
+        if (!flatSchema || typeof flatSchema !== 'object') return []
+
+        const tokens = new Set()
+
+        Object.entries(flatSchema).forEach(([path, info]) => {
+          if (path) {
+            tokens.add(path)
+            path.split('.').forEach((segment) => {
+              if (segment) tokens.add(segment)
+            })
+          }
+
+          if (info && typeof info === 'object') {
+            tokens.add(JSON.stringify(info))
+            if (info.type) tokens.add(String(info.type))
+            if (info.kind) tokens.add(String(info.kind))
+            if (info.description) tokens.add(String(info.description))
+            if (Array.isArray(info.enumValues)) {
+              info.enumValues.forEach((value) => tokens.add(String(value)))
+            }
+          } else if (info !== null && info !== undefined) {
+            tokens.add(String(info))
+          }
+        })
+
+        tokens.add(JSON.stringify(flatSchema))
+        return Array.from(tokens)
+      }
+
+      function schemaSectionToSearchTokens(flatSchema, sectionName) {
+        if (!flatSchema || typeof flatSchema !== 'object') return []
+        const sectionEntries = Object.entries(flatSchema).filter(
+          ([path]) => path === sectionName || path.startsWith(`${sectionName}.`),
+        )
+
+        if (sectionEntries.length === 0) return []
+        return flatSchemaToSearchTokens(Object.fromEntries(sectionEntries))
+      }
+
+      function typeFilterTokensByLeaf(flatSchema) {
+        if (!flatSchema || typeof flatSchema !== 'object') return { tokens: [], hasEnum: false }
+
+        const tokens = new Set()
+        let hasEnum = false
+
+        Object.values(flatSchema).forEach((info) => {
+          if (!info || typeof info !== 'object') return
+          if (info.type) tokens.add(String(info.type))
+          if (info.kind) tokens.add(String(info.kind))
+          if (Array.isArray(info.enumValues) && info.enumValues.length > 0) {
+            hasEnum = true
+            info.enumValues.forEach((value) => tokens.add(String(value)))
+          }
+        })
+
+        return { tokens: Array.from(tokens), hasEnum }
+      }
+
       function selectedFieldIds() {
         return SEARCH_FIELDS.filter((field) => {
           const input = document.getElementById(`field-${field.id}`)
@@ -389,6 +537,42 @@
         })
       }
 
+      function matchesTypeFilter(leaf, typeEngine, matchMode, hasEnumOnly) {
+        const schemaFlatByLeaf = state.payload?.schemaFlatByLeaf || {}
+        const { tokens, hasEnum } = typeFilterTokensByLeaf(schemaFlatByLeaf?.[leaf.key])
+
+        if (hasEnumOnly && !hasEnum) return false
+        if (!typeEngine.active) return true
+
+        if (matchMode === 'exact') {
+          const sourceTokens = typeEngine.caseSensitive
+            ? tokens
+            : tokens.map((token) => token.toLowerCase())
+          const needle = typeEngine.caseSensitive ? typeEngine.query : typeEngine.query.toLowerCase()
+          return sourceTokens.includes(needle)
+        }
+
+        return tokens.some((token) => typeEngine.test(token))
+      }
+
+      function createTypeSearchEngine(queryRaw) {
+        const query = queryRaw || ''
+        const caseSensitive = Boolean(caseSensitiveInput.checked)
+        if (!query) return { active: false, query, caseSensitive, test: () => true }
+
+        const needle = caseSensitive ? query : query.toLowerCase()
+        return {
+          active: true,
+          query,
+          caseSensitive,
+          test: (text) => {
+            const source = String(text ?? '')
+            const hay = caseSensitive ? source : source.toLowerCase()
+            return hay.includes(needle)
+          },
+        }
+      }
+
       function el(tag, className, text) {
         const node = document.createElement(tag)
         if (className) node.className = className
@@ -492,6 +676,29 @@
         const childKeys = Object.keys(node.children)
         const hasChildren = childKeys.length > 0
         const hasInfo = Boolean(node.info)
+        const appendNameCell = (row) => {
+          const nameWrap = el('span', 'mono tree-name')
+          const nameNode = el('span')
+          setHighlighted(nameNode, node.name, engine)
+          nameWrap.appendChild(nameNode)
+
+          if (node.info && !node.info.optional) {
+            const star = el('span', 'required-star', '*')
+            nameWrap.appendChild(star)
+          }
+
+          if (node.info?.nullable) {
+            nameWrap.appendChild(el('span', 'tree-col-muted', '-'))
+          }
+
+          row.appendChild(nameWrap)
+        }
+
+        const appendTypeCell = (row, info) => {
+          const type = el('span', 'tree-pill')
+          setHighlighted(type, info?.type || info?.kind || '—', engine)
+          row.appendChild(type)
+        }
 
         if (isRoot || hasChildren) {
           const details = el('details')
@@ -499,21 +706,8 @@
           const summary = el('summary')
           const row = el('div', 'tree-row')
 
-          const nameNode = el('span', 'mono')
-          setHighlighted(nameNode, node.name, engine)
-          row.appendChild(nameNode)
-
-          if (hasInfo) {
-            const type = el('span', 'tree-pill')
-            setHighlighted(type, node.info.type, engine)
-            row.appendChild(type)
-            row.appendChild(el('span', 'tree-col-muted', node.info.optional ? 'optional' : 'required'))
-            row.appendChild(el('span', 'tree-col-muted', node.info.nullable ? 'nullable' : 'non-null'))
-          } else {
-            row.appendChild(el('span'))
-            row.appendChild(el('span'))
-            row.appendChild(el('span'))
-          }
+          appendNameCell(row)
+          appendTypeCell(row, hasInfo ? node.info : null)
 
           summary.appendChild(row)
           details.appendChild(summary)
@@ -527,15 +721,8 @@
         }
 
         const row = el('div', 'tree-row')
-        const nameNode = el('span', 'mono')
-        setHighlighted(nameNode, node.name, engine)
-        row.appendChild(nameNode)
-
-        const type = el('span', 'tree-pill')
-        setHighlighted(type, node.info ? node.info.type : '—', engine)
-        row.appendChild(type)
-        row.appendChild(el('span', 'tree-col-muted', node.info?.optional ? 'optional' : 'required'))
-        row.appendChild(el('span', 'tree-col-muted', node.info?.nullable ? 'nullable' : 'non-null'))
+        appendNameCell(row)
+        appendTypeCell(row, node.info)
 
         return row
       }
@@ -655,28 +842,42 @@
           caseSensitive: caseSensitiveInput.checked,
           regex: regexSearchInput.checked,
         })
+        const typeEngine = createTypeSearchEngine(typeFilterInput.value.trim())
+        const hasEnumOnly = Boolean(hasEnumOnlyInput.checked)
+        const typeMatchMode = typeMatchModeInput.value === 'exact' ? 'exact' : 'contains'
 
         if (engine.error) {
           statusEl.textContent = `Invalid regex: ${engine.error}`
           resultsEl.innerHTML = ''
           resultsEl.appendChild(el('div', 'empty', 'Fix the regex to continue.'))
+          renderActiveFilterChips({
+            selectedIds: selectedFieldIds(),
+            hasRegexError: true,
+          })
           return
         }
 
         const selectedIds = selectedFieldIds()
-        const filtered = state.leaves.filter((leaf) => matchesLeaf(leaf, engine, selectedIds))
+        const filtered = state.leaves.filter(
+          (leaf) =>
+            matchesLeaf(leaf, engine, selectedIds) &&
+            matchesTypeFilter(leaf, typeEngine, typeMatchMode, hasEnumOnly),
+        )
 
         statusEl.textContent = `${filtered.length} / ${state.leaves.length} routes matched.`
         resultsEl.innerHTML = ''
+        renderActiveFilterChips({ selectedIds, hasRegexError: false })
 
         if (filtered.length === 0) {
           resultsEl.appendChild(el('div', 'empty', 'No matches.'))
+          syncFilterStateToUrl()
           return
         }
 
         filtered.forEach((leaf) => {
           resultsEl.appendChild(renderLeaf(leaf, engine))
         })
+        syncFilterStateToUrl()
       }
 
       function renderFieldCheckboxes() {
@@ -694,6 +895,114 @@
         })
       }
 
+      function setFieldSelection(allowedIds) {
+        SEARCH_FIELDS.forEach((field) => {
+          const input = document.getElementById(`field-${field.id}`)
+          if (!input) return
+          input.checked = allowedIds.has(field.id)
+        })
+        renderResults()
+      }
+
+      function resetFiltersToDefault() {
+        searchInput.value = ''
+        typeFilterInput.value = ''
+        caseSensitiveInput.checked = false
+        regexSearchInput.checked = false
+        hasEnumOnlyInput.checked = false
+        typeMatchModeInput.value = 'contains'
+        setFieldSelection(new Set(SEARCH_FIELDS.map((field) => field.id)))
+      }
+
+      function renderActiveFilterChips({ selectedIds, hasRegexError }) {
+        activeFilterChips.innerHTML = ''
+        const chips = []
+
+        const searchValue = searchInput.value.trim()
+        const typeValue = typeFilterInput.value.trim()
+
+        if (searchValue) chips.push(`search: ${searchValue}`)
+        if (typeValue) chips.push(`type: ${typeValue}`)
+        if (typeMatchModeInput.value === 'exact') chips.push('type mode: exact')
+        if (caseSensitiveInput.checked) chips.push('case sensitive')
+        if (regexSearchInput.checked) chips.push('regex')
+        if (hasEnumOnlyInput.checked) chips.push('has enum only')
+        if (hasRegexError) chips.push('regex error')
+
+        const allIds = SEARCH_FIELDS.map((field) => field.id)
+        if (selectedIds.length !== allIds.length) {
+          chips.push(`fields: ${selectedIds.join(', ') || 'none'}`)
+        }
+
+        if (chips.length === 0) {
+          activeFilterChips.appendChild(el('span', 'empty', 'No active filters'))
+          return
+        }
+
+        chips.forEach((chipText) => {
+          const chip = el('span', 'chip')
+          chip.textContent = chipText
+          activeFilterChips.appendChild(chip)
+        })
+      }
+
+      function collectFilterState() {
+        return {
+          search: searchInput.value,
+          typeFilter: typeFilterInput.value,
+          caseSensitive: caseSensitiveInput.checked,
+          regex: regexSearchInput.checked,
+          hasEnumOnly: hasEnumOnlyInput.checked,
+          typeMatchMode: typeMatchModeInput.value === 'exact' ? 'exact' : 'contains',
+          selectedFields: selectedFieldIds(),
+        }
+      }
+
+      function syncFilterStateToUrl() {
+        if (isHydratingFromUrl) return
+
+        const data = collectFilterState()
+        const params = new URLSearchParams(window.location.hash.replace(/^#/, ''))
+        const serialized = encodeURIComponent(JSON.stringify(data))
+        params.set(URL_PARAM_KEY, serialized)
+        const nextHash = params.toString()
+        if (window.location.hash !== `#${nextHash}`) {
+          window.location.hash = nextHash
+        }
+      }
+
+      function hydrateFilterStateFromUrl() {
+        const params = new URLSearchParams(window.location.hash.replace(/^#/, ''))
+        const raw = params.get(URL_PARAM_KEY)
+        if (!raw) return
+
+        try {
+          const parsed = JSON.parse(decodeURIComponent(raw))
+          isHydratingFromUrl = true
+          if (typeof parsed.search === 'string') searchInput.value = parsed.search
+          if (typeof parsed.typeFilter === 'string') typeFilterInput.value = parsed.typeFilter
+          caseSensitiveInput.checked = Boolean(parsed.caseSensitive)
+          regexSearchInput.checked = Boolean(parsed.regex)
+          hasEnumOnlyInput.checked = Boolean(parsed.hasEnumOnly)
+          if (parsed.typeMatchMode === 'exact' || parsed.typeMatchMode === 'contains') {
+            typeMatchModeInput.value = parsed.typeMatchMode
+          }
+
+          if (Array.isArray(parsed.selectedFields)) {
+            const allowed = new Set(parsed.selectedFields)
+            SEARCH_FIELDS.forEach((field) => {
+              const input = document.getElementById(`field-${field.id}`)
+              if (!input) return
+              input.checked = allowed.has(field.id)
+            })
+          }
+        } catch (error) {
+          // Ignore malformed hash state.
+        } finally {
+          isHydratingFromUrl = false
+        }
+      }
+
       async function handleFile(file) {
         const text = await file.text()
         const parsed = JSON.parse(text)
@@ -729,11 +1038,24 @@
       })
 
       searchInput.addEventListener('input', renderResults)
+      typeFilterInput.addEventListener('input', renderResults)
       caseSensitiveInput.addEventListener('change', renderResults)
       regexSearchInput.addEventListener('change', renderResults)
+      hasEnumOnlyInput.addEventListener('change', renderResults)
+      typeMatchModeInput.addEventListener('change', renderResults)
+
+      selectAllFieldsBtn.addEventListener('click', () =>
+        setFieldSelection(new Set(SEARCH_FIELDS.map((field) => field.id))),
+      )
+      clearAllFieldsBtn.addEventListener('click', () => setFieldSelection(new Set()))
+      schemasOnlyFieldsBtn.addEventListener('click', () => setFieldSelection(SCHEMA_FIELD_IDS))
+      metadataOnlyFieldsBtn.addEventListener('click', () => setFieldSelection(METADATA_FIELD_IDS))
+      resetFiltersBtn.addEventListener('click', resetFiltersToDefault)
 
       renderFieldCheckboxes()
+      hydrateFilterStateFromUrl()
       initializeFromBakedPayload()
+      renderResults()
     </script>
   </body>
 </html>