@tldiagram/core-ui 1.87.0

package/src/utils/edgeDistribution.ts

@@ -0,0 +1,103 @@
+import type { CSSProperties } from 'react'
+import { Position } from 'reactflow'
+
+export const HANDLE_SLOT_COUNT = 5
+export const HANDLE_SLOT_GAP = 12
+export const HANDLE_SLOT_CENTER_INDEX = Math.floor(HANDLE_SLOT_COUNT / 2)
+
+export type LogicalHandleSide = 'top' | 'bottom' | 'left' | 'right'
+
+export const DEFAULT_SOURCE_HANDLE_SIDE: LogicalHandleSide = 'right'
+export const DEFAULT_TARGET_HANDLE_SIDE: LogicalHandleSide = 'left'
+
+function clampSlot(slot: number) {
+  return Math.max(0, Math.min(HANDLE_SLOT_COUNT - 1, slot))
+}
+
+export function getLogicalHandleId(
+  handleId: string | null | undefined,
+  fallback: LogicalHandleSide | null = null,
+): LogicalHandleSide | null {
+  if (!handleId) return fallback
+  const side = handleId.split('-', 1)[0]
+  if (side === 'top' || side === 'bottom' || side === 'left' || side === 'right') return side
+  return fallback
+}
+
+export function getVisualHandleSlot(groupIndex: number, groupCount: number) {
+  if (groupIndex < 0) return HANDLE_SLOT_CENTER_INDEX
+  if (groupCount <= 1) return HANDLE_SLOT_CENTER_INDEX
+  return clampSlot(Math.round((groupIndex * (HANDLE_SLOT_COUNT - 1)) / (groupCount - 1)))
+}
+
+export function getVisualHandleSlotFromId(handleId: string | null | undefined) {
+  if (!handleId) return null
+  const parts = handleId.split('-')
+  if (parts.length < 2) return null
+  const slot = Number(parts[1])
+  return Number.isInteger(slot) ? clampSlot(slot) : null
+}
+
+export function getVisualHandleId(side: LogicalHandleSide, slot: number) {
+  return `${side}-${clampSlot(slot)}`
+}
+
+export function getVisualHandleIdForGroup(side: LogicalHandleSide, groupIndex: number, groupCount: number) {
+  return getVisualHandleId(side, getVisualHandleSlot(groupIndex, groupCount))
+}
+
+export function ensureVisualHandleId(
+  handleId: string | null | undefined,
+  fallback: LogicalHandleSide,
+) {
+  const side = getLogicalHandleId(handleId, fallback)
+  if (!side) return null
+  const slot = getVisualHandleSlotFromId(handleId) ?? HANDLE_SLOT_CENTER_INDEX
+  return getVisualHandleId(side, slot)
+}
+
+export function getHandleSlotOffset(slot: number) {
+  return (clampSlot(slot) - HANDLE_SLOT_CENTER_INDEX) * HANDLE_SLOT_GAP
+}
+
+export function getHandleSlotOffsetFromId(handleId: string | null | undefined) {
+  const slot = getVisualHandleSlotFromId(handleId)
+  if (slot === null) return 0
+  return getHandleSlotOffset(slot)
+}
+
+export function getVisualHandleStyle(position: Position, slot: number): CSSProperties {
+  const offset = getHandleSlotOffset(slot)
+
+  switch (position) {
+    case Position.Top:
+    case Position.Bottom:
+      return { left: `calc(50% + ${offset}px)` }
+    case Position.Left:
+    case Position.Right:
+      return { top: `calc(50% + ${offset}px)` }
+  }
+}
+
+export function getHandleFlowPosition(
+  nodeX: number,
+  nodeY: number,
+  width: number,
+  height: number,
+  handleId: string | null | undefined,
+  fallback: LogicalHandleSide,
+) {
+  const side = getLogicalHandleId(handleId, fallback) ?? fallback
+  const offset = getHandleSlotOffsetFromId(handleId)
+
+  switch (side) {
+    case 'top':
+      return { x: nodeX + width / 2 + offset, y: nodeY, side }
+    case 'bottom':
+      return { x: nodeX + width / 2 + offset, y: nodeY + height, side }
+    case 'left':
+      return { x: nodeX, y: nodeY + height / 2 + offset, side }
+    case 'right':
+      return { x: nodeX + width, y: nodeY + height / 2 + offset, side }
+  }
+}

package/src/utils/githubApi.ts

