# YPY > YPY is a hypermedia framework: HTML attributes ask the server for HTML and say where the answer goes. One script, no build step, no dependency. Version 0.1.1, MIT licence. Source code: https://github.com/ypy-develop/ypy ## Docs - [Docs](https://ypy.dev/docs): One page on YPY, from the first attribute to security and configuration: install it, make requests, swap HTML, handle errors and history, serve it. - [Reference](https://ypy.dev/reference): Every YPY attribute, CSS class, header, event, JavaScript method, setting and extension in one place, generated from the same table of names the library uses. - [Migration from the older library](https://ypy.dev/migration): Move a project written for the older library to YPY: the path, what is different, the ypy migrate conversion and the ypy check worklist, rule by rule. ## Examples - [Examples](https://ypy.dev/examples): Interface patterns built with YPY attributes, from click to edit to infinite scroll, each with the HTML, what the server answers and a demo you can use. - [Click to edit](https://ypy.dev/examples/click-to-edit): Show a contact as text, swap in an edit form on click, and swap the text back after Save or Cancel, with no page reload and no script of your own. - [Bulk update](https://ypy.dev/examples/bulk-update): Tick rows in a table, press Activate or Deactivate, and one request updates every ticked row and shows a message, with no page reload. - [Click to load](https://ypy.dev/examples/click-to-load): A table shows five orders and a Load more button. Each click adds the next five rows and moves the button down, until the list ends. - [Delete row](https://ypy.dev/examples/delete-row): Ask for confirmation, send a DELETE request for one table row, and remove that row from the page when the server says it is gone. - [Edit row](https://ypy.dev/examples/edit-row): A table row turns into inputs on Edit and back into text on Save or Cancel, and the server checks the values before it keeps them. - [Lazy loading](https://ypy.dev/examples/lazy-loading): Draw the page at once with a placeholder, then load a slow report on its own request and swap it in when it is ready, with no script of your own. - [Inline validation](https://ypy.dev/examples/inline-validation): Check an email address on the server when the visitor leaves the field, show the message under it, and check the whole form again on submit. - [Active search](https://ypy.dev/examples/active-search): Filter a table while the visitor types, with a short delay between keystrokes, and show a message when nothing matches the search. - [Infinite scroll](https://ypy.dev/examples/infinite-scroll): Fetch the next page of rows when the last row scrolls into view. Each answer carries its own next trigger, so the server decides when to stop. - [Progress bar](https://ypy.dev/examples/progress-bar): Start a job with a button, then let each answer ask for the next progress value after a short delay, until the server answers that the job is done. - [Dependent selects](https://ypy.dev/examples/value-select): Fill a model select from the make chosen in the first one: the server returns the options and owns the rule that links the two. - [Animations](https://ypy.dev/examples/animations): Fade a swap in and out, animate a class that changed, or use view transitions. YPY adds classes during a swap and plain CSS does the motion. - [File upload](https://ypy.dev/examples/file-upload): Send a file with a multipart form and fill a progress bar while it uploads, using the ypy-upload extension and a server that reads an ordinary form. - [Keep file inputs after a form error](https://ypy.dev/examples/preserve-file-inputs): Return a 422 with validation errors without clearing the file the user chose, by keeping the file input in place with ypy-preserve. - [Reset the form after a save](https://ypy.dev/examples/reset-user-input): Empty a comment form after a successful save and keep the typed text after a rejection, with a partial that swaps in a fresh form. - [Confirm and prompt](https://ypy.dev/examples/confirm-and-prompt): Ask yes or no with ypy-confirm, or collect a reason with ypy-prompt that reaches the server in a header. A cancel sends no request. - [Dialogs with layers](https://ypy.dev/examples/dialogs-layers): Open a form in a native modal dialog with ypy-layers, keep 422 errors inside it, and close it when the server fires a saved event. - [Tabs](https://ypy.dev/examples/tabs): Tabs that ask the server for one panel at a time, with the strip and the panel updated by a single answer so the selected tab is never stored twice. - [Keyboard shortcuts](https://ypy.dev/examples/keyboard-shortcuts): Start a request from Alt+N or the slash key with a ypy-trigger event filter, or use the HTML accesskey attribute when you want no script at all. - [Drag and drop sorting](https://ypy.dev/examples/drag-and-drop-sort): Reorder a task list by dragging or with Space and the arrow keys. One POST saves the whole order, and a failed save puts the list back. - [Updating other content](https://ypy.dev/examples/updating-other-content): Update the cart, the item count and a message from one response, with partials, a retarget header, or an event that the server fires. - [Session expired](https://ypy.dev/examples/session-expired): Send the user to the sign-in page with a YPY-Redirect header when a background request finds the session gone, or keep the page and show a 401 message. - [Live updates](https://ypy.dev/examples/live-updates): A chat room where every open page receives new messages over one ypy-stream response, and a reconnecting page gets the current state first. - [Optimistic UI](https://ypy.dev/examples/optimistic-ui): Show a like, a comment or a deleted row before the server answers, and restore the page if the request fails, with ypy-optimistic. - [Polling](https://ypy.dev/examples/polling): Poll a background job every second, let the server change the interval, and stop the polling with a 286 status when the job is done. ## Extensions - [Extensions](https://ypy.dev/extensions): The 48 official YPY extensions: what each one adds to the core, how to load them, how to restrict which ones may run and how to write your own. - [Alpine.js: the ypy-alpine-compat extension](https://ypy.dev/extensions/alpine-compat): Keeps Alpine.js state alive across a YPY swap or a restored page by moving it from the old node to the new one. Needed only when both run on one page. - [Start-up and dependencies: the ypy-boot extension](https://ypy.dev/extensions/boot): Checks dependencies between extensions, fires ypy:ready once, makes ypy-ignore work on live elements and moves keyboard focus to the #fragment of a request. - [Browser loading indicator: the ypy-browser-indicator extension](https://ypy.dev/extensions/browser-indicator): Shows the browser's own tab spinner and stop button while a YPY request runs, using the Navigation API. Does nothing where the API is missing. - [Cache with revalidation: the ypy-cache extension](https://ypy.dev/extensions/cache): Shows the saved copy of a response at once, asks the server whether it is still current and swaps again only if it is not (stale-while-revalidate). - [Client commands from the server: the ypy-commands extension](https://ypy.dev/extensions/commands): The server sends small client-side effects (highlight a row, move focus, hide a banner, fire an event) in one YPY-Commands header, from a fixed set. - [Content Security Policy: the ypy-csp extension](https://ypy.dev/extensions/csp): Strips ypy attributes from markup that carries no page nonce, enforces Trusted Types and runs author code without unsafe-eval, so a strict CSP stays strict. - [CSRF token on every request: the ypy-csrf extension](https://ypy.dev/extensions/csrf): Sends the CSRF token from one meta tag with every request except GET and HEAD to your own origin, so no element can fail with a silent 403. - [One request for identical GETs: the ypy-dedupe extension](https://ypy.dev/extensions/dedupe): Joins identical GET requests that are in flight at the same moment into one network request and gives every element the same answer. - [Development mode: the ypy-dev extension](https://ypy.dev/extensions/dev): For development only: errors that name the element and request, a latency and offline simulator, warnings for markup that does nothing, an error overlay. - [Disable while loading: the ypy-disable extension](https://ypy.dev/extensions/disable): Disables buttons and fields, or makes the target inert, while a request runs, so a visitor cannot send the same form twice. - [File downloads: the ypy-download extension](https://ypy.dev/extensions/download): Reads a response as a stream, reports progress events for a progress bar and hands the finished file to the browser as a download. - [Author code without eval: the ypy-expr extension](https://ypy.dev/extensions/expr): Parses trigger filters, ypy-on handlers and js: values itself, so author code runs under script-src 'self' without eval or new Function. - [Page head: the ypy-head extension](https://ypy.dev/extensions/head): When YPY swaps the body for a full page, merges that page's title, styles and scripts into the current head. A head inside a fragment is never merged. - [Pages kept for back and forward: the ypy-history-cache extension](https://ypy.dev/extensions/history-cache): Saves a snapshot of each page in sessionStorage so back and forward show it at once with no request, keeping typed values and scroll position. - [The inspector: the ypy-inspector extension](https://ypy.dev/extensions/inspector): A floating panel for development that records requests, swaps, ypy events, signals and stream events as they happen. Open it with Alt+Shift+Y. - [Layers: the ypy-layers extension](https://ypy.dev/extensions/layers): Modals, drawers and popups on the native element, themed with CSS variables and never writing a style attribute, so it runs under a strict CSP. - [Regions that load when seen: the ypy-lazy extension](https://ypy.dev/extensions/lazy): Leaves a placeholder in the page and loads the real content only when it nears the viewport, so visitors who never scroll there never request it. - [Keyed and bounded lists: the ypy-list extension](https://ypy.dev/extensions/list): Adds the key and limit modifiers to append and prepend swaps: an item that arrives twice replaces its copy, and the list stops growing past a set size. - [Live expressions: the ypy-live extension](https://ypy.dev/extensions/live): Binds an element to values read from the page. The expression runs again whenever the DOM, an input or a swap may have changed those values. - [Configuration lock: the ypy-lock extension](https://ypy.dev/extensions/lock): Freezes the security settings of YPY once the page has chosen them, so a script that runs later, including an injected one, cannot change them. - [Model answers: the ypy-model extension](https://ypy.dev/extensions/model): The page side of a streamed language-model answer: an untrusted container, screen reader announcements, and controls to follow and stop it. - [Multipart responses: the ypy-multipart extension](https://ypy.dev/extensions/multipart): Reads a multipart/mixed response part by part and swaps each part as it arrives, so one HTTP response can carry a series of page updates. - [Native app bridge: the ypy-native extension](https://ypy.dev/extensions/native): The web half of a native shell: a page in an iOS, Android or desktop web view talks to the app, so native navigation and titles can replace page parts. - [Navigation](https://ypy.dev/extensions/nav): Boost every link and form, prefetch before the click, mark the current link, draw a progress bar, keep elements across pages and detect a new deploy. - [Optimistic UI: the ypy-optimistic extension](https://ypy.dev/extensions/optimistic): Shows the result of an action before the server answers and puts the page back if the request fails: a like, a new comment, a deleted row. - [Placeholder while loading: the ypy-pending extension](https://ypy.dev/extensions/pending): Puts a skeleton or spinner from a template into the target while a request runs, and removes it just before the swap, so nothing is left behind. - [Persistent elements and deploy detection: the ypy-persist extension](https://ypy.dev/extensions/persist): Keeps a video, player or widget alive across boosted navigations, and reloads the page when a new deploy changes the assets. - [Smart polling: the ypy-poll extension](https://ypy.dev/extensions/poll): Polling that slows down in a background tab, lets the server pick the next interval and lets the server end the polling. - [Preload: the ypy-preload extension](https://ypy.dev/extensions/preload): Starts a GET on mousedown or touchstart, before the click finishes, and reuses the answer when the real request has the same URL. - [Keep what the visitor did: the ypy-preserve extension](https://ypy.dev/extensions/preserve): Keeps typed text, caret, focus and scroll of fields and containers through a swap, and holds the swap while an input method is still composing. - [Progress bar: the ypy-progress extension](https://ypy.dev/extensions/progress): A thin bar along the top of the page while a boosted navigation or an element's request waits for the server. It needs no CSS. - [Ask before sending: the ypy-prompt extension](https://ypy.dev/extensions/prompt): Asks the visitor one question before the request, sends the answer in the YPY-Prompt header, and sends nothing if they cancel. - [Skip unchanged polls: the ypy-ptag extension](https://ypy.dev/extensions/ptag): The server tags each polled fragment and the client sends the tag back, so the server can answer 304 when nothing changed and the swap is skipped. - [ypy-retry](https://ypy.dev/extensions/retry): Repeats a request that could not reach the server, and with on:error also one answered with a 5xx. Off until the extension is loaded. - [Selectors by area: the ypy-scope extension](https://ypy.dev/extensions/scope): Three selectors, scope, layer and shadow, for ypy-target, ypy-indicator, ypy-include and ypy.find(), relative to the element that asks. - [Signals: the ypy-signals extension](https://ypy.dev/extensions/signals): Client state without a build step or eval: named signals bound to inputs and read by attributes, which the server reads and patches as JSON. - [Reorder a list by hand: the ypy-sort extension](https://ypy.dev/extensions/sort): Lets a person reorder a list by dragging or with the keyboard, and sends the new order of the item ids to the server in one request. - [Server-Sent Events: the ypy-sse extension](https://ypy.dev/extensions/sse): Opens an event stream from an element, swaps each unnamed message into the page, turns named messages into DOM events and reconnects when it drops. - [Streaming: the ypy-stream extension](https://ypy.dev/extensions/stream): The client of the YPY streaming protocol: one long response that patches HTML and signals, redirects, fires events and reconnects by itself. - [Show or hide part of a form by a field: the ypy-switch extension](https://ypy.dev/extensions/switch): Shows or hides part of a form from the value of another field, with no request. Hidden fields are disabled, so they are not submitted. - [One response, many elements: the ypy-targets extension](https://ypy.dev/extensions/targets): Swaps one response into every element that matches a selector, such as a counter shown in both the header and the sidebar of a page. - [Every failure in one place: the ypy-telemetry extension](https://ypy.dev/extensions/telemetry): Reports every client failure (no answer, a 5xx, a missing target, a refused swap, a lost connection) in one shape for an error tracker or a log. - [Waiting for the page in browser tests: the ypy-test extension](https://ypy.dev/extensions/test): Gives browser tests ypy.idle(), a promise that resolves when no request, swap or timer is pending, and data-ypy-busy on html while work runs. - [View transitions: the ypy-transitions extension](https://ypy.dev/extensions/transitions): Runs each swap inside the browser's View Transitions API, queued one after another, with events you can hook into to prepare or clean up. - [Upload progress: the ypy-upload extension](https://ypy.dev/extensions/upload): Progress for file uploads: sends the request with XMLHttpRequest and fires ypy:upload:progress on the element while the file goes out. - [Update or insert by id: the ypy-upsert extension](https://ypy.dev/extensions/upsert): A swap style for live lists: an item whose id is on the page replaces the old one, a new id is inserted, with an optional sort. - [Field validation on the server: the ypy-validate extension](https://ypy.dev/extensions/validate): Sends the form's values to the server when the user leaves a field and shows the answer next to it, without submitting the form. - [WebSocket: the ypy-ws extension](https://ypy.dev/extensions/ws): Opens a WebSocket from an element, swaps incoming messages into the page and sends form values back over the same connection. ## Essays - [Essays](https://ypy.dev/essays): Seven short essays on why YPY works the way it does: hypermedia, when to use it, progressive enhancement, fragments, one script tag, speed and security. - [Why hypermedia](https://ypy.dev/essays/why-hypermedia): Why YPY keeps the rules and the links on the server and sends HTML fragments, what plain HTML controls cannot do, and where the approach costs you. - [When to use YPY](https://ypy.dev/essays/when-to-use-ypy): Which projects suit YPY, which need care, which should use something else, and a four-question test to decide before you write the first screen. - [Progressive enhancement](https://ypy.dev/essays/progressive-enhancement): Write links and forms that work with the script off, then add YPY attributes so the same elements update part of the page instead of reloading it. - [Template fragments](https://ypy.dev/essays/template-fragments): Define a row, a form or a list once as a named block of your template, then draw it inside the full page and alone as the answer to a YPY request. - [No build step](https://ypy.dev/essays/no-build-step): YPY loads with one script tag and runs the file as shipped. What that saves you, what the core weighs against its budget, and where a bundler still fits. - [Performance](https://ypy.dev/essays/performance): Where a YPY page spends its time: the bytes you ship, the requests you make and the DOM you swap, and the few attributes that reduce each one. - [Security](https://ypy.dev/essays/security): Why attributes that start requests change what an injection can do, and the defaults YPY ships to answer it: escaping, no author code, same origin, CSP. ## Optional - [YPY documentation, in full](https://ypy.dev/llms-full.txt): every page below as plain text - [Documentação do YPY](https://ypy.dev/docs/pt-BR): O YPY é uma biblioteca hipermídia: um elemento HTML diz, em atributos, qual requisição fazer, quando, e onde colocar o HTML que o servidor responde. - [Conceitos centrais](https://ypy.dev/docs/pt-BR/guides/core-concepts): O modelo inteiro cabe numa página: um elemento leva atributos, um gatilho dispara, o YPY faz uma requisição, o servidor responde com HTML e uma troca (swap) coloca o HTML na página. - [Primeiros passos](https://ypy.dev/docs/pt-BR/guides/getting-started): Em dez minutos você terá uma página em que um botão pede HTML ao servidor e a resposta troca um pedaço da página. Há dois caminhos de entrada, e os dois chegam ao mesmo lugar: - [Guia de migração: de marcação legada para o YPY](https://ypy.dev/docs/pt-BR/guides/migration): Levar um projeto escrito antes do YPY leva minutos para converter e uma revisão para terminar. - [Checklist de segurança](https://ypy.dev/docs/pt-BR/guides/security-checklist): Percorra esta lista antes de publicar. Cada item é algo que você faz ou verifica; as razões e os ajustes estão em Security (em inglês), e os achados da última revisão estão na auditoria. - [Receita: Arandu (Hesape e Kyse)](https://ypy.dev/docs/pt-BR/recipes/arandu): Como uma aplicação Go feita com o Arandu serve o YPY. O trabalho de rede é do SDK Go, o mesmo da receita Go; - [Receita: Go (net/http)](https://ypy.dev/docs/pt-BR/recipes/go): Um servidor completo com a biblioteca padrão e o SDK Go do YPY: uma página, um formulário que acrescenta um item, um fragmento para o YPY, um 303 para o navegador sem script, um 422 para formulário...