studio-engine 0.92.2 → 0.94.0

data/app/models/concerns/sluggable.rb

@@ -1,17 +1,167 @@
+# A human-readable `slug` that is written once and changed only on purpose.
+#
+# The slug is set at create from `name_slug` (each including model defines it)
+# and never recomputed by a later save, because other tables point at it by
+# value: a display-name edit must not rename the row and orphan its children.
+# A persisted row whose slug is blank gets one on its next save, since filling a
+# blank is still the first write. A `name_slug` that reads the id (`user-<id>`)
+# is settled once more right after the insert, inside the create, because the
+# id does not exist when before_save runs.
+#
+# The one way to change a persisted slug is `rename_slug!` (or `rename_slug`),
+# which updates the row and every child column that references it in one
+# transaction. The children are found two ways:
+#
+#   * every `has_many` / `has_one` on the model with `primary_key: :slug`;
+#   * every pair declared with `has_slug_children`, for a table that has no
+#     association here:
+#
+#       class Person < ApplicationRecord
+#         include Sluggable
+#         has_slug_children "athletes" => :person_slug,
+#                           "news" => %i[primary_person_slug secondary_person_slug]
+#       end
+#
+# The declaration lives on the parent so the cascade never depends on whether a
+# child class happens to be loaded.
+#
+# A refusal (blank, badly formed, or taken) raises Sluggable::SlugRefused, a
+# subclass of ActiveRecord::RecordInvalid, with the reason on `errors[:slug]`.
+# Studio::ErrorHandling answers it with 422 and the reason, never a 500, and
+# `rename_slug` returns false instead of raising, for an inline form error.
 module Sluggable
   extend ActiveSupport::Concern
 
+  # Lowercase words of letters and digits joined by single hyphens: the shape
+  # `String#parameterize` produces. A model whose slugs legitimately hold other
+  # characters sets its own `self.slug_format`.
+  DEFAULT_SLUG_FORMAT = /\A[a-z0-9]+(?:-[a-z0-9]+)*\z/
+
+  # The refusal rename_slug! raises: a RecordInvalid, so a caller that already
+  # rescues RecordInvalid keeps working, with a class of its own so the
+  # controller layer can answer it with 422 without claiming every invalid save.
+  class SlugRefused < ActiveRecord::RecordInvalid; end
+
   included do
-    before_save :set_slug
+    class_attribute :slug_format, instance_writer: false, default: DEFAULT_SLUG_FORMAT
+    class_attribute :declared_slug_children, instance_writer: false, default: [].freeze
+
+    before_save :set_slug, if: :sluggable_unwritten?
+    after_create :sluggable_settle_derived_slug
+  end
+
+  class_methods do
+    # Declares child columns that hold this model's slug: a hash of table name to
+    # one column or a list of columns. Repeatable; each call adds to the set.
+    def has_slug_children(pairs)
+      added = pairs.flat_map do |table, columns|
+        Array(columns).map { |column| [table.to_s, column.to_s].freeze }
+      end
+      self.declared_slug_children = (declared_slug_children + added).uniq.freeze
+    end
+
+    # Every [table, column] pair `rename_slug!` updates: the slug-keyed
+    # associations plus the declared pairs, without duplicates.
+    def slug_children
+      from_associations = reflect_on_all_associations.filter_map do |reflection|
+        next unless %i[has_many has_one].include?(reflection.macro)
+        next if reflection.through_reflection? || reflection.polymorphic? || reflection.options[:as]
+        next unless reflection.options[:primary_key].to_s == "slug"
+
+        [reflection.klass.table_name, reflection.foreign_key.to_s].freeze
+      end
+      (from_associations + declared_slug_children).uniq
+    end
   end
 
   def to_param
     slug
   end
 
+  # Changes this row's slug to `new_slug` and rewrites every child column that
+  # held the old one, all or nothing. Returns { "table.column" => rows updated }.
+  # Raises Sluggable::SlugRefused, with the reason on errors[:slug], when
+  # the slug is blank, badly formed, or already taken.
+  def rename_slug!(new_slug)
+    raise ActiveRecord::RecordNotSaved.new("a slug can be renamed only on a saved record", self) unless persisted?
+
+    new_slug = new_slug.to_s.strip
+    old_slug = slug_in_database
+    errors.delete(:slug)
+    return {} if new_slug == old_slug
+
+    sluggable_refuse!(:blank) if new_slug.empty?
+    sluggable_refuse!(:invalid) unless slug_format.match?(new_slug)
+    sluggable_refuse!(:taken, value: new_slug) if sluggable_taken?(new_slug)
+
+    renamed = { slug: new_slug }
+    renamed[:updated_at] = Time.current if has_attribute?(:updated_at)
+    counts = {}
+    self.class.transaction(requires_new: true) do
+      self.class.base_class.unscoped.where(self.class.primary_key => id).update_all(renamed)
+      self.class.slug_children.each do |table, column|
+        counts["#{table}.#{column}"] = sluggable_cascade(table, column, old_slug, new_slug)
+      end
+    end
+    renamed.each { |name, value| write_attribute(name, value) }
+    clear_attribute_changes(renamed.keys)
+    counts
+  rescue ActiveRecord::RecordNotUnique
+    # The pre-check passed and a concurrent write took the slug first; the
+    # unique index is the arbiter, and the answer is the same refusal.
+    sluggable_refuse!(:taken, value: new_slug)
+  rescue ActiveRecord::InvalidForeignKey
+    sluggable_refuse!(:invalid, message: "cannot change while a constraint without ON UPDATE CASCADE references it")
+  end
+
+  # rename_slug! for a form: false, with the reason on errors[:slug], instead of
+  # raising.
+  def rename_slug(new_slug)
+    rename_slug!(new_slug)
+    true
+  rescue SlugRefused
+    false
+  end
+
   private
 
