studio-engine 0.82.1 → 0.84.0

data/app/helpers/studio/site_footer_helper.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Studio
+  # The site footer and the booking primitives, as view helpers. See
+  # docs/SITE_FOOTER.md and docs/BOOKING.md.
+  #
+  #   <%= studio_site_footer %>             the footer, where it should show
+  #   <%= studio_booking_frame %>           Google's booking page, inline
+  #   <%= studio_booking_link "Book a call", class: "btn btn-primary" %>
+  #   <%= studio_booking_popup %>           the dialog those links open
+  #   <%= studio_footer_map %>              the map alone, e.g. on a contact page
+  #
+  # Every one of them renders NOTHING when its configuration is absent
+  # (Studio.site_footer, Studio.booking_url), so a layout or a shared view can
+  # call them before an app has declared anything.
+  #
+  # Prefixed names for the reason Studio::GeoHelper gives: every helper module is
+  # included into every view.
+  module SiteFooterHelper
+    # The resolved facts (Studio::SiteFooter.resolve), or nil. Resolved once per
+    # request.
+    #
+    # A callable that RAISES must not take every page down with it, because the
+    # footer is in the layout. In production the error is logged once per process
+    # and the page renders with no footer; locally it raises, so whoever wrote the
+    # callable sees it.
+    def studio_site_footer_facts
+      return @_studio_site_footer_facts if defined?(@_studio_site_footer_facts)
+
+      @_studio_site_footer_facts =
+        begin
+          Studio.site_footer_for(self)
+        rescue StandardError => error
+          raise if studio_site_footer_raise?
+
+          studio_site_footer_report(error)
+          nil
+        end
+    end
+
+    # Where the footer shows: Studio.site_footer_visible, asked of this view. By
+    # default that is every page for a visitor and, for a signed-in viewer, only
+    # the controllers in Studio.site_footer_controllers (plus the booking page).
+    # Always false for an app that declared no footer.
+    def studio_show_site_footer?
+      return false if studio_site_footer_facts.nil?
+
+      Studio.site_footer_visible.call(self) ? true : false
+    end
+
+    # The one layout line. Renders the footer (and, with a booking_url, the
+    # booking popup) where studio_show_site_footer? says it belongs.
+    def studio_site_footer
+      return unless studio_show_site_footer?
+
+      render "studio/site_footer/footer", facts: studio_site_footer_facts
+    end
+
+    # The live map alone. With no arguments it maps the footer's address;
+    # pass lat:/lng: (and street:/city_line:/directions_url:) to map another.
+    # `class:` and `style:` size it: the element has no height of its own.
+    def studio_footer_map(address = nil, **options)
+      address = address ? Studio::SiteFooter.address(Studio::SiteFooter.symbolize(address)) : studio_site_footer_facts&.dig(:address)
+      return unless address && address[:map]
+
+      render "studio/site_footer/map", address: address, classes: options[:class], style: options[:style],
+                                       zoom: options[:zoom], controls: options.fetch(:controls, true)
+    end
+
+    # ---- booking ------------------------------------------------------------
+
+    def studio_booking? = Studio.booking_url.present?
+
+    # Google's embeddable page for the configured schedule (with gv=true).
+    def studio_booking_embed_url = Studio::Booking.embed_url(Studio.booking_url)
+
+    # Where a booking link goes when the popup cannot open (scripts off, a
+    # modified click, a page with no dialog): the app's booking page
+    # (Studio.booking_path, or the engine's /schedule when drawn), else Google's
+    # own page.
+    def studio_booking_fallback_path
+      Studio.booking_path_for(self) || Studio.booking_url
+    end
+
+    # The frame's accessible name.
+    def studio_booking_title(title = nil)
+      title.presence || studio_site_footer_facts&.dig(:booking_title) ||
+        "#{studio_booking_label} with #{studio_site_footer_name}"
+    end
+
+    # What the booking links, the popup and the booking page call the act.
+    def studio_booking_label
+      studio_site_footer_facts&.dig(:booking_label) || Studio::SiteFooter::DEFAULT_BOOKING_LABEL
+    end
+
+    # The site's name: the footer's, else the site identity's title.
+    def studio_site_footer_name
+      studio_site_footer_facts&.dig(:name) || Studio.site_identity[:title]
+    end
+
+    # The crop a frame renders with: { offset:, window:, frame_height: }, or nil
+    # for the whole frame at rest. `true` reads Studio.booking_crop; a Hash is a
+    # one-off; false or nil is no crop.
+    def studio_booking_crop(crop = true)
+      Studio::Booking.crop(crop == true ? Studio.booking_crop : crop)
+    end
+
+    # The inline booking frame. `crop:` is true (the default: use
+    # Studio.booking_crop, which is no crop until the app declares one), false
+    # (the whole page at rest) or a Hash for this frame alone.
+    def studio_booking_frame(title: nil, crop: true)
+      return unless studio_booking?
+
+      render "studio/booking/frame", title: studio_booking_title(title), crop: studio_booking_crop(crop)
+    end
+
+    # The booking dialog, once per page however often it is asked for. The
+    # footer renders it; call this yourself only on a page that has booking
+    # links and no footer.
+    def studio_booking_popup(label: nil, title: nil)
+      return unless studio_booking?
+      return if @_studio_booking_popup_rendered
+
+      @_studio_booking_popup_rendered = true
+      render "studio/booking/popup",
+             label: label.presence || studio_booking_label,
+             title: studio_booking_title(title)
+    end
+
+    # A link that opens the booking popup in place. Its href is the fallback, so
+    # it is an ordinary link wherever the popup is unavailable. With no
+    # booking_url and no href there is nowhere to go, and it renders nothing.
+    #
+    #   <%= studio_booking_link %>                                  "Schedule a call"
+    #   <%= studio_booking_link "Book a call", class: "btn btn-primary" %>
+    #   <%= studio_booking_link "Book a call", contact_path %>      your own fallback
+    def studio_booking_link(name = nil, href = nil, html_options = nil, **options, &block)
+      html_options, href = href, nil if href.is_a?(Hash)
+      html_options, name = name, nil if name.is_a?(Hash)
+      html_options = (html_options || {}).merge(options)
+      href ||= studio_booking_fallback_path
+      return if href.blank?
+
+      html_options[:data] = { booking_popup: true, studio_booking: true }.merge(html_options[:data] || {}) if studio_booking?
+      content = block ? capture(&block) : (name || studio_booking_label)
+      link_to(content, href, html_options)
+    end
+
+    # ---- once-per-page assets -----------------------------------------------
+
+    def studio_site_footer_assets
+      return if @_studio_site_footer_assets_rendered
+
+      @_studio_site_footer_assets_rendered = true
+      render "studio/site_footer/assets"
+    end
+
+    def studio_booking_assets
+      return if @_studio_booking_assets_rendered
+
+      @_studio_booking_assets_rendered = true
+      render "studio/booking/assets"
+    end
+
+    private
+
+    def studio_site_footer_raise?
+      defined?(Rails) && Rails.respond_to?(:env) && (Rails.env.development? || Rails.env.test?)
+    end
+
+    def studio_site_footer_report(error)
+      return if Studio::SiteFooterHelper.reported
+
+      Studio::SiteFooterHelper.reported = true
+      if defined?(::ErrorLog) && ::ErrorLog.respond_to?(:capture!)
+        ::ErrorLog.capture!(error)
+      elsif defined?(Rails.logger) && Rails.logger
+        Rails.logger.error("[studio.site_footer] #{error.class}: #{error.message}")
+      end
+    rescue StandardError
+      nil
+    end
+
+    class << self
+      attr_accessor :reported
+    end
+  end
+end

