Abbiamo tolto la documentazione dalla modale

Stai scrivendo la pagina di onboarding di un servizio di pagamenti. Sei titoli, due blocchi di codice, una tabella delle queue che consuma e un paragrafo che continui a riscrivere perché è il paragrafo che il prossimo ingegnere leggerà davvero.

In Archyl, fino a questa settimana, scrivevi tutto questo dentro una finestra di dialogo. La pagina dietro si oscurava. L'albero dei documenti, dove vivono le pagine sorelle e dove saresti andato a controllare come avevi chiamato l'ultima, si oscurava con lei. L'editor riempiva la finestra di dialogo, la finestra di dialogo non era lo schermo, e leggere una pagina e scrivere una pagina succedevano in due posti diversi.

Funzionava. E non è che sembrasse davvero professionale: è la frase a cui continuavo a tornare finché non mi sono seduto e l'ho ricostruito.

Nel workspace della documentazione non c'è più nessuna modale. Ecco cosa ha preso il suo posto.

L'editor si apre dove sta il documento

Premi Modifica su una pagina, o batti E mentre la leggi, e l'editor prende la colonna dei contenuti sul posto. L'albero resta dov'era, a piena luce, ancora cliccabile. Niente si sovrappone a niente.

Il documento sembra un documento mentre lo scrivi. Il titolo è un campo semplice della dimensione di un'intestazione, senza etichetta e senza riquadro attorno. I tag stanno sotto: scrivi e premi Enter o la virgola per aggiungerne uno, backspace su un campo vuoto per riprenderti l'ultimo. Il percorso della cartella corre lungo la parte alta della barra delle azioni, così sai sempre dove atterrerà la pagina che stai scrivendo.

La barra porta anche lo stato. Un pallino ambra e Modifiche non salvate finché la bozza differisce da ciò che è archiviato, poi Salva con il suo suggerimento ⌘↵. Quella scorciatoia funziona da qualsiasi punto dell'editor, anche da dentro il corpo Markdown, così non devi mai tornare fino al bottone. Accanto al selettore di modalità c'è un interruttore a schermo intero per quando vuoi il paragrafo e nient'altro, ed Escape ti riporta indietro. Lungo il bordo inferiore, un conteggio delle parole e un tempo di lettura.

Scrivi, Affiancato, Anteprima

L'editor ha tre modalità, e sono l'unica decisione di barra degli strumenti che devi prendere:

• Scrivi è solo Markdown, per tutta la larghezza della colonna.
• Affiancato mette il sorgente e la pagina renderizzata fianco a fianco.
• Anteprima è la pagina renderizzata da sola.

Affiancato è il default. Qualunque modalità tu scelga, Archyl la salva nel tuo browser e riapre ogni documento così: chi scrive in Markdown grezzo e chi vuole vedere le intestazioni renderizzate non devono mai discuterne né rimetterla a posto su ogni pagina.

Le cartelle sono una riga nell'albero

Creare una cartella era prima una finestra di dialogo a sé: un riquadro, un campo di testo, un bottone Crea e nessun indizio su dove la cartella stesse per comparire.

Ora, cliccando l'icona della cartella nell'intestazione dell'albero si apre una riga modificabile esattamente dove la cartella vivrà, con il rientro giusto e l'icona della cartella già disegnata. Scrivi il nome, premi Enter, ed esiste. Escape annulla. Chiedi una sottocartella dal menu di una cartella e quella superiore si espande e la riga compare al suo interno.

Rinominare funziona allo stesso modo, nella riga. Spostare pagine e cartelle resta drag and drop.

Non puoi cliccare via dal lavoro non salvato

Ogni movimento dentro il workspace della documentazione passa da un unico guardiano: selezionare un'altra pagina nell'albero, iniziare una pagina nuova, aprirne un'altra in modifica, annullare e uscire dall'editor. Se la bozza ha modifiche non salvate, l'azione viene trattenuta e prima ricevi una conferma, con Continua a modificare come via d'uscita e Scarta modifiche come scelta deliberata. Appena confermi, parte l'azione che avevi chiesto all'inizio.

Anche il browser è coperto. Chiudere la scheda con una bozza non salvata fa comparire l'avviso del browser stesso.

È il cambiamento meno visibile della release e quello che difenderei con più forza. Un albero di pagine cliccabili accanto a un editor è un buon layout solo se cliccare non può costarti un paragrafo.

L'indice segue il pannello, non la finestra

Quando la colonna è abbastanza larga, le intestazioni della pagina stanno in una barra sticky alla destra del testo, con la sezione corrente evidenziata mentre scorri. Quando è troppo stretta per una barra, si richiudono in un popover Contenuti nella barra degli strumenti.

Il passaggio tra le due è guidato dalla larghezza del pannello, non da quella della finestra del browser. La distinzione è tutto il punto: la colonna dei doc condivide il suo spazio con l'albero, quindi un monitor da 27 pollici con l'albero aperto è una finestra larga attorno a una colonna di lettura stretta. Un breakpoint basato sulla finestra ci metterebbe una barra e schiaccerebbe la prosa. Le container query di Tailwind 4 fanno sì che il pannello si misuri da solo.

Cliccare un'intestazione fa scorrere l'articolo, e solo l'articolo. La barra scorre la propria lista per tenere in vista la voce attiva senza spostarti il documento sotto gli occhi.

Cosa è uscito dalla pila

Quattro componenti sono stati cancellati del tutto in questa release: la modale del documento, la modale di creazione cartella, la vecchia sidebar dell'indice e una pagina di documentazione a lista di card che non veniva più renderizzata da nulla.

L'editor Markdown è sempre @uiw/react-md-editor, ma il suo stile ora arriva dagli stessi design token del resto di Archyl. Chiaro e scuro sono un unico insieme di regole invece di un blocco di override per tema appoggiato sopra quello della libreria.

Gli allegati non cambiano e funzionano esattamente come prima: rilascia un file sull'editor, incolla uno screenshot, oppure usa Allega. Le immagini si inseriscono nel testo, tutto il resto atterra nel pannello degli allegati, e il contatore della graffetta nell'intestazione della pagina ti ci porta con un salto. La storia completa è in Trascina, rilascia, fatto: i file arrivano nei doc di Archyl.

Perché mettersi a ridisegnare una casella di testo

Il compito di Archyl è tenere il modello di architettura fedele al codice, e la discovery fa quella parte da sola. La prosa attorno al modello non riceve nessun aiuto del genere. L'ADR che spiega perché la queue è lì, la pagina di onboarding, il runbook: quelli restano veri solo perché qualcuno continua a scriverli, e le persone scrivono meno quando la superficie di scrittura le combatte.

Una modale era una piccola tassa riscossa proprio ogni volta. Non c'è più.

Accedi, apri Docs su un progetto qualsiasi e premi E su una pagina. Non c'è niente da attivare e nessun passaggio di migrazione: le tue pagine, cartelle e allegati sono dove li hai lasciati. La guida della funzionalità è su Documentazione e ADR.