Update docs

Author: jho406

docs/configuration.md

@@ -2,15 +2,37 @@ You've installed Superglue and now you're ready to configure your app.
 
 ## `application.js`
 
-This is the entry point of your application and uses Superglue's `createApp`
-function. You can add a custom layout here.
+This is the entry point of your application. You can add a custom layout here.
 
 ```tsx
-<Provider>
-  <MyLayout>
-    <Outlet />
-  </MyLayout>
-</Provider>
+import { createApp } from "@thoughtbot/superglue";
+
+...
+
+const { Provider, Outlet, ujs } = createApp({
+    // The base url prefixed to all calls made by `visit` and `remote`.
+    baseUrl: location.origin,
+    // The global var SUPERGLUE_INITIAL_PAGE_STATE is set by your erb
+    // template, e.g., index.html.erb
+    initialPage: window.SUPERGLUE_INITIAL_PAGE_STATE,
+    // The initial path of the page, e.g., /foobar
+    path: location.pathname + location.search + location.hash,
+    // Callback used to setup visit and remote
+    buildVisitAndRemote,
+    // Mapping between the page identifier to page component
+    mapping: pageIdentifierToPageComponent,
+  });
+
+  const root = createRoot(appEl);
+  root.render(
+    <div onClick={ujs.onClick} onSubmit={ujs.onSubmit}>
+      <Provider>
+        <MyLayout>
+          <Outlet />
+        </MyLayout>
+      </Provider>
+    </div>,
+  );
 ```
 
 ## `page_to_page_mapping.js`
@@ -61,7 +83,7 @@ submission to replace history instead of the usual push.
 ```js
   const navigationAction = !!dataset?.sgReplace
     ? "replace"
-    : meta.navigationAction
+    : result.navigationAction
 ```
 
 This is where you'll add [progress bars], error handling, custom UJS attributes,

docs/page-response.md

@@ -59,19 +59,8 @@ The parts of your page that have been marked for [deferment](./deferments.md).
 
 ### `assets`
 An `array` of asset fingerprint `string`s. Used by Superglue to detect the need to
-refresh the browser due to new assets. You can control the refresh behavior in
-`application_visit.js`:
-
-```js
-/**
-  * The assets fingerprints changed, instead of transitioning
-  * just go to the URL directly to retrieve new assets
-  */
-if (meta.needsRefresh) {
-  window.location.href = meta.pageKey
-  return meta
-}
-```
+refresh the browser due to new assets. When Superglue detects that the assets have
+changed, it automatically performs a full page reload to retrieve the new assets.
 
 ### `csrfToken`
 The authenticity token that Superglue will use for non-GET request made by using

docs/recipes/progress-bar.md

@@ -14,8 +14,8 @@ And make the following edits to `application_visit.js`
 ````diff
 + import { requestStripe } from 'request-stripe';
 
