bh 6.1.4 → 6.2.0

data/lib/bh/form_builder.rb

@@ -0,0 +1,96 @@
+require 'action_view'
+require_relative 'form_builder/comboboxes'
+require_relative 'form_builder/controls'
+require_relative 'form_builder/pins'
+
+module Bh
+  # The 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 builder's, its
+  # `data` is merged key by key with the builder's, and any other option of its overrides.
+  class FormBuilder < ActionView::Helpers::FormBuilder
+    include Comboboxes, Controls, 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, with `legend` over them where one is
+    # given, wearing nothing of ours. It carries
+    # its own spacing, twice as much under it as over, so one group reads as belonging to the
+    # words above it rather than sitting evenly between two. Every option is the fieldset's.
+    def fieldset(legend = nil, **options, &)
+      heading = (@template.tag.legend legend if legend)
+      inside = @template.safe_join [heading, @template.capture(&)].compact
+
+      @template.tag.fieldset inside, **with_classes(options, 'd-grid flow-fieldset')
+    end
+
+    # A label is Bootstrap's `form-label`, whatever else it is given -- and given both words
+    # and a block, the control the words name as well, which Rails' own label has no meaning
+    # for: it drops the words and renders the block. Wrapped, the pair is one element, so a
+    # form laid out in columns has a cell to place and neither an id nor a stylesheet counting
+    # children has to bind them -- which a control drawing markup of its own, a combobox say,
+    # would break on connect.
+    def label(method, text = nil, options = {}, &block)
+      return label(method, nil, text, &block) if text.is_a? Hash
+      return super(method, text, with_classes(options, 'form-label'), &block) unless text && block
+
+      words = @template.tag.span text, class: 'form-label'
+      inside = @template.safe_join [words, @template.capture(&block)]
+
+      @template.tag.label inside, for: field_id(method), **with_classes(options, 'flow-field')
+    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 builder's button, solid.
+    def submit(value = nil, options = {})
+      super(value, with_classes(options, "#{PILL} btn-solid #{SPACE}"))
+    end
+
+    # A button is the builder'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/bh/helpers/chats/asides.rb

@@ -0,0 +1,49 @@
+module Bh
+  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 bh_chat_aside(message)
+          parts = [
+            message.sender, bh_chat_time(message.at),
+            bh_chat_delivery(message.delivery), bh_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 bh_chat_time(at)
+          return unless at
+
+          tag.time t('bh.ago', time: time_ago_in_words(at)),
+                   datetime: at.xmlschema, title: l(at, format: :long)
+        end
+
+        def bh_chat_delivery(delivery)
+          return unless delivery
+
+          mark, tone = DELIVERIES.fetch delivery.to_sym
+          tag.strong mark, class: "fg-#{tone}"
+        end
+
+        def bh_chat_cost(cost)
+          "· #{number_to_currency cost, precision: 4}" if cost
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+module Bh
+  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 bh_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('bh.ask'), for: 'ask', class: 'visually-hidden'),
+              text_field_tag(:ask, nil, **bh_chat_ask_options(hints)),
+              submit_tag(t('bh.send'), class: SEND_CLASSES),
+            ], "\n"
+          end
+        end
+
+        def bh_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', turbo_permanent: '',
+                    **bh_chat_placeholder_data(hints), },
+          }
+        end
+
+        def bh_chat_placeholder_data(hints)
+          return {} if hints.size < 2
+
+          { controller: 'placeholder', placeholder_questions_value: hints.to_json }
+        end
+      end
+    end
+  end
+end

data/lib/bh/helpers/chats.rb

@@ -0,0 +1,42 @@
+require_relative 'chats/asides'
+require_relative 'chats/asks'
+
+module Bh
+  module Helpers
+    # A conversation drawn as the bubbles every Bh 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 = [bh_chat_messages(messages)]
+        parts.push bh_chat_ask(url, hints) if url
+
+        tag.div safe_join(parts, "\n"), class: 'chat-thread', data: { controller: 'thread' }
+      end
+
+    private
+
+      def bh_chat_messages(messages)
+        tag.div class: 'chat', data: { thread_target: 'messages' } do
+          safe_join messages.map { |message| bh_chat_message message }, "\n"
+        end
+      end
+
+      def bh_chat_message(message)
+        parts = [bh_chat_aside(message), bh_chat_bubble(message)]
+
+        safe_join parts.compact, "\n"
+      end
+
+      def bh_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('bh.typing') }
+      end
+    end
+  end
+end

