Docs: add Available since component

Author: skryukov

docs/.vitepress/availableSinceMarkdownPlugin.ts

@@ -0,0 +1,60 @@
+import MarkdownIt from 'markdown-it'
+
+export interface AvailableSinceParams {
+  rails?: string
+  core?: string
+  description?: string
+}
+
+function parseAvailableSinceParams(info: string): AvailableSinceParams {
+  const basicMatch = info.trim().match(/^available_since(?:\s+(.*))?$/)
+  if (!basicMatch) return {}
+
+  const allParams = basicMatch[1] || ''
+  const params: AvailableSinceParams = {}
+
+  // Parse out key=value pairs first
+  const keyValueMatches = [...allParams.matchAll(/([a-z]+)(?:=("[^"]*"|[^\s"]+))?/g)]
+  for (const [, key, value] of keyValueMatches) {
+    let cleanValue = value ? value.replace(/^"|"$/g, '') : true
+
+    if (key === 'rails') params.rails = cleanValue as string
+    if (key === 'core') params.core = cleanValue as string
+    if (key === 'description') params.description = cleanValue as string
+  }
+
+  return params
+}
+
+export function availableSinceMarkdownPlugin(md: MarkdownIt) {
+  md.block.ruler.before('paragraph', 'available_since_oneliner', (state, start, end, silent) => {
+    const line = state.getLines(start, start + 1, 0, false).trim()
+
+    const match = line.match(/^@available_since\s+(.+)$/)
+    if (!match) return false
+
+    if (silent) return true
+
+    const params = parseAvailableSinceParams(`available_since ${match[1]}`)
+    const token = state.push('available_since_oneliner', '', 0)
+
+    token.content = renderAvailableSince(params, md)
+    token.map = [start, start + 1]
+
+    state.line = start + 1
+    return true
+  })
+
+  // Render the one-liner available_since token
+  md.renderer.rules.available_since_oneliner = (tokens, idx) => {
+    return tokens[idx].content + '\n'
+  }
+}
+
+function renderAvailableSince(params: AvailableSinceParams, md: MarkdownIt): string {
+  const railsAttr = params.rails ? `rails="${md.utils.escapeHtml(params.rails)}"` : ''
+  const coreAttr = params.core ? `core="${md.utils.escapeHtml(params.core)}"` : ''
+  const descriptionAttr = params.description ? `description="${md.utils.escapeHtml(params.description)}"` : ''
+
+  return `<AvailableSince ${railsAttr} ${coreAttr} ${descriptionAttr} />`
+}

docs/.vitepress/config.mts

@@ -1,5 +1,6 @@
 import { defineConfig } from 'vitepress'
 import llmstxt from 'vitepress-plugin-llms'
+import { availableSinceMarkdownPlugin } from './availableSinceMarkdownPlugin'
 import { tabsMarkdownPlugin } from './vitepress-plugin-tabs/tabsMarkdownPlugin'
 
 const title = 'Inertia Rails'
