Superglue

https://thoughtbot.github.io/superglue/2.0.alpha/
Admin
Superglue is a Rails framework for building React applications using familiar Rails concepts like...
Tokens:46,596
Snippets:312
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Generate Superglue Scaffold

Source: https://thoughtbot.github.io/superglue/2.0.alpha/installation

Commands to generate a scaffold for a new resource using Superglue. This includes examples for both JavaScript and TypeScript projects.

```bash
rails g superglue:scaffold post body:string

```

```bash
rails g superglue:scaffold post body:string --typescript

```

--------------------------------

### Run Superglue Installation Generator

Source: https://thoughtbot.github.io/superglue/2.0.alpha/installation

Commands to run after adding Superglue to the Gemfile. This includes bundling and running the installation generator, with an option for TypeScript.

```bash
bundle
rails g superglue:install

```

```bash
rails g superglue:install --typescript

```

--------------------------------

### Setup Superglue Application

Source: https://thoughtbot.github.io/superglue/2.0.alpha/reference

Demonstrates the `setup` function, the primary entry point for initializing a Superglue application. It returns core components for navigation, remote data handling, and state management.

```typescript
const { visit, remote, nextHistory, initialPageKey, ujs, streamActions } = setup({
  // ... setup props
})

```

--------------------------------

### Seed Database and Start Development Server

Source: https://thoughtbot.github.io/superglue/2.0.alpha/tutorial

Executes the database seeding script to populate the application with sample data and then starts the development server to make the application accessible via `http://localhost:3000`.

```bash
rails db:seed
bin/dev

```

--------------------------------

### setup() Function

Source: https://thoughtbot.github.io/superglue/2.0.alpha/reference

The primary setup function for a Superglue application. It initializes core components like visit, remote, history, UJS handlers, and stream actions.

```APIDOC
## setup() Function

### Description
The primary setup function for a Superglue application. It initializes core components like visit, remote, history, UJS handlers, and stream actions. Use this function if you need to build a custom Application component.

### Parameters
- `__namedParameters` (SetupProps) - Required - An object containing setup configurations.
  - `visit`: ApplicationVisit
  - `remote`: ApplicationRemote
  - `nextHistory`: History
  - `initialPageKey`: string
  - `ujs`: Handlers (optional, defaults to `handlers`)
  - `streamActions`: StreamActions

### Returns
An object containing:
- `visit`: `ApplicationVisit`
- `remote`: `ApplicationRemote`
- `nextHistory`: `History`
- `initialPageKey`: `string`
- `ujs`: `Handlers`
- `streamActions`: `StreamActions`
```

--------------------------------

### Superglue Digging with URL Example

Source: https://thoughtbot.github.io/superglue/2.0.alpha/digging

Shows a URL example for fetching a specific node ('data.header.search') using the 'props_at' parameter, along with another query parameter.

```URL
/dashboard?props_at=data.header.search&some_search_str=haircuts

```

--------------------------------

### Install Candy Wrapper

Source: https://thoughtbot.github.io/superglue/2.0.alpha/candy-wrapper

Installs the candy_wrapper package as a development dependency using npm.

```bash
npm install -D candy_wrapper

```

--------------------------------

### Nested Deferments Example (Ruby)

Source: https://thoughtbot.github.io/superglue/2.0.alpha/tutorial

This example demonstrates how to apply `defer: :auto` to nested JSON objects within a `metrics` block. It shows the flexibility of Superglue in handling performance optimizations for deeply nested data structures.

```ruby
json.metrics do 
  json.visits(defer: :auto) do
    json.total(defer: :auto) do
    end
    json.average(defer: :auto) do
    end
  end
end


```

--------------------------------

### Install PropsTemplate Gem

Source: https://thoughtbot.github.io/superglue/2.0.alpha/props-template

Shows how to add the PropsTemplate gem to your Rails project's Gemfile and install it using Bundler.

```ruby
gem 'props_template'


```

--------------------------------

### Install Source Map Support (Yarn)

Source: https://thoughtbot.github.io/superglue/2.0.alpha/humid

Install the 'source-map-support' package using Yarn for source-map debugging capabilities.

```bash
yarn add source-map-support
```

--------------------------------

### Superglue Digging with Collections (Index-based URL)

Source: https://thoughtbot.github.io/superglue/2.0.alpha/digging

Provides a URL example for fetching collection details using an index in the 'props_at' parameter.

```URL
remote('/dashboard?props_at=data.posts.0.details')

```

--------------------------------

### Superglue Digging with Partials

Source: https://thoughtbot.github.io/superglue/2.0.alpha/digging

Shows how to query into partials using the 'props_at' parameter. This example fetches details of posts from a partial named 'list_of_posts'.

```Ruby
remote('/dashboard?props_at=data.posts.some_id=1.details')

```

```Ruby
json.data(dig: params[:props_at]) do
  json.posts(partial: 'list_of_posts')do
  end
end

```

```Ruby
# list_of_posts.json.props
json.array! @posts , key: :some_id do |post|
  json.details do
    json.title post.title
  end

  # The following will be auto appended by the key: option
  # json.some_id post.some_id
end

```

--------------------------------

### Manual refresh button with props_at

Source: https://thoughtbot.github.io/superglue/2.0.alpha/tutorial

This example shows how to create a button that refreshes a specific part of the screen using the `props_at` attribute with Superglue's remote data fetching.

```html
<button>
  <a href="/shopping_list?props_at=data.totalCost" data-sg-remote>
    Refresh Cost
  </a>
</button>
```

