studio-engine 0.82.1 → 0.83.0

data/app/views/studio/site_footer/_footer.html.erb

@@ -0,0 +1,99 @@
+<%# The site footer (Studio.site_footer; docs/SITE_FOOTER.md): brand and social
+    profiles at the left, plain link columns under bold headings, a centred
+    Location band with a live map, then a quiet centred legal line. Rendered by
+    `studio_site_footer`, which passes the resolved `facts`.
+
+    Every part is optional and a missing fact removes its part. The layout lives
+    in studio/site_footer/_assets as scoped CSS (.ftr-*), not Tailwind
+    utilities: a utility a consumer's build has not already seen compiles to
+    nothing, and a footer that silently loses its grid is the result. %>
+<% address = facts[:address] %>
+<% booking = studio_booking? %>
+<% columns = facts[:columns] %>
+<%= studio_site_footer_assets %>
+<footer class="ftr" data-site-footer>
+  <div class="ftr-wrap">
+    <div class="ftr-cols" style="--ftr-n: <%= columns.size %>; --ftr-n-md: <%= [ columns.size, 4 ].min.clamp(1, 4) %>;">
+      <div class="ftr-brand">
+        <% if facts[:logo] || facts[:wordmark] %>
+          <a href="<%= facts[:home_path] %>" class="ftr-home" aria-label="<%= facts[:name] %>">
+            <% if facts[:logo] %>
+              <%= image_tag facts[:logo], class: [ "ftr-logo", ("ftr-logo-invert" if facts[:logo_invert]) ].compact.join(" "), alt: "" %>
+            <% end %>
+            <% if facts[:wordmark] %>
+              <span class="ftr-wordmark"><% if facts[:wordmark][0].present? %><span><%= facts[:wordmark][0] %></span><% end %><span class="ftr-wordmark-accent"><%= facts[:wordmark][1] %></span></span>
+            <% end %>
+          </a>
+        <% end %>
+        <% if facts[:tagline] %>
+          <p class="ftr-tagline"><%= facts[:tagline] %></p>
+        <% end %>
+        <% if facts[:email] %>
+          <p class="ftr-email"><a href="mailto:<%= facts[:email] %>" class="ftr-link"><%= facts[:email] %></a></p>
+        <% end %>
+        <% if facts[:social].any? %>
+          <ul class="ftr-socials" aria-label="Social profiles">
+            <% facts[:social].each do |profile| %>
+              <li>
+                <%# A nil url renders the icon unlinked: the handle is not on record yet. %>
+                <%= content_tag(profile[:url] ? :a : :span,
+                      render("studio/site_footer/social_icon", icon: profile[:icon], label: profile[:label]),
+                      { class: "ftr-social", title: profile[:url] || profile[:unlinked] ? profile[:label] : "#{profile[:label]} (handle needed)",
+                        "aria-label": profile[:label] }
+                        .merge(profile[:url] ? { href: profile[:url], target: "_blank", rel: "noopener" } : { "data-pending": true })) %>
+              </li>
+            <% end %>
+          </ul>
+        <% end %>
+      </div>
+
+      <% columns.each do |column| %>
+        <nav aria-label="<%= column[:heading] || "Footer" %>">
+          <% if column[:heading] %>
+            <h2 class="ftr-heading"><%= column[:heading] %></h2>
+          <% end %>
+          <ul class="ftr-list">
+            <% column[:links].each do |link| %>
+              <li><%= render "studio/site_footer/link", link: link, booking: booking %></li>
+            <% end %>
+          </ul>
+        </nav>
+      <% end %>
+    </div>
+
+    <% if address %>
+      <div class="ftr-location" data-footer-location>
+        <h2 class="ftr-location-title">Location</h2>
+        <address class="ftr-address">
+          <a href="<%= address[:directions_url] %>" target="_blank" rel="noopener" class="ftr-link"
+             aria-label="Get directions to <%= address[:full] %>">
+            <%= safe_join([ address[:street], address[:city_line] ].compact, tag.br) %>
+          </a>
+        </address>
+      </div>
+    <% end %>
+  </div>
+
+  <%# Outside the centred column on purpose: the map runs edge to edge. %>
+  <% if address && address[:map] %>
+    <%= render "studio/site_footer/map", address: address, classes: "ftr-map-wide", style: nil, zoom: nil, controls: true %>
+  <% end %>
+
+  <div class="ftr-wrap">
+    <div class="ftr-legal<%= " ftr-legal-ruled" unless address && address[:map] %>">
+      <% if facts[:legal].any? %>
+        <p>
+          <% facts[:legal].each_with_index do |link, index| %>
+            <%= " · " unless index.zero? %><%= render "studio/site_footer/link", link: link, booking: booking %>
+          <% end %>
+        </p>
+      <% end %>
+      <% if facts[:name] %>
+        <p class="ftr-copyright">© <%= Time.current.year %> <%= facts[:name] %></p>
+      <% end %>
+    </div>
+  </div>
+</footer>
+
+<%# The dialog the footer's booking links open. Nothing without a booking_url. %>
+<%= studio_booking_popup(label: facts[:booking_label], title: facts[:booking_title]) %>

data/app/views/studio/site_footer/_link.html.erb

