keystone_ui-app 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8baed1af3145b6225cba7256510492d03a2f6ef3945742053c54758ab8330730
+  data.tar.gz: 3c088d53b28241d1c74a75712dfaab074e4e695fe3dd848bb93e47cb975ff805
+SHA512:
+  metadata.gz: 898e732c1403fe43b9ac93b380383987d1b235cac81f7ed846663b435f6de24052bd92c21503fc47299b014bc64053fa53262595716df9632962d8a61908b253
+  data.tar.gz: 458b9cd3f057d02ba88bafc92f6bf9bd131f39916de54d0e2e0e076e7d6fddd9326207376a05d1b7959d3e4b9c1ac09c2a28e876bd32f823e6ed7b045dca4c9d

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tyler Schneider
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,50 @@
+# keystone_ui-app
+
+The app shell for Rails apps built on keystone_ui. It draws the page frame for desktop browsers, phone browsers and the Hotwire Native app from one call in the layout.
+
+## Install
+
+```ruby
+gem "keystone_ui"
+gem "keystone_ui-app"
+```
+
+The gem requires keystone_ui-styles 0.30.0 or later, which defines the `hotwire-native` and `not-hotwire-native` Tailwind variants, and turbo-rails, whose `hotwire_native_app?` tells the shell it is inside the native app.
+
+## Use
+
+Replace the layout with one call to `ui_app_shell`, filling its slots and putting the page inside it:
+
+```erb
+<%= ui_app_shell do |shell| %>
+  <% shell.with_head do %><%= render "head" %><% end %>
+  <% shell.with_flash do %><%= render "flash" %><% end %>
+  <% shell.with_logo do %><%= link_to "Shop", root_path %><% end %>
+  <% shell.with_menus do %><%= render "user_menu" %><% end %>
+  <% shell.with_footer do %><%= render "footer" %><% end %>
+  <%= yield %>
+<% end %>
+```
+
+Register the gem's Stimulus controllers beside keystone_ui's in `app/javascript/controllers/index.js`. The engine pins them in the importmap, along with its own copy of the Hotwire Native Bridge library:
+
+```js
+import { registerControllers as registerKeystoneUiAppControllers } from "keystone_ui_app/index"
+registerKeystoneUiAppControllers(application)
+```
+
+Every slot is optional. The shell writes the `<!DOCTYPE html>`, the `html`, `head` and `body` elements and the viewport meta tag, so the app's head leaves out its own viewport tag.
+
+## What it draws
+
+- The `html` element carries keystone_ui's theme attributes and the current locale.
+- On a desktop browser, keystone_ui's navigation bar with the logo and the menus.
+- On a phone browser, keystone_ui's phone header for a page drawn with `ui_form_page` or `ui_show_page`, with its back link, title and subtitle.
+- On a phone browser, a page that is not a form or show page shows a menu of the current section's tabs, with the tab the page belongs to marked as active. The section is the navigation group holding the tab keystone_ui's current tab supplier names, and the menu leaves out tabs the person is not permitted to see. A page in no section shows no menu.
+- Inside the native app, the `menu-button` bridge component sends the section's label and tabs to the native menu button, and choosing a tab opens its page in place of the current one. A page in no section sends an empty list.
+- Inside the native app, no navigation bar, no phone header and no footer, the `hotwire-native` class on the `html` element, and a viewport that cannot be pinch-zoomed.
+- In a browser, the footer, unless the page calls `content_for :hide_footer, true`.
+
+## Licence
+
+MIT.

data/app/assets/javascripts/keystone_ui_app/hotwire_native_bridge.js