```html
<a href="/shopping_list?props_at=data.items" data-sg-remote>
  Refresh List
</a>
```

--------------------------------

### Install Source Map Support in Entry File

Source: https://thoughtbot.github.io/superglue/2.0.alpha/humid

Include the source-map-support installation in your JavaScript entry file to enable source map retrieval for debugging.

```javascript
require("source-map-support").install({
  retrieveSourceMap: filename => {
    return {
      url: filename,
      map: readSourceMap(filename)
    };
  }
});
```

--------------------------------

### Superglue Digging with Collections (Attribute-based URL)

Source: https://thoughtbot.github.io/superglue/2.0.alpha/digging

Provides a URL example for fetching collection details using an attribute-based key in the 'props_at' parameter.

```URL
remote('/dashboard?props_at=data.posts.some_id=1.details')

```

--------------------------------

### Install Mantine Dependencies

Source: https://thoughtbot.github.io/superglue/2.0.alpha/candy-wrapper

Installs necessary libraries for using Mantine wrappers with Candy Wrapper: dayjs, @mantine/core, and @mantine/dates.

```bash
yarn add dayjs
yarn add @mantine/core
yarn add @mantine/dates

```

--------------------------------

### Example Form Payload

Source: https://thoughtbot.github.io/superglue/2.0.alpha/candy-wrapper

An example of the JSON payload generated by the form_props helper, detailing form properties, extras, and input configurations.

```json
{
  "someForm": {
    "props": {
      "id": "create-post",
      "action": "/posts/123",
      "acceptCharset": "UTF-8",
      "method": "post"
    },
    "extras": {
      "method": {
        "name": "_method",
        "type": "hidden",
        "defaultValue": "patch",
        "autoComplete": "off"
      },
      "utf8": {
        "name": "utf8",
        "type": "hidden",
        "defaultValue": "\u0026#x2713;",
        "autoComplete": "off"
      },
      "csrf": {
        "name": "utf8",
        "type": "authenticity_token",
        "defaultValue": "SomeTOken!23$",
        "autoComplete": "off"
      }
    },
    "inputs": {
      "title": {"name": "post[title]", "id": "post_title", "type": "text", "defaultValue": "hello"},
      "submit": {"type": "submit", "value": "Update a Post"}
    }
  }
}

```

--------------------------------

### Add Superglue to Gemfile

Source: https://thoughtbot.github.io/superglue/2.0.alpha/installation

This snippet shows how to add the Superglue gem to your project's Gemfile. Ensure you are using the specified alpha version.

```ruby
# Gemfile
gem "superglue", "2.0.0.alpha.8"

```

--------------------------------

### Install Humid Gem

Source: https://thoughtbot.github.io/superglue/2.0.alpha/humid

Add the Humid gem to your Gemfile to include it in your Rails project.

```ruby
gem 'humid'
```

--------------------------------

### Rails Routes and Controller Example

Source: https://thoughtbot.github.io/superglue/2.0.alpha/index

Defines a resource route for posts and a controller action to display a single post. It uses Rails conventions for routing and controller logic.

```ruby
resource :posts
```

```ruby
class PostsController < ApplicationController
  def show
    @post = Post.find(params[:id])
  end

  def update
    @post = Post.find(params[:id])
    @post.body = "Updated" #no save

    redirect_back fallback_location: root_path
  end
end
```

--------------------------------

### Superglue Digging with props_at Parameter

Source: https://thoughtbot.github.io/superglue/2.0.alpha/digging

Demonstrates how to use the 'props_at' parameter to selectively fetch parts of a page. This example shows fetching the 'search' node from a PropsTemplate.

```Ruby
path = param_to_dig_path(params[:props_at])
json.data(dig: path) do
  json.header do
    json.search do
      # Results is a leaf node
      json.results Post.search(params[:some_search_str])
    end
  end

  json.content do
    json.barChart do
       ...bar chart data
    end

    ...
  end

  ...
end

```

--------------------------------

### Rails Directory Structure Example

Source: https://thoughtbot.github.io/superglue/2.0.alpha/rails-utils

Illustrates a typical directory structure for Superglue templates in a Rails application, including duplicated index files and specific JSX and JSON.props files.

```erb
app/views/
  posts/
    index.html.erb # duplicated
    index.jsx
    index.json.props
  users/
    index.html.erb # duplicated
    index.jsx
    index.json.props
```

--------------------------------

### Frontend Data Structure for Superglue

Source: https://thoughtbot.github.io/superglue/2.0.alpha/performance

This example demonstrates the data structure used by Superglue on the frontend, including page-specific data and fragment references for reactive updates.

```json
{
  "pages": {
    "/current-page": {
      "data": {
        "title": "Hello",
        "cart": { "__id": "userCart" }  // Fragment reference
      }
    }
  },
  "fragments": {
    "userCart": {
      "items": [
        { "id": 1, "name": "Widget", "price": 19.99, "quantity": 2 },
        { "id": 2, "name": "Gadget", "price": 29.99, "quantity": 1 }
      ],
      "totalCost": 69.97,
      "itemCount": 3
    }
  }

}
```

--------------------------------

### Implement Digging Support for Collections in PropsTemplate

Source: https://thoughtbot.github.io/superglue/2.0.alpha/props-template

Provides examples of how to make collections compatible with PropsTemplate's digging functionality by implementing `member_at` and `member_by`.