+  def sluggable_unwritten?
+    new_record? || slug.blank?
+  end
+
+  # A model may override this; the override owns its slug, and the post-insert
+  # settle below leaves it alone.
   def set_slug
-    self.slug = name_slug
+    self.slug = @sluggable_derived_slug = name_slug
+  end
+
+  def sluggable_settle_derived_slug
+    derived = @sluggable_derived_slug
+    @sluggable_derived_slug = nil
+    return if derived.nil? || slug != derived
+
+    settled = name_slug
+    update_column(:slug, settled) if settled.present? && settled != slug
+  end
+
+  def sluggable_taken?(candidate)
+    self.class.base_class.unscoped.where(slug: candidate).where.not(self.class.primary_key => id).exists?
+  end
+
+  # One UPDATE on the parent's connection: the cascade a foreign key with
+  # ON UPDATE CASCADE would run, and it needs no model for the child table.
+  def sluggable_cascade(table, column, old_slug, new_slug)
+    connection = self.class.connection
+    quoted_column = connection.quote_column_name(column)
+    connection.update(<<~SQL.squish, "Sluggable cascade")
+      UPDATE #{connection.quote_table_name(table)}
+      SET #{quoted_column} = #{connection.quote(new_slug)}
+      WHERE #{quoted_column} = #{connection.quote(old_slug)}
+    SQL
+  end
+
+  def sluggable_refuse!(reason, **options)
+    errors.add(:slug, reason, **options)
+    raise SlugRefused, self
   end
 end

data/app/views/layouts/_navbar.html.erb

@@ -40,20 +40,27 @@
   logo_path = Studio.logo_for("Navbar Logo")
 %>
 
-<%# nav-shell is the --nav-p scope: navCollapse() (layouts/studio/_head) writes
+<%# nav-shell is the --nav-p scope: the engine's nav-collapse controller (studio/nav_collapse) writes
     the collapse progress, 0 expanded .. 1 collapsed, on THIS element once per
     animation frame, and the band table below derives the row padding, logo size
     and title sizes from it with calc(). Nothing on the collapse path carries a
     time-based transition — the head's comment carries the measurements that
     bought that. transition-shadow stays: box-shadow paints, it never reflows,
     so it cannot move content under the reader.
-    Preview keeps nav-shell (the calc()s have to resolve) but no x-data — the
-    /navbar review page drives --nav-p from its own Scrolled toggle. %>
+    The controller toggles the scrolled classes (the shadow) when the scroll
+    passes its hysteresis.
+    Preview keeps nav-shell (the calc()s have to resolve) but no controller — the
+    /navbar review page drives --nav-p from its own Scrolled toggle, and its
+    :class reads that toggle's `scrolled`. %>
 <%# data-pin names this header as a layer of the pinned stack, so
     layouts/studio/_head publishes --pin-nav-h and --pin-nav-bottom for it and
     anything below can position off it in pure CSS. The legacy --nav-h /
     --nav-bottom keep publishing unchanged; this is additive. %>
-<header data-pin="nav" <%= 'x-data="navCollapse()"'.html_safe unless is_preview %>
+<%# The bare x-data is the Alpine scope the header's descendants still bind
+    through ($store.devMode on the user nav, the sidebar trigger's @click):
+    Alpine initializes directives only inside a component, and the header was
+    that component while navCollapse() lived on it. %>
+<header data-pin="nav"<% unless is_preview %> x-data data-studio-controller="nav-collapse" data-nav-collapse-scrolled-class="shadow-lg border-b border-subtle is-scrolled"<% end %>
         <%# top-0, a STATIC value, and never a custom property. Any bars render as
             this header's sibling in normal flow (studio/banners/_stack), so they
             already occupy their own height above it and there is nothing to
@@ -63,7 +70,7 @@
             during a view transition composited at two different tops. Only CSS
             can set this top now, so none of that is reachable. %>
         class="nav-shell <%= is_preview ? 'bg-page' : "#{'vt-pinned-header ' if pin_header}sticky top-0 z-50 bg-page transition-shadow duration-300" %>"
-        :class="scrolled && 'shadow-lg border-b border-subtle is-scrolled'">
+        <%= %(:class="scrolled && 'shadow-lg border-b border-subtle is-scrolled'").html_safe if is_preview %>>
   <style>
     /* THE PHONE STEP IS A SHARE OF THE VIEWPORT, NOT A CONSTANT, and that is the
        whole width fix. 14rem is 224px — 57% of a 390px screen — handed to a
@@ -109,7 +116,8 @@
        was left to hand-write its own — the way four independent copies happened
        in the first place. It ships from engine.css now (every consuming app
        imports it), so a forking app OPTS IN with `nav-shell` +
-       x-data="navCollapse()" and overrides only the endpoints that differ.
+       data-studio-controller="nav-collapse" (or x-data="navCollapse()",
+       the Alpine shim) and overrides only the endpoints that differ.
 
        THE OPT-IN IS NOT THE WHOLE JOB — this is the partial a forker actually
        reads, so the caveat belongs here too rather than only beside the band