-export function buildVisitAndRemote({navigateTo, visit, remote}) {
-  const appRemote = (path, {dataset, options} = {}) => {
+export const buildVisitAndRemote = ({navigateTo, visit, remote}) => {
+  const appRemote = (path, {dataset, ...options} = {}) => {
     /**
      * You can make use of `dataset` to add custom UJS options.
      * If you are implementing a progress bar, you can selectively
@@ -31,49 +31,25 @@ export function buildVisitAndRemote({navigateTo, visit, remote}) {
      */
 +   const done = requestStripe()
     return remote(path, options)
-+       .finally(() => done())
++     .finally(() => done())
   }
 
   const appVisit = (path, {dataset, ...options} = {}) => {
 +   const done = requestStripe()
     return visit(path, options)
-      .then((meta) => {
-        if (meta.needsRefresh) {
-          window.location = meta.url
-          return
-        }
-
-        navigateTo(meta.pageKey, {
-          action: meta.navigationAction,
+      .then(result => {
+        const navigationAction = !!dataset?.sgReplace
+          ? "replace"
+          : result.navigationAction
+        navigateTo(result.pageKey, {
+          action: navigationAction,
         })
 
-        return meta
+        return result
       })
       .finally(() => {
 +       done()
       })
-      .catch((err) => {
-        const response = err.response
-
-        if (!response) {
-          console.error(err)
-          return
-        }
-
-        if (response.ok) {
-          window.location = response.url
-        } else {
-          if (response.status >= 400 && response.status < 500) {
-            window.location = '/400.html'
-            return
-          }
-
-          if (response.status >= 500) {
-            window.location = '/500.html'
-            return
-          }
-        }
-      })
   }
 
   return { visit: appVisit, remote: appRemote }

docs/recipes/ssr.md

@@ -139,12 +139,13 @@ Change your `application.js` to use `hydrateRoot`:
 
 and change the rest of `application.js` accordingly. For example:
 
-```js
+```jsx
 import React from 'react';
 import { createApp } from '@thoughtbot/superglue';
 import { hydrateRoot } from 'react-dom/client';
 import { buildVisitAndRemote } from './application_visit';
 import { pageIdentifierToPageComponent } from './page_to_page_mapping';
+import { Layout } from './components';
 
 if (typeof window !== "undefined") {
   document.addEventListener("DOMContentLoaded", function () {
@@ -161,7 +162,13 @@ if (typeof window !== "undefined") {
       })
 
       hydrateRoot(appEl,
-        <Provider><Outlet /></Provider>
+        <div onClick={ujs.onClick} onSubmit={ujs.onSubmit}>
+          <Provider>
+            <Layout>
+              <Outlet />
+            </Layout>
+          </Provider>
+        </div>
       );
     }
   });

docs/recipes/turbo.md

@@ -10,14 +10,13 @@ In your `application_visit.js` file:
 
 + import { urlToPageKey } from '@thoughtbot/superglue'
 
-const appVisit = (...args) => {
+  const appVisit = (path, {dataset, ...options} = {}) => {
++   const pageKey = urlToPageKey(path)
++   // attempt to navigate first
++   navigateTo(pageKey)
 
-  const pageKey = urlToPageKey(args[0])
-+ // attempt to navigate first
-+ navigateTo(pageKey)
-
-  return visit(...args)
-    ....
+    return visit(path, options)
+      ....
 ```
 
 This is different from [restore strategy] which controls what happens

docs/runtime-types.md

@@ -3,9 +3,7 @@
 End-to-end typing is a common way to ensure correctness across the frontend
 and backend, but it's not the only way. Tools like Typelizer annotate types in
 Ruby and regenerate them in TypeScript, but now you're learning two different
-type languages and wondering how one maps to the other. TypeScript is just so
-much more expressive. It has union types, mapped types, conditional types, and
-generics that Ruby's type systems can't match.
+type languages and wondering how one maps to the other. 
 
 Superglue takes a different approach, a typescript first approach. Instead of
 end-to-end typing, we use
@@ -15,10 +13,9 @@ what the component needs (a header, a list of posts, each with a title and
 body) via `useContent<T>()`. Then you build the props template to fulfill it.
 The UI shape comes first, the business logic follows.
 
-You can use any runtime type validation library you like. Superglue includes
-experimental support for [Deepkit](https://deepkit.io/), which validates your
-server responses against your TypeScript types during development. Write the
-type, load the page, and the errors will guide you.
+Superglue ships an experimental [Deepkit](https://deepkit.io/) plugin that
+validates your server responses against your TypeScript types during
+development. Write the type, load the page, and the errors will guide you.
 
 ## Getting started with Deepkit
 
@@ -28,27 +25,42 @@ To get started, run the installation generator with the typescript flag.
 rails g superglue:install --typescript
 ```
 
-The installation generator will add
+The installation generator will ask if you'd like to enable Deepkit and set up
+the build plugin for your bundler. If you prefer to set it up manually, add the
+plugin to your build config:
 
-1. a [esbuild plugin](https://github.com/thoughtbot/superglue_rails/blob/af7edd35d3ed211822663ac21a5c9910abcc6d88/lib/generators/superglue/install/templates/esbuild/plugin.js) that enables deepkit to work with Superglue
-2. a [build.mjs](https://github.com/thoughtbot/superglue_rails/blob/af7edd35d3ed211822663ac21a5c9910abcc6d88/lib/generators/superglue/install/templates/ts/build.mjs), a esbuild node script that builds your application.
-3. And setup deepkit to work with esbuild. If you are using [vite](./recipes/vite.md) or bun with superglue, please use [deepkit/vite](https://deepkit.io/en/documentation/package/vite) or [deepkit/bun](https://deepkit.io/en/documentation/package/bun) plugins.
+```javascript
+// esbuild
+import { esbuild as deepkitPlugin } from '@thoughtbot/superglue/deepkit'
 
-## How It Works
+// vite
+import { vite as deepkitPlugin } from '@thoughtbot/superglue/deepkit'
 
-Deepkit provides runtime type validation during development:
+// webpack
+const { webpack: deepkitPlugin } = require('@thoughtbot/superglue/deepkit')
+```
 
-1. **Build Time**: Deepkit's compiler transforms TypeScript types into runtime validation code
-2. **Development Mode**: `useContent()` validates server responses against your types
-3. **Production Mode**: Validation code is stripped entirely
+Then include it conditionally in your plugins array:
+
+```javascript
+plugins: isDev ? [deepkitPlugin()] : []
+```
+
+## How It Works
+
+The Superglue Deepkit plugin transforms `useContent<T>()` and
+`useFragment<T>()` calls to inject a `validate` callback via AST
+transformation. Deepkit's compiler generates the runtime type metadata.
+When the page loads, the hooks validate server responses against your
+types and log errors to the console.
 
 ## Writing your types
 
 `useContent` is the generic hook used to access the props [you
 build](shaping.md). To make use of runtime types, simply pass a type
-describing your page's props as you normally would: 
+describing your page's props as you normally would:
 
-For example: 
+For example:
 
 ```tsx
   import React from 'react'
@@ -71,7 +83,7 @@ For example:
     return (
       <div>
         <h1>{header}</h1>
-        
+
         <ul>
           <li>{post.id}</li>
           <li>{post.title}</li>
@@ -96,4 +108,4 @@ json.post do
   json.title "This is a title"
   json.content "This is a body"
 end
-```
+```

mkdocs.yml

@@ -114,7 +114,6 @@ nav:
       - Client-Side updates: client-updates.md
       - Digging: digging.md
       - Deferments: deferments.md
-      - Redux: redux.md
 
     - Navigating:
       - The return of Rails UJS: ujs.md