ruflet_rails 0.0.12 → 0.0.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d142d63121dae012354a763ef756504d64534adbc4b2c11eaf0dc51b514c6b32
-  data.tar.gz: d3d1e6cbf9af94c81d5514b71325484e547b40ba34afe3d8601a111f08e4af6a
+  metadata.gz: '097cfb74aac7af1e15b8bcb49135851595cbd7a1856eef1b4df39672c95ebab8'
+  data.tar.gz: 27d2e764c20535ebc41befd5672741500cb78387ee74f56ea284a60de9d8d721
 SHA512:
-  metadata.gz: daf5bf66b258ece12da18cbb4c455d2f9f5dd141faa3638c2ef0ec9a64d85be9b25d94add15ae0374a96c6694f6e393ee015290df62368bd1d9cd6920a3185f3
-  data.tar.gz: 075def7cfb22688619559ba1ca55ede0d4c152c403c95a2273c1fa322a2862b20aafe7bda0507bf73bb4a8e8f40e03eb6c87b9505900fb31aa3ac08098dbf88b
+  metadata.gz: ad4c0ab96a6741c9ff4339590e854abf2e72648a0b10c85bdf371ff7aaaee005e394f5063eecf9395756e1d9260d021a4d6c54737a8ad6326e811e63dca9d75a
+  data.tar.gz: c5aa7b3df32bedad4122d379739e05f770b8caa359e3ac01b114a29ee9c89bc7c5a3ecd175857dc79eaccb737b33bcd007d977086061b9ad25c9187872a2f994

data/README.md

@@ -2,17 +2,18 @@
 
 `ruflet_rails` is the Rails-first integration package for Ruflet.
 
-Internal Rails transport/protocol code is bundled inside this gem as `Ruflet::Rails::Protocol`.
-No separate protocol gem is required.
+It mounts Ruby-driven Ruflet interfaces in a Rails application, makes Rails
+views able to opt into native WebView chrome, and connects web, mobile, and
+desktop clients to the same application entrypoint.
 
-## Usage
+## Add The Gem
 
 ```ruby
 # Gemfile
-gem "ruflet_rails", ">= 0.0.5"
+gem "ruflet_rails"
 ```
 
-## Install into Rails
+## Install Into Rails
 
 ```bash
 bin/rails generate ruflet:install
@@ -23,27 +24,29 @@ bin/rails generate ruflet:install --web --desktop
 
 This generator will:
 - create `app/views/ruflet/main.rb`
-- create `ruflet.yaml`
+- create `config/initializers/ruflet.rb`
 - add the Ruflet WebSocket route to `config/routes.rb`
 - add a `/ruflet` web mount when `--web` is used
 - download prebuilt clients from GitHub releases when `--web`, `--desktop`, or
   `--client=web|desktop|all` is used
 
-Generated `ruflet.yaml`:
+Generated `config/initializers/ruflet.rb`:
 
-```yaml
-app:
-  name: My App
-  backend_url: http://localhost:3000
+```ruby
+Ruflet::Rails.configure do |config|
+  config.app_name = "My App"
+  config.backend_url = ENV.fetch("RUFLET_BACKEND_URL", "http://localhost:3000")
 
-services: []
+  config.services = []
 
-assets:
-  splash_screen: assets/splash.png
-  icon_launcher: assets/icon.png
+  config.splash_screen = Rails.root.join("app/assets/images/splash.png")
+  config.icon_launcher = Rails.root.join("app/assets/images/icon.png")
+end
 ```
 
-For Rails apps, those asset paths are resolved from `app/assets/` during build.
+At build time `ruflet_rails` serializes this Rails config into the Ruflet CLI
+config shape, so the initializer remains the source of truth for app name,
+backend URL, services, assets, and build colors.
 
 ## Web client
 
@@ -85,7 +88,7 @@ bundle exec rake ruflet:build[desktop]
 ```
 
 Rails desktop builds are server-driven. The built desktop app connects back to the
-Rails backend configured in `ruflet.yaml`; it does not package a self-contained
+Rails backend configured in `config/initializers/ruflet.rb`; it does not package a self-contained
 Ruby runtime.
 
 Plain Rails dev server commands do not launch the desktop app. Request a desktop
@@ -117,76 +120,183 @@ bundle exec rake ruflet:install
 bundle exec rake ruflet:install[DEVICE_ID]
 ```
 