data/lib/bh/helpers/dialogs.rb

@@ -0,0 +1,47 @@
+module Bh
+  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('bh.okay'), **options, &)
+        id = "dialog-#{text.parameterize}"
+        data = { **options.fetch(:data, {}), bs_toggle: 'dialog', bs_target: "##{id}" }
+        parts = [bh_dialog_header(id, title), tag.div(capture(&), class: 'dialog-body')]
+        parts.push bh_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 bh_dialog_header(id, title)
+        tag.div class: 'dialog-header' do
+          heading = tag.h2 title, class: 'dialog-title', id: "#{id}-title"
+
+          safe_join [heading, bh_dialog_close]
+        end
+      end
+
+      def bh_dialog_close
+        tag.button type: 'button', class: 'btn-close ms-auto', data: { bs_dismiss: 'dialog' },
+                   aria: { label: t('bh.close') }
+      end
+
+      def bh_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/bh/helpers/flows.rb

@@ -0,0 +1,49 @@
+module Bh
+  module Helpers
+    # The page of a signup flow: a mark over whatever it stands on, a title, a line, one card,
+    # the way out.
+    module Flows
+      # How wide the card is unless a page says otherwise: as wide as a thread, a table or a
+      # contract wants. A page asking one question says a narrower one.
+      WIDTH = '75rem'
+
+      # Draws the page around the card's content: `header` 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 header draws no header,
+      # no subtitle no line and an empty footer no foot: a page says only what it has. Every
+      # other option is an attribute of the column, which is where a host names the controller
+      # that paints what the page stands on.
+      def flow(header: nil, footer: [], **options, &)
+        parts = [
+          (tag.header header if header),
+          *bh_flow_words,
+          bh_flow_card(content_for(:width), &),
+          bh_flow_footer(footer),
+        ]
+        classes = class_names 'flow', options[:class]
+
+        tag.div safe_join(parts.compact), class: classes, **options.except(:class)
+      end
+
+    private
+
+      def bh_flow_words
+        [tag.h1(content_for(:title)), (tag.p content_for :subtitle if content_for? :subtitle)]
+      end
+
+      def bh_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 bh_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/bh/helpers/heads.rb

@@ -0,0 +1,27 @@
+module Bh
+  module Helpers
+    # What a page built on Bootstrap 6 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 metas Bootstrap and Turbo read, and the stylesheet and script this gem serves.
+      # `color-scheme` is what lets `light dark` follow the system, so most pages need no
+      # theme attribute at all. 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.
+      # The icon font is the host's to link: which glyphs a page draws is the host's business,
+      # and a gem reaching for somebody else's CDN on its own is not.
+      def bh_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: "#{Engine::PREFIX}css/bh.css"),
+          tag.script('', type: 'module', src: "#{Engine::PREFIX}js/bh.js"),
+        ], INDENT
+      end
+    end
+  end
+end

data/lib/bh/helpers/notices.rb

@@ -0,0 +1,55 @@
+module Bh
+  module Helpers
+    # What the flash says, as the toasts every Bh page shows them in.
+    module Notices
+      # Bootstrap's tone for each key, so a notice and an alert read apart; a key of the
+      # host's own reads neutral.
+      TONES = { 'notice' => 'theme-success', 'alert' => 'theme-danger' }.freeze
+
+      # The toast controller's hooks: the timed hide stops while a reader hovers or focuses
+      # a toast, so a message stays while someone reads it or aims for the X.
+      HOLD = 'mouseenter->toast#stopTimer mouseleave->toast#startTimer ' \
+             'focusin->toast#stopTimer focusout->toast#startTimer'
+
+      # Every message in the flash as a toast at the bottom right, visible at first paint and
+      # gone after a moment or a click. Only messages: a value that is not words is data some
+      # other part of a host keeps in the flash, and is not something to show. Nothing at all
+      # where there is nothing to say. `data-turbo-temporary`, so a toast born visible does
+      # not replay from the page's snapshot on every Back.
+      def notices
+        messages = flash.to_hash.select { |_, message| message.is_a? String }
+        return if messages.empty?
+
+        toasts = messages.map { |key, message| bh_toast key, message }
+
+        tag.div safe_join(toasts), class: 'toast-container position-fixed bottom-0 end-0 p-3',
+                                   data: { turbo_temporary: '' }
+      end
+
+    private
+
+      def bh_toast(key, message)
+        classes = class_names 'toast fade show', TONES.fetch(key, 'theme-primary')
+        options = {
+          role: 'alert', aria: { live: 'assertive', atomic: true },
+          data: { controller: 'toast', action: HOLD },
+        }
+
+        tag.div class: classes, **options do
+          safe_join [bh_toast_header(message), tag.div(class: 'toast-body d-none')]
+        end
+      end
+
+      def bh_toast_header(message)
+        tag.div class: 'toast-header border-0' do
+          safe_join [tag.span(message, class: 'me-auto'), bh_toast_close]
+        end
+      end
+
+      def bh_toast_close
+        tag.button type: 'button', class: 'btn-close', data: { bs_dismiss: 'toast' },
+                   aria: { label: t('bh.close') }
+      end
+    end
+  end
+end