@@ -0,0 +1,121 @@
+const GITHUB_API_BASE = 'https://api.github.com'
+const MIN_REQUEST_GAP_MS = 300
+
+type RepoVisibility = 'public' | 'private' | 'unknown'
+
+let queue: Promise<void> = Promise.resolve()
+let lastRequestAt = 0
+let rateLimitedUntil = 0
+
+const visibilityInFlight = new Map<string, Promise<RepoVisibility>>()
+
+function wait(ms: number): Promise<void> {
+  if (ms <= 0) return Promise.resolve()
+  return new Promise((resolve) => {
+    window.setTimeout(resolve, ms)
+  })
+}
+
+function toNumber(value: string | null): number | null {
+  if (!value) return null
+  const parsed = Number(value)
+  return Number.isFinite(parsed) ? parsed : null
+}
+
+function getAuthHeader(): string | null {
+  const clientId = import.meta.env.VITE_GH_CLIENT_ID?.trim()
+  const clientSecret = import.meta.env.VITE_GH_CLIENT_SECRET?.trim()
+  if (!clientId || !clientSecret) return null
+  return `Basic ${window.btoa(`${clientId}:${clientSecret}`)}`
+}
+
+function updateRateLimitState(response: Response) {
+  const now = Date.now()
+  const retryAfterSeconds = toNumber(response.headers.get('retry-after'))
+  const remaining = toNumber(response.headers.get('x-ratelimit-remaining'))
+  const resetUnixSeconds = toNumber(response.headers.get('x-ratelimit-reset'))
+
+  if (retryAfterSeconds !== null && retryAfterSeconds > 0) {
+    rateLimitedUntil = Math.max(rateLimitedUntil, now + retryAfterSeconds * 1000)
+  }
+
+  if (remaining === 0 && resetUnixSeconds !== null) {
+    // Add a small safety buffer after reset time to avoid immediate re-limit.
+    rateLimitedUntil = Math.max(rateLimitedUntil, resetUnixSeconds * 1000 + 500)
+  }
+
+  if ((response.status === 403 || response.status === 429) && retryAfterSeconds === null && remaining === 0) {
+    rateLimitedUntil = Math.max(rateLimitedUntil, now + 60_000)
+  }
+}
+
+function enqueueRequest<T>(request: () => Promise<T>): Promise<T> {
+  const run = async () => {
+    const now = Date.now()
+    if (rateLimitedUntil > now) {
+      await wait(rateLimitedUntil - now)
+    }
+
+    const elapsedSinceLast = Date.now() - lastRequestAt
+    if (elapsedSinceLast < MIN_REQUEST_GAP_MS) {
+      await wait(MIN_REQUEST_GAP_MS - elapsedSinceLast)
+    }
+
+    lastRequestAt = Date.now()
+    return request()
+  }
+
+  const chained = queue.then(run, run)
+  queue = chained.then(() => undefined, () => undefined)
+  return chained
+}
+
+export async function githubRequest(path: string): Promise<Response> {
+  return enqueueRequest(async () => {
+    const headers = new Headers({
+      Accept: 'application/vnd.github+json',
+    })
+    const authHeader = getAuthHeader()
+    if (authHeader) headers.set('Authorization', authHeader)
+
+    let response = await fetch(`${GITHUB_API_BASE}${path}`, {
+      method: 'GET',
+      headers,
+    })
+
+    // If the request failed with 401 but we provided credentials, retry without credentials.
+    // This handles cases where client ID/secret are misconfigured but the resource is public.
+    if (response.status === 401 && authHeader) {
+      headers.delete('Authorization')
+      response = await fetch(`${GITHUB_API_BASE}${path}`, {
+        method: 'GET',
+        headers,
+      })
+    }
+
+    updateRateLimitState(response)
+    return response
+  })
+}
+
+export function getGithubRepoVisibility(repoSlug: string): Promise<RepoVisibility> {
+  const inFlight = visibilityInFlight.get(repoSlug)
+  if (inFlight) return inFlight
+
+  const promise = (async () => {
+    const response = await githubRequest(`/repos/${repoSlug}`)
+    if (response.status === 200) return 'public'
+    if (response.status === 404 || response.status === 401) return 'private'
+    if (response.status === 403 || response.status === 429) {
+      const remaining = toNumber(response.headers.get('x-ratelimit-remaining'))
+      if (remaining === 0 || Date.now() < rateLimitedUntil) return 'unknown'
+      return 'private'
+    }
+    return 'unknown'
+  })().finally(() => {
+    visibilityInFlight.delete(repoSlug)
+  })
+
+  visibilityInFlight.set(repoSlug, promise)
+  return promise
+}