data/app/views/studio/booking/_assets.html.erb

@@ -0,0 +1,196 @@
+<%# Styles and scripts for the booking frame and the booking popup. Rendered
+    once per page, by `studio_booking_assets` (the frame and the popup both ask).
+    Scoped CSS for the reason studio/site_footer/_assets gives. %>
+<style>
+  /* The inline frame. Google's page cannot be themed, so the panel is white. */
+  /* content-box, so the heights below are the WINDOW onto the frame whatever
+     reset the host runs: under border-box the border would eat 2px of the crop. */
+  .booking-frame { box-sizing: content-box; margin-inline: auto; overflow: hidden; background: #fff; border-radius: .75rem;
+    border: 1px solid var(--color-border, rgb(127 127 127 / .25));
+    /* A booking link on this page scrolls here; land below the pinned navbar. */
+    scroll-margin-top: calc(var(--nav-bottom, 4rem) + 1rem); }
+  .booking-frame iframe { display: block; width: 100%; border: 0; height: 1200px; }
+  /* From 640px up Google lays the month beside the slots. A cropped wrapper
+     carries its own numbers (Studio::Booking.crop_style): how far the frame is
+     pulled up, the window's height, and the frame's full height. A wrapper with
+     no crop carries none, and shows the frame whole at the default height. */
+  @media (min-width: 640px) {
+    .booking-frame iframe { height: var(--booking-frame-height, 732px); }
+    .booking-frame-cropped { height: var(--booking-crop-window); transition: height .25s ease; }
+    .booking-frame-cropped iframe { margin-top: calc(-1 * var(--booking-crop-offset)); transition: margin-top .25s ease; }
+    .booking-frame-cropped.is-open { height: var(--booking-frame-height, 732px); }
+    .booking-frame-cropped.is-open iframe { margin-top: 0; }
+  }
+  /* Scripts off: the frame never gets its src, so it is hidden and a plain link
+     stands in its place (the <noscript> in studio/booking/_frame). */
+  .booking-frame-noscript { margin: 0; padding: 3rem 1.5rem; text-align: center; color: #111; }
+  .booking-frame-noscript a { color: #4338ca; font-weight: 700; text-decoration: underline; }
+  .booking-frame-note { margin: 1rem 0 0; text-align: center; font-size: .875rem; line-height: 1.25rem; color: var(--color-text-muted, inherit); }
+  .booking-frame-note a { color: var(--color-primary, #8b5cf6); }
+  .booking-frame-note a:hover { text-decoration: underline; }
+
+  /* The popup. */
+  .booking-popup { width: min(960px, calc(100vw - 2rem)); height: min(800px, calc(100vh - 3rem)); height: min(800px, calc(100dvh - 3rem)); max-width: none; max-height: none;
+    /* Tailwind's reset zeroes a dialog's margin, which is what centres it. */
+    margin: auto; inset: 0;
+    padding: 0; border: 1px solid rgb(127 127 127 / .3); border-radius: .75rem; overflow: hidden;
+    background: var(--color-surface, #fff); color: var(--color-text-body, inherit); }
+  .booking-popup[open] { display: flex; flex-direction: column; }
+  .booking-popup::backdrop { background: rgb(15 12 31 / .72); backdrop-filter: blur(3px); }
+  .booking-popup-bar { display: flex; align-items: center; justify-content: space-between; gap: 1rem; margin: 0;
+    padding: .6rem .75rem .6rem 1.1rem; }
+  .booking-popup-title { font-weight: 700; color: var(--color-text, inherit); }
+  /* THE WAY OUT HAS TO BE UNMISSABLE. Once focus is inside Google's frame the
+     Escape key goes to Google, not to this dialog, and nothing here can change
+     that. So Close is a solid, full-size button, not a quiet glyph, and a click
+     anywhere on the backdrop closes too. */
+  /* Ink on surface, inverted: the theme's text colour as the fill and its
+     surface as the label. That pair is the theme's own highest contrast in both
+     modes (white on the primary measured 3.10:1, under the 4.5:1 a label needs). */
+  .booking-popup-close { flex: none; min-height: 2.75rem; padding: .5rem 1.1rem; border-radius: .5rem; border: 0;
+    background: var(--color-text, #111827); color: var(--color-surface, #fff); font: inherit; font-size: .95rem; font-weight: 700; cursor: pointer; }
+  .booking-popup-close:hover { filter: brightness(1.12); }
+  .booking-popup-close:focus-visible { outline: 3px solid var(--color-primary, #8b5cf6); outline-offset: 2px; }
+  /* The page behind does not scroll while the dialog is open. Pure CSS, so every
+     way of closing it (the button, the backdrop, Escape) lifts the lock. On html
+     rather than body for the reason studio/modals/_host gives. */
+  html:has(dialog[data-booking-dialog][open]) { overflow: hidden; }
+  .booking-popup iframe { flex: 1; width: 100%; border: 0; background: #fff; }
+  @media (prefers-reduced-motion: reduce) { .booking-frame, .booking-frame iframe { transition: none; } }
+</style>
+
+<script>
+  // The inline frame: assign src after `load`, once the frame is near the
+  // viewport, and open the crop when focus moves into the frame.
+  //
+  // THE GUARDS ARE THE ENGINE'S OWN NAMES, AND THE ELEMENTS ARE THE ENGINE'S OWN
+  // (data-studio-booking), for the reason studio/site_footer/_assets gives for
+  // the map: an app that still renders a local booking script guards it with
+  // the unprefixed names and marks its frame, dialog and links with the same
+  // data-booking-* attributes. Sharing either lets one script stand the other
+  // down across a Turbo visit, or act on elements that are not its own.
+  (function () {
+    if (window.__studioBookingFramesArmed) return;
+    window.__studioBookingFramesArmed = true;
+
+    // ASK GOOGLE ONCE. Two things can ask for a frame: scrolling near it, and a
+    // booking link that jumps to it. Assigning src a second time, even to the
+    // same URL, is a second request, so whoever comes second finds it set.
+    function load(frame) {
+      if (!frame.getAttribute('src')) frame.src = frame.dataset.src;
+    }
+    window.__studioBookingLoad = load;
+
+    function arm() {
+      document.querySelectorAll('iframe[data-booking-frame][data-studio-booking][data-src]').forEach(function (frame) {
+        if (frame.__bookingArmed) return;
+        frame.__bookingArmed = true;
+        if (typeof IntersectionObserver !== 'function') { load(frame); return; }
+        var watcher = new IntersectionObserver(function (entries) {
+          if (!entries.some(function (entry) { return entry.isIntersecting; })) return;
+          watcher.disconnect();
+          load(frame);
+        }, { rootMargin: '200px' });
+        watcher.observe(frame);
+      });
+    }
+
+    function armAfterLoad() {
+      if (document.readyState === 'complete') arm();
+      else window.addEventListener('load', arm, { once: true });
+    }
+
+    // Focus moving into the frame is the one signal a cross-origin frame gives
+    // its parent. It means the visitor has started using the calendar.
+    function openActive() {
+      var active = document.activeElement;
+      if (!active || !active.matches || !active.matches('iframe[data-booking-frame][data-studio-booking]')) return;
+      var wrap = active.closest('[data-booking-wrap][data-studio-booking]');
+      if (wrap) wrap.classList.add('is-open');
+    }
+
+    // THE WINDOW BLURS ONCE. Focus that moves from one frame straight into
+    // another never comes back through this window, so no second blur announces
+    // the second frame, and on a page with two cropped frames it would stay
+    // cropped under the visitor's cursor. So while focus is away in a frame and a
+    // cropped wrapper is still shut, look again a few times a second. It stops
+    // when focus returns here or nothing is left to open, and a page with one
+    // frame never starts it: that frame is open by then.
+    var watching = null;
+    function shut() { return document.querySelector('[data-booking-wrap][data-studio-booking][data-booking-crop]:not(.is-open)'); }
+    function stopWatching() { if (watching) { clearInterval(watching); watching = null; } }
+
+    window.addEventListener('blur', function () {
+      openActive();
+      var active = document.activeElement;
+      if (watching || !active || active.tagName !== 'IFRAME' || !shut()) return;
+      watching = setInterval(function () {
+        openActive();
+        if (!shut()) stopWatching();
+      }, 250);
+    });
+    window.addEventListener('focus', stopWatching);
+
+    document.addEventListener('turbo:load', armAfterLoad);
+    armAfterLoad();
+  })();
+</script>
+
+<script>
+  // Any a[data-booking-popup] link opens the booking dialog instead of leaving
+  // the page. Delegated from document, so it survives Turbo body swaps. A
+  // modified click (new tab, new window) is left alone, and so is everything
+  // when the dialog is missing or <dialog> is unsupported: the link's own href
+  // then takes the visitor to the booking page.
+  //
+  // ON A PAGE THAT ALREADY SHOWS THE INLINE FRAME the link goes to that frame
+  // instead: it scrolls there, opens the crop and moves focus in. A popup would
+  // be a second copy of the calendar on top of the first.
+  (function () {
+    if (window.__studioBookingPopupArmed) return;
+    window.__studioBookingPopupArmed = true;
+
+    document.addEventListener('click', function (event) {
+      var link = event.target.closest && event.target.closest('a[data-booking-popup][data-studio-booking]');
+      if (!link) return;
+      if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+
+      var inline = document.querySelector('iframe[data-booking-frame][data-studio-booking]');
+      if (inline) {
+        event.preventDefault();
+        var wrap = inline.closest('[data-booking-wrap][data-studio-booking]');
+        if (wrap) wrap.classList.add('is-open');
+        // Before `load` the frame keeps waiting: its own script assigns src then.
+        if (document.readyState === 'complete' && window.__studioBookingLoad) window.__studioBookingLoad(inline);
+        var calm = window.matchMedia && window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+        (wrap || inline).scrollIntoView({ behavior: calm ? 'auto' : 'smooth', block: 'start' });
+        inline.focus({ preventScroll: true });
+        return;
+      }
+
+      var dialog = document.querySelector('dialog[data-booking-dialog][data-studio-booking]');
+      if (!dialog || typeof dialog.showModal !== 'function') return;
+
+      event.preventDefault();
+      var frame = dialog.querySelector('iframe[data-booking-popup-frame]');
+      if (frame && !frame.getAttribute('src')) frame.src = frame.dataset.src;
+      if (!dialog.open) dialog.showModal();
+    });
+
+    // A click on the backdrop lands on the dialog element itself.
+    document.addEventListener('click', function (event) {
+      if (event.target.matches && event.target.matches('dialog[data-booking-dialog][data-studio-booking]')) event.target.close();
+    });
+
+    // Never snapshot the dialog open: a restored page would show it stuck. And
+    // never snapshot its frame loaded: a restored page would ask Google for a
+    // popup nobody has opened. The src goes back to waiting in data-src.
+    document.addEventListener('turbo:before-cache', function () {
+      var dialog = document.querySelector('dialog[data-booking-dialog][data-studio-booking]');
+      if (!dialog) return;
+      if (dialog.open) dialog.close();
+      var frame = dialog.querySelector('iframe[data-booking-popup-frame]');
+      if (frame) frame.removeAttribute('src');
+    });
+  })();
+</script>

data/app/views/studio/booking/_frame.html.erb

@@ -0,0 +1,44 @@
+<%# Google's inline booking page for the app's appointment schedule
+    (Studio.booking_url). Rendered by `studio_booking_frame`. It fills its
+    container, so it lines up with the cards around it. Google lays it out by
+    width: month beside the slots from about 600px, stacked below that. It
+    cannot be themed, so it sits on a white panel in both themes.
+
+    WHOLE AT REST unless the app declares a crop (Studio.booking_crop, or
+    `crop:` on the call). `crop` here is the resolved crop, a Hash of offset,
+    window and frame_height, or nil.
+
+    CROPPED AT REST, WHOLE IN USE, when it has one. From 640px up the wrapper
+    shows only the "Select an appointment time" box: Google's header above it
+    and its credit lines below are clipped. Where that box sits belongs to one
+    schedule, so the numbers ride on the wrapper as custom properties and two
+    frames with different crops can share a page. The crop cannot stay on,
+    because the form that opens when a slot is picked is a dialog centred in the
+    frame's FULL height, so a cropped frame cuts off its title and its Book
+    button. A cross-origin frame reports no clicks, but the parent window does
+    lose focus to it; on that signal the wrapper opens to the full frame.
+    Below 640px Google stacks the month above the slots and nothing is cropped.
+
+    THE SRC IS DEFERRED, and not with loading="lazy". The frame is a third
+    party, and a frame that starts loading before the window's `load` event
+    holds that event open for as long as Google takes to answer. So the URL
+    waits in data-src and the script in studio/booking/_assets assigns it only
+    AFTER `load`, once the frame is near the viewport.
+
+    WITH SCRIPTS OFF nothing ever assigns the src, so the <noscript> hides the
+    empty frame and puts a plain link to Google's booking page in its place. %>
+<%= studio_booking_assets %>
+<div class="booking-frame<%= " booking-frame-cropped" if crop %>" data-booking-wrap data-studio-booking<% if crop %> data-booking-crop style="<%= Studio::Booking.crop_style(crop) %>"<% end %>>
+  <iframe data-booking-frame data-studio-booking
+          data-src="<%= studio_booking_embed_url %>"
+          title="<%= title %>"
+          width="100%" frameborder="0"></iframe>
+  <noscript>
+    <style>.booking-frame { height: auto !important; } .booking-frame iframe { display: none !important; }</style>
+    <p class="booking-frame-noscript"><a href="<%= Studio.booking_url %>" target="_blank" rel="noopener">Open the booking page to pick a time</a></p>
+  </noscript>
+</div>
+<p class="booking-frame-note">
+  Scheduling by Google Calendar. Trouble seeing it?
+  <a href="<%= Studio.booking_url %>" target="_blank" rel="noopener">Open the booking page</a>.
+</p>

data/app/views/studio/booking/_popup.html.erb

@@ -0,0 +1,34 @@
+<%# The booking popup: Google's appointment page in a dialog, opened by any
+    a[data-booking-popup] link on the page (studio/booking/_assets carries the
+    script). Rendered once per page by `studio_booking_popup`; the site footer
+    calls it.
+
+    It does what Google's own scheduling-button script does, without loading
+    that script, its stylesheet and its icon font on every public page: the
+    frame is requested only when the dialog first opens. The links keep their
+    own href, so with scripts off, or on a modified click, they are ordinary
+    links to the booking page.
+
+    A NATIVE <dialog>, NOT THE MODAL HOST (studio/modals/_host), on purpose. The
+    host needs Alpine, its store, and each modal registered inside the host's
+    block in the layout, so the footer would stop being one layout line and an
+    app with no host would have no popup. Its card is padded and scrolls, where
+    this body is a full-bleed frame. And it mounts content through
+    <template x-if>, which would build a new frame, and ask Google again, on
+    every open; this dialog keeps the loaded one. showModal() gives the top
+    layer, the inert page and the focus trap without any of that.
+
+    ESCAPE HAS A LIMIT NOTHING HERE CAN LIFT. Once focus is inside Google's
+    frame, key presses go to Google (it is another origin), so Escape no longer
+    reaches the dialog. The Close button and a click on the backdrop always
+    work, which is why the button is a solid one. %>
+<%= studio_booking_assets %>
+<dialog class="booking-popup" data-booking-dialog data-studio-booking aria-label="<%= label %>">
+  <form method="dialog" class="booking-popup-bar">
+    <span class="booking-popup-title"><%= label %></span>
+    <button type="submit" class="booking-popup-close" data-booking-close>Close ✕</button>
+  </form>
+  <iframe data-booking-popup-frame
+          data-src="<%= studio_booking_embed_url %>"
+          title="<%= title %>" frameborder="0"></iframe>
+</dialog>

data/app/views/studio/bookings/show.html.erb

@@ -0,0 +1,22 @@
+<%# /schedule — the booking page (Studio::BookingsController), drawn by
+    Studio.draw_booking_routes. It is where a booking link lands when the popup
+    cannot open. The frame takes the app's crop (Studio.booking_crop), as it
+    does anywhere. An app that wants different words around the frame renders
+    `studio_booking_frame` in a view of its own instead, and names that page in
+    Studio.booking_path. %>
+<% label = studio_booking_label %>
+<% content_for(:title, "#{label} · #{studio_site_footer_name}") %>
+<% content_for(:full_width, true) %>
+
+<section class="booking-page" data-booking-page>
+  <h1 class="booking-page-title"><%= label %></h1>
+  <p class="booking-page-lede">Pick a time that works and it goes straight on the calendar.</p>
+  <%= studio_booking_frame %>
+</section>
+
+<style>
+  .booking-page { max-width: 56rem; margin-inline: auto; padding: 4rem 1rem; }
+  .booking-page-title { margin: 0; text-align: center; font-size: 2.25rem; font-weight: 800; letter-spacing: -.025em;
+    color: var(--color-text, inherit); }
+  .booking-page-lede { margin: .75rem 0 2rem; text-align: center; font-size: 1.125rem; color: var(--color-text-secondary, inherit); }
+</style>