```ruby
class ObjectCollection < SimpleDelegator
  def member_at(index)
    at(index)
  end

  def member_by(attr, val)
    find do |ele|
      ele[attr] == val
    end
  end
end

data = ObjectCollection.new([
  {id: 1, name: 'foo'},
  {id: 2, name: 'bar'}
])

json.array! data do
  # ...
end


```

```ruby
class ApplicationRecord < ActiveRecord::Base
  def self.member_at(index)
    offset(index).limit(1).first
  end

  def self.member_by(attr, value)
    find_by(Hash[attr, val])
  end
end

json.array! Post.all do
  # ...
end


```

--------------------------------

### Deferred Content Request (HTTP)

Source: https://thoughtbot.github.io/superglue/2.0.alpha/tutorial

This snippet represents an HTTP GET request made by Superglue to fetch deferred content. The `props_at=data.totalCost` parameter specifies the exact data to be retrieved after the initial page load, facilitating background updates.

```http
GET /shopping_list?props_at=data.totalCost


```

--------------------------------

### Superglue .props for Page Structure

Source: https://thoughtbot.github.io/superglue/2.0.alpha/shaping

Demonstrates the Superglue .props syntax for representing the same page structure as the ERB example. It shows how to define header information, a list of posts, and menu items using a JSON-like structure.

```ruby
json.header do
  json.email current_user.email
  json.firstName current_user.first_name
end

json.postList do
  json.array! @posts do |post|
    json.title post.title.capitalize
    json.body post.body
  end
end

json.menu do 
  json.homePath root_path
end

```

--------------------------------

### Enabling Layouts in API-only Rails Controllers

Source: https://thoughtbot.github.io/superglue/2.0.alpha/props-template

Provides a Ruby code example for API-only Rails controllers to enable layout support by including `ActionView::Layouts` and specifying a layout file.

```ruby
module Api
  class BaseController < ActionController::API
    include ActionView::Layouts

    layout "api"
  end
end
```

--------------------------------

### Add react-infinite-scroll-hook using Yarn

Source: https://thoughtbot.github.io/superglue/2.0.alpha/recipes/infinite-scroll

Installs the `react-infinite-scroll-hook` package using the Yarn package manager. This is a necessary step before implementing infinite scroll functionality.

```bash
yarn add react-infinite-scroll-hook

```

--------------------------------

### Package.json Build Scripts for Superglue

Source: https://thoughtbot.github.io/superglue/2.0.alpha/recipes/ssr

Provides example build scripts for a package.json file to build both client and server-side rendering (SSR) JavaScript bundles for Superglue using esbuild.

```json
   "build": "yarn run build:web && yarn run build:ssr",
   "build:web": "esbuild app/javascript/application.js --bundle --sourcemap --outdir=app/assets/builds --loader:.js=jsx --loader:.svg=dataurl --public-path=/assets",
   "build:ssr": "node ./build-ssr.mjs",
```

--------------------------------

### Optimistic Navigation with URL Params

Source: https://thoughtbot.github.io/superglue/2.0.alpha/navigation-context

Provides an example of using `navigateTo` in conjunction with `copyPage`, `pageKey`, and `search` for optimistic navigation, such as implementing local faceted search. It illustrates how to update the URL with search parameters and retrieve them after navigation.

```javascript
import { copyPage, NavigationContext } from '@thoughtbot/superglue'
import { myAppDispatch } from '@myJavascript/store'

// In your component somewhere
const { 
  navigateTo,
  pageKey,
  search
} = useContext(NavigationContext)

const nextPageKey = pageKey + "?active=true"
dispatch(copyPage({from: pageKey, to: nextPageKey}))

// On a click handler
navigateTo(nextPageKey, { action: 'push'})

// later after navigation.
console.log(search) // would return {active: "true"}
```

--------------------------------

### ERB Template for Page Structure

Source: https://thoughtbot.github.io/superglue/2.0.alpha/shaping

An example of how to structure page content using ERB, including user email, capitalized first name, a list of posts with titles and bodies, and a menu link. This serves as a baseline for comparison with the Superglue .props approach.

```erb
<header>
  Email: <%= current_user.email %>
  First Name: <%= current_user.first_name.capitalize %> 
</header>

<div>
  <h2>Post List</h2>
  <%- @posts.each do |post| %>
    <div>
      <h3><%= post.title.capitalize %></h3>
      <p><%= post.body %></p>
    </div>
  <% end %>
</div>

<div>
  <h3>Menu</h3>
  <%= link_to "Home", root_path%>
<div>

```

--------------------------------

### Logout Link Example (HTML)

Source: https://thoughtbot.github.io/superglue/2.0.alpha/securing

Demonstrates the correct way to implement a logout link using a standard HTML anchor tag that triggers a full page reload, thus clearing Superglue's in-memory state.

```html
  <a href="/users/logout"> Logout </a>

```

--------------------------------

### Redirecting Back with Props in Rails Controller

Source: https://thoughtbot.github.io/superglue/2.0.alpha/rails-utils

Provides an example of using the `redirect_back_with_props_at` helper in a Rails controller action to maintain the `props_at` parameter during a redirect.

```ruby
def create
  redirect_back_with_props_at fallback_url: '/'
end
```

--------------------------------

### Setting componentIdentifier in application.json.props

Source: https://thoughtbot.github.io/superglue/2.0.alpha/page-response

An example demonstrating how to set the componentIdentifier in application.json.props using the active_template_virtual_path, which guides Superglue in selecting the correct component to render.

```ruby
# application.json.props
json.componentIdentifier active_template_virtual_path

```

--------------------------------