package/src/utils/githubCache.ts

@@ -0,0 +1,108 @@
+interface CacheEntry<T> {
+  data: T
+  timestamp: number
+}
+
+const CACHE_TTL = 10 * 60 * 1000 // 10 minutes
+const STORAGE_KEY = 'diag_github_cache'
+
+interface CacheData {
+  branches: Record<string, CacheEntry<string[]>>
+  trees: Record<string, CacheEntry<string[]>>
+  contents: Record<string, CacheEntry<string>>
+  repoVisibility: Record<string, CacheEntry<boolean>>
+}
+
+class GithubCache {
+  private cache: CacheData
+
+  constructor() {
+    this.cache = this.load()
+    this.cleanup()
+  }
+
+  private load(): CacheData {
+    try {
+      const stored = localStorage.getItem(STORAGE_KEY)
+      if (stored) return JSON.parse(stored)
+    } catch { /* empty */ }
+    return { branches: {}, trees: {}, contents: {}, repoVisibility: {} }
+  }
+
+  private save() {
+    try {
+      // Basic size limit check - clear if too big (simple for now)
+      const str = JSON.stringify(this.cache)
+      if (str.length > 4 * 1024 * 1024) { // 4MB
+        this.cache = { branches: {}, trees: {}, contents: {}, repoVisibility: {} }
+      }
+      localStorage.setItem(STORAGE_KEY, JSON.stringify(this.cache))
+    } catch { /* empty */ }
+  }
+
+  private cleanup() {
+    const now = Date.now()
+    let changed = false
+    const clean = <T>(map: Record<string, CacheEntry<T>>) => {
+      for (const [k, v] of Object.entries(map)) {
+        if (now - v.timestamp > CACHE_TTL) { delete map[k]; changed = true }
+      }
+    }
+    clean(this.cache.branches)
+    clean(this.cache.trees)
+    clean(this.cache.contents)
+    if (!this.cache.repoVisibility) this.cache.repoVisibility = {}
+    clean(this.cache.repoVisibility)
+    if (changed) this.save()
+  }
+
+  getBranches(repo: string): string[] | null {
+    const entry = this.cache.branches[repo]
+    if (entry && Date.now() - entry.timestamp < CACHE_TTL) return entry.data
+    return null
+  }
+
+  setBranches(repo: string, data: string[]) {
+    this.cache.branches[repo] = { data, timestamp: Date.now() }
+    this.save()
+  }
+
+  getTree(repo: string, branch: string): string[] | null {
+    const key = `${repo}/${branch}`
+    const entry = this.cache.trees[key]
+    if (entry && Date.now() - entry.timestamp < CACHE_TTL) return entry.data
+    return null
+  }
+
+  setTree(repo: string, branch: string, data: string[]) {
+    const key = `${repo}/${branch}`
+    this.cache.trees[key] = { data, timestamp: Date.now() }
+    this.save()
+  }
+
+  getContent(rawUrl: string): string | null {
+    const entry = this.cache.contents[rawUrl]
+    if (entry && Date.now() - entry.timestamp < CACHE_TTL) return entry.data
+    return null
+  }
+
+  setContent(rawUrl: string, data: string) {
+    this.cache.contents[rawUrl] = { data, timestamp: Date.now() }
+    this.save()
+  }
+
+  getRepoPublic(slug: string): boolean | null {
+    if (!this.cache.repoVisibility) return null
+    const entry = this.cache.repoVisibility[slug]
+    if (entry && Date.now() - entry.timestamp < CACHE_TTL) return entry.data
+    return null
+  }
+
+  setRepoPublic(slug: string, isPublic: boolean) {
+    if (!this.cache.repoVisibility) this.cache.repoVisibility = {}
+    this.cache.repoVisibility[slug] = { data: isPublic, timestamp: Date.now() }
+    this.save()
+  }
+}
+
+export const githubCache = new GithubCache()

package/src/utils/ids.ts

@@ -0,0 +1,9 @@
+export function parseNumericId(value: string | null | undefined): number | null {
+  if (value == null) return null
+  const n = Number(value)
+  return Number.isInteger(n) && n > 0 ? n : null
+}
+
+export function idToString(value: number | null | undefined): string {
+  return value == null ? '' : String(value)
+}

package/src/utils/technologyCatalog.ts

