Theming

Theming dark/light guidato da token, senza reload.

Token

src/styles/tokens.ts: getThemeTokens(theme) / deriveSurfaceTokens(bg, text): un piccolo set fisso di token base (sfondo, testo, accento) più token di superficie/bordo derivati mescolando bg verso text, senza mai introdurre una nuova tonalità.

Applicarlo senza reload

src/styles/apply-theme.ts: scrive le custom property CSS risultanti e l'attributo data-theme su <html>; cambiare tema modifica solo i valori delle variabili, senza re-render dell'albero dei componenti.

Zustand store

src/state/theme-store.ts: uno store Zustand che persiste il tema scelto in localStorage e lo applica in modo sincrono prima del primo render (nessun flash con il tema sbagliato).

Document Model

Prima che qualcosa arrivi a un componente, il documento OpenAPI grezzo viene normalizzato in un modello in memoria (tagGroups → endpoints), implementato in puro TypeScript, testato in modo indipendente, senza dipendenze da React. Le quattro responsabilità:

  • normalize.ts: dereferenzia ogni $ref tramite @apidevtools/swagger-parser e raggruppa gli endpoint per tag, preservando l'ordine dichiarato.
  • cap-depth.ts: rende sicuro per JSON.stringify uno schema dereferenziato (e possibilmente ciclico), per il pulsante "Copy OpenAPI".
  • example.ts / schema-tree.ts: costruisce il payload di esempio con type-token e l'albero schema navigabile a partire dallo stesso schema, senza inventare dati falsi.
  • filter.ts: la ricerca lato client usata dalla sidebar.

Ogni funzione che percorre lo schema (flattenSchema, schemaToTreeNodes, extractValidationRules) tiene traccia dei nodi visitati per identità dell'oggetto, non con un limite numerico di profondità, così un DTO genuinamente ricorsivo renderizza un singolo marker (circular reference) / ↩ circular invece di srotolarsi N volte o andare in crash.