### Create New Rails Project

Source: https://thoughtbot.github.io/superglue/2.0.alpha/tutorial

Initializes a new Rails project with esbuild for JavaScript bundling and skips Hotwire. This sets up the foundational structure for the application.

```bash
rails new shopping_list -j esbuild --skip-hotwire

```

--------------------------------

### Rails Controller Setup for Form Error Flash Messages

Source: https://thoughtbot.github.io/superglue/2.0.alpha/forms

Provides an example of how to set up a Rails controller to capture form errors and store them in `flash.now` for subsequent display in the React frontend. This approach leverages Rails' built-in flash mechanism to pass error data.

```ruby
class PostsController < ApplicationController
  def create
    @post = Post.new(post_params)

    if @post.save
      redirect_to :index
    else
      flash.now[:postFormErrors] = @post.errors.as_json
      render :new
    end
  end
end

```

--------------------------------

### Define Application Routes

Source: https://thoughtbot.github.io/superglue/2.0.alpha/tutorial

Configures the application's routes in `config/routes.rb`, setting the root path to `shopping_lists#show`, and defining show actions for `shopping_list` and `items` resources.

```ruby
Rails.application.routes.draw do
  root 'shopping_lists#show'
  resource :shopping_list, only: [:show]
  resources :items, only: [:show]
end

```

--------------------------------

### prepareStore() Function

Source: https://thoughtbot.github.io/superglue/2.0.alpha/reference

Initializes the Superglue store with the initial page data and path.

```APIDOC
## prepareStore() Function

### Description
Initializes the Superglue store with the initial page data and path.

### Parameters
- `store` (SuperglueStore) - Required - The Superglue store instance.
- `initialPage` (SaveResponse) - Required - The initial page data.
- `path` (string) - Required - The initial path of the application.

### Returns
`void`
```

--------------------------------

### JavaScript for SSR Setup (React)

Source: https://thoughtbot.github.io/superglue/2.0.alpha/recipes/ssr

Configures the React application for server-side rendering by defining a custom renderer using Humid. It includes necessary imports for Superglue, React, and state management, along with source map retrieval for debugging.

```javascript
import React from 'react';
import { Application } from '@thoughtbot/superglue';
import { buildVisitAndRemote } from './application_visit';
import { pageIdentifierToPageComponent } from './page_to_page_mapping';
import { store } from './store'
import { renderToString } from 'react-dom/server';

require("source-map-support").install({
  retrieveSourceMap: filename => {
    return {
      url: filename,
      map: readSourceMap(filename)
    };
  }
});

setHumidRenderer((json, baseUrl, path) => {
  const initialState = JSON.parse(json)
  return renderToString(
    <Application
      className="full-height"
      // The base url prefixed to all calls made by the `visit`
      // and `remote` thunks.
      baseUrl={baseUrl}
      // The global var SUPERGLUE_INITIAL_PAGE_STATE is set by your erb
      // template, e.g., application/superglue.html.erb
      initialPage={initialState}
      // The initial path of the page, e.g., /foobar
      path={path}
      // Callback used to setup visit and remote
      buildVisitAndRemote={buildVisitAndRemote}
      // Callback used to setup the store
      store={store}
      // Mapping between the page identifier to page component
      mapping={pageIdentifierToPageComponent}
    />,
    {
      concurrentFeatures: false,
    }
  )
})
```

--------------------------------

### Shopping List Controller

Source: https://thoughtbot.github.io/superglue/2.0.alpha/tutorial

Defines the `ShoppingListsController` with a `show` action that fetches all 'Item' records from the database.

```ruby
class ShoppingListsController < ApplicationController
  def show
    @items = Item.all
  end
end

```

--------------------------------

### Define Custom Navigation Logic in application_visit.js

Source: https://thoughtbot.github.io/superglue/2.0.alpha/configuration

This snippet demonstrates how to create custom navigation functions for Superglue by exporting a factory that builds remote and visit functions. It allows for intercepting and enhancing Superglue's core navigation, with examples of custom UJS attributes like data-sg-replace.

```javascript
export const buildVisitAndRemote = (ref, store) => {
  // Your custom logic here
  return { visit: appVisit, remote: appRemote }
}
```

```javascript
const navigationAction = !!dataset?.sgReplace
    ? "replace"
    : meta.navigationAction
```

--------------------------------

### Seed Sample Shopping List Data

Source: https://thoughtbot.github.io/superglue/2.0.alpha/tutorial

Populates the database with initial sample data for the shopping list, creating several 'Item' records with different names and completion statuses.

```ruby
# db/seeds.rb
Item.create!([
  { name: "Milk", completed: false },
  { name: "Bread", completed: true },
  { name: "Eggs", completed: false },
  { name: "Apples", completed: false },
  { name: "Cheese", completed: true }
])

```

--------------------------------

### Generate Item Model and Migrate Database

Source: https://thoughtbot.github.io/superglue/2.0.alpha/tutorial

Generates the 'Item' model with 'name' (string) and 'completed' (boolean) attributes and applies the database migrations to create the corresponding table.

```bash
rails generate model Item name:string completed:boolean
rails db:migrate

```

--------------------------------

### Set up ActionCable Subscription in JSON Props

Source: https://thoughtbot.github.io/superglue/2.0.alpha/tutorial

Configures ActionCable subscription properties within a JSON structure. It defines a stream to receive updates for 'shopping'.