@@ -25,6 +26,7 @@ export default defineConfig({
   markdown: {
     config(md) {
       md.use(tabsMarkdownPlugin)
+      md.use(availableSinceMarkdownPlugin)
     },
   },
 

docs/.vitepress/theme/components/AvailableSince.vue

@@ -0,0 +1,5 @@
+import AvailableSince from './AvailableSince.vue'
+
+export {
+  AvailableSince,
+}

docs/.vitepress/theme/components/index.ts

@@ -3,6 +3,7 @@ import type { Theme } from 'vitepress'
 import { enhanceAppWithTabs } from 'vitepress-plugin-tabs/client'
 import DefaultTheme from 'vitepress/theme'
 import { h } from 'vue'
+import { AvailableSince } from './components'
 import { setupFrameworksTabs } from './frameworksTabs'
 import './style.css'
 
@@ -15,6 +16,7 @@ export default {
   },
   enhanceApp({ app, router, siteData }) {
     enhanceAppWithTabs(app)
+    app.component('AvailableSince', AvailableSince)
   },
   setup() {
     setupFrameworksTabs()

docs/.vitepress/theme/index.ts

@@ -46,38 +46,44 @@ Use `component_path_resolver` to customize component path resolution when [`defa
 
 ### `deep_merge_shared_data`
 
-**Default**: `false`  
+**Default**: `false`
 **ENV**: `INERTIA_DEEP_MERGE_SHARED_DATA`
 
+@available_since rails=3.8.0
+
 When enabled, props will be deep merged with shared data, combining hashes
 with the same keys instead of replacing them.
 
 ### `default_render`
 
-**Default**: `false`  
+**Default**: `false`
 **ENV**: `INERTIA_DEFAULT_RENDER`
 
 Overrides Rails default rendering behavior to render using Inertia by default.
 
 ### `encrypt_history`
 
-**Default**: `false`  
+**Default**: `false`
 **ENV**: `INERTIA_ENCRYPT_HISTORY`
 
+@available_since rails=3.7.0 core=2.0.0
+
 When enabled, you instruct Inertia to encrypt your app's history, it uses
 the browser's built-in [`crypto` api](https://developer.mozilla.org/en-US/docs/Web/API/Crypto)
 to encrypt the current page's data before pushing it to the history state.
 
 ### `ssr_enabled` _(experimental)_
 
-**Default**: `false`  
+**Default**: `false`
 **ENV**: `INERTIA_SSR_ENABLED`
 
+@available_since rails=3.6.0 core=2.0.0
+
 Whether to use a JavaScript server to pre-render your JavaScript pages,
 allowing your visitors to receive fully rendered HTML when they first visit
 your application.
 
-Requires a JS server to be available at `ssr_url`. [_Example_](https://github.com/ElMassimo/inertia-rails-ssr-template)
+Requires a JavaScript server to be available at `ssr_url`. [_Example_](https://github.com/ElMassimo/inertia-rails-ssr-template)
 
 ### `ssr_url` _(experimental)_
 

docs/guide/configuration.md

@@ -1,5 +1,7 @@
 # Deferred props
 
+@available_since rails=3.6.0 core=2.0.0
+
 Inertia's deferred props feature allows you to defer the loading of certain page data until after the initial page render. This can be useful for improving the perceived performance of your app by allowing the initial page render to happen as quickly as possible.
 
 ## Server side

docs/guide/deferred-props.md

@@ -4,31 +4,52 @@ By default, Inertia overwrites props with the same name when reloading a page. H
 
 ## Server side
 
-> `deep_merge` requires `@inertiajs/core` v2.0.8 or higher, and `inertia_rails` v3.8.0 or higher.
+### Using `merge`
 
-To specify that a prop should be merged, use the `merge` or `deep_merge` method on the prop's value.
+@available_since rails=3.8.0 core=2.0.8
 
-Use `merge` for merging simple arrays, and `deep_merge` for handling nested objects that include arrays or complex structures, such as pagination objects.
+To specify that a prop should be merged, use the `merge` method on the prop's value. This is ideal for merging simple arrays.
+
+On the client side, Inertia detects that this prop should be merged. If the prop returns an array, it will append the response to the current prop value. If it's an object, it will merge the response with the current prop value.
 
 ```ruby
 class UsersController < ApplicationController
   include Pagy::Backend
 
   def index
-    pagy, records = pagy(User.all)
+    _pagy, records = pagy(User.all)
 
     render inertia: {
       # simple array:
       users: InertiaRails.merge { records.as_json(...) },
+      # with match_on parameter for smart merging:
+      products: InertiaRails.merge(match_on: 'id') { Product.all.as_json(...) },
+    }
+  end
+end
+```
+
+### Using `deep_merge`
+
+@available_since rails=3.8.0 core=2.0.8
+
+For handling nested objects that include arrays or complex structures, such as pagination objects, use the `deep_merge` method.
+
+```ruby
+class UsersController < ApplicationController
+  include Pagy::Backend
+
+  def index
+    pagy, records = pagy(User.all)
+
+    render inertia: {
       # pagination object:
       data: InertiaRails.deep_merge {
         {
           records: records.as_json(...),
           pagy: pagy_metadata(pagy)
         }
       },
-      # with match_on parameter for smart merging:
-      products: InertiaRails.merge(match_on: 'id') { Product.all.as_json(...) },
       # nested objects with match_on:
       categories: InertiaRails.deep_merge(match_on: %w[items.id tags.id]) {
         {
@@ -41,10 +62,12 @@ class UsersController < ApplicationController
 end
 ```
 
-On the client side, Inertia detects that this prop should be merged. If the prop returns an array, it will append the response to the current prop value. If it's an object, it will merge the response with the current prop value. If you have opted to `deepMerge`, Inertia ensures a deep merge of the entire structure.
+If you have opted to use `deep_merge`, Inertia ensures a deep merge of the entire structure, including nested objects and arrays.
 
 ### Smart merging with `match_on`
 
+@available_since rails=master core=2.0.13
+
 By default, arrays are simply appended during merging. If you need to update specific items in an array or replace them based on a unique identifier, you can use the `match_on` parameter.
 
 The `match_on` parameter enables smart merging by specifying a field to match on when merging arrays of objects: