studio-engine 0.82.0 → 0.83.0

data/app/views/style/_site_footer.html.erb

@@ -0,0 +1,79 @@
+<%#  The Site footer and booking group of the Tricks board (admin/style).
+     The primitives a public site ends with: the footer, its map, and the Google
+     Calendar booking frame, popup and link (docs/SITE_FOOTER.md). Each card
+     gives the helper to call; the preview below them is the real footer partial,
+     rendered with THIS app's facts when it has declared any and with a sample
+     when it has not, so the group is never empty.
+
+     The booking frame is described, not embedded: a style guide should not ask
+     Google for a calendar every time an admin scrolls past. %>
+<%
+  own_facts    = studio_site_footer_facts
+  sample       = {
+    name: Studio.site_identity[:title], tagline: "What this app is, in a line",
+    email: "team@example.com",
+    address: { street: "123 Example St", city_line: "Washington, DC 20024", lat: 38.8894, lng: -77.0352 },
+    social: [ [ "LinkedIn", :linkedin, "https://www.linkedin.com/" ], [ "Instagram", :instagram, nil ], [ "X", :x, "https://x.com/" ] ],
+    columns: [ [ "Contact", [ [ "Schedule a call", "#site-footer", { booking: true } ], [ "Contact", "#site-footer" ] ] ],
+               [ "Company", [ [ "Home", "/" ], [ "Career", nil ], [ "Blog", "https://example.com" ] ] ] ],
+    legal: [ [ "Privacy Policy", "#site-footer" ], [ "Terms of Service", "#site-footer" ] ]
+  }
+  preview      = own_facts || Studio::SiteFooter.resolve(sample, self, logo: Studio.logo_for("Footer Logo"))
+  booking      = studio_booking?
+%>
+<section id="site-footer" class="space-y-5" style="scroll-margin-top: calc(var(--nav-h, 0px) + 5rem)">
+  <div class="space-y-1">
+    <h3 class="text-xl font-bold text-heading">Site footer and booking</h3>
+    <p class="text-muted text-sm max-w-2xl">
+      One layout line renders the public site's footer from
+      <code class="font-mono text-2xs">config.site_footer</code>; every part is optional. With
+      <code class="font-mono text-2xs">config.booking_url</code> the same pages get Google Calendar's
+      booking page inline, in a popup and on <code class="font-mono text-2xs">/schedule</code>.
+    </p>
+    <p class="text-muted text-sm" data-site-footer-status>
+      This app:
+      footer <strong class="text-body"><%= own_facts ? "declared" : "not declared" %></strong> &middot;
+      booking <strong class="text-body"><%= booking ? "on" : "off" %></strong> &middot;
+      booking page <strong class="text-body"><%= Studio.draw_booking_routes ? "drawn" : "not drawn" %></strong>
+    </p>
+  </div>
+
+  <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+    <%= render layout: "style/specimen",
+          locals: { klass: "studio_site_footer",
+                    usage: %(studio_site_footer   # one line, at the end of the layout body) } do %>
+      <p class="text-sm text-secondary text-center">
+        The footer, where it should show: every page for a visitor, listed controllers when signed in.
+        Previewed below.
+      </p>
+    <% end %>
+
+    <%= render layout: "style/specimen",
+          locals: { klass: "studio_booking_link",
+                    disabled: !booking, disabled_label: "no booking_url",
+                    usage: %(studio_booking_link "Schedule a call", class: "btn btn-primary") } do %>
+      <% if booking %>
+        <%= studio_booking_link "Schedule a call", class: "btn btn-primary" %>
+      <% else %>
+        <span class="btn btn-primary">Schedule a call</span>
+      <% end %>
+    <% end %>
+
+    <%= render layout: "style/specimen",
+          locals: { klass: "studio_booking_frame",
+                    disabled: !booking, disabled_label: "no booking_url",
+                    usage: %(studio_booking_frame   # crop: false shows Google's whole page at rest) } do %>
+      <p class="text-sm text-secondary text-center">
+        Google's booking page inline. Asked for only after the page has loaded and the frame is near
+        the viewport; cropped to the slot picker until it is used.
+      </p>
+    <% end %>
+  </div>
+
+  <div class="space-y-2">
+    <p class="label-upper"><%= own_facts ? "This app's footer" : "Sample footer (this app declares none)" %></p>
+    <div class="card overflow-hidden" data-site-footer-preview>
+      <%= render "studio/site_footer/footer", facts: preview %>
+    </div>
+  </div>
+</section>

data/app/views/style/_tricks.html.erb

@@ -497,4 +497,7 @@
       <% end %>
     </div>
   </section>
+
+  <!-- Site footer and booking -->
+  <%= render "style/site_footer" %>
 </section>

data/lib/generators/studio/site_identity/site_identity_generator.rb

@@ -82,9 +82,13 @@ module Studio
         return say_status(:skip, "#{CONTROLLER} not found", :yellow) unless File.exist?(path)
         return say_status(:identical, "#{CONTROLLER} (Studio::LinkPreviewBots)", :blue) if File.read(path).include?("Studio::LinkPreviewBots")
 
-        inject_into_class CONTROLLER, "ApplicationController", <<~RUBY
+        # inject_into_class inserts the text as given, right after the class
+        # line, so the body's two-space indent is written here (a bare heredoc
+        # landed at column 0 in cyvasse).
+        inject_into_class CONTROLLER, "ApplicationController", <<~RUBY.gsub(/^(?=.)/, "  ")
           # Preview fetchers (iMessage, Slack, Discord, X...) get a slim page under
-          # Apple's 1 MiB limit. studio-engine docs/LINK_PREVIEW.md.
+          # Apple's 1 MiB limit, and are exempt from allow_browser. studio-engine
+          # docs/LINK_PREVIEW.md.
           include Studio::LinkPreviewBots
         RUBY
       end

data/lib/studio/booking.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Studio.booking_url — the app's Google Calendar appointment schedule — and the
+# two URLs the booking primitives derive from it. Pure Ruby. See
+# docs/SITE_FOOTER.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"
+
+    module_function
+
+    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/SITE_FOOTER.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/link_preview.rb

@@ -135,6 +135,97 @@ module Studio
       value
     end
 
+    # The base URL every preview URL is built on: the app's PINNED canonical
+    # base (Studio.link_preview_base_url) when it set one, else the request's.
+    # Trailing slash dropped, so a path joins cleanly. nil when neither exists.
+    def base_url(pinned:, request_base_url:)
+      pinned_value = pinned.to_s.strip.chomp("/")
+      return pinned_value unless pinned_value.empty?
+
+      request_value = request_base_url.to_s.strip.chomp("/")
+      request_value.empty? ? nil : request_value
+    end
+
+    # The page's og:url. With a pinned base it is that base plus the PATH: no
+    # herokuapp host, no ?utm_ query, so every share of a page counts as one URL.
+    # Without one it is the URL as requested, as it always was.
+    def page_url(base_url:, request_url:, path:)
+      pinned_value = base_url.to_s.strip.chomp("/")
+      return request_url.to_s.empty? ? nil : request_url.to_s if pinned_value.empty?
+
+      "#{pinned_value}#{path.to_s.empty? ? "/" : path}"
+    end
+
+    # [width, height] of a PNG, GIF, JPEG or WebP file, read from its header
+    # only, or nil when the file is missing, unreadable or another format. Lets
+    # the static fallback (public/og.png) emit og:image:width/height, which
+    # WhatsApp and others use to lay the card out before the image arrives.
+    def image_dimensions(path)
+      File.open(path.to_s, "rb") { |file| dimensions_from(file.read(64 * 1024).to_s.b) }
+    rescue SystemCallError, IOError
+      nil
+    end
+
+    def dimensions_from(bytes)
+      dims =
+        if bytes.start_with?("\x89PNG\r\n\x1A\n".b) && bytes.bytesize >= 24
+          bytes[16, 8].unpack("NN")
+        elsif bytes.start_with?("GIF8") && bytes.bytesize >= 10
+          bytes[6, 4].unpack("vv")
+        elsif bytes.start_with?("\xFF\xD8".b)
+          jpeg_dimensions(bytes)
+        elsif bytes.start_with?("RIFF") && bytes[8, 4] == "WEBP"
+          webp_dimensions(bytes)
+        end
+      dims && dims.all? { |n| n.is_a?(Integer) && n.positive? } ? dims : nil
+    end
+
+    # Walk the JPEG segments to the first start-of-frame marker.
+    JPEG_SOF_MARKERS = [0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7, 0xC9, 0xCA, 0xCB, 0xCD, 0xCE, 0xCF].freeze
+
+    def jpeg_dimensions(bytes)
+      offset = 2
+      while offset + 9 <= bytes.bytesize
+        return nil unless bytes.getbyte(offset) == 0xFF
+
+        marker = bytes.getbyte(offset + 1)
+        if marker == 0xFF # fill byte
+          offset += 1
+          next
+        end
+        length = bytes[offset + 2, 2].unpack1("n")
+        if JPEG_SOF_MARKERS.include?(marker)
+          height, width = bytes[offset + 5, 4].unpack("nn")
+          return [width, height]
+        end
+        return nil if length.nil? || length < 2
+
+        offset += 2 + length
+      end
+      nil
+    end
+
+    def webp_dimensions(bytes)
+      case bytes[12, 4]
+      when "VP8 "
+        return nil if bytes.bytesize < 30
+
+        width, height = bytes[26, 4].unpack("vv")
+        [width & 0x3FFF, height & 0x3FFF]
+      when "VP8L"
+        return nil if bytes.bytesize < 25
+
+        bits = bytes[21, 4].unpack1("V")
+        [(bits & 0x3FFF) + 1, ((bits >> 14) & 0x3FFF) + 1]
+      when "VP8X"
+        return nil if bytes.bytesize < 30
+
+        w = bytes[24, 3].unpack("CCC")
+        h = bytes[27, 3].unpack("CCC")
+        [(w[0] | (w[1] << 8) | (w[2] << 16)) + 1, (h[0] | (h[1] << 8) | (h[2] << 16)) + 1]
+      end
+    end
+
     # The whole response a preview fetcher gets: the page's own identity tags,
     # lifted out of its <head>, and a one-card body. Built FROM the rendered
     # page, so the slim document cannot drift from what a person's page says.

data/lib/studio/site_footer.rb

@@ -0,0 +1,294 @@
+# 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
+
+    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 when the engine draws it, 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/")
+    #   }
+    def default_visible?(view, controllers: nil)
+      controllers = Studio.site_footer_controllers if controllers.nil? && defined?(Studio.site_footer_controllers)
+      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 ] or { heading:, links: }.
+    def column(row, booking_path)
+      heading, links =
+        if row.respond_to?(:to_h) && !row.is_a?(Array)
+          hash = symbolize(row)
+          [hash[:heading] || hash[:title], hash[:links]]
+        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?
+
+      { heading: heading, links: links }
+    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 engine's booking page, 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.0"
+  VERSION = "0.83.0"
 end