settings_hub 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ad85780a6a73a02eb859164d7c912fb92229e357e63f0b52e90a7d1cf11c5929
+  data.tar.gz: c6e248ee131cd3b0a95b41907af314a106e999f117f6f7c8290d3d18780dfb4d
+SHA512:
+  metadata.gz: 38d3f21a99d9dd6b5b03c2f4be5a4d509b9d596923ca1f23abdcf626c36f58324194ec9e058ee559e0cc3df0b8d37362bd6ca60cf74a18658d92ce54584b9840
+  data.tar.gz: 23c5e8a36399efa81853564f9480cc780855b3452c3c3e43b6dd2b130037d960ac19160aec0fc4125e2e6b0fce83a40af02018c2561ce3bf25aab31263245f8c

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright tylercschneider
+
+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,28 @@
+# SettingsHub
+Short description and motivation.
+
+## Usage
+How to use my plugin.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "settings_hub"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install settings_hub
+```
+
+## Contributing
+Contribution directions go here.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"
+require "the_local/rake"
+
+task test: "app:test"
+task default: :test

data/app/assets/stylesheets/settings_hub/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/settings_hub/api/sections_controller.rb

@@ -0,0 +1,41 @@
+module SettingsHub
+  module Api
+    class SectionsController < SettingsHub::ApplicationController
+      before_action :refuse_without_capability, only: :update
+
+      def index
+        render json: available_sections.map { |section| { key: section.key, actions: section.actions.keys } }
+      end
+
+      def update
+        return head :unprocessable_content unless requested_action
+
+        result = requested_action.new(person: current_person, account: account_settings_act_on, values: submitted_values).call
+
+        render json: { ok: result.ok?, message: result.message }
+      end
+
+      private
+
+      def refuse_without_capability
+        head :forbidden unless section && allowed?(section)
+      end
+
+      def requested_action
+        section.actions[params[:action_name].to_sym]
+      end
+
+      def section
+        SettingsHub.registry.find(params[:key])
+      end
+
+      def submitted_values
+        params.except(:controller, :action, :key, :action_name).permit!.to_h.symbolize_keys
+      end
+
+      def available_sections
+        visible_areas.values.flatten
+      end
+    end
+  end
+end

data/app/controllers/settings_hub/application_controller.rb

@@ -0,0 +1,23 @@
+module SettingsHub
+  class ApplicationController < ::ApplicationController
+    helper KeystoneUiHelper, SettingsHub::Engine.routes.url_helpers, SettingsHub::AppRoutesHelper
+
+    before_action { SettingsHub::AppRoutesHelper.define_app_route_helpers }
+
+    private
+
+    def account_settings_act_on
+      SettingsAccount.of(self)
+    end
+
+    def visible_areas
+      SettingsHub.registry.areas
+        .transform_values { |sections| sections.select { |section| allowed?(section) } }
+        .reject { |_area, sections| sections.empty? }
+    end
+
+    def allowed?(section)
+      section.capability.nil? || can?(section.capability)
+    end
+  end
+end

data/app/controllers/settings_hub/sections_controller.rb

@@ -0,0 +1,78 @@
+module SettingsHub
+  class SectionsController < ApplicationController
+    before_action :set_section
+    before_action :refuse_without_capability
+
+    def show
+      return redirect_to @section.at if @section.at
+
+      @person = current_person
+      @account = account_settings_act_on
+      @areas = visible_areas
+      @section_addresses = section_addresses
+      @selection = selection
+
+      render template: "settings_hub/settings/show"
+    end
+
+    def update
+      return head :unprocessable_content unless requested_action
+
+      result = requested_action.new(person: current_person, account: account_settings_act_on, values: submitted_values).call
+      return show_refusal(result.message) unless result.ok?
+
+      tell_the_app_it_ran
+
+      redirect_to section_path(params[:key])
+    end
+
+    private
+
+    def requested_action
+      return @section.actions[params[:action_name].to_sym] if params[:action_name]
+
+      @section.action
+    end
+
+    def selection
+      params.except(:controller, :action, :key, :action_name).permit!.to_h.symbolize_keys
+    end
+
+    def section_addresses
+      return { submit_url: section_path(@section.key) } unless @section.named_actions?
+
+      { submit_urls: @section.actions.keys.to_h { |name| [ name, section_action_path(@section.key, name) ] } }
+    end
+
+    def show_refusal(message)
+      @person = current_person
+      @account = account_settings_act_on
+      @areas = visible_areas
+      @section_addresses = section_addresses
+      @selection = selection
+      @refusal = message
+
+      render template: "settings_hub/settings/show", status: :unprocessable_content
+    end
+
+    def tell_the_app_it_ran
+      return unless respond_to?(:after_settings_change, true)
+
+      after_settings_change(section: @section, person: current_person)
+    end
+
+    def submitted_values
+      params.except(:controller, :action, :key, :signed_in_as).permit!.to_h.symbolize_keys
+    end
+
+    def set_section
+      @section = SettingsHub.registry.find(params[:key])
+
+      raise ActionController::RoutingError, "No settings section named #{params[:key]}" unless @section
+    end
+
+    def refuse_without_capability
+      head :forbidden unless allowed?(@section)
+    end
+  end
+end

data/app/controllers/settings_hub/settings_controller.rb

@@ -0,0 +1,7 @@
+module SettingsHub
+  class SettingsController < ApplicationController
+    def show
+      @areas = visible_areas
+    end
+  end
+end

data/app/helpers/settings_hub/app_routes_helper.rb

@@ -0,0 +1,12 @@
+module SettingsHub
+  module AppRoutesHelper
+    def self.define_app_route_helpers
+      @app_route_helpers_defined ||= begin
+        (Rails.application.routes.named_routes.helper_names - SettingsHub::Engine.routes.named_routes.helper_names).each do |name|
+          define_method(name) { |*args, **options| main_app.public_send(name, *args, **options) }
+        end
+        true
+      end
+    end
+  end
+end

data/app/helpers/settings_hub/application_helper.rb

@@ -0,0 +1,4 @@
+module SettingsHub
+  module ApplicationHelper
+  end
+end

data/app/jobs/settings_hub/application_job.rb

@@ -0,0 +1,4 @@
+module SettingsHub
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/mailers/settings_hub/application_mailer.rb

@@ -0,0 +1,6 @@
+module SettingsHub
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/settings_hub/application_record.rb

@@ -0,0 +1,5 @@
+module SettingsHub
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/settings_hub/change_name.rb

@@ -0,0 +1,15 @@
+module SettingsHub
+  class ChangeName
+    def initialize(person:, account:, values:)
+      @person = person
+      @account = account
+      @values = values
+    end
+
+    def call
+      return Result.refused(@person.errors.full_messages.to_sentence) unless @person.update(name: @values[:name])
+
+      Result.ok
+    end
+  end
+end

data/app/views/settings_hub/sections/_profile.html.erb

@@ -0,0 +1,6 @@
+<%= ui_panel do %>
+  <%= ui_form(action: submit_url, method: :patch) do %>
+    <%= ui_form_field(attribute: "name", label: "Name", value: person.name, required: true) %>
+    <%= ui_button(label: "Save") %>
+  <% end %>
+<% end %>

data/app/views/settings_hub/settings/show.html.erb

@@ -0,0 +1,26 @@
+<%= ui_page(max_width: :xl) do %>
+  <%= ui_page_header(title: "Settings") %>
+
+  <%= ui_grid(cols: { default: 1, lg: 2 }, gap: :lg) do %>
+    <%= ui_section do %>
+      <% @areas.each do |area, sections| %>
+        <section aria-label="<%= area.to_s.titleize %>">
+          <%= ui_section(title: area.to_s.titleize) do %>
+            <%= ui_panel do %>
+              <nav aria-label="Settings">
+                <% sections.each do |section| %>
+                  <%= link_to section.title, section.at || section_path(section.key), "aria-current": ("page" if section == @section) %>
+                <% end %>
+              </nav>
+            <% end %>
+          <% end %>
+        </section>
+      <% end %>
+    <% end %>
+
+    <%= ui_section do %>
+      <%= ui_alert(message: @refusal, type: :error) if @refusal %>
+      <%= render partial: @section.renders, locals: {person: @person, account: @account, selection: @selection || {}, **(@section_addresses || {})} if @section %>
+    <% end %>
+  <% end %>
+<% end %>

data/config/routes.rb

@@ -0,0 +1,11 @@
+SettingsHub::Engine.routes.draw do
+  get "/", to: "settings#show", as: :settings
+  namespace :api do
+    resources :sections, only: :index
+    patch "sections/:key/:action_name", to: "sections#update"
+  end
+
+  get "/:key", to: "sections#show", as: :section
+  patch "/:key", to: "sections#update"
+  patch "/:key/:action_name", to: "sections#update", as: :section_action
+end

data/lib/generators/settings_hub/section/section_generator.rb

@@ -0,0 +1,43 @@
+require "rails/generators"
+
+module SettingsHub
+  module Generators
+    class SectionGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      INITIALIZER = "config/initializers/settings_hub.rb".freeze
+      OPENING = "Rails.application.config.to_prepare do\n".freeze
+
+      def register_the_section
+        create_file INITIALIZER, "#{OPENING}end\n" unless initializer_exists?
+        inject_into_file INITIALIZER, registration, after: OPENING
+      end
+
+      def write_the_object
+        template "action.rb.tt", "app/models/save_#{file_name}.rb"
+      end
+
+      def write_the_partial
+        template "partial.html.erb.tt", "app/views/settings/_#{file_name}.html.erb"
+      end
+
+      def write_the_test
+        template "action_test.rb.tt", "test/models/save_#{file_name}_test.rb"
+      end
+
+      private
+
+      def registration
+        %(  SettingsHub.section :#{file_name}, area: :user, title: "#{human_name}", renders: "settings/#{file_name}", runs: "#{save_object}"\n)
+      end
+
+      def save_object
+        "Save#{class_name}"
+      end
+
+      def initializer_exists?
+        File.exist?(File.join(destination_root, INITIALIZER))
+      end
+    end
+  end
+end

data/lib/generators/settings_hub/section/templates/action.rb.tt

@@ -0,0 +1,11 @@
+class <%= save_object %>
+  def initialize(person:, account:, values:)
+    @person = person
+    @account = account
+    @values = values
+  end
+
+  def call
+    SettingsHub::Result.ok
+  end
+end

data/lib/generators/settings_hub/section/templates/action_test.rb.tt

@@ -0,0 +1,9 @@
+require "test_helper"
+
+class <%= save_object %>Test < ActiveSupport::TestCase
+  test "it accepts a submitted change" do
+    result = <%= save_object %>.new(person: nil, account: nil, values: {}).call
+
+    assert result.ok?
+  end
+end

data/lib/generators/settings_hub/section/templates/partial.html.erb.tt

@@ -0,0 +1,6 @@
+<%%= ui_panel do %>
+  <%%= ui_form(action: submit_url, method: :patch) do %>
+    <%%= ui_form_field(attribute: "<%= file_name %>", label: "<%= human_name %>") %>
+    <%%= ui_button(label: "Save") %>
+  <%% end %>
+<%% end %>

data/lib/settings_hub/bad_registration.rb

@@ -0,0 +1,4 @@
+module SettingsHub
+  class BadRegistration < StandardError
+  end
+end

data/lib/settings_hub/engine.rb

@@ -0,0 +1,9 @@
+module SettingsHub
+  class Engine < ::Rails::Engine
+    isolate_namespace SettingsHub
+
+    config.to_prepare do
+      SettingsHub.prepare!
+    end
+  end
+end

data/lib/settings_hub/reference/guide.md

@@ -0,0 +1,216 @@
+## SettingsHub
+
+> **DO NOT** explore the settings_hub gem source code. This reference is the complete
+> user-facing API, and settings_hub's locals are authored from it. Keep it the single
+> source of truth: change it in the same pass that changes the interface, then
+> author the locals again.
+
+SettingsHub is the settings page, shared across apps: **a section is a registration,
+not a page.** SettingsHub owns the page, the list of sections on it, the address each
+section is served at, and the check deciding who may see one. A section owns
+only its fields and the things a person can do with them. Adding a section
+changes no routing, no navigation and no controller.
+
+SettingsHub owns no database table. It is a mountable Rails engine and it draws every
+page with keystone_ui.
+
+### Installing it
+
+```ruby
+gem "settings_hub"
+```
+
+```ruby
+mount SettingsHub::Engine => "/settings"
+```
+
+The host's `ApplicationController` supplies four things. Only the first is
+required:
+
+```ruby
+def current_person          # required — who is signed in
+def settings_account        # the account settings act on
+def current_account         # used when settings_account is not defined
+def can?(capability)        # required once any section names a capability
+def after_settings_change(section:, person:)   # optional, runs after a change
+```
+
+`settings_account` is asked for first and `current_account` is the fallback, so
+an app whose settings act on something other than the account a person last
+switched to says which by defining `settings_account`. An app that defines
+neither gets `nil`, which is correct for a product whose settings are all
+personal.
+
+### Generating a section
+
+```
+bin/rails generate settings_hub:section reminders
+```
+
+It registers the section in the app's settings_hub initializer, creating that file if
+it is missing, and writes the object the section runs, the partial it draws and
+a test for the object. The generated test passes as written, and the section
+appears on the settings page with nothing further to wire. Everything it writes
+is a starting point to edit.
+
+### Registering a section
+
+```ruby
+Rails.application.config.to_prepare do
+  SettingsHub.section :password, area: :user, title: "Password",
+    renders: "settings/password", runs: "ChangePassword"
+end
+```
+
+| Detail | Required | What it is |
+|---|---|---|
+| first argument | yes | the section's key, used in its address |
+| `area:` | yes | which list it appears in — any symbol, commonly `:user`, `:team`, `:account` |
+| `title:` | yes | what the list calls it |
+| `renders:` | no | the partial drawn inside the settings page |
+| `runs:` | no | the object or objects a submitted change is handed to |
+| `capability:` | no | what a person must hold to see it |
+| `at:` | no | an address to send a person to instead of drawing a partial |
+
+A section with `at:` draws nothing and sends the person to that address. Use it
+for a page settings_hub cannot serve, such as one a vendored engine owns.
+
+Registrations go in `config.to_prepare`, which runs again on every code reload.
+SettingsHub clears its registry each time, so registrations are made fresh rather
+than added to what is already there.
+
+### Replacing a registration
+
+`SettingsHub.section` refuses a key already taken in that area. Code that means to
+override a registered section says so:
+
+```ruby
+SettingsHub.replace_section :profile, area: :user, title: "Profile",
+  renders: "my_app/profile", runs: "MyApp::ChangeName"
+```
+
+### What settings_hub refuses when the app starts
+
+Three mistakes raise `SettingsHub::BadRegistration` at registration rather than in
+front of a person:
+
+- a key already taken in that area, named in the message
+- an object named in `runs:` that the app cannot find, named in the message
+- a capability the app does not recognise, named in the message
+
+The third runs only once the app declares what it recognises:
+
+```ruby
+SettingsHub.capabilities = -> { Citizen.capabilities }
+```
+
+An app that declares nothing gets no capability check, which is what lets settings_hub
+be installed without citizen.
+
+### The object a section runs
+
+`runs:` names a class as a string. The object takes three keywords and answers
+`call`:
+
+```ruby
+class ChangeName
+  def initialize(person:, account:, values:)
+    @person = person
+    @account = account
+    @values = values
+  end
+
+  def call
+    return SettingsHub::Result.refused(@person.errors.full_messages.to_sentence) unless @person.update(name: @values[:name])
+
+    SettingsHub::Result.ok
+  end
+end
+```
+
+`values` is what the person submitted, as a hash with symbol keys. The object
+reads no request, no session and no params object, which is what lets a caller
+other than the page run it.
+
+```ruby
+SettingsHub::Result.ok                  # it worked
+SettingsHub::Result.refused("why not")  # it did not, and this is shown to the person
+```
+
+A refusal re-draws the section with the message above it and saves nothing, and
+the app is not told a change was made.
+
+### The partial a section renders
+
+The partial is handed locals and nothing else. It draws no page heading, no
+frame and no layout, because it is rendered inside the settings page:
+
+```erb
+<%= ui_panel do %>
+  <%= ui_form(action: submit_url, method: :patch) do %>
+    <%= ui_form_field(attribute: "name", label: "Name", value: person.name, required: true) %>
+    <%= ui_button(label: "Save") %>
+  <% end %>
+<% end %>
+```
+
+| Local | What it is |
+|---|---|
+| `person` | who is signed in |
+| `account` | the account settings act on |
+| `selection` | the query string, as a hash with symbol keys |
+| `submit_url` | where to submit, for a section naming one object |
+| `submit_urls` | where to submit each named object, for a section naming several |
+
+`selection` is how a section holds a choice across a request without a
+controller of its own — a section listing people links each one to
+`?member_id=1` and reads `selection[:member_id]` to draw that person.
+
+### Calling it from JSON
+
+The same registrations and the same objects answer a caller that speaks JSON,
+signed in as a person the same way the page is:
+
+```
+GET   /settings/api/sections
+PATCH /settings/api/sections/:key/:action_name
+```
+
+The listing gives back only the sections that person holds the capability for,
+each naming the actions it offers. A section running one object names that
+action after the section itself, so `profile` offers the action `profile`.
+
+```json
+[{"key": "profile", "actions": ["profile"]},
+ {"key": "team",    "actions": ["invite", "remove"]}]
+```
+
+A change answers whether it worked and why not:
+
+```json
+{"ok": false, "message": "That name is spoken for"}
+```
+
+A caller naming a section the person may not see is refused, and a refused
+change saves nothing.
+
+### A section that does several things
+
+`runs:` takes a hash when a section offers more than one thing. Each gets its
+own address, handed to the partial in `submit_urls`:
+
+```ruby
+SettingsHub.section :team, area: :team, title: "Team", capability: :manage_team,
+  renders: "citizen/members/team",
+  runs: {
+    invite: "Citizen::Invite",
+    remove: "Citizen::RemoveMember"
+  }
+```
+
+```erb
+<%= ui_form(action: submit_urls[:invite], method: :patch) do %>
+```
+
+Every object in the hash takes the same three keywords and returns the same
+result as the single-object case.