@@ -0,0 +1,143 @@
+import type { TechnologyCatalogItem } from '../types'
+import { isNativeApp } from '../config/runtime'
+
+interface SearchableCatalogItem {
+  item: TechnologyCatalogItem
+  haystack: string
+}
+
+interface TechnologyCatalogIndex {
+  items: TechnologyCatalogItem[]
+  searchable: SearchableCatalogItem[]
+  bySlug: Map<string, TechnologyCatalogItem>
+}
+
+let indexPromise: Promise<TechnologyCatalogIndex> | null = null
+
+export function resolveWithBase(urlOrPath: string): string {
+  if (!urlOrPath) return urlOrPath
+  if (urlOrPath.startsWith('http://') || urlOrPath.startsWith('https://') || urlOrPath.startsWith('data:')) {
+    return urlOrPath
+  }
+
+  // When running inside the native mobile app (Capacitor), or inside an embedded webview
+  // that serves content from localhost, avoid prefixing the app BASE_URL. Mobile builds and
+  // the local webview often serve/resolve static assets from the web root (\"/\"), so
+  // returning the path without adding import.meta.env.BASE_URL avoids requests to
+  // unexpected URLs like \"https://localhost/app/icons/...\" which can 404.
+  const runningOnLocalhost = typeof window !== 'undefined' && (() => {
+    // file: is unequivocally a native / packaged environment (Capacitor)
+    if (window.location.protocol === 'file:') return true
+
+    // Only treat plain localhost/127.0.0.1 as the native webview when it's
+    // served in a way that matches Capacitor's webview (typically https
+    // without an explicit dev port). We must NOT treat the dev server
+    // (e.g. http://localhost:5173) as native.
+    const hostIsLocal = window.location.hostname === 'localhost' || window.location.hostname === '127.0.0.1'
+
+    if (!hostIsLocal) return false
+
+    // If served over HTTPS on localhost (Capacitor uses https://localhost) assume native/webview.
+    if (window.location.protocol === 'https:') return true
+
+    // If there's no explicit port (or it's the default HTTPS port), treat as native/webview.
+    // Dev servers usually expose a non-default port (like 5173) - those should NOT be treated as native.
+    const port = (window.location.port || '').trim()
+    if (!port || port === '443') return true
+
+    return false
+  })()
+  if (isNativeApp || runningOnLocalhost) {
+    // Ensure the path is absolute so it resolves correctly from the app's web root.
+    return urlOrPath.startsWith('/') ? urlOrPath : `/${urlOrPath}`
+  }
+
+  const base = import.meta.env.BASE_URL || '/'
+  const normalizedBase = base.endsWith('/') ? base : `${base}/`
+  if (urlOrPath.startsWith(normalizedBase) || urlOrPath === normalizedBase.slice(0, -1)) {
+    return urlOrPath
+  }
+  const normalizedPath = urlOrPath.startsWith('/') ? urlOrPath.slice(1) : urlOrPath
+  return `${normalizedBase}${normalizedPath}`
+}
+
+function normalizeText(value: string): string {
+  return value.toLowerCase().trim()
+}
+
+function createHaystack(item: TechnologyCatalogItem): string {
+  return normalizeText([
+    item.name,
+    item.nameShort,
+    item.provider,
+    item.defaultSlug,
+  ].filter(Boolean).join(' '))
+}
+
+async function loadCatalogItems(): Promise<TechnologyCatalogItem[]> {
+  const response = await fetch(resolveWithBase('icons.json'), { cache: 'force-cache' })
+  if (!response.ok) {
+    throw new Error('Failed to load technology catalog')
+  }
+  const data = await response.json()
+  if (!Array.isArray(data)) return []
+
+  return data as TechnologyCatalogItem[]
+}
+
+export async function getTechnologyCatalogIndex(): Promise<TechnologyCatalogIndex> {
+  if (!indexPromise) {
+    indexPromise = loadCatalogItems().then((items) => {
+      const bySlug = new Map<string, TechnologyCatalogItem>()
+      const searchable: SearchableCatalogItem[] = []
+
+      for (const item of items) {
+        bySlug.set(item.defaultSlug, item)
+        searchable.push({ item, haystack: createHaystack(item) })
+      }
+
+      return { items, searchable, bySlug }
+    }).catch((error) => {
+      indexPromise = null
+      throw error
+    })
+  }
+
+  return indexPromise
+}
+
+export async function searchTechnologyCatalog(query: string, maxResults = 12): Promise<TechnologyCatalogItem[]> {
+  const normalizedQuery = query.trim()
+  if (!normalizedQuery) return []
+
+  const index = await getTechnologyCatalogIndex()
+
+  try {
+    const regex = new RegExp(normalizedQuery, 'i')
+    const matches: TechnologyCatalogItem[] = []
+    for (const entry of index.searchable) {
+      if (regex.test(entry.haystack)) {
+        matches.push(entry.item)
+        if (matches.length >= maxResults) break
+      }
+    }
+    return matches
+  } catch {
+    const needle = normalizeText(normalizedQuery)
+    const matches: TechnologyCatalogItem[] = []
+    for (const entry of index.searchable) {
+      if (entry.haystack.includes(needle)) {
+        matches.push(entry.item)
+        if (matches.length >= maxResults) break
+      }
+    }
+    return matches
+  }
+}
+
+export async function getTechnologyCatalogItemBySlug(slug: string): Promise<TechnologyCatalogItem | null> {
+  const cleanSlug = slug.trim()
+  if (!cleanSlug) return null
+  const index = await getTechnologyCatalogIndex()
+  return index.bySlug.get(cleanSlug) ?? null
+}

