houseaccount 0.1.0 → 0.3.0

data/art/icons.txt

@@ -0,0 +1,184 @@
+# Every Bootstrap Icon a HouseAccount page may draw: the ones unicon names for its concepts,
+# and the few written out by name in recourse and here. The icon font and its stylesheet
+# are cut down to these by rake icons; a name missing here is a blank box on a page.
+airplane
+alarm
+archive
+arrow-clockwise
+arrow-counterclockwise
+arrow-down
+arrow-left
+arrow-right
+arrow-up
+arrows-angle-contract
+arrows-angle-expand
+award
+bag
+bank
+bar-chart
+battery
+bell
+bicycle
+book
+bookmark
+bookmark-fill
+box
+box-arrow-in-right
+box-arrow-right
+briefcase
+brush
+building
+bus-front
+c-circle
+calendar
+calendar-check
+camera
+camera-video
+car-front
+card-checklist
+cart
+cash
+chat
+check
+check-circle
+check-circle-fill
+check2-square
+chevron-down
+chevron-left
+chevron-right
+chevron-up
+circle
+clipboard
+clock
+cloud
+cloud-rain
+collection-play
+compass
+copy
+credit-card
+dash
+display
+download
+droplet
+emoji-smile
+envelope
+exclamation-triangle
+eye
+eye-slash
+file-earmark
+file-earmark-text
+fingerprint
+fire
+flag
+folder
+funnel
+gear
+geo
+geo-alt
+gift
+globe
+graph-up
+grid
+grip-vertical
+hammer
+hand-thumbs-down
+hand-thumbs-up
+hdd-rack
+headphones
+heart
+hospital
+hourglass
+house
+image
+inbox
+infinity
+info-circle
+key
+keyboard
+laptop
+layout-sidebar
+lightbulb
+lightning
+link
+list
+list-ul
+lock
+magic
+map
+megaphone
+mic
+moon
+moon-fill
+music-note
+palette
+paperclip
+pause
+pen
+pencil
+people
+percent
+person
+person-circle
+person-dash
+person-plus
+person-rolodex
+person-vcard
+phone
+pie-chart
+play
+plus
+power
+printer
+puzzle
+qr-code
+question-circle
+receipt
+repeat
+reply
+rulers
+scissors
+search
+send
+share
+shield
+shop
+shuffle
+signpost-split
+skip-forward
+sliders
+snow
+sort-down
+soundwave
+speedometer
+square
+star
+sticky
+stop
+stopwatch
+sun
+sun-fill
+table
+tag
+telephone
+terminal
+three-dots
+ticket
+tools
+train-front
+trash
+tree
+trophy
+truck
+unlock
+upc
+upload
+volume-up
+wallet
+wifi
+window
+wrench
+x
+x-circle
+x-lg
+zoom-in
+zoom-out

data/config/locales/houseaccount.en.yml

@@ -0,0 +1,12 @@
+en:
+  houseaccount:
+    ago: '%{time} ago'
+    ask: Ask a question
+    close: Close
+    okay: Okay
+    one_time_code: |-
+      Enter this 6-digit code to proceed: %{pin}
+
+      @%{host} #%{pin}
+    send: Send
+    typing: Typing

data/lib/houseaccount/down.rb

@@ -0,0 +1,19 @@
+require 'rack/files'
+
+module HouseAccount
+  # Answers `/down.html` with the page the host shows while it is down: its own where it is
+  # one of the family, the house's otherwise.
+  class Down
+    def initialize(app)
+      @app = app
+      @files = Rack::Files.new Engine.root.join('public/down').to_s
+    end
+
+    # The page where the path asks for it, and the host otherwise.
+    def call(env)
+      return @app.call env unless env['PATH_INFO'] == '/down.html'
+
+      @files.call env.merge('PATH_INFO' => "/#{HouseAccount.app}.html")
+    end
+  end
+end

data/lib/houseaccount/engine.rb