-## Ruflet resource scaffolds
+## Native WebView shell
 
-Generate a mountable Ruflet CRUD component for an existing Rails model:
-
-```bash
-bin/rails generate ruflet:scaffold Post
-```
+Beyond the server-driven UI, Ruflet can wrap an existing Rails HTML app in a
+managed native WebView. This is an opt-in shell: calling
+`Ruflet::Rails.native_app` wraps web pages in a native Ruflet shell whose body is
+a WebView. Plain `Ruflet.run { |page| ... }` remains a normal Ruflet app with no
+WebView wrapper or HTML adapter.
 
-The scaffold creates generated app code the Rails developer can own and edit:
+Native behavior is explicit from Rails views: ordinary links and Turbo visits
+stay inside the WebView, while links annotated with `data-ruflet-*` can push
+native screens, replace/root the stack, open a sheet, show a dialog, toast, or
+promote page chrome.
 
 ```ruby
-# app/views/ruflet/components/posts/post_component.rb
-class PostComponent < Ruflet::Rails::ResourceComponent
-  def render
-    # edit the scaffold layout here
-  end
+# app/views/ruflet/main.rb
+Ruflet.run do |page|
+  Ruflet::Rails.native_app(
+    page,
+    start_url: "https://myapp.com",
+    title: "My App",                       # opt into a native AppBar (tracks <title>)
+    loading: :shimmer                      # default; can be "Loading..." or false
+  )
 end
 ```
 
-Mount it explicitly in `config/routes.rb`:
+### Crossing web and native from HTML
 
-```ruby
-mount Ruflet::Rails.web_app(view: "PostComponent"), at: "/posts"
+A tiny HTML adapter reads `data-ruflet-*` attributes from the rendered page and
+sends those payloads back to Ruby. Ruby then builds the native AppBar, drawer,
+tabs, dialogs, sheets, services, and navigation with normal Ruflet controls. The
+page stays a normal page in a plain browser; the attributes only activate inside
+the native shell. Keep using normal Rails helpers like `link_to`; add Ruflet data
+attributes only where the native app should augment the web behavior.
+
+**Navigation** — `action` is `push` (default), `root` (reset to a root screen,
+tab-style), `replace`, `sheet`, or `back`:
+
+```erb
+<%= link_to "Messages", messages_path,
+      data: { ruflet_screen: { action: "push", title: "Messages" }.to_json } %>
+
+<%= link_to "Sign in", new_session_path,
+      data: { ruflet_screen: { action: "push", title: "Sign in",
+        leading: { icon: "close", action: "back" } }.to_json } %>
+
+<%= link_to "Sign in", new_session_path,
+      data: { ruflet_screen: { action: "sheet" }.to_json } %>
+
+<a href="/dashboard" data-ruflet-screen='{"action":"root","title":"Dashboard"}'>Dashboard</a>
 ```
 
-The generated component contains the developer-owned UI and persistence calls.
-`ruflet_rails` provides the reusable model, navigation, dialog, and formatting
-helpers. Component files under `app/views/ruflet/components` are loaded by the
-Railtie so both web mounts and `main.rb` can reference them.
+**Promote HTML chrome to native** — hide HTML header/nav elements and render
+native AppBar, NavigationBar, NavigationDrawer, or desktop NavigationRail:
+
+```erb
+<%= tag.div hidden: true,
+      data: { ruflet_appbar: { title: "Sign in",
+        leading: { icon: "close", action: "back" } }.to_json } %>
+
+<%= ruflet_appbar "Inbox", leading: { icon: "menu", action: "drawer" } do %>
+  <%= ruflet_appbar_action "search", search_path %>
+<% end %>
+
+<%= ruflet_drawer do %>
+  <%= ruflet_drawer_item "Home", root_path, icon: "home", selected: true %>
+  <%= ruflet_drawer_item "Settings", settings_path, icon: "settings", nav: :push %>
+<% end %>
+
+<%= ruflet_bottom_nav do %>
+  <%= ruflet_nav_item "Home", root_path, icon: "house", selected: true %>
+  <%= ruflet_nav_item "Profile", profile_path, icon: "person" %>
+<% end %>
+
+<%= ruflet_navigation_rail extended: true, breakpoint: 720 do %>
+  <%= ruflet_rail_item "Home", root_path, icon: "home", selected: true %>
+  <%= ruflet_rail_item "Inbox", inbox_path, icon: "mail" %>
+  <%= ruflet_rail_item "Settings", settings_path, icon: "settings", nav: :push %>
+<% end %>
+```
 
-## Ruflet model forms
+**Native dialogs and toasts** — from annotated Rails links and buttons.
+Dialogs, bottom sheets, and snackbars are adaptive by default, so the native shell
+can use platform-appropriate presentation instead of forcing the same Material
+look everywhere:
 
-Generate only a reusable Ruflet form for an existing Rails model:
+```erb
+<%= link_to "Delete", item_path(item),
+      data: { ruflet_action: { component: "dialog", title: "Delete?",
+        content: "This cannot be undone.", confirm: "Delete", action: "replace" }.to_json } %>
 
