studio-engine 0.82.1 → 0.84.0

data/lib/studio/booking.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+# Studio.booking_url — the app's Google Calendar appointment schedule — the two
+# URLs the booking primitives derive from it, and the frame's crop
+# (Studio.booking_crop). Pure Ruby. See docs/BOOKING.md.
+#
+# The configured value is the schedule's PUBLIC page, the URL Google gives you
+# to share, without `?gv=true`:
+#
+#   config.booking_url = "https://calendar.google.com/calendar/appointments/schedules/EXAMPLE-SCHEDULE-ID"
+#
+# `gv=true` is what makes Google serve the embeddable page, so the frame and the
+# popup add it; the "open the booking page" link does not.
+module Studio
+  module Booking
+    EMBED_PARAM = "gv=true"
+
+    # THE CROP. At rest the inline frame can show only Google's "Select an
+    # appointment time" box, with Google's header above it and its credit lines
+    # below clipped away. Where that box sits is a fact about ONE schedule (its
+    # header is as tall as its title, description and meeting line; its box is as
+    # tall as its fullest day), so the app measures its own and declares it:
+    #
+    #   config.booking_crop = { top: 200, bottom: 600, frame_height: 720 }
+    #
+    # All three are pixels in Google's own page, at 640px wide or more:
+    #
+    #   top:          the box's top edge. Stable for a schedule.
+    #   bottom:       the box's bottom edge ON ITS FULLEST DAY. Not stable: the box
+    #                 grows a row per appointment slot, so it is shorter on a day
+    #                 with fewer slots left. Declare the tallest it gets.
+    #   frame_height: the whole page's height on that fullest day. The frame is
+    #                 this tall once it opens.
+    #
+    # `bin/booking-crop-measure <booking url>` prints the Hash.
+    #
+    # The window is [top - CROP_MARGIN, bottom + CROP_MARGIN], held inside the
+    # frame. Because `bottom` is the tallest the box gets, a day with fewer slots
+    # shows a strip of Google's credit lines under a shorter box; it never cuts
+    # the box. A value that cannot be a crop (not a number, negative, bottom not
+    # below top, a box that ends outside the frame, a window that hides nothing)
+    # is reported once and the frame shows whole.
+    CROP_MARGIN = 6
+    CROP_KEYS = %i[top bottom frame_height].freeze
+    REPORTED_LIMIT = 100
+
+    class << self
+      # Where a refused crop is reported: a callable taking the message. The
+      # default writes one warning to the Rails log (or to stderr without Rails).
+      attr_writer :reporter
+
+      def reporter
+        @reporter ||= lambda do |message|
+          if defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
+            ::Rails.logger.warn(message)
+          else
+            warn(message)
+          end
+        end
+      end
+
+      def reported
+        @reported ||= {}
+      end
+    end
+
+    module_function
+
+    def validate_crop!(declared)
+      return if declared.nil? || declared == false || declared.is_a?(Hash)
+
+      raise ArgumentError,
+            "Studio.booking_crop must be nil, false, or a Hash of top:, bottom: and frame_height: " \
+            "(got #{declared.inspect}). See docs/BOOKING.md."
+    end
+
+    # The crop to render: { offset:, window:, frame_height: } in whole pixels, or
+    # nil for the whole frame at rest. `offset` is how far the frame is pulled up
+    # behind its wrapper and `window` is the wrapper's height.
+    def crop(declared)
+      return nil if declared.nil? || declared == false
+      return refuse_crop(declared, "it is not a Hash") unless declared.is_a?(Hash)
+
+      values = CROP_KEYS.to_h { |key| [key, declared[key] || declared[key.to_s]] }
+      missing = values.reject { |_key, value| value.is_a?(Numeric) && value.respond_to?(:round) && value.finite? }.keys
+      return refuse_crop(declared, "#{missing.join(', ')} must be a number") unless missing.empty?
+
+      top, bottom, frame_height = values.values_at(*CROP_KEYS).map(&:round)
+      return refuse_crop(declared, "top is negative") if top.negative?
+      return refuse_crop(declared, "bottom is not below top") unless bottom > top
+      return refuse_crop(declared, "bottom is outside the frame") if bottom > frame_height
+
+      offset = [top - CROP_MARGIN, 0].max
+      window = [bottom + CROP_MARGIN, frame_height].min - offset
+      return refuse_crop(declared, "the window is the whole frame") unless window < frame_height
+
+      { offset: offset, window: window, frame_height: frame_height }
+    end
+
+    # The crop as the custom properties the wrapper carries, so two frames with
+    # different crops can share a page (studio/booking/_assets reads them).
+    def crop_style(crop)
+      return nil if crop.nil?
+
+      "--booking-crop-offset: #{crop[:offset]}px; --booking-crop-window: #{crop[:window]}px; " \
+        "--booking-frame-height: #{crop[:frame_height]}px"
+    end
+
+    def refuse_crop(declared, why)
+      report_once("[studio.booking] booking crop #{declared.inspect} is ignored (#{why}); the frame shows whole. " \
+                  "See docs/BOOKING.md.")
+      nil
+    end
+
+    # A LOCAL PATH, and nothing else, may be the booking page: it is written into
+    # hrefs (the footer's booking links, `studio_booking_link`). It begins with
+    # one "/" and carries no control character. That refuses a scheme
+    # ("javascript:", "https:") and a protocol-relative "//host", which a browser
+    # reads as another site.
+    def local_path?(path)
+      string = path.to_s
+      string.start_with?("/") && !string.start_with?("//") && !string.match?(/[\x00-\x1f\x7f\\]/)
+    end
+
+    # Studio.booking_path: nil, a local path, or a callable receiving the view.
+    def validate_path!(declared)
+      return if declared.nil? || declared.respond_to?(:call)
+      return if declared.is_a?(String) && (declared.strip.empty? || local_path?(declared.strip))
+
+      raise ArgumentError,
+            "Studio.booking_path must be nil, a path beginning with one \"/\", or a callable receiving the view " \
+            "(got #{declared.inspect}). See docs/BOOKING.md."
+    end
+
+    # The declared value as it is stored: a stripped path, a callable, or nil.
+    def normalize_path(declared)
+      validate_path!(declared)
+      return declared unless declared.is_a?(String)
+
+      declared.strip.empty? ? nil : declared.strip
+    end
+
+    # The booking page's path for a view: the app's own (`declared`, a path or
+    # a callable receiving the view), else the engine's /schedule when it is
+    # `drawn`, else nil. A callable may decline with nil. What a callable returns
+    # is held to the same rule as a declared String: anything but a local path is
+    # reported once and treated as no answer.
+    def path_for(declared, view, drawn: false)
+      unless declared.nil?
+        path = (declared.respond_to?(:call) ? declared.call(view) : declared).to_s.strip
+        return path if local_path?(path)
+
+        refuse_path(path) unless path.empty?
+      end
+
+      drawn && view.respond_to?(:studio_booking_path) ? view.studio_booking_path : nil
+    end
+
+    def refuse_path(path)
+      report_once("[studio.booking] booking_path #{path.inspect} is ignored: it is not a local path " \
+                  "(one leading \"/\"). See docs/BOOKING.md.")
+      nil
+    end
+
+    def report_once(message)
+      seen = Studio::Booking.reported
+      return if seen.key?(message)
+
+      seen[message] = true if seen.size < REPORTED_LIMIT
+      Studio::Booking.reporter.call(message)
+    end
+
+    # True when `current` (a request path) is the page `declared` names. A query
+    # string, a fragment and a trailing slash on either side do not count.
+    def same_path?(current, declared)
+      a, b = [current, declared].map { |path| path.to_s.strip.sub(/[?#].*\z/m, "").sub(%r{(?<=.)/+\z}, "") }
+      !a.empty? && a == b
+    end
+
+    def validate!(url)
+      return if url.nil? || url.to_s.strip.empty?
+      return if url.to_s.strip.match?(%r{\Ahttps://\S+\z})
+
+      raise ArgumentError,
+            "Studio.booking_url must be an https URL (got #{url.inspect}). Use the appointment " \
+            "schedule's public link. See docs/BOOKING.md."
+    end
+
+    # The public page, with any embed parameter removed. nil when unset.
+    def page_url(url)
+      string = url.to_s.strip
+      return nil if string.empty?
+
+      base, query = string.split("?", 2)
+      kept = query.to_s.split("&").reject { |pair| pair.empty? || pair == EMBED_PARAM }
+      kept.empty? ? base : "#{base}?#{kept.join('&')}"
+    end
+
+    # The embeddable page: the public page plus gv=true. nil when unset.
+    def embed_url(url)
+      page = page_url(url)
+      return nil if page.nil?
+
+      "#{page}#{page.include?('?') ? '&' : '?'}#{EMBED_PARAM}"
+    end
+  end
+end

data/lib/studio/engine.rb

@@ -47,6 +47,8 @@ module Studio
         studio/canvas_confetti.js
         studio/studio_confetti.js
         studio/sortable.js
+        studio/leaflet.js
+        studio/leaflet.css
         studio/session.js
         studio/montserrat-latin.woff2
         studio/montserrat-latin-ext.woff2

data/lib/studio/site_footer.rb

@@ -0,0 +1,350 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+# Resolves Studio.site_footer — the facts the site footer prints — for a view.
+# Pure Ruby (no Rails dependency), so the unit suite exercises the rules without
+# booting the dummy app. See docs/SITE_FOOTER.md.
+#
+# The declared value is a Hash, or a callable that receives the view (for route
+# helpers). EVERY KEY IS OPTIONAL, and a missing key removes its part of the
+# footer rather than printing a placeholder:
+#
+#   config.site_footer = ->(view) {
+#     { tagline: "Everything, by example",
+#       address: { street: "123 Example St", city_line: "Washington, DC 20024",
+#                  lat: 38.8894, lng: -77.0352 },
+#       email:   "team@example.com",
+#       social:  [ [ "LinkedIn", :linkedin, "https://www.linkedin.com/in/someone/" ],
+#                  [ "Instagram", :instagram, nil ] ],          # nil url: unlinked
+#       columns: [ [ "Company", [ [ "Home", view.root_path ],
+#                                 [ "Career", nil ],            # nil path: disabled
+#                                 [ "Blog", "https://blog.example.com" ] ] ] ],
+#       legal:   [ [ "Privacy Policy", "/privacy" ], [ "Terms of Service", "/terms" ] ] }
+#   }
+#
+# Rows may be written as tuples (above) or as hashes ({ label:, href: }); both
+# normalize to the same symbol-keyed shape, which is what the partials read.
+module Studio
+  module SiteFooter
+    DEFAULT_BOOKING_LABEL = "Schedule a call"
+    DEFAULT_ZOOM = 15
+
+    # The engine's own booking page keeps the footer for a signed-in viewer.
+    OWN_CONTROLLERS = %w[studio/bookings].freeze
+
+    # The only schemes a footer href may carry. Anything else, notably
+    # `javascript:` and `data:`, is never written into an href: the label is
+    # printed unlinked and the rejection is reported once.
+    SAFE_SCHEMES = %w[http https mailto tel].freeze
+    REPORTED_LIMIT = 100
+
+    class << self
+      # Where a rejected href is reported: a callable taking the message. The
+      # default writes one warning to the Rails log (or to stderr without Rails).
+      attr_writer :reporter
+
+      def reporter
+        @reporter ||= lambda do |message|
+          if defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
+            ::Rails.logger.warn(message)
+          else
+            warn(message)
+          end
+        end
+      end
+
+      def reported
+        @reported ||= {}
+      end
+
+      def reset_reported!
+        @reported = {}
+      end
+    end
+
+    module_function
+
+    # A relative path (no scheme), or one of SAFE_SCHEMES. A control character
+    # anywhere fails it: browsers drop tabs and newlines inside a scheme, so
+    # "java\tscript:" would otherwise read as a relative path here and as
+    # script there.
+    def safe_href?(href)
+      string = href.to_s
+      return false if string.match?(/[\x00-\x1f\x7f]/)
+
+      scheme = string[/\A\s*([a-z][a-z0-9+.\-]*):/i, 1]
+      scheme.nil? || SAFE_SCHEMES.include?(scheme.downcase)
+    end
+
+    # The href when it may be linked, else nil, reported once per value.
+    def safe_href(value, where)
+      raw = value.nil? || value == false ? nil : value.to_s
+      return nil if raw.nil? || raw.strip.empty?
+      return raw.strip if safe_href?(raw)
+
+      key = "#{where}:#{raw}"
+      unless SiteFooter.reported.key?(key) || SiteFooter.reported.size >= REPORTED_LIMIT
+        SiteFooter.reported[key] = true
+        SiteFooter.reporter.call(
+          "[studio.site_footer] #{where} #{raw[0, 80].inspect} is not linked: only relative paths, " \
+          "http:, https:, mailto: and tel: are allowed"
+        )
+      end
+      nil
+    end
+
+    # True on the app's OWN booking page (Studio.booking_path), which keeps the
+    # footer for a signed-in viewer as the engine's page does. Matched by the
+    # request's path, because the app's controller could be named anything.
+    def booking_page?(view, booking_path)
+      return false if booking_path.nil?
+      return false unless view.respond_to?(:request) && view.request.respond_to?(:path)
+
+      Studio::Booking.same_path?(view.request.path, booking_path)
+    end
+
+    def validate!(declared)
+      return if declared.nil? || declared.is_a?(Hash) || declared.respond_to?(:call)
+
+      raise ArgumentError,
+            "Studio.site_footer must be nil, a Hash, or a callable receiving the view " \
+            "(got #{declared.class}). See docs/SITE_FOOTER.md."
+    end
+
+    # The normalized facts, or nil when the app declared no footer.
+    #
+    #   name:         the site name the engine resolved (the site identity's title)
+    #   logo:         the logo the engine resolved (the navbar logo), or nil
+    #   booking_path: the booking page's path (Studio.booking_path_for), or nil
+    def resolve(declared, view, name: nil, logo: nil, booking_path: nil)
+      raw = declared.respond_to?(:call) ? declared.call(view) : declared
+      return nil if raw.nil?
+
+      facts = symbolize(raw)
+      site_name = text(facts[:name]) || text(name)
+      booking = symbolize(facts[:booking] || {})
+
+      {
+        name: site_name,
+        wordmark: wordmark(facts[:wordmark], site_name),
+        logo: facts.key?(:logo) ? text(facts[:logo]) : text(logo),
+        logo_invert: facts[:logo_invert] ? true : false,
+        home_path: safe_href(facts[:home_path], "home_path") || "/",
+        tagline: text(facts[:tagline]),
+        email: text(facts[:email]),
+        address: address(facts),
+        social: Array(facts[:social]).filter_map { |row| social(row) },
+        columns: Array(facts[:columns]).filter_map { |row| column(row, booking_path) },
+        legal: Array(facts[:legal]).filter_map { |row| link(row, booking_path) },
+        booking_label: text(booking[:label]) || DEFAULT_BOOKING_LABEL,
+        booking_title: text(booking[:title])
+      }
+    end
+
+    # Where the footer shows. A visitor always gets it; a signed-in viewer gets
+    # it only on the controllers the app lists, because every other signed-in
+    # page is a working surface. `controllers` entries match the controller's
+    # name ("landing") or its path ("studio/bookings").
+    def visible?(logged_in:, controller_name:, controller_path: nil, controllers: [])
+      return true unless logged_in
+
+      listed = Array(controllers).map(&:to_s)
+      listed.include?(controller_name.to_s) || (!controller_path.nil? && listed.include?(controller_path.to_s))
+    end
+
+    # The default rule, asked of a view: the answer Studio.site_footer_visible
+    # gives until an app replaces it. An app narrowing the rule composes with it:
+    #
+    #   config.site_footer_visible = ->(view) {
+    #     Studio::SiteFooter.default_visible?(view) && !view.controller_path.start_with?("app/")
+    #   }
+    #
+    # `booking_path` is the app's own booking page (Studio.booking_path, resolved
+    # for this view); the engine's page is exempt by its controller instead.
+    def default_visible?(view, controllers: nil, booking_path: nil)
+      controllers = Studio.site_footer_controllers if controllers.nil? && defined?(Studio.site_footer_controllers)
+      if booking_path.nil? && Studio.respond_to?(:booking_path) && Studio.booking_path
+        booking_path = Studio.booking_path_for(view)
+      end
+      return true if booking_page?(view, booking_path)
+
+      visible?(
+        logged_in: view.respond_to?(:logged_in?) && view.logged_in? ? true : false,
+        controller_name: view.respond_to?(:controller_name) ? view.controller_name : nil,
+        controller_path: view.respond_to?(:controller_path) ? view.controller_path : nil,
+        controllers: Array(controllers) + OWN_CONTROLLERS
+      )
+    end
+
+    def validate_visible!(rule)
+      return if rule.respond_to?(:call)
+
+      raise ArgumentError,
+            "Studio.site_footer_visible must be a callable receiving the view (got #{rule.class}). " \
+            "See docs/SITE_FOOTER.md."
+    end
+
+    # ---- normalization ------------------------------------------------------
+
+    # Two parts: everything but the last word, then the last word, which the
+    # footer prints in the primary colour (the navbar splits app_name the same
+    # way). A one-word name has an empty first part.
+    def wordmark(declared, name)
+      parts = Array(declared).map { |part| text(part) }.compact
+      return [parts[0..-2].join(" "), parts.last] if parts.length >= 2
+
+      words = (parts.first || name).to_s.split
+      return nil if words.empty?
+
+      [words[0..-2].join(" "), words.last]
+    end
+
+    # The address may be nested under :address or written flat (street:,
+    # city_line:, lat:, lng:, directions_url:). No street and no city line means
+    # no address at all: no Location band and no map.
+    def address(facts)
+      declared = facts[:address]
+      source = declared.nil? ? facts : symbolize(declared)
+      street = text(source[:street])
+      city_line = text(source[:city_line])
+      return nil if street.nil? && city_line.nil?
+
+      full = [street, city_line].compact.join(", ")
+      lat = coordinate(source[:lat])
+      lng = coordinate(source[:lng])
+      {
+        street: street,
+        city_line: city_line,
+        full: full,
+        lat: lat,
+        lng: lng,
+        map: !lat.nil? && !lng.nil?,
+        zoom: (source[:zoom] || DEFAULT_ZOOM).to_i,
+        # A directions_url that may not be linked falls back to the default, so
+        # the address and the map's no-script link still lead somewhere.
+        directions_url: safe_href(source[:directions_url], "directions_url") ||
+          "https://www.google.com/maps/dir/?api=1&destination=#{CGI.escape(full)}"
+      }
+    end
+
+    def coordinate(value)
+      return nil if value.nil? || value.to_s.strip.empty?
+
+      Float(value)
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    # [ label, icon, url ] or { label:, icon:, url: }. A nil url renders the
+    # icon unlinked.
+    def social(row)
+      label, icon, url =
+        if row.respond_to?(:to_h) && !row.is_a?(Array)
+          hash = symbolize(row)
+          [hash[:label], hash[:icon], hash[:url] || hash[:href]]
+        else
+          Array(row)
+        end
+      label = text(label)
+      return nil if label.nil?
+
+      { label: label, icon: (icon || label).to_s.downcase.to_sym, url: safe_href(url, "social url"),
+        unlinked: !text(url).nil? && safe_href(url, "social url").nil? }
+    end
+
+    # [ heading, links ], [ heading, links, { width: 1.5 } ] or { heading:,
+    # links:, width: }. `width` is an optional hint: this column's share of the
+    # row against the others' 1 (see `tracks`).
+    def column(row, booking_path)
+      heading, links, options =
+        if row.respond_to?(:to_h) && !row.is_a?(Array)
+          hash = symbolize(row)
+          [hash[:heading] || hash[:title], hash[:links], hash]
+        else
+          Array(row)
+        end
+      heading = text(heading)
+      links = Array(links).filter_map { |link_row| link(link_row, booking_path) }
+      return nil if heading.nil? && links.empty?
+
+      options = options.respond_to?(:to_h) && !options.is_a?(Array) ? symbolize(options) : {}
+      { heading: heading, links: links, width: column_width(options[:width]) }
+    end
+
+    # A column's width hint, or nil for the default share. Anything that is not a
+    # number between MIN_COLUMN_WIDTH and MAX_COLUMN_WIDTH is no hint.
+    MIN_COLUMN_WIDTH = 0.5
+    MAX_COLUMN_WIDTH = 4
+
+    def column_width(value)
+      return nil unless value.is_a?(Numeric) && value.respond_to?(:finite?) && value.finite?
+      return nil unless value >= MIN_COLUMN_WIDTH && value <= MAX_COLUMN_WIDTH
+
+      value.to_f
+    end
+
+    # True for a label that is an address rather than words: no space in it, and
+    # an "@", a "." or a "/". It is kept on one line (.ftr-link-solid).
+    def solid_label?(label)
+      string = label.to_s
+      !string.match?(/\s/) && string.match?(%r{[@./]})
+    end
+
+    # THE LINK COLUMNS' GRID TRACKS from 768px, one per column: its `width:`
+    # hint as an fr share, else FIRST_COLUMN_WIDTH for the first (the one that
+    # usually holds an email address) and 1 for the rest. nil when there are no
+    # columns, or more than MAX_ROW_COLUMNS: those wrap as equal tracks.
+    FIRST_COLUMN_WIDTH = 1.5
+    MAX_ROW_COLUMNS = 4
+
+    def tracks(columns)
+      columns = Array(columns)
+      return nil if columns.empty? || columns.size > MAX_ROW_COLUMNS
+
+      columns.each_with_index.map do |column, index|
+        "#{format('%g', column[:width] || (index.zero? ? FIRST_COLUMN_WIDTH : 1))}fr"
+      end.join(" ")
+    end
+
+    # [ label, href ], [ label, href, { booking: true } ] or { label:, href:,
+    # booking: }. A nil href is a disabled label; an http(s) href opens in a new
+    # tab; `booking: true`, or an href equal to the booking page's path, opens
+    # the booking popup (the href stays as the fallback).
+    def link(row, booking_path = nil)
+      label, href, options =
+        if row.respond_to?(:to_h) && !row.is_a?(Array)
+          hash = symbolize(row)
+          [hash[:label], hash[:href] || hash[:path] || hash[:url], hash]
+        else
+          Array(row)
+        end
+      label = text(label)
+      return nil if label.nil?
+
+      declared = text(href)
+      href = safe_href(href, "link href")
+      options = options.respond_to?(:to_h) ? symbolize(options) : {}
+      booking = !href.nil? && (options[:booking] ? true : (!booking_path.nil? && href == booking_path))
+      {
+        label: label,
+        href: href,
+        # A nil href is a page that does not exist yet. A REFUSED href is not
+        # that: the label prints plain, with no "coming soon".
+        disabled: declared.nil?,
+        unlinked: !declared.nil? && href.nil?,
+        external: !href.nil? && href.match?(%r{\Ahttps?://}i),
+        booking: booking
+      }
+    end
+
+    def text(value)
+      string = value.to_s.strip
+      value.nil? || value == false || string.empty? ? nil : string
+    end
+
+    def symbolize(hash)
+      hash.to_h.each_with_object({}) { |(key, value), out| out[key.to_sym] = value }
+    end
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.82.1"
+  VERSION = "0.84.0"
 end