@@ -0,0 +1,53 @@
+# rails/engine alone raises NoMethodError: railtie.rb calls delegate_missing_to too early.
+require 'rails'
+
+module HouseAccount
+  # Hooks the gem into a host app: serves its files, its error pages and its helpers.
+  class Engine < ::Rails::Engine
+    # The folders the design site publishes, served from this gem at the same paths so a
+    # page on an app and a page on the site link one file — this version's copy under its
+    # own prefix among them. Each keeps its slash: `Rack::Static` matches on `start_with?`,
+    # and `/page` would swallow `/pages` itself.
+    PREFIXES = %W[/css/ /js/ /theme/ /font/ /logo/ /favicon/ /page/ /v#{VERSION}/].freeze
+
+    # An unversioned file is asked for again on every full load and answered `304 Not
+    # Modified` while it stands, since its URL never changes between versions. A font, whose
+    # name carries a hash of its bytes, and anything under this version's prefix never change
+    # at all, so a browser may keep them for good.
+    HEADERS = [
+      [:all, { 'cache-control' => 'no-cache' }],
+      ['/font/', { 'cache-control' => 'public, max-age=31536000, immutable' }],
+      ['/v', { 'cache-control' => 'public, max-age=31536000, immutable' }],
+    ].freeze
+
+    # What a file is kept for while the gem is being worked on: not at all, since the
+    # version's copy is rewritten under the same name until it is released, and a browser
+    # told to keep it for a year would show yesterday's stylesheet on today's page.
+    DEVELOPMENT_HEADERS = HEADERS.first 1
+
+    # Before `Rails::Rack::Logger`, so fetching a stylesheet writes no `Started GET` line, and
+    # cascading, so a host route under one of these prefixes still answers.
+    initializer 'houseaccount.assets' do |app|
+      headers = Rails.env.development? ? DEVELOPMENT_HEADERS : HEADERS
+      app.middleware.insert_before Rails::Rack::Logger, Rack::Static,
+                                   urls: PREFIXES, root: Engine.root.join('public').to_s,
+                                   header_rules: headers, cascade: true
+    end
+
+    # The branded error pages, read by status from `public/page` the way Rails reads a host's
+    # own `public/`, unless the host has already named an app of its own.
+    initializer 'houseaccount.exceptions' do |app|
+      app.config.exceptions_app ||=
+        ActionDispatch::PublicExceptions.new Engine.root.join('public/page').to_s
+    end
+
+    # The page a host shows while it is down, at the path Heroku and a reader expect.
+    initializer 'houseaccount.down' do |app|
+      app.middleware.insert_before Rails::Rack::Logger, Down
+    end
+
+    initializer 'houseaccount.helpers' do
+      ActiveSupport.on_load(:action_view) { include HouseAccount::Helpers }
+    end
+  end
+end

data/lib/houseaccount/form_builder/pins.rb

@@ -0,0 +1,30 @@
+require 'action_view'
+
+module HouseAccount
+  class FormBuilder < ActionView::Helpers::FormBuilder
+    # The field Rails has none of: the six slots a code is typed into.
+    module Pins
+      # What the one real PIN field carries: digits only, six of them, offered by the phone from
+      # the text that brought them, and drawn as slots by Bootstrap and the `otp` controller.
+      PIN = {
+        class: 'otp-input', inputmode: :numeric, pattern: '[0-9]{6}', minlength: 6, maxlength: 6,
+        autocomplete: 'one-time-code',
+      }.freeze
+
+      # `method` as Bootstrap's OTP input: one real field rendered as six slots, the slots
+      # reddened where the record refused the code. Every option is the field's. The field is
+      # drawn by the view rather than this builder on purpose, so it is never dressed as a
+      # `form-control`: a refused one would wear a red box of its own around slots that say so.
+      def pin_field(method, **options)
+        invalid = @object.respond_to?(:errors) && @object.errors.include?(method)
+        classes = @template.class_names 'otp otp-lg', 'is-invalid': invalid
+
+        field = with_classes PIN.merge(options), PIN[:class]
+
+        @template.tag.div class: classes, data: { controller: 'otp', bs_otp: true } do
+          @template.text_field @object_name, method, **field, object: @object
+        end
+      end
+    end
+  end
+end

data/lib/houseaccount/form_builder.rb

@@ -0,0 +1,84 @@
+require 'action_view'
+require_relative 'form_builder/pins'
+
+module HouseAccount
+  # The house's form: what a label, a field and a button of one wear, and the field Rails has
+  # none of. Given to one form as `builder:`, or to every form of a controller through
+  # `default_form_builder`. What a view passes is kept: its classes join the house's, its
+  # `data` is merged key by key with the house's, and any other option of its overrides.
+  class FormBuilder < ActionView::Helpers::FormBuilder
+    include Pins
+
+    # What a field wears: Bootstrap's control, at the size a thumb finds.
+    CONTROL = 'form-control form-control-lg'
+
+    # What a button wears: the large pill in the primary color, solid or outlined.
+    PILL = 'btn btn-lg rounded-5 theme-primary'
+
+    # What clears a button of the field or the button above it.
+    SPACE = 'mt-3 md:mt-4'
+
+    # What a phone field carries: the bundle's `phone` controller, which shapes the number as
+    # it is typed, and the keyboard and autofill a phone offers for one.
+    PHONE = {
+      autocomplete: 'tel',
+      data: { controller: 'phone', action: 'keydown->phone#down input->phone#input' },
+    }.freeze
+
+    # The fieldset a form's controls sit in: a grid one column wide, so each takes the whole
+    # row, with `legend` over them as a `form-label` where one is given. Every option is the
+    # fieldset's.
+    def fieldset(legend = nil, **options, &)
+      heading = (@template.tag.legend legend, class: 'form-label' if legend)
+      inside = @template.safe_join [heading, @template.capture(&)].compact
+
+      @template.tag.fieldset inside, **with_classes(options, 'd-grid')
+    end
+
+    # A label is Bootstrap's `form-label`, whatever else it is given.
+    def label(method, text = nil, options = {}, &)
+      return label(method, nil, text, &) if text.is_a? Hash
+
+      super(method, text, with_classes(options, 'form-label'), &)
+    end
+
+    # A text field is a large control.
+    def text_field(method, options = {}) = super(method, with_classes(options, CONTROL))
+
+    # A phone field is a large control shaped by the `phone` controller as it is typed.
+    def phone_field(method, options = {})
+      super(method, PHONE.deep_merge(with_classes(options, CONTROL)))
+    end
+
+    # A submit is the house's button, solid.
+    def submit(value = nil, options = {})
+      super(value, with_classes(options, "#{PILL} btn-solid #{SPACE}"))
+    end
+
+    # A button is the house's too: solid where it submits, which is what one does unless told
+    # `type: :button`, and outlined where it does not. A disabled one given a `title` says why
+    # on hover — `Available soon` — from a wrapper around it, since a disabled button hears no
+    # mouse; the wrapper then takes the button's place in the column.
+    def button(value = nil, options = {}, &)
+      return button(nil, value, &) if value.is_a? Hash
+
+      wrapped = options[:disabled] && options[:title]
+      fill = options[:type].to_s == 'button' ? 'btn-outline' : 'btn-solid'
+      classes = @template.class_names PILL, fill, (SPACE unless wrapped)
+      button = super(value, with_classes(options.except(:title), classes), &)
+
+      wrapped ? tooltipped(button, options[:title]) : button
+    end
+
+  private
+
+    def tooltipped(button, title)
+      @template.tag.span button, class: "d-grid #{SPACE}",
+                                 data: { controller: 'tooltip', bs_title: title }
+    end
+
+    def with_classes(options, classes)
+      options.merge class: @template.class_names(classes, options[:class])
+    end
+  end
+end

data/lib/houseaccount/helpers/chats/asides.rb

@@ -0,0 +1,49 @@
+module HouseAccount
+  module Helpers
+    module Chats
+      # Who sent a message, when, whether it arrived and what it cost, small above its bubble.
+      module Asides
+        # Which bubble: the other party's comes in on the left, the reader's goes out on the right.
+        SIDES = { left: 'in', right: 'out' }.freeze
+
+        # How a delivery reads, and in which of Bootstrap's tones: a mark for arrived, a mark
+        # for sent and not yet, a cross for either way it failed.
+        DELIVERIES = {
+          delivered: %w[✓ success], sent: %w[✓ secondary],
+          failed: %w[✕ danger], undelivered: %w[✕ danger],
+        }.freeze
+
+      private
+
+        def houseaccount_chat_aside(message)
+          parts = [
+            message.sender, houseaccount_chat_time(message.at),
+            houseaccount_chat_delivery(message.delivery), houseaccount_chat_cost(message.cost),
+          ]
+          return if parts.compact.empty?
+
+          side = SIDES.fetch message.side
+          tag.small safe_join(parts.compact, ' '), class: "chat-aside chat-aside-#{side}"
+        end
+
+        def houseaccount_chat_time(at)
+          return unless at
+
+          tag.time t('houseaccount.ago', time: time_ago_in_words(at)),
+                   datetime: at.xmlschema, title: l(at, format: :long)
+        end
+
+        def houseaccount_chat_delivery(delivery)
+          return unless delivery
+
+          mark, tone = DELIVERIES.fetch delivery.to_sym
+          tag.strong mark, class: "fg-#{tone}"
+        end
+
+        def houseaccount_chat_cost(cost)
+          "· #{number_to_currency cost, precision: 4}" if cost
+        end
+      end
+    end
+  end
+end

data/lib/houseaccount/helpers/chats/asks.rb

@@ -0,0 +1,40 @@
+module HouseAccount
+  module Helpers
+    module Chats
+      # The field under a thread that sends the next question.
+      module Asks
+        # A solid button in the primary, rounded like the field beside it.
+        SEND_CLASSES = 'btn btn-solid rounded-3 theme-primary ms-3'
+
+      private
+
+        # `replace`, so the redirect back to the page the form is on is a page refresh to Turbo
+        # — morphed in place, scroll kept — rather than a visit that lands at the top.
+        def houseaccount_chat_ask(url, hints)
+          data = { controller: 'require', turbo_action: 'replace' }
+          form_with url:, class: 'd-flex align-items-center', data: do
+            safe_join [
+              tag.label(t('houseaccount.ask'), for: 'ask', class: 'visually-hidden'),
+              text_field_tag(:ask, nil, **houseaccount_chat_ask_options(hints)),
+              submit_tag(t('houseaccount.send'), class: SEND_CLASSES),
+            ], "\n"
+          end
+        end
+
+        def houseaccount_chat_ask_options(hints)
+          {
+            id: 'ask', required: true, autofocus: true, autocomplete: 'off',
+            class: 'form-control rounded-4 flex-grow-1 chat-ask', placeholder: hints.first,
+            data: { thread_target: 'field', **houseaccount_chat_placeholder_data(hints) },
+          }
+        end
+
+        def houseaccount_chat_placeholder_data(hints)
+          return {} if hints.size < 2
+
+          { controller: 'placeholder', placeholder_questions_value: hints.to_json }
+        end
+      end
+    end
+  end
+end

data/lib/houseaccount/helpers/chats.rb

@@ -0,0 +1,42 @@
+require_relative 'chats/asides'
+require_relative 'chats/asks'
+
+module HouseAccount
+  module Helpers
+    # A conversation drawn as the bubbles every HouseAccount chat wears.
+    module Chats
+      include Asides, Asks
+
+      # `messages` as a thread that opens at its newest and, where `url` is given, a field
+      # under it that posts the next message there, suggesting `hints` one at a time.
+      def chat_with(messages:, url: nil, hints: [])
+        parts = [houseaccount_chat_messages(messages)]
+        parts.push houseaccount_chat_ask(url, hints) if url
+
+        tag.div safe_join(parts, "\n"), class: 'chat-thread', data: { controller: 'thread' }
+      end
+
+    private
+
+      def houseaccount_chat_messages(messages)
+        tag.div class: 'chat', data: { thread_target: 'messages' } do
+          safe_join messages.map { |message| houseaccount_chat_message message }, "\n"
+        end
+      end
+
+      def houseaccount_chat_message(message)
+        parts = [houseaccount_chat_aside(message), houseaccount_chat_bubble(message)]
+
+        safe_join parts.compact, "\n"
+      end
+
+      def houseaccount_chat_bubble(message)
+        side = Asides::SIDES.fetch message.side
+        return tag.p message.text, class: "chat-bubble chat-#{side}" if message.text
+
+        tag.p safe_join(Array.new(3) { tag.span }), class: "chat-bubble chat-#{side} chat-typing",
+                                                    aria: { label: t('houseaccount.typing') }
+      end
+    end
+  end
+end

data/lib/houseaccount/helpers/dialogs.rb

@@ -0,0 +1,47 @@
+module HouseAccount
+  module Helpers
+    # A dialog a page opens from a link, with none of Bootstrap's markup written by hand.
+    module Dialogs
+      # A link reading `text` and the dialog it opens: headed `title` with an X to close it,
+      # holding the block, and closed as well by a footer button reading `okay` — `Okay`
+      # unless told otherwise, or none at all for `false`. The two share an id made from the
+      # link's own words, so a page needs to invent none; Bootstrap's own `data-bs-toggle`
+      # does the opening, and the browser's element brings the backdrop, the focus trap and
+      # Esc. Any other option is an attribute of the link.
+      def dialog(text, title:, okay: t('houseaccount.okay'), **options, &)
+        id = "dialog-#{text.parameterize}"
+        data = { **options.fetch(:data, {}), bs_toggle: 'dialog', bs_target: "##{id}" }
+        parts = [houseaccount_dialog_header(id, title), tag.div(capture(&), class: 'dialog-body')]
+        parts.push houseaccount_dialog_footer(okay) if okay
+
+        safe_join [
+          link_to(text, "##{id}", **options, data:),
+          tag.dialog(safe_join(parts), class: 'dialog dialog-slide-down', id:,
+                                       aria: { labelledby: "#{id}-title" }),
+        ]
+      end
+
+    private
+
+      def houseaccount_dialog_header(id, title)
+        tag.div class: 'dialog-header' do
+          heading = tag.h2 title, class: 'dialog-title', id: "#{id}-title"
+
+          safe_join [heading, houseaccount_dialog_close]
+        end
+      end
+
+      def houseaccount_dialog_close
+        tag.button type: 'button', class: 'btn-close ms-auto', data: { bs_dismiss: 'dialog' },
+                   aria: { label: t('houseaccount.close') }
+      end
+
+      def houseaccount_dialog_footer(okay)
+        tag.div class: 'dialog-footer' do
+          tag.button okay, type: 'button', class: 'btn btn-solid theme-secondary',
+                           data: { bs_dismiss: 'dialog' }
+        end
+      end
+    end
+  end
+end

data/lib/houseaccount/helpers/flows.rb

@@ -0,0 +1,45 @@
+module HouseAccount
+  module Helpers
+    # The page of a signup flow: the mark over the wall, a title, a line, one card, the way out.
+    module Flows
+      # How wide the card is unless a page says otherwise: one column of a form, on a desktop.
+      WIDTH = '30rem'
+
+      # Draws the page around the card's content, standing on the wall: the mark linking to
+      # `logo` over what the view said in `content_for` — its `:title`, its `:subtitle`, how
+      # wide the card is in `:width` — and the pieces of `footer` under the card joined by a
+      # middot. No subtitle draws no line and an empty footer no foot: a page says only what
+      # it has.
+      def flow(footer: [], logo: Logos::HOME, &)
+        parts = [
+          tag.header(houseaccount_logo(href: logo)),
+          *houseaccount_flow_words,
+          houseaccount_flow_card(content_for(:width), &),
+          houseaccount_flow_footer(footer),
+        ]
+
+        tag.div safe_join(parts.compact), class: 'flow', data: { controller: 'wall' }
+      end
+
+    private
+
+      def houseaccount_flow_words
+        [tag.h1(content_for(:title)), (tag.p content_for :subtitle if content_for? :subtitle)]
+      end
+
+      def houseaccount_flow_card(width, &)
+        width = width.presence || WIDTH
+        style = "--flow-width: #{width}" unless width == WIDTH
+
+        tag.div capture(&), class: 'flow-card p-3 md:p-4 mx-auto', style:
+      end
+
+      def houseaccount_flow_footer(pieces)
+        pieces = Array(pieces).compact_blank
+        return if pieces.empty?
+
+        tag.footer safe_join(pieces, tag.span('·', class: 'fg-2', aria: { hidden: true }))
+      end
+    end
+  end
+end

data/lib/houseaccount/helpers/heads.rb

@@ -0,0 +1,42 @@
+module HouseAccount
+  module Helpers
+    # What every HouseAccount page puts in its `<head>`.
+    module Heads
+      # One line per tag, each at the depth a head's children sit at in a layout indented
+      # by two: `<html>`, then `<head>`, then these.
+      INDENT = "\n    "
+
+      # The stylesheet and the script every page needs, and the icons this app is known
+      # by. Both files at this version's own path, which never changes and so is kept for
+      # a year. A page refresh Turbo is sent morphs the page in place and keeps the scroll,
+      # so an answer landing in a thread leaves the reader where they were.
+      def houseaccount_head_tags
+        safe_join [
+          tag.meta(name: 'viewport', content: 'width=device-width, initial-scale=1'),
+          tag.meta(name: 'color-scheme', content: 'light dark'),
+          tag.meta(name: 'turbo-refresh-method', content: 'morph'),
+          tag.meta(name: 'turbo-refresh-scroll', content: 'preserve'),
+          tag.link(rel: 'stylesheet', href: "/v#{VERSION}/css/houseaccount.css"),
+          tag.script('', type: 'module', src: "/v#{VERSION}/js/houseaccount.js"),
+          *houseaccount_icon_tags,
+        ], INDENT
+      end
+
+      # An asset on the design site by its path, for a page this engine does not serve.
+      def houseaccount_url(path) = "#{HouseAccount.url}/#{path}"
+
+    private
+
+      def houseaccount_icon_tags
+        app = HouseAccount.app
+        mark = Rails.env.development? ? "#{app}-dev" : app
+        [
+          tag.link(rel: 'icon', href: "/favicon/#{mark}.svg", type: 'image/svg+xml'),
+          tag.link(rel: 'icon', href: "/favicon/#{app}-96.png", type: 'image/png', sizes: '96x96'),
+          tag.link(rel: 'apple-touch-icon', href: "/favicon/#{app}-180.png"),
+          tag.link(rel: 'manifest', href: "/favicon/#{app}.webmanifest"),
+        ]
+      end
+    end
+  end
+end