data/lib/bh/helpers.rb

@@ -0,0 +1,12 @@
+require_relative 'helpers/chats'
+require_relative 'helpers/dialogs'
+require_relative 'helpers/flows'
+require_relative 'helpers/heads'
+require_relative 'helpers/notices'
+
+module Bh
+  # Everything a view may call, in one module the engine puts on every Action View.
+  module Helpers
+    include Chats, Dialogs, Flows, Heads, Notices
+  end
+end

data/lib/bh/message.rb

@@ -0,0 +1,11 @@
+module Bh
+  # One message of a chat, as `chat_with` draws it: which `side` its bubble is on (`:left`
+  # for the other party, `:right` for the reader), its `text`, who the `sender` was, when it
+  # was said (`at`), how its `delivery` went (`:delivered`, `:sent`, `:failed`,
+  # `:undelivered` or nil) and what it `cost` in dollars, where anything did. Any object
+  # answering the same six is a message too; this is for a host that has the facts and no
+  # model to hang them on. A message with no text yet is drawn as being typed.
+  Message = Data.define :side, :text, :sender, :at, :delivery, :cost do
+    def initialize(side:, text: nil, sender: nil, at: nil, delivery: nil, cost: nil) = super
+  end
+end

data/lib/bh/version.rb

@@ -1,5 +1,4 @@
-# frozen_string_literal: true
-
 module Bh
-  VERSION = '6.1.4'
+  # Version of the gem, read by the gemspec and by hosts checking compatibility.
+  VERSION = '6.2.0'
 end

data/lib/bh.rb

@@ -1,9 +1,11 @@
-# frozen_string_literal: true
-
-require 'bh/version'
-require 'bh/engine' if defined?(Rails)
+require_relative 'bh/version'
+require_relative 'bh/message'
+require_relative 'bh/helpers'
+require_relative 'bh/form_builder'
+require_relative 'bh/engine'
 
+# Bootstrap 6 in a Rails app: the form builder that dresses every field a page asks for, the
+# components Bootstrap ships behavior for and no markup, and the one stylesheet and script
+# that carry them.
 module Bh
-  class Error < StandardError; end
-  # Your code goes here...
 end

data/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "bh6",
+  "version": "6.2.0",
+  "description": "Bootstrap 6 in a Rails app: the form builder that dresses every field, the components Bootstrap ships behavior for and no markup, and the Stimulus controllers behind them.",
+  "license": "MIT",
+  "type": "module",
+  "repository": "github:claudiob/bh",
+  "files": [
+    "app/javascript",
+    "app/stylesheets",
+    "public/bh",
+    "vendor",
+    "MIT-LICENSE"
+  ],
+  "exports": {
+    ".": "./app/javascript/bh.js",
+    "./controllers/*": "./app/javascript/bh/*",
+    "./bh.css": "./app/stylesheets/bh.css",
+    "./bootstrap": "./vendor/bootstrap.bundle.min.js"
+  },
+  "scripts": {
+    "build": "node build.mjs"
+  },
+  "dependencies": {
+    "@hotwired/stimulus": ">=3.2",
+    "@hotwired/turbo-rails": ">=8.0",
+    "sortablejs": "^1.15.7"
+  },
+  "devDependencies": {
+    "esbuild": ">=0.28"
+  }
+}