-```bash
-bin/rails generate ruflet:form Post
+<%= button_tag "Copy link",
+      data: { ruflet_action: { component: "toast", message: "Copied to clipboard" }.to_json } %>
 ```
 
-When no fields are passed, the generator reads the model columns and skips `id`,
-`created_at`, and `updated_at`. You can also pass fields explicitly:
+**Native menus and bottom sheets** — menus are regular Ruflet bottom sheets
+driven by Rails payload data. Item taps close the native sheet first, wait for
+the native dismiss event, then run the item callback or navigation. This keeps
+the overlay lifecycle stable on mobile and desktop.
+
+```erb
+<%= ruflet_appbar "T4U",
+      actions: [
+        {
+          icon: "language",
+          action: "menu",
+          title: "Language",
+          items: [
+            { label: "FR", icon: "check", url: url_for(locale: :fr), action: "root", selected: I18n.locale == :fr },
+            { label: "EN", icon: "translate", url: url_for(locale: :en), action: "root" },
+            { label: "AR", icon: "translate", url: url_for(locale: :ar), action: "root" }
+          ]
+        }
+      ] %>
+```
 
-```bash
-bin/rails generate ruflet:form Post title:string body:text published:boolean category:references
+Items close the sheet by default. Pass `close: false` only for an item that
+should run without dismissing the sheet:
+
+```erb
+<%= ruflet_appbar "Filters",
+      actions: [
+        {
+          icon: "tune",
+          action: "menu",
+          title: "Filters",
+          items: [
+            { label: "Toggle remote only", icon: "check", close: false }
+          ]
+        }
+      ] %>
 ```
 
-Foreign keys and references, such as `category:references` or `user_id`, render
-as Ruflet dropdowns populated from the associated Rails model.
+Use `action: "sheet"` to present a Rails URL inside a native bottom sheet whose
+body is still a WebView:
 
-The generated form lives at `app/views/ruflet/components/posts/post_form.rb`.
-The form generator creates `app/views/ruflet/components/application_component.rb`
-when that base component does not already exist.
+```erb
+<%= link_to "Choose language", languages_path,
+      data: { ruflet_action: { component: "sheet", url: languages_path }.to_json } %>
+```
 
-## Shared Ruflet components
+Inside a WebView sheet, plain Rails links are promoted to native actions so the
+sheet closes before navigation:
 
-Put shared Ruflet UI components under `app/views/ruflet/components`. Those files
-are reloaded with Rails application code:
+```erb
+<!-- app/views/languages/index.html.erb, rendered inside the sheet -->
+<%= link_to "Français", url_for(locale: :fr) %>
+<%= link_to "English", url_for(locale: :en) %>
+<%= link_to "العربية", url_for(locale: :ar) %>
+```
 
-```ruby
-# app/views/ruflet/components/page_title_component.rb
-class PageTitleComponent < ApplicationComponent
-  def render(value)
-    text(value, size: desktop? || web? ? 28 : 24, weight: "bold")
-  end
-end
+Add `data-ruflet-close="false"` when a sheet link should not dismiss:
+
+```erb
+<%= link_to "Preview", preview_path, data: { ruflet_close: "false" } %>
 ```
 