```ruby
  json.header do
    json.title "Family Shopping List"
  end

+ # Set up streaming subscription
+ json.streamFromShopping stream_from_props("shopping")

  json.items(partial: ["item_list", fragment: "shopping_list"]) do
  end

  # ... rest remains the same

```

--------------------------------

### Superglue Application Entry Point

Source: https://thoughtbot.github.io/superglue/2.0.alpha/reference

Shows the basic structure of the `Application` component, which serves as the entry point for a Superglue application. It sets up the Redux provider and navigation components.

```typescript
const App = () => (
  <Application />
)

```

--------------------------------

### Broadcasting item creation for streaming (Ruby on Rails)

Source: https://thoughtbot.github.io/superglue/2.0.alpha/tutorial

This `.json.props` file defines how to broadcast an appended item to a specific target (`shopping_list` fragment), creating a new fragment (`item_1`) for the item's content.

```ruby
broadcast_append_props(
  model: @item, 
  save_target: "item_#{@item.id}",
  target: "shopping_list",
  partial: "shopping_lists/item"
)
```

--------------------------------

### Install form_props Gem

Source: https://thoughtbot.github.io/superglue/2.0.alpha/form-props

Add the form_props gem to your Gemfile to include it in your Rails project.

```ruby
gem "form_props"


```

--------------------------------

### Rails form_props Usage with JSON.props

Source: https://thoughtbot.github.io/superglue/2.0.alpha/form-props

Example of using form_props in a new.json.props file to generate form attributes for a model.

```ruby
json.some_form do
  form_props(model: @post) do |f|
    f.text_field :title
    f.submit
  end
end


```

--------------------------------

### Add request-stripe dependency

Source: https://thoughtbot.github.io/superglue/2.0.alpha/recipes/progress-bar

Installs the 'request-stripe' package using Yarn, which is used to implement the progress bar functionality.

```bash
yarn add request-stripe
```

--------------------------------

### Superglue Datetime Field Example

Source: https://thoughtbot.github.io/superglue/2.0.alpha/form-props

Illustrates how to use the `datetime_field` helper in Superglue and the structure of the generated JSON for datetime input properties.

```ruby
form_props(model: @post) do |f|
  f.datetime_field(:created_at)
end
```

```json
{
  "type": "datetime-local",
  "defaultValue": "2004-06-15T01:02:03",
  "name": "post[created_at]",
  "id": "post_created_at"
}
```

--------------------------------

### Enable JSX Rendering Defaults

Source: https://thoughtbot.github.io/superglue/2.0.alpha/tutorial

Configures the application controller to enable JSX rendering defaults, allowing Rails to recognize and process `.jsx` and `.props` files for frontend components.

```ruby
class ApplicationController < ActionController::Base
  before_action :use_jsx_rendering_defaults
end

```

--------------------------------

### Superglue Text Field Example

Source: https://thoughtbot.github.io/superglue/2.0.alpha/form-props

Demonstrates the usage of the `text_field` helper within `form_props` and the resulting JSON output for the input attributes.

```ruby
form_props(model: @post) do |f|
  f.text_field(:title)
end
```

```json
{
  "type": "text",
  "defaultValue": "Hello World",
  "name": "post[title]",
  "id": "post_title"
}
```

--------------------------------

### Superglue Component Initialization

Source: https://thoughtbot.github.io/superglue/2.0.alpha/recipes/ssr

Illustrates how to initialize a Superglue component with various properties like initial page state, path, and callbacks for setting up visits, remotes, and the store.

```javascript
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={buildVisitAndRemote}
          // Callback used to setup the store
          store={store}
          // Mapping between the page identifier to page component
          mapping={pageIdentifierToPageComponent}
        />
      );
    }
  });
```

--------------------------------

### unproxy Function Example

Source: https://thoughtbot.github.io/superglue/2.0.alpha/reference/hooks

Shows how to use the unproxy function to extract the underlying state from a proxy object returned by the useContent hook.

```typescript
const content = useContent()
const rawContent = unproxy(content)
```

--------------------------------

### Updating items list with Super Turbo Stream (Ruby on Rails)

Source: https://thoughtbot.github.io/superglue/2.0.alpha/tutorial

This demonstrates how to update a list of items using Super Turbo Stream. It involves modifying the controller to respond with JSON and updating the `.json.props` files to handle fragments for individual items and the overall list.

```ruby
json.header do
  json.title "Family Shopping List"
end

+ json.items(partial: ["item_list", fragment: "shopping_list"]) do
- json.items do
-   json.array! @items do |item|
-     json.id item.id
-     json.name item.name  
-     json.completed item.completed
-     json.detailPath item_path(item)
-     json.toggleForm do
-       form_props(model: item) do |f|
-         f.submit "Toggle"
-       end
-     end
-   end
  end

  # ... rest remains the same
```

```ruby
json.array!(
  @items, 
  partial: ['item', fragment: ->(item){"item_#{item.id}"}]
  ) do |item|
end
```

```ruby
json.id item.id
json.name item.name  
json.completed item.completed
json.detailPath item_path(item)
json.toggleForm do
  form_props(model: item) do |f|
    f.submit "Toggle"
  end
end
```

--------------------------------

### Shopping List Show JSON Props

Source: https://thoughtbot.github.io/superglue/2.0.alpha/tutorial

Defines the JSON structure for the shopping list's show view, including a header with a title and an array of items with their details and paths.

```ruby
json.header do
  json.title "Family Shopping List"
end

json.items do
  json.array! @items do |item|
    json.id item.id
    json.name item.name
    json.completed item.completed
    json.detailPath item_path(item)
  end
end

```

--------------------------------

### Defer Total Cost Calculation (Ruby)

Source: https://thoughtbot.github.io/superglue/2.0.alpha/tutorial

This Ruby snippet updates `show.json.props` to use `defer: :auto` for the `totalCost` field. It includes placeholder values for the initial load, improving perceived performance by allowing the rest of the page to render immediately while the cost is calculated in the background.

```ruby
json.header do
    json.title "Family Shopping List"
  end

  json.items do
    json.array! @items do |item|
      json.id item.id
      json.name item.name  
      json.completed item.completed
      json.detailPath item_path(item)
      json.toggleForm do
        form_props(model: item) do |f|
          f.submit "Toggle"
        end
      end
    end
  end

- json.totalCost do
+ json.totalCost(defer: [:auto, placeholder: { amount: "Calculating...", message: "Getting current prices" }]) do
    # Simulate expensive API call to get current prices
    sleep 3
    json.amount "$23.45"
    json.message "Estimated total based on current prices"
  end

  json.newItemForm do
    form_props(model: Item.new, url: items_path) do |f|
      f.text_field :name, placeholder: "Add item..."
      f.submit "Add"
    end
  end


```

--------------------------------

### Define JSON Attributes with PropsTemplate

Source: https://thoughtbot.github.io/superglue/2.0.alpha/props-template

Explains and shows examples of using `json.set!` and direct key assignment for defining JSON attributes and nested structures.

```ruby
json.set! :authorDetails, {...options} do
  json.set! :firstName, 'David'
end

# or

json.authorDetails, {...options} do
  json.firstName 'David'
end


# => {"authorDetails": { "firstName": "David" }}


```

```ruby
json.set! :firstName, 'David'

# or

json.firstName 'David'

# => { "firstName": "David" }


```

```ruby
json.set! :details do
  # ...
end

or

json.details do
  # ...
end


```

--------------------------------

### Prepare Redux Store for Superglue

Source: https://thoughtbot.github.io/superglue/2.0.alpha/reference

Illustrates the `prepareStore` function, which initializes the Redux store with initial page data and a path.

```typescript
prepareStore(store, initialPage, path)

```

--------------------------------

### Broadcasting item update for streaming (Ruby on Rails)

Source: https://thoughtbot.github.io/superglue/2.0.alpha/tutorial

This `.json.props` file demonstrates how to broadcast an updated item. It saves the item's content to a target fragment (`item_1`), overwriting any existing content for that fragment.

```ruby
# This will update the item for all connected clients
broadcast_save_props(
  model: @item, 
  target: "item_#{@item.id}",
  partial: "shopping_lists/item",
)
```

--------------------------------

### Superglue Range Field Example

Source: https://thoughtbot.github.io/superglue/2.0.alpha/form-props

Shows the implementation of the `range_field` helper in Superglue, including the `in:` argument, and the resulting JSON output with `min` and `max` attributes.

```ruby
@post.favs = 2

form_props(model: @post) do |f|
  f.range_field(:favs, in: 1...10)
end
```

```json
{
  "type": "range",
  "defaultValue": "2",
  "name": "post[favs]",
  "min": 1,
  "max": 9,
  "id": "post_favs"
}
```

--------------------------------

### Example of Rails Form Helper Block in Superglue

Source: https://thoughtbot.github.io/superglue/2.0.alpha/form-props

Demonstrates how to use `collection_radio_buttons` with a block for label structure in Superglue, contrasting with the removed `f.label` functionality.

```ruby
f.collection_radio_buttons(:active, [true, false], :to_s, :to_s) do |b|
  b.label { b.radio_button + b.text }
end
```

--------------------------------

### Application() Component

Source: https://thoughtbot.github.io/superglue/2.0.alpha/reference

The main entry point component for a Superglue application. It sets up the Redux Provider, initial state, and the Navigation component.

```APIDOC
## Application() Component

### Description
The main entry point component for a Superglue application. It sets up the Redux Provider, initial state, and the Navigation component. This component's source code can be copied and modified to create custom application structures, leveraging its internal `start` and `ujsHandler` methods.

### Parameters
- `__namedParameters` (ApplicationProps) - Required - Properties for the Application component.
```

--------------------------------

### Rails: Add route for item creation

Source: https://thoughtbot.github.io/superglue/2.0.alpha/tutorial

This snippet updates the Rails routes file to include the `create` action for the `items` resource, enabling the handling of new item submissions.

```ruby
Rails.application.routes.draw do
  root 'shopping_lists#show'
  resource :shopping_list, only: [:show]
- resources :items, only: [:show]
+ resources :items, only: [:show, :create]
end
```

--------------------------------

### Create a JSON.props View File

Source: https://thoughtbot.github.io/superglue/2.0.alpha/props-template

Illustrates the naming convention and basic structure for creating a PropsTemplate view file in the app/views directory.

```ruby
# app/views/posts/index.json.props

json.greetings "hello world"


```

--------------------------------

### Using form_props with Custom React Components (react-select)

Source: https://thoughtbot.github.io/superglue/2.0.alpha/form-props

Example of integrating form_props with a custom React component like react-select for a time zone select field.

```javascript
import React from 'react'
import Select from 'react-select';

export default (({props, inputs, extras})) => {
  return (
    <form {...props}>
      <Select
        {...inputs.timeZone}
        isMulti={inputs.timeZone.multiple}
      />
    </form>
  )
}


```

--------------------------------

### Map Page Identifiers to Components

Source: https://thoughtbot.github.io/superglue/2.0.alpha/tutorial

Establishes a mapping between page route identifiers (e.g., 'shopping_lists/show') and their corresponding React components, enabling Superglue to render the correct UI for each page.

```javascript
// app/javascript/page_to_page_mapping.js
import ShoppingListsShow from '../views/shopping_lists/show'
import ItemsShow from '../views/items/show'

export const pageIdentifierToPageComponent = {
  'shopping_lists/show': ShoppingListsShow,
  'items/show': ItemsShow,
}

```

--------------------------------

### Extend Array with PropsTemplate Core Extension

Source: https://thoughtbot.github.io/superglue/2.0.alpha/props-template

Adds convenience methods to the Array class for use with PropsTemplate. Requires 'props_template/core_ext'. Example demonstrates iterating over an array of hashes.

```ruby
require 'props_template/core_ext'
data = [
  {id: 1, name: 'foo'},
  {id: 2, name: 'bar'}
]

json.posts
  json.array! data do
    # ...
  end
end
```

--------------------------------

### Item Show JSON Props

Source: https://thoughtbot.github.io/superglue/2.0.alpha/tutorial

Defines the JSON structure for the item's show view, including item details like name, completion status, and formatted addition date, along with a path to return to the list.

```ruby
json.itemDetails do
  json.name @item.name
  json.completed @item.completed
  json.addedAt @item.created_at.strftime("%B %d, %Y at %I:%M %p")
end

json.backPath root_path

```

--------------------------------

### Superglue Checkbox Helper Example

Source: https://thoughtbot.github.io/superglue/2.0.alpha/form-props

Demonstrates the `check_box` helper in Superglue, explaining how `unchecked_value` and `include_hidden` are passed to replicate Rails behavior, and shows the corresponding JSON output.

```ruby
@post.admin = "on"

form_props(model: @post) do |f|
  f.check_box(:admin, {}, "on", "off")
end
```

```json
{
  "type": "checkbox",
  "defaultValue": "on",
  "uncheckedValue": "off",
  "name": "post[admin]",
  "id": "post_admin",
  "includeHidden": true
}
```

--------------------------------

### Server-side Data Transformation with Ruby

Source: https://thoughtbot.github.io/superglue/2.0.alpha/shaping

Illustrates how to transform data on the server-side using Ruby before passing it to the frontend. This example shows converting a post title to uppercase.

```ruby
json.title @post.title.upcase

```

--------------------------------

### Define a Fragment in Rails

Source: https://thoughtbot.github.io/superglue/2.0.alpha/fragments

Example of defining a fragment in a Rails view using `json.cart` with a partial and fragment name. This sets up the server-side rendering of a partial with a specific identity.

```ruby
json.title "Hello"

json.cart(partial: ["user/cart", fragment: "userCart"]) do
end
```

--------------------------------

### Shopping List Show JSX Component

Source: https://thoughtbot.github.io/superglue/2.0.alpha/tutorial

A React component for the shopping list's show view, using Superglue's `useContent` hook to display the title and a list of items with checkboxes and details links.

```javascript
import React from 'react'
import { useContent } from '@thoughtbot/superglue'

export default function ShoppingListsShow() {
  const { header, items } = useContent()

  return (
    <div>
      <h1>{header.title}</h1>

      <ul>
        {items.map(item => (
          <li key={item.id}>
            <input
              type="checkbox"
              checked={item.completed}
              readOnly
            />
            {item.name}
            <a href={item.detailPath}>Details</a>
          </li>
        ))}
      </ul>
    </div>
  )
}

```

--------------------------------

### Item Show JSX Component

Source: https://thoughtbot.github.io/superglue/2.0.alpha/tutorial

A React component for displaying individual item details, using Superglue's `useContent` hook to show the item's name, status, addition date, and a back link.

```javascript
import React from 'react'
import { useContent } from '@thoughtbot/superglue'

export default function ItemsShow() {
  const { itemDetails, backPath } = useContent()

  return (
    <div>
      <h1>{itemDetails.name}</h1>
      <p>Status: {itemDetails.completed ? 'Completed' : 'Pending'}</p>
      <p>Added: {itemDetails.addedAt}</p>
      <a href={backPath}>← Back to list</a>
    </div>
  )
}

```

--------------------------------

### Client-side Data Transformation (Discouraged)

Source: https://thoughtbot.github.io/superglue/2.0.alpha/shaping

Shows an example of data transformation performed in JavaScript on the client-side, which is discouraged by Superglue. This highlights the potential pitfalls compared to server-side transformations.

```javascript
const content = useContent()
const title = content.title.toUpperCase()

```

--------------------------------

### Superglue: Add form for creating new items (JSON Props)

Source: https://thoughtbot.github.io/superglue/2.0.alpha/tutorial

This snippet demonstrates how to use Superglue's `form_props` to generate React-compatible props for a form in a JSON props file. It sets up the model, URL, and form fields.

```ruby
json.header do
    json.title "Family Shopping List"
  end

json.items do
  json.array! @items do |item|
    json.id item.id
    json.name item.name
    json.completed item.completed
    json.detailPath item_path(item)
  end
end

+ json.newItemForm do
+   form_props(model: Item.new, url: items_path) do |f|
+     f.text_field :name, placeholder: "Add item..."
+     f.submit "Add"
+   end
+ end
```

--------------------------------

### Mutating Nested Fragments with `useSetFragment`

Source: https://thoughtbot.github.io/superglue/2.0.alpha/fragments