package/src/utils/toast.ts

@@ -0,0 +1,100 @@
+import { createStandaloneToast, UseToastOptions, ToastId } from '@chakra-ui/react'
+import theme from '../theme'
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const { toast: chakraToast, ToastContainer }: any = createStandaloneToast({
+  theme,
+  defaultOptions: {
+    status: 'error',
+    duration: 5000,
+    isClosable: true,
+    position: 'bottom-right',
+  },
+})
+
+let errorToastId: ToastId | null = null
+let errorCount = 0
+const errorSummaries = new Set<string>()
+
+/**
+ * Extracts a short error code or summary from a ConnectRPC error message.
+ * ConnectRPC messages often look like "[unavailable] upstream request timeout"
+ * or REST responses like "HTTP 500 Internal Server Error"
+ */
+function getErrorSummary(options: UseToastOptions): string {
+  const text = (options.description || options.title || 'Unknown error').toString()
+  
+  // ConnectRPC: matches "[code] message"
+  const connectMatch = text.match(/^\[(\w+)\]/)
+  if (connectMatch) return connectMatch[1]
+  
+  // HTTP status: "HTTP 500"
+  const httpMatch = text.match(/HTTP \d+/)
+  if (httpMatch) return httpMatch[0]
+  
+  // Generic fallback: first part of message (before colon or newline)
+  return text.split(':')[0].split('\n')[0].substring(0, 32).trim()
+}
+
+/**
+ * Global toast utility that intercepts 'error' status toasts to combine multiple
+ * backend errors into a single notification with a counter.
+ */
+interface CustomToast {
+  (options: UseToastOptions): ToastId | undefined;
+  close: typeof chakraToast.close;
+  closeAll: typeof chakraToast.closeAll;
+  update: typeof chakraToast.update;
+  isActive: typeof chakraToast.isActive;
+}
+
+const toast: CustomToast = (options: UseToastOptions) => {
+  const status = options.status || 'error'
+
+  if (status === 'error') {
+    const summary = getErrorSummary(options)
+    
+    // Check if an error toast is already active
+    if (errorToastId && chakraToast.isActive(errorToastId)) {
+      errorCount++
+      errorSummaries.add(summary)
+      
+      chakraToast.update(errorToastId, {
+        ...options,
+        title: `${errorCount} Requests Failed`,
+        description: `Errors: ${Array.from(errorSummaries).join(', ')}`,
+        duration: 5000, // Refresh the timer
+      })
+      return errorToastId;
+    } else {
+      // First error or previous toast was closed
+      errorCount = 1
+      errorSummaries.clear()
+      errorSummaries.add(summary)
+      
+      const originalOnCloseComplete = options.onCloseComplete
+      
+      errorToastId = chakraToast({
+        ...options,
+        title: options.title || 'Request Failed',
+        onCloseComplete: () => {
+          if (originalOnCloseComplete) originalOnCloseComplete()
+          errorToastId = null
+          errorCount = 0
+          errorSummaries.clear()
+        }
+      })
+      return errorToastId;
+    }
+  }
+
+  return chakraToast(options)
+}
+
+// Proxy standard chakra toast methods for complete compatibility
+toast.close = chakraToast.close
+toast.closeAll = chakraToast.closeAll
+toast.update = chakraToast.update
+toast.isActive = chakraToast.isActive
+
+export { toast, ToastContainer }