+**Native services** — ERB can trigger safe platform services through the same
+`data-ruflet-action` channel:
+
+```erb
+<%= ruflet_share_link "Share", "#",
+      text: "Look at this", title: "My App" %>
+
+<%= ruflet_copy_button "Copy invite", text: invite_url(@invite) %>
+
+<%= ruflet_launch_link "Open docs", "https://flutteronrails.com" %>
+
+<%= ruflet_haptic_button "Tap", style: "light" %>
+```
+
+For a Fizzy-style web app, keep `Ruflet::Rails.native_app` simple and opt in from
+the views that need native treatment:
+
 ```ruby
 # app/views/ruflet/main.rb
 Ruflet.run do |page|
-  page.add(PageTitleComponent.render(page, "Posts"))
+  Ruflet::Rails.native_app(page, start_url: "#{Ruflet::Rails.backend_url}/")
 end
 ```
 

data/lib/generators/ruflet/install/install_generator.rb

@@ -19,11 +19,11 @@ module Ruflet
         create_file target, Ruflet::Rails::InstallSupport.default_app_template(app_title: app_name)
       end
 
-      def create_ruflet_yaml
-        target = File.join(destination_root, "ruflet.yaml")
+      def create_ruflet_initializer
+        target = File.join(destination_root, "config", "initializers", "ruflet.rb")
         return if File.exist?(target)
 
-        create_file target, Ruflet::Rails::InstallSupport.default_ruflet_yaml(app_name: app_name)
+        create_file target, Ruflet::Rails::InstallSupport.default_initializer(app_name: app_name)
       end
 
       # Mount the native WebSocket endpoint explicitly in config/routes.rb.

data/lib/ruflet/rails/configuration.rb

@@ -4,9 +4,9 @@ module Ruflet
   module Rails
     # Central configuration for ruflet_rails.
     #
-    # An install needs no config/initializers/ruflet.rb: routes mount
-    # app/views/ruflet/main.rb explicitly and build metadata is read from
-    # ruflet.yaml. Add an initializer only to override these settings:
+    # Rails apps keep Ruflet build metadata in config/initializers/ruflet.rb.
+    # The build task serializes this object to the ruflet.yaml structure the
+    # Ruflet CLI consumes, so Rails remains the source of truth:
     #
     #   Ruflet::Rails.configure do |config|
     #     # Runtime / server
@@ -15,8 +15,9 @@ module Ruflet
     #     # App metadata (ruflet.yaml → app:)
     #     config.app_name = "My App"
     #
-    #     # Services (ruflet.yaml → services:)
+    #     # Services / extensions (ruflet.yaml → services: / extensions:)
     #     config.services = []
+    #     config.extensions = %w[webview]
     #
     #     # Assets (ruflet.yaml → assets:)
     #     config.splash_screen = Rails.root.join("app/assets/images/splash.png")
@@ -38,16 +39,17 @@ module Ruflet
       # --- Runtime / server ---
 
       # Backend base URL. Used as --dart-define=RUFLET_URL at build time
-      # and by the desktop launcher. Replaces ruflet.yaml → app.backend_url.
+      # and by the desktop launcher.
       attr_accessor :backend_url
 
       # --- App metadata (ruflet.yaml → app:) ---
 
       attr_accessor :app_name
 
-      # --- Services (ruflet.yaml → services:) ---
+      # --- Services / extensions (ruflet.yaml → services: / extensions:) ---
 
       attr_accessor :services
+      attr_accessor :extensions
 
       # --- Assets (ruflet.yaml → assets:) ---
 
@@ -71,6 +73,7 @@ module Ruflet
         @backend_url = nil
         @app_name = nil
         @services = []
+        @extensions = []
       end
 
       # Serialises config to the ruflet.yaml hash structure so the CLI can
@@ -84,7 +87,10 @@ module Ruflet
         app["backend_url"] = @backend_url if @backend_url
         hash["app"] = app unless app.empty?
 
-        hash["services"] = Array(@services)
+        services = Array(@services)
+        extensions = Array(@extensions)
+        hash["services"] = services unless services.empty?
+        hash["extensions"] = extensions unless extensions.empty?
 
         assets = {}
         assets["splash_screen"] = @splash_screen.to_s if @splash_screen