activeadmin_annotations 0.1.0

data/app/assets/stylesheets/activeadmin_annotations.css

@@ -0,0 +1,362 @@
+.aa-annotations-panel {
+  margin-top: 1rem;
+}
+
+.aa-annotations-stale-banner {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+  margin-bottom: 1rem;
+  padding: 0.75rem 1rem;
+  border: 1px solid #f59e0b;
+  border-radius: 0.5rem;
+  background: #fffbeb;
+}
+
+.dark .aa-annotations-stale-banner {
+  border-color: #b45309;
+  background: #451a03;
+}
+
+.aa-annotations-stale-banner p {
+  margin: 0;
+}
+
+.aa-annotations-version {
+  margin: 0 0 0.75rem;
+  color: #6b7280;
+  font-size: 0.875rem;
+}
+
+.dark .aa-annotations-version {
+  color: #9ca3af;
+}
+
+.aa-annotations-layout {
+  align-items: start;
+  display: grid;
+  gap: 1.5rem;
+  grid-template-columns: minmax(0, 1fr) minmax(16rem, 22rem);
+}
+
+.aa-annotations-sidebar {
+  background: #ffffff;
+  border: 1px solid #e5e7eb;
+  border-radius: 0.5rem;
+  padding: 1rem;
+  position: sticky;
+  top: 5rem;
+}
+
+.dark .aa-annotations-sidebar {
+  background: rgb(3 7 18 / 0.6);
+  border-color: rgb(255 255 255 / 0.1);
+}
+
+.aa-annotations-sidebar h4,
+.aa-annotations-composer h4 {
+  color: #111827;
+  font-size: 0.95rem;
+  font-weight: 600;
+  margin: 0 0 0.75rem;
+}
+
+.dark .aa-annotations-sidebar h4,
+.dark .aa-annotations-composer h4 {
+  color: #f9fafb;
+}
+
+.aa-annotations-hint {
+  color: #6b7280;
+  font-size: 0.875rem;
+  line-height: 1.4;
+  margin: 0 0 1rem;
+}
+
+.dark .aa-annotations-hint {
+  color: #9ca3af;
+}
+
+.aa-annotations-annotation-item {
+  border-top: 1px solid #e5e7eb;
+  padding-top: 0.75rem;
+}
+
+.aa-annotations-list .aa-annotations-annotation-item:first-child {
+  border-top: none;
+  padding-top: 0;
+}
+
+.dark .aa-annotations-annotation-item {
+  border-top-color: rgb(255 255 255 / 0.1);
+}
+
+.aa-annotations-annotation-item blockquote {
+  border-left: 3px solid #2563eb;
+  color: #374151;
+  margin: 0 0 0.5rem;
+  padding-left: 0.75rem;
+}
+
+.dark .aa-annotations-annotation-item blockquote {
+  color: #d1d5db;
+}
+
+.aa-annotations-annotation-item p {
+  color: #111827;
+  font-size: 0.875rem;
+  line-height: 1.45;
+  margin: 0.25rem 0;
+}
+
+.aa-annotations-annotation-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  margin-top: 0.75rem;
+}
+
+.aa-annotations-annotation-actions .action-item-button {
+  cursor: pointer;
+}
+
+.aa-annotations-delete-button {
+  color: #b91c1c;
+}
+
+.dark .aa-annotations-delete-button {
+  color: #f87171;
+}
+
+.aa-annotations-empty {
+  color: #6b7280;
+  font-size: 0.875rem;
+  margin: 0;
+}
+
+.dark .aa-annotations-empty {
+  color: #9ca3af;
+}
+
+.aa-annotations-list {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.dark .aa-annotations-annotation-item p {
+  color: #e5e7eb;
+}
+
+.aa-annotations-composer-hidden,
+.aa-annotations-hidden {
+  display: none;
+}
+
+.aa-annotations-composer {
+  border-bottom: 1px solid #e5e7eb;
+  margin-bottom: 1rem;
+  padding-bottom: 1rem;
+}
+
+.dark .aa-annotations-composer {
+  border-bottom-color: rgb(255 255 255 / 0.1);
+}
+
+.aa-annotations-composer label {
+  color: #374151;
+  display: block;
+  font-size: 0.875rem;
+  font-weight: 500;
+  margin: 0 0 0.35rem;
+}
+
+.dark .aa-annotations-composer label {
+  color: #d1d5db;
+}
+
+.aa-annotations-selected-preview {
+  background: #f9fafb;
+  border: 1px solid #e5e7eb;
+  border-left: 3px solid #2563eb;
+  border-radius: 0.375rem;
+  color: #374151;
+  font-size: 0.875rem;
+  line-height: 1.45;
+  margin: 0 0 1rem;
+  padding: 0.65rem 0.75rem;
+}
+
+.dark .aa-annotations-selected-preview {
+  background: rgb(255 255 255 / 0.05);
+  border-color: rgb(255 255 255 / 0.1);
+  color: #e5e7eb;
+}
+
+.aa-annotations-composer textarea,
+.aa-annotations-composer select {
+  background-color: #f9fafb;
+  border: 1px solid #d1d5db;
+  border-radius: 0.375rem;
+  box-sizing: border-box;
+  color: #111827;
+  display: block;
+  font-size: 0.875rem;
+  line-height: 1.45;
+  margin: 0 0 1rem;
+  padding: 0.55rem 0.75rem;
+  width: 100%;
+}
+
+.aa-annotations-composer textarea {
+  min-height: 6rem;
+  resize: vertical;
+}
+
+.aa-annotations-composer select {
+  appearance: auto;
+}
+
+.aa-annotations-composer textarea:focus,
+.aa-annotations-composer select:focus {
+  border-color: #3b82f6;
+  outline: 2px solid transparent;
+  outline-offset: 2px;
+  box-shadow: 0 0 0 3px rgb(59 130 246 / 0.25);
+}
+
+.dark .aa-annotations-composer textarea,
+.dark .aa-annotations-composer select {
+  background-color: rgb(255 255 255 / 0.05);
+  border-color: rgb(255 255 255 / 0.1);
+  color: #ffffff;
+}
+
+.dark .aa-annotations-composer select option {
+  background-color: #1f2937;
+  color: #ffffff;
+}
+
+.aa-annotations-composer-actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+}
+
+.aa-annotations-composer-actions .action-item-button {
+  cursor: pointer;
+}
+
+.aa-annotations-save-button {
+  background-color: #2563eb;
+  border-color: #2563eb;
+  color: #ffffff;
+}
+
+.aa-annotations-save-button:hover {
+  background-color: #1d4ed8;
+  border-color: #1d4ed8;
+  color: #ffffff;
+}
+
+.dark .aa-annotations-save-button {
+  background-color: #2563eb;
+  border-color: #2563eb;
+  color: #ffffff;
+}
+
+.dark .aa-annotations-save-button:hover {
+  background-color: #1d4ed8;
+  border-color: #1d4ed8;
+  color: #ffffff;
+}
+
+.aa-annotations-annotatable {
+  background: #ffffff;
+  border: 1px solid #e5e7eb;
+  border-radius: 0.5rem;
+  padding: 1rem;
+  user-select: text;
+}
+
+.dark .aa-annotations-annotatable {
+  background: rgb(255 255 255 / 0.03);
+  border-color: rgb(255 255 255 / 0.1);
+}
+
+::highlight(aa-annotations-saved) {
+  background-color: color-mix(in srgb, #2563eb 30%, #fef08a);
+  color: inherit;
+}
+
+::highlight(aa-annotations-pending) {
+  background-color: color-mix(in srgb, #2563eb 40%, #fef08a);
+  color: inherit;
+  text-decoration: underline;
+  text-decoration-color: #2563eb;
+  text-underline-offset: 2px;
+}
+
+.aa-annotations-context {
+  margin-top: 1rem;
+}
+
+.aa-annotations-context-panel {
+  border: 1px solid #e5e7eb;
+  border-radius: 0.375rem;
+  margin-bottom: 0.75rem;
+  padding: 0.5rem 0.75rem;
+}
+
+.dark .aa-annotations-context-panel {
+  border-color: rgb(255 255 255 / 0.1);
+}
+
+.aa-annotations-context-panel summary {
+  color: #111827;
+  cursor: pointer;
+  font-size: 0.875rem;
+  font-weight: 600;
+}
+
+.dark .aa-annotations-context-panel summary {
+  color: #f9fafb;
+}
+
+.aa-annotations-context-panel pre {
+  background: #f9fafb;
+  border-radius: 0.375rem;
+  color: #374151;
+  font-size: 0.75rem;
+  margin-top: 0.5rem;
+  max-height: 24rem;
+  overflow: auto;
+  padding: 0.75rem;
+  white-space: pre-wrap;
+}
+
+.dark .aa-annotations-context-panel pre {
+  background: rgb(255 255 255 / 0.05);
+  color: #d1d5db;
+}
+
+.aa-annotations-error {
+  color: #b91c1c;
+  font-size: 0.875rem;
+  margin: 0.75rem 0 0;
+}
+
+.dark .aa-annotations-error {
+  color: #f87171;
+}
+
+@media (max-width: 960px) {
+  .aa-annotations-layout {
+    grid-template-columns: 1fr;
+  }
+
+  .aa-annotations-sidebar {
+    position: static;
+  }
+}

data/app/helpers/active_admin/annotations/panel_helper.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module ActiveAdmin::Annotations
+  module PanelHelper
+    def activeadmin_annotations_panel(
+      subject:,
+      field:,
+      context:,
+      context_digest: nil,
+      context_panels: [],
+      categories: nil,
+      category_label: nil,
+      content: nil,
+      content_revision_enabled: nil,
+      content_revision_version: nil,
+      latest_content_revision_version: nil,
+      content_stale: false,
+      advance_review_url: nil,
+      annotations: nil,
+      review: nil,
+      &content_block
+    )
+      rendered_content = content.presence || capture(&content_block)
+      reviewer = current_activeadmin_annotations_reviewer
+      unless reviewer
+        return render partial: "active_admin/annotations/read_only_content",
+          locals: {content: rendered_content}
+      end
+
+      revision_enabled = content_revision_enabled.nil? ? ContentRevision.enabled_for?(subject) : content_revision_enabled
+      review ||= ReviewService.find_or_sync_review!(
+        subject: subject,
+        reviewer: reviewer,
+        context: context,
+        context_digest: context_digest,
+        content_revision_version: content_revision_version || 0,
+        latest_content_revision_version: latest_content_revision_version || content_revision_version || 0,
+        content_revision_enabled: revision_enabled
+      )
+      annotations ||= annotations_for(review:, field:, revision_enabled:)
+      stale_message = stale_message_for(
+        review: review,
+        revision_enabled: revision_enabled,
+        pinned_version: review.content_revision_version,
+        latest_version: latest_content_revision_version || review.content_revision_version
+      )
+
+      render partial: "active_admin/annotations/panel",
+        locals: {
+          subject: subject,
+          field: field.to_s,
+          review: review,
+          annotations: annotations,
+          context_panels: context_panels,
+          categories: categories || ActiveAdmin::Annotations.categories,
+          category_label: category_label || ActiveAdmin::Annotations.category_label,
+          content: rendered_content,
+          content_revision_enabled: revision_enabled,
+          content_revision_version: review.content_revision_version,
+          latest_content_revision_version: latest_content_revision_version || review.content_revision_version,
+          content_revision_label: ContentRevision.version_label(review.content_revision_version),
+          content_stale: content_stale || review.context_stale?,
+          stale_message: stale_message,
+          advance_review_url: advance_review_url
+        }
+    end
+
+    private
+
+    def annotations_for(review:, field:, revision_enabled:)
+      scope = review.annotations.where(field_name: field.to_s).order(:created_at)
+      return scope unless revision_enabled
+
+      scope.where(content_revision_version: review.content_revision_version)
+    end
+
+    def stale_message_for(review:, revision_enabled:, pinned_version:, latest_version:)
+      return unless review.context_stale?
+
+      if revision_enabled
+        ContentRevision.stale_review_message(
+          review: review,
+          pinned_version: pinned_version,
+          latest_version: latest_version
+        )
+      else
+        ContentRevision.stale_context_message(review: review)
+      end
+    end
+
+    def current_activeadmin_annotations_reviewer
+      respond_to?(:current_user) ? current_user : nil
+    end
+  end
+end

data/app/models/active_admin/annotations/annotation.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+class ActiveAdmin::Annotations::Annotation < ActiveAdmin::Annotations::ApplicationRecord
+  self.table_name = "annotation_spans"
+
+  belongs_to :annotation_review,
+    class_name: "ActiveAdmin::Annotations::Review",
+    inverse_of: :annotations
+
+  validates :field_name, :selected_text, :comment, presence: true
+  validates :start_offset, :end_offset, numericality: {greater_than_or_equal_to: 0}
+  validate :end_offset_after_start_offset
+  validate :category_must_be_allowed
+
+  def self.ransackable_attributes(_auth_object = nil)
+    %w[annotation_review_id field_name category comment created_at]
+  end
+
+  def self.ransackable_associations(_auth_object = nil)
+    %w[annotation_review]
+  end
+
+  private
+
+  def end_offset_after_start_offset
+    return if start_offset.blank? || end_offset.blank?
+    return if end_offset >= start_offset
+
+    errors.add(:end_offset, "must be greater than or equal to start offset")
+  end
+
+  def category_must_be_allowed
+    return if ActiveAdmin::Annotations::Categories.allowed?(category)
+
+    errors.add(:category, "is invalid")
+  end
+end

data/app/models/active_admin/annotations/application_record.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class ActiveAdmin::Annotations::ApplicationRecord < ActiveRecord::Base
+  self.abstract_class = true
+
+  def self.ransackable_associations(_auth_object = nil)
+    reflect_on_all_associations.map { |association| association.name.to_s }
+  end
+
+  def self.ransackable_attributes(_auth_object = nil)
+    column_names
+  end
+end

data/app/models/active_admin/annotations/review.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+class ActiveAdmin::Annotations::Review < ActiveAdmin::Annotations::ApplicationRecord
+  self.table_name = "annotation_reviews"
+
+  REVIEW_STATUSES = %w[pending reviewed escalated].freeze
+
+  belongs_to :subject, polymorphic: true
+  belongs_to :reviewer, class_name: ActiveAdmin::Annotations.reviewer_class_name
+
+  has_many :annotations,
+    class_name: "ActiveAdmin::Annotations::Annotation",
+    foreign_key: :annotation_review_id,
+    inverse_of: :annotation_review,
+    dependent: :destroy
+
+  validates :review_status, inclusion: {in: REVIEW_STATUSES}
+  validates :reviewer_id, uniqueness: {scope: %i[subject_type subject_id]}
+  validates :context_json, presence: true
+
+  scope :pending, -> { where(review_status: "pending") }
+  scope :reviewed, -> { where(review_status: "reviewed") }
+  scope :escalated, -> { where(review_status: "escalated") }
+  scope :needs_follow_up, lambda {
+    if connection.adapter_name.match?(/postgres/i)
+      where("metadata_json @> ?", {needs_follow_up: true}.to_json)
+    else
+      where("json_extract(metadata_json, '$.needs_follow_up') = ?", true)
+    end
+  }
+
+  def needs_follow_up?
+    ActiveModel::Type::Boolean.new.cast(metadata_json.to_h["needs_follow_up"])
+  end
+
+  def context_stale?
+    ActiveModel::Type::Boolean.new.cast(metadata_json.to_h["context_stale"])
+  end
+
+  def self.ransackable_attributes(_auth_object = nil)
+    %w[
+      subject_type
+      subject_id
+      reviewer_id
+      review_status
+      context_digest
+      created_at
+    ]
+  end
+
+  def self.ransackable_associations(_auth_object = nil)
+    %w[reviewer subject annotations]
+  end
+end

data/app/services/active_admin/annotations/review_service.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module ActiveAdmin::Annotations
+  class ReviewService
+    class << self
+      def find_or_sync_review!(
+        subject:,
+        reviewer:,
+        context:,
+        context_digest: nil,
+        content_revision_version: 0,
+        latest_content_revision_version: content_revision_version,
+        content_revision_enabled: ContentRevision.enabled_for?(subject)
+      )
+        2.times do |attempt|
+          return sync_and_save_review!(
+            subject: subject,
+            reviewer: reviewer,
+            context: context,
+            context_digest: context_digest,
+            content_revision_version: content_revision_version,
+            latest_content_revision_version: latest_content_revision_version,
+            content_revision_enabled: content_revision_enabled
+          )
+        rescue ActiveRecord::RecordNotUnique
+          raise if attempt == 1
+        end
+      end
+
+      def advance_to_latest!(
+        subject:,
+        reviewer:,
+        context:,
+        latest_content_revision_version:, context_digest: nil,
+        content_revision_enabled: ContentRevision.enabled_for?(subject)
+      )
+        raise ArgumentError, "content revisions are not enabled for this subject" unless content_revision_enabled
+
+        review = Review.find_by!(subject: subject, reviewer: reviewer)
+        context_hash = context.deep_stringify_keys
+        digest = context_digest.presence || Context.digest_for(context_hash)
+        latest_version = latest_content_revision_version.to_i
+
+        review.update!(
+          content_revision_version: latest_version,
+          context_json: context_hash,
+          context_digest: digest,
+          metadata_json: review.metadata_json.to_h.merge("context_stale" => false)
+        )
+        review
+      end
+
+      private
+
+      def sync_with_content_revision!(review, context_hash:, digest:, pinned_version:, latest_version:)
+        if review.new_record?
+          review.assign_attributes(
+            content_revision_version: pinned_version,
+            context_json: context_hash,
+            context_digest: digest,
+            metadata_json: review.metadata_json.to_h.merge("context_stale" => false)
+          )
+        elsif latest_version > review.content_revision_version
+          review.metadata_json = review.metadata_json.to_h.merge("context_stale" => true)
+        elsif review.content_revision_version == pinned_version && review.context_digest != digest
+          review.assign_attributes(
+            context_json: context_hash,
+            context_digest: digest,
+            metadata_json: review.metadata_json.to_h.merge("context_stale" => false)
+          )
+        elsif !review.context_stale?
+          review.metadata_json = review.metadata_json.to_h.merge("context_stale" => false)
+        end
+      end
+
+      def sync_and_save_review!(
+        subject:,
+        reviewer:,
+        context:,
+        context_digest:,
+        content_revision_version:,
+        latest_content_revision_version:,
+        content_revision_enabled:
+      )
+        context_hash = context.deep_stringify_keys
+        digest = context_digest.presence || Context.digest_for(context_hash)
+        pinned_version = content_revision_version.to_i
+        latest_version = latest_content_revision_version.to_i
+
+        review = Review.find_or_initialize_by(
+          subject: subject,
+          reviewer: reviewer
+        )
+
+        if content_revision_enabled
+          sync_with_content_revision!(
+            review,
+            context_hash: context_hash,
+            digest: digest,
+            pinned_version: pinned_version,
+            latest_version: latest_version
+          )
+        else
+          sync_without_content_revision!(review, context_hash: context_hash, digest: digest)
+        end
+
+        return review unless review.changed?
+
+        review.save!
+        review
+      end
+
+      def sync_without_content_revision!(review, context_hash:, digest:)
+        if review.new_record?
+          review.assign_attributes(
+            content_revision_version: 0,
+            context_json: context_hash,
+            context_digest: digest,
+            metadata_json: review.metadata_json.to_h.merge("context_stale" => false)
+          )
+        elsif review.context_digest != digest
+          review.metadata_json = review.metadata_json.to_h.merge("context_stale" => true)
+        else
+          review.assign_attributes(
+            context_json: context_hash,
+            context_digest: digest,
+            metadata_json: review.metadata_json.to_h.merge("context_stale" => false)
+          )
+        end
+      end
+    end
+  end
+end

data/app/views/active_admin/annotations/_copy_details_action.html.erb

@@ -0,0 +1,21 @@
+<div
+  class="aa-annotations-copy-action"
+  data-controller="activeadmin-annotations--clipboard"
+  data-activeadmin-annotations--clipboard-source-url-value="<%= copy_text_url %>"
+  data-activeadmin-annotations--clipboard-success-message-value="Copied annotation details">
+  <button
+    type="button"
+    class="action-item-button"
+    data-action="activeadmin-annotations--clipboard#copyFromUrl">
+    Copy details
+  </button>
+  <p
+    class="aa-annotations-copy-action__status"
+    data-activeadmin-annotations--clipboard-target="status"
+    aria-live="polite"></p>
+  <textarea
+    class="aa-annotations-copy-action__manual-copy"
+    data-activeadmin-annotations--clipboard-target="manualCopy"
+    hidden
+    readonly></textarea>
+</div>