@@ -0,0 +1,14 @@
+<%# One footer link (a normalized row from Studio::SiteFooter.link). A nil href
+    is a disabled label. An off-site link opens in a new tab, so the visitor
+    keeps the page. A booking link opens the booking popup when the app has a
+    booking_url; its href stays as the fallback. %>
+<% if link[:unlinked] %>
+  <%# Its href was refused (not a relative path, http, https, mailto or tel). %>
+  <span class="ftr-link-plain"><%= link[:label] %></span>
+<% elsif link[:disabled] %>
+  <span class="ftr-link-disabled" aria-disabled="true" title="Coming soon"><%= link[:label] %></span>
+<% else %>
+  <%= link_to link[:label], link[:href], { class: "ftr-link" }
+        .merge(link[:external] ? { target: "_blank", rel: "noopener" } : {})
+        .merge(link[:booking] && booking ? { data: { booking_popup: true, studio_booking: true } } : {}) %>
+<% end %>

data/app/views/studio/site_footer/_map.html.erb

@@ -0,0 +1,22 @@
+<%# One live map of an address. Leaflet mounts on this element (see
+    studio/site_footer/_assets, which this partial pulls in); until it does, and
+    if it never does, the link inside is the whole map: an address that opens
+    directions. `classes` and `style` size and shape it.
+
+    Leaflet's two files ride the engine's asset pipeline (studio/leaflet.js,
+    studio/leaflet.css). Their URLs travel on the element, so the script fetches
+    them only on a page that has a map. %>
+<%= studio_site_footer_assets %>
+<div class="ftr-map <%= local_assigns[:classes] %>"
+     <% if local_assigns[:style].present? %>style="<%= style %>"<% end %>
+     data-footer-map
+     data-lat="<%= address[:lat] %>" data-lng="<%= address[:lng] %>"
+     data-zoom="<%= local_assigns[:zoom] || address[:zoom] %>"
+     data-controls="<%= local_assigns.fetch(:controls, true) %>"
+     data-leaflet-js="<%= asset_path("studio/leaflet.js") %>"
+     data-leaflet-css="<%= asset_path("studio/leaflet.css") %>"
+     role="region" aria-label="Map of <%= address[:full] %>">
+  <a href="<%= address[:directions_url] %>" target="_blank" rel="noopener" class="ftr-map-fallback">
+    <%= address[:full] %> · Open in Maps
+  </a>
+</div>

data/app/views/studio/site_footer/_social_icon.html.erb

@@ -0,0 +1,23 @@
+<%# Brand marks for the footer's social row, drawn in currentColor. An icon the
+    engine has no mark for falls back to the label's first letter. %>
+<% case icon %>
+<% when :linkedin, :instagram, :x, :facebook, :youtube %>
+  <svg viewBox="0 0 24 24" width="18" height="18" aria-hidden="true" focusable="false">
+    <% case icon %>
+    <% when :linkedin %>
+      <path fill="currentColor" d="M20.447 20.452h-3.554v-5.569c0-1.328-.027-3.037-1.852-3.037-1.853 0-2.136 1.445-2.136 2.939v5.667H9.351V9h3.414v1.561h.046c.477-.9 1.637-1.85 3.37-1.85 3.601 0 4.267 2.37 4.267 5.455v6.286zM5.337 7.433a2.062 2.062 0 1 1 0-4.125 2.062 2.062 0 0 1 0 4.125zm1.782 13.019H3.555V9h3.564v11.452z"/>
+    <% when :instagram %>
+      <rect x="3" y="3" width="18" height="18" rx="5" fill="none" stroke="currentColor" stroke-width="2"/>
+      <circle cx="12" cy="12" r="4.2" fill="none" stroke="currentColor" stroke-width="2"/>
+      <circle cx="17.3" cy="6.7" r="1.3" fill="currentColor"/>
+    <% when :x %>
+      <path fill="currentColor" d="M18.901 1.153h3.68l-8.04 9.19L24 22.846h-7.406l-5.8-7.584-6.638 7.584H.474l8.6-9.83L0 1.154h7.594l5.243 6.932ZM17.61 20.644h2.039L6.486 3.24H4.298Z"/>
+    <% when :facebook %>
+      <path fill="currentColor" d="M22 12a10 10 0 1 0-11.56 9.88v-6.99H7.9V12h2.54V9.8c0-2.5 1.49-3.89 3.78-3.89 1.09 0 2.24.2 2.24.2v2.46h-1.26c-1.24 0-1.63.77-1.63 1.56V12h2.78l-.44 2.89h-2.34v6.99A10 10 0 0 0 22 12z"/>
+    <% when :youtube %>
+      <path fill="currentColor" d="M23.5 6.2a3 3 0 0 0-2.1-2.1C19.5 3.6 12 3.6 12 3.6s-7.5 0-9.4.5A3 3 0 0 0 .5 6.2 31 31 0 0 0 0 12a31 31 0 0 0 .5 5.8 3 3 0 0 0 2.1 2.1c1.9.5 9.4.5 9.4.5s7.5 0 9.4-.5a3 3 0 0 0 2.1-2.1A31 31 0 0 0 24 12a31 31 0 0 0-.5-5.8zM9.6 15.6V8.4l6.2 3.6-6.2 3.6z"/>
+    <% end %>
+  </svg>
+<% else %>
+  <span class="ftr-social-letter" aria-hidden="true"><%= label.to_s[0].to_s.upcase %></span>
+<% end %>

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/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/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.1"
+  VERSION = "0.83.0"
 end