An advanced example of using `useSetFragment` to mutate nested fragments. It demonstrates passing a fragment reference directly to `set` to update a deeply nested property.

```javascript
const set = useSetFragment()

set('userCart', (cartDraft) => {
  // carDraft.availableCoupons is a fragment ref in the shape of {__id: 'availableCoupons'}
  // you can use the fragment ref instead of a string
  set(cartDraft.availableCoupons, (couponsDraft) => {
    couponsDraft[0].title = "super free shipping"
  })
})
```

--------------------------------

### Utility Functions

Source: https://thoughtbot.github.io/superglue/2.0.alpha/reference

Documentation for utility functions provided by Superglue.

```APIDOC
## getIn()

### Description
Retrieves data from a JSON object using a Keypath.

### Method
N/A (Function Signature)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "node": "JSONMappable",
  "path": "string"
}
```

### Response
#### Success Response (200)
- **JSONValue**: The value found at the specified path.

### Response Example
```json
{
  "value": "JSONValue"
}
```

## urlToPageKey()

### Description
Converts a URL to a PageKey.

### Method
N/A (Function Signature)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "url": "string"
}
```

### Response
#### Success Response (200)
- **string**: The resulting PageKey.

### Response Example
```json
{
  "pageKey": "string"
}
```
```

--------------------------------

### Load Modal with data-sg-remote

Source: https://thoughtbot.github.io/superglue/2.0.alpha/ujs

This example shows how to use `data-sg-remote` on a link to efficiently load a modal when the next page is navigated to. The `props_at` parameter specifies where the modal data resides.

```html
<a href="/posts/new?props_at=data.modal">Create Post</a>
```

--------------------------------

### Items Controller

Source: https://thoughtbot.github.io/superglue/2.0.alpha/tutorial

Defines the `ItemsController` with a `show` action that retrieves a specific 'Item' record based on the provided ID parameter.

```ruby
class ItemsController < ApplicationController
  def show
    @item = Item.find(params[:id])
  end
end

```

--------------------------------

### Add update route for items (Ruby)

Source: https://thoughtbot.github.io/superglue/2.0.alpha/tutorial

This snippet modifies the `config/routes.rb` file to include the `update` action in the `resources :items` route. This allows the application to handle PUT requests to update item resources.

```ruby
Rails.application.routes.draw do
  root 'shopping_lists#show'
  resource :shopping_list, only: [:show]
  resources :items, only: [:show, :create, :update]
end
```

--------------------------------

### useContent Hook Example

Source: https://thoughtbot.github.io/superglue/2.0.alpha/reference/hooks

Demonstrates how to use the useContent hook to access nested content and automatically resolve fragment references. It shows accessing page data and specific fragments by reference or ID.

```typescript
const page = useContent()
const user = useContent({__id: 'user_123'})
const cart = useContent('userCart')
```

--------------------------------

### JavaScript Page to Page Mapping

Source: https://thoughtbot.github.io/superglue/2.0.alpha/recipes/modals

Maps component identifiers to their corresponding page components using JavaScript. This setup is crucial for Superglue to correctly identify and render components based on the route.

```javascript
import PostIndex from '../views/posts/index';

export const pageIdentifierToPageComponent = {
  'posts/index': PostIndex,
  'posts/new': PostIndex,
};
```

--------------------------------

### Include PropsTemplate Core Extensions

Source: https://thoughtbot.github.io/superglue/2.0.alpha/props-template

Demonstrates how to require the core extensions for PropsTemplate in an initializer file.

```ruby
require 'props_template/core_ext'


```

--------------------------------

### Reload Shopping Cart with data-sg-remote

Source: https://thoughtbot.github.io/superglue/2.0.alpha/ujs

This example demonstrates how to use the `data-sg-remote` attribute on an anchor tag to reload a shopping cart, providing SPA-like functionality without a full page reload.

```html
<a href="/props_at=data.sideBar.shoppingCart" data-sg-remote>Reload the cart</a>
```

--------------------------------

### Item Detail Component with SPA Navigation

Source: https://thoughtbot.github.io/superglue/2.0.alpha/tutorial

Modifies the `ItemsShow` React component to use the `data-sg-visit` attribute on a back link. This enables SPA-like navigation, allowing users to return to the previous list view without a full page reload, enhancing the user experience.

```javascript
import React from 'react'
import { useContent } from '@thoughtbot/superglue'

export default function ItemsShow() {
  const { itemDetails, backPath } = useContent()

  return (
    <div>
      <h1>{itemDetails.name}</h1>
      <p>Status: {itemDetails.completed ? 'Completed' : 'Pending'}</p>
      <p>Added: {itemDetails.addedAt}</p>
      <a href={backPath} data-sg-visit>← Back to list</a>
    </div>
  )
}
```

--------------------------------

### Generate Page Component Mapping with Vite

Source: https://thoughtbot.github.io/superglue/2.0.alpha/recipes/vite

This JavaScript snippet automates the creation of a `page_to_page_mapping` object by importing all `.jsx` files from the `../views` directory. It uses Vite's `import.meta.glob` for efficient module loading.

```javascript
const pageIdentifierToPageComponent = {}
const pages = import.meta.glob('../views/**/*.jsx', {eager: true})

for (const key in pages) {
  if (pages.hasOwnProperty(key)) {
    const identifier = key.replace("../views/", "").split('.')[0];
    pageIdentifierToPageComponent[identifier] = pages[key].default;
  }
}

export { pageIdentifierToPageComponent }

```
Tokens:
Raw