@@ -0,0 +1,4 @@
+// @hotwired/hotwire-native-bridge@1.2.2 downloaded from https://ga.jspm.io/npm:@hotwired/hotwire-native-bridge@1.2.2/dist/hotwire-native-bridge.js
+
+import{Controller as e}from"@hotwired/stimulus";var t=class{#e;#t;#s;#n;constructor(){this.#e=null;this.#t=0;this.#s=[];this.#n=new Map}start(){this.notifyApplicationAfterStart()}notifyApplicationAfterStart(){document.dispatchEvent(new Event("web-bridge:ready"))}supportsComponent(e){return!!this.#e&&this.#e.supportsComponent(e)}send({component:e,event:t,data:s,callback:n}){if(!this.#e){this.#i({component:e,event:t,data:s,callback:n});return null}if(!this.supportsComponent(e))return null;const i=this.generateMessageId();const r={id:i,component:e,event:t,data:s||{}};this.#e.receive(r);n&&this.#n.set(i,n);return i}receive(e){this.executeCallbackFor(e)}executeCallbackFor(e){const t=this.#n.get(e.id);t&&t(e)}removeCallbackFor(e){this.#n.has(e)&&this.#n.delete(e)}removePendingMessagesFor(e){this.#s=this.#s.filter((t=>t.component!=e))}generateMessageId(){const e=++this.#t;return e.toString()}setAdapter(e){this.#e=e;document.documentElement.dataset.bridgePlatform=this.#e.platform;this.adapterDidUpdateSupportedComponents();this.#r()}adapterDidUpdateSupportedComponents(){this.#e&&(document.documentElement.dataset.bridgeComponents=this.#e.supportedComponents.join(" "))}#i(e){this.#s.push(e)}#r(){this.#s.forEach((e=>this.send(e)));this.#s=[]}};var s=class{constructor(e){this.element=e}get title(){return(this.bridgeAttribute("title")||this.attribute("aria-label")||this.element.textContent||this.element.value).trim()}get enabled(){return!this.disabled}get disabled(){const e=this.bridgeAttribute("disabled");return e==="true"||e===this.platform}enableForComponent(e){e.enabled&&this.removeBridgeAttribute("disabled")}hasClass(e){return this.element.classList.contains(e)}attribute(e){return this.element.getAttribute(e)}bridgeAttribute(e){return this.attribute(`data-bridge-${e}`)}setBridgeAttribute(e,t){this.element.setAttribute(`data-bridge-${e}`,t)}removeBridgeAttribute(e){this.element.removeAttribute(`data-bridge-${e}`)}click(){this.platform=="android"&&this.element.removeAttribute("target");this.element.click()}get platform(){return document.documentElement.dataset.bridgePlatform}};var{userAgent:n}=window.navigator;function i(e){const t=n.match(/bridge-components: \[(.*?)\]/);return!!t&&t[1].split(" ").includes(e)}var r=class extends e{static component="";static get shouldLoad(){return i(this.component)}pendingMessageCallbacks=[];initialize(){this.pendingMessageCallbacks=[]}connect(){this.removeRestoreEventListener();this.addRestoreEventListener()}disconnect(){this.removePendingCallbacks();this.removePendingMessages();this.removeRestoreEventListener()}addRestoreEventListener(){this.restore=this.restore.bind(this);document.addEventListener("native:restore",this.restore)}removeRestoreEventListener(){document.removeEventListener("native:restore",this.restore)}restore(){this.connect()}get component(){return this.constructor.component}get platformOptingOut(){const{bridgePlatform:e}=document.documentElement.dataset;return this.identifier==this.element.getAttribute(`data-controller-optout-${e}`)}get enabled(){return!this.platformOptingOut&&this.bridge.supportsComponent(this.component)}send(e,t={},s){t.metadata={url:window.location.href};const n={component:this.component,event:e,data:t,callback:s};const i=this.bridge.send(n);s&&this.pendingMessageCallbacks.push(i)}removePendingCallbacks(){this.pendingMessageCallbacks.forEach((e=>this.bridge.removeCallbackFor(e)))}removePendingMessages(){this.bridge.removePendingMessagesFor(this.component)}get bridgeElement(){return new s(this.element)}get bridge(){return window.HotwireNative.web}};if(!window.HotwireNative){const e=new t;window.HotwireNative={web:e};a(e);e.start()}function a(e){window.Strada||(window.Strada={web:e});window.webBridge||(window.webBridge=e)}export{r as BridgeComponent,s as BridgeElement};
+

data/app/assets/javascripts/keystone_ui_app/index.js

@@ -0,0 +1,7 @@
+import MenuButtonController from "keystone_ui_app/menu_button_controller"
+
+export function registerControllers(application) {
+  application.register("bridge--menu-button", MenuButtonController)
+}
+
+export { MenuButtonController }

data/app/assets/javascripts/keystone_ui_app/menu_button_controller.js

@@ -0,0 +1,13 @@
+import { BridgeComponent } from "keystone_ui_app/hotwire_native_bridge"
+
+export default class extends BridgeComponent {
+  static component = "menu-button"
+  static values = { menu: Object }
+
+  connect() {
+    super.connect()
+    this.send("connect", this.menuValue, (message) => {
+      if (message.data.path) window.Turbo.visit(message.data.path, { action: "replace" })
+    })
+  }
+}

data/app/components/keystone_ui/app/native_menu_button_component.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "keystone_ui/app/current_section"
+
+module KeystoneUi
+  module App
+    class NativeMenuButtonComponent < ViewComponent::Base
+      CONTROLLER = "bridge--menu-button"
+
+      def call
+        tag.div(data: { controller: CONTROLLER, "#{CONTROLLER}-menu-value": menu.to_json })
+      end
+
+      def menu
+        { title: section&.label, items: tabs.map { |tab| { title: tab.label, path: tab.href } } }
+      end
+
+      def tabs
+        section ? section.tabs : []
+      end
+
+      def section
+        @section ||= KeystoneUi::App::CurrentSection.new(helpers).group
+      end
+    end
+  end
+end

data/app/components/keystone_ui/app/section_menu_component.html.erb

@@ -0,0 +1,7 @@
+<div class="<%= WRAPPER_CLASSES %>">
+  <%= render Keystone::Ui::NavDropdownComponent.new(title: title, area: section.label) do %>
+    <% section.tabs.each do |tab| %>
+      <%= render Keystone::Ui::NavItemComponent.new(label: tab.label, href: tab.href, active: tab.active) %>
+    <% end %>
+  <% end %>
+</div>

data/app/components/keystone_ui/app/section_menu_component.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "keystone_ui/app/current_section"
+
+module KeystoneUi
+  module App
+    class SectionMenuComponent < ViewComponent::Base
+      WRAPPER_CLASSES = "lg:hidden"
+
+      def render?
+        section.present?
+      end
+
+      def title
+        helpers.content_for(:mobile_page_title).presence || section.label
+      end
+
+      def section
+        @section ||= KeystoneUi::App::CurrentSection.new(helpers).group
+      end
+    end
+  end
+end

data/app/components/keystone_ui/app/shell_component.html.erb

@@ -0,0 +1,29 @@
+<!DOCTYPE html>
+<html <%= helpers.keystone_theme_attributes %> class="<%= class_names("hotwire-native": native_app?) %>" lang="<%= I18n.locale %>">
+  <head>
+    <%= tag.meta name: "viewport", content: viewport %>
+    <%= head %>
+  </head>
+  <body>
+    <header>
+      <%= flash %>
+      <% if phone_header_shown? %>
+        <%= helpers.ui_mobile_header(title: page_signalled(:title), back_url: page_signalled(:back_url), subtitle: page_signalled(:subtitle)) %>
+      <% elsif !native_app? %>
+        <%= render KeystoneUi::App::SectionMenuComponent.new %>
+      <% end %>
+    </header>
+    <% page = tag.main(content) %>
+    <% if native_app? %>
+      <%= render KeystoneUi::App::NativeMenuButtonComponent.new %>
+      <%= page %>
+    <% else %>
+      <%= helpers.ui_navigation do |navigation| %>
+        <% navigation.with_logo { logo.to_s } if logo? %>
+        <% navigation.with_menus { menus.to_s } if menus? %>
+        <%= page %>
+      <% end %>
+    <% end %>
+    <%= footer if footer_shown? %>
+  </body>
+</html>

data/app/components/keystone_ui/app/shell_component.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module KeystoneUi
+  module App
+    class ShellComponent < ViewComponent::Base
+      renders_one :head
+      renders_one :flash
+      renders_one :logo
+      renders_one :menus
+      renders_one :footer
+
+      PAGE_SIGNALS = %i[show_page form_page].freeze
+      VIEWPORT = "width=device-width, initial-scale=1"
+      NATIVE_APP_VIEWPORT = "#{VIEWPORT}, maximum-scale=1.0, user-scalable=0"
+
+      def native_app?
+        return @native_app if defined?(@native_app)
+
+        @native_app = helpers.hotwire_native_app?
+      end
+
+      def viewport
+        native_app? ? NATIVE_APP_VIEWPORT : VIEWPORT
+      end
+
+      def phone_header_shown?
+        page_signal && !native_app?
+      end
+
+      def footer_shown?
+        !native_app? && !helpers.content_for?(:hide_footer)
+      end
+
+      def page_signal
+        PAGE_SIGNALS.find { |signal| helpers.content_for?(signal) }
+      end
+
+      def page_signalled(name)
+        helpers.content_for(:"#{page_signal}_#{name}")
+      end
+    end
+  end
+end

data/app/helpers/keystone_ui_app_helper.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module KeystoneUiAppHelper
+  def ui_app_shell(&block)
+    render KeystoneUi::App::ShellComponent.new, &block
+  end
+end

data/config/importmap.rb

@@ -0,0 +1,3 @@
+pin "keystone_ui_app/index", to: "keystone_ui_app/index.js"
+pin "keystone_ui_app/menu_button_controller", to: "keystone_ui_app/menu_button_controller.js"
+pin "keystone_ui_app/hotwire_native_bridge", to: "keystone_ui_app/hotwire_native_bridge.js"

data/lib/keystone_ui/app/current_section.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "keystone_ui/visible_navigation"
+
+module KeystoneUi
+  module App
+    class CurrentSection
+      def initialize(view)
+        @view = view
+      end
+
+      def group
+        KeystoneUi::VisibleNavigation.new(
+          KeystoneUi.configuration.navigation_groups,
+          view: @view,
+          saved_order: [],
+          current_tab: KeystoneUi.configuration.supplied_current_tab(@view)
+        ).groups.find(&:active)
+      end
+    end
+  end
+end

data/lib/keystone_ui/app/engine.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module KeystoneUi
+  module App
+    class Engine < ::Rails::Engine
+      initializer "keystone_ui_app.importmap", before: "importmap" do |app|
+        app.config.importmap.paths << root.join("config/importmap.rb") if app.config.respond_to?(:importmap)
+      end
+    end
+  end
+end

data/lib/keystone_ui/app/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module KeystoneUi
+  module App
+    VERSION = "0.1.0"
+  end
+end

data/lib/keystone_ui/app.rb

@@ -0,0 +1,10 @@
+require "keystone_ui"
+require "view_component"
+require "turbo-rails"
+require "keystone_ui/app/version"
+require "keystone_ui/app/engine"
+
+module KeystoneUi
+  module App
+  end
+end

data/lib/keystone_ui-app.rb

@@ -0,0 +1 @@
+require "keystone_ui/app"

metadata

@@ -0,0 +1,123 @@
+--- !ruby/object:Gem::Specification
+name: keystone_ui-app
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tyler Schneider
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-11-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: keystone_ui
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.66.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.66.0
+- !ruby/object:Gem::Dependency
+  name: keystone_ui-styles
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.30.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.30.0
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: turbo-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.20
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.0.20
+description: A companion engine for keystone_ui that draws a layout's page frame for
+  desktop browsers, phone browsers and the Hotwire Native app from one call.
+email:
+- tylercschneider@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- app/assets/javascripts/keystone_ui_app/hotwire_native_bridge.js
+- app/assets/javascripts/keystone_ui_app/index.js
+- app/assets/javascripts/keystone_ui_app/menu_button_controller.js
+- app/components/keystone_ui/app/native_menu_button_component.rb
+- app/components/keystone_ui/app/section_menu_component.html.erb
+- app/components/keystone_ui/app/section_menu_component.rb
+- app/components/keystone_ui/app/shell_component.html.erb
+- app/components/keystone_ui/app/shell_component.rb
+- app/helpers/keystone_ui_app_helper.rb
+- config/importmap.rb
+- lib/keystone_ui-app.rb
+- lib/keystone_ui/app.rb
+- lib/keystone_ui/app/current_section.rb
+- lib/keystone_ui/app/engine.rb
+- lib/keystone_ui/app/version.rb
+homepage: https://github.com/DYB-Development/keystone_ui-app
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/DYB-Development/keystone_ui-app
+  source_code_uri: https://github.com/DYB-Development/keystone_ui-app
+  changelog_uri: https://github.com/DYB-Development/keystone_ui-app/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/DYB-Development/keystone_ui-app/issues
+  documentation_uri: https://github.com/DYB-Development/keystone_ui-app#readme
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: The page frame for a Rails app built on Keystone UI.
+test_files: []