panda-core 0.12.5 → 1.1.0

data/app/models/concerns/panda/core/has_metadata.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Panda
+  module Core
+    # Concern for models with a JSONB `metadata` column.
+    #
+    # Provides a DSL to declare typed metadata fields that auto-generate
+    # scopes, predicates, and virtual attribute setters.
+    #
+    #   class User < ApplicationRecord
+    #     include HasMetadata
+    #
+    #     metadata_field :internal, type: :boolean, filterable: true,
+    #       label: "Visibility", default_scope: :external,
+    #       filter_options: [["All Users", ""], ["Staff Users", "internal"], ["External Users", "external"]]
+    #   end
+    #
+    #   User.internal          # => scope
+    #   User.external          # => scope
+    #   user.internal?         # => true/false
+    #   user.mark_as_internal! # => saves
+    #   user.mark_as_external! # => saves
+    #   user.internal = "1"    # => virtual setter for forms
+    #
+    module HasMetadata
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :_metadata_fields, default: {}
+
+        scope :with_metadata, ->(key, value) {
+          if connection.adapter_name == "PostgreSQL"
+            where("metadata @> ?", {key.to_s => value}.to_json)
+          else
+            where("json_extract(metadata, ?) = ?", "$.#{key}", json_cast(value))
+          end
+        }
+      end
+
+      class_methods do
+        # Declare a metadata field with auto-generated scopes and accessors.
+        #
+        # Options:
+        #   type:           :boolean (default). Only :boolean supported currently.
+        #   filterable:     When true, the field appears in admin filter dropdowns.
+        #   label:          Human-readable label for the filter dropdown header.
+        #   default_scope:  Scope name for the false/absent case (default: not_<key>).
+        #   filter_options: Array of [label, value] pairs for the dropdown. Values must
+        #                   match scope names (e.g. "internal", "external").
+        def metadata_field(key, type: :boolean, filterable: false, label: nil, default_scope: nil, filter_options: nil)
+          config = {
+            type: type,
+            filterable: filterable,
+            label: label || key.to_s.humanize,
+            filter_options: filter_options
+          }
+          self._metadata_fields = _metadata_fields.merge(key.to_s => config)
+
+          case type
+          when :boolean
+            define_boolean_metadata_field(key, default_scope: default_scope)
+          end
+        end
+
+        # Returns only fields marked as filterable.
+        def filterable_metadata_fields
+          _metadata_fields.select { |_, config| config[:filterable] }
+        end
+
+        # Apply all filterable metadata filters from request params to a scope.
+        # Only values listed in filter_options are allowed (safe from arbitrary scope calls).
+        def apply_metadata_filters(scope, params)
+          filterable_metadata_fields.each do |key, config|
+            value = params[key.to_sym]
+            next if value.blank?
+
+            allowed = (config[:filter_options] || []).map(&:last).reject(&:blank?)
+            next unless allowed.include?(value)
+
+            scope = scope.send(value.to_sym) if scope.respond_to?(value.to_sym)
+          end
+          scope
+        end
+
+        # Returns true if any filterable metadata param is present.
+        def metadata_filter_active?(params)
+          filterable_metadata_fields.any? { |key, _| params[key.to_sym].present? }
+        end
+
+        private
+
+        def define_boolean_metadata_field(key, default_scope: nil)
+          default_scope_name = default_scope || :"not_#{key}"
+
+          # Scope for records where key is true
+          scope key, -> {
+            if connection.adapter_name == "PostgreSQL"
+              where("metadata @> ?", {key.to_s => true}.to_json)
+            else
+              where("json_extract(metadata, ?) = 1", "$.#{key}")
+            end
+          }
+
+          # Scope for records where key is absent or not true
+          scope default_scope_name, -> {
+            if connection.adapter_name == "PostgreSQL"
+              where.not("metadata @> ?", {key.to_s => true}.to_json)
+            else
+              where("json_extract(metadata, ?) IS NULL OR json_extract(metadata, ?) != 1", "$.#{key}", "$.#{key}")
+            end
+          }
+
+          # Predicate
+          define_method(:"#{key}?") { metadata_value(key.to_s) == true }
+
+          # Reader (for form builders)
+          define_method(key) { metadata_value(key.to_s) }
+
+          # Bang methods
+          define_method(:"mark_as_#{key}!") { set_metadata(key.to_s, true) }
+          define_method(:"mark_as_#{default_scope_name}!") { remove_metadata(key.to_s) }
+
+          # Virtual attribute setter — handles checkbox "1"/"0" strings
+          define_method(:"#{key}=") do |value|
+            cast_value = ActiveRecord::Type::Boolean.new.cast(value)
+            if cast_value
+              set_metadata_attribute(key.to_s, true)
+            else
+              self.metadata = (self[:metadata] || {}).except(key.to_s)
+            end
+          end
+        end
+
+        def json_cast(value)
+          case value
+          when true then 1
+          when false then 0
+          else value
+          end
+        end
+      end
+
+      # -- Instance methods for generic metadata access --
+
+      def metadata_value(key)
+        (self[:metadata] || {})[key.to_s]
+      end
+
+      def set_metadata(key, value)
+        self.metadata = (self[:metadata] || {}).merge(key.to_s => value)
+        save!
+      end
+
+      def set_metadata_attribute(key, value)
+        self.metadata = (self[:metadata] || {}).merge(key.to_s => value)
+      end
+
+      def remove_metadata(key)
+        self.metadata = (self[:metadata] || {}).except(key.to_s)
+        save!
+      end
+    end
+  end
+end

data/app/models/concerns/panda/core/importable.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Panda
+  module Core
+    module Importable
+      extend ActiveSupport::Concern
+
+      class FieldDefinition
+        attr_reader :name, :label, :required, :transform
+
+        def initialize(name, label:, required: false, transform: nil)
+          @name = name
+          @label = label
+          @required = required
+          @transform = transform || ->(v) { v }
+        end
+      end
+
+      class Configuration
+        attr_reader :field_definitions
+
+        def initialize
+          @field_definitions = []
+        end
+
+        def field(name, label: name.to_s.humanize, required: false, &transform)
+          @field_definitions << FieldDefinition.new(
+            name, label: label, required: required,
+            transform: block_given? ? transform : nil
+          )
+        end
+      end
+
+      included do
+        class_attribute :import_configuration, instance_writer: false
+        self.import_configuration = Configuration.new
+      end
+
+      class_methods do
+        def importable(&block)
+          raise ArgumentError, "importable requires a block to define fields" unless block
+          config = Configuration.new
+          block.call(config)
+          self.import_configuration = config
+        end
+
+        def import_field_definitions
+          import_configuration.field_definitions
+        end
+
+        def import_row(row_data, column_mapping)
+          attrs = {}
+          errors = []
+
+          column_mapping.each do |csv_col, field_name|
+            next if field_name.blank?
+            defn = import_field_definitions.find { |d| d.name.to_s == field_name.to_s }
+            next unless defn
+
+            raw_value = row_data[csv_col]
+            begin
+              attrs[defn.name] = defn.transform.call(raw_value)
+            rescue => e
+              errors << "#{defn.label}: #{e.message}"
+            end
+          end
+
+          import_field_definitions.select(&:required).each do |defn|
+            if attrs[defn.name].blank?
+              errors << "#{defn.label} is required"
+            end
+          end
+
+          [attrs, errors]
+        end
+      end
+    end
+  end
+end

data/app/models/concerns/panda/core/searchable.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Panda
+  module Core
+    module Searchable
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :searchable_config, default: {}
+      end
+
+      class_methods do
+        def searchable(&block)
+          config = SearchableConfig.new
+          block.call(config)
+          self.searchable_config = config.to_h
+
+          # Auto-register with SearchRegistry
+          Panda::Core::SearchRegistry.register(
+            name: searchable_config[:group]&.parameterize || model_name.plural,
+            search_class: self
+          )
+        end
+
+        def admin_search(query, limit: 5)
+          config = searchable_config
+          return [] if config[:fields].blank?
+
+          sanitized_query = "%#{sanitize_sql_like(query)}%"
+          conditions = config[:fields].map { |f| "#{table_name}.#{f} ILIKE :q" }.join(" OR ")
+          records = where(conditions, q: sanitized_query).limit(limit)
+
+          records.map do |record|
+            {
+              name: config[:display]&.call(record) || record.to_s,
+              description: config[:description]&.call(record),
+              href: config[:path]&.call(record)
+            }
+          end
+        end
+      end
+    end
+
+    class SearchableConfig
+      KEYS = %i[fields display description path icon group].freeze
+
+      def initialize
+        @config = {}
+      end
+
+      KEYS.each do |key|
+        define_method(key) do |value = nil|
+          if value.nil?
+            @config[key]
+          else
+            @config[key] = value
+          end
+        end
+      end
+
+      def to_h
+        @config.dup
+      end
+    end
+  end
+end

data/app/models/concerns/panda/core/taggable.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Panda
+  module Core
+    module Taggable
+      extend ActiveSupport::Concern
+
+      included do
+        has_many :taggings, class_name: "Panda::Core::Tagging",
+          as: :taggable, dependent: :destroy
+        has_many :tags, through: :taggings, class_name: "Panda::Core::Tag"
+
+        scope :tagged_with, ->(tag_ids) {
+          joins(:taggings)
+            .where(panda_core_taggings: {tag_id: Array(tag_ids)})
+            .distinct
+        }
+
+        scope :tagged_with_all, ->(tag_ids) {
+          tag_ids = Array(tag_ids)
+          joins(:taggings)
+            .where(panda_core_taggings: {tag_id: tag_ids})
+            .group(arel_table[:id])
+            .having("COUNT(DISTINCT panda_core_taggings.tag_id) = ?", tag_ids.size)
+        }
+      end
+
+      def tag_list
+        tags.map(&:name).sort.join(", ")
+      end
+
+      def tag_ids=(ids)
+        self.tags = Panda::Core::Tag.where(id: Array(ids).reject(&:blank?))
+      end
+    end
+  end
+end

data/app/models/panda/core/feature_flag.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Panda
+  module Core
+    class FeatureFlag < ApplicationRecord
+      self.table_name = "panda_core_feature_flags"
+
+      validates :key, presence: true, uniqueness: true
+
+      # Check whether a feature flag is enabled.
+      # Returns false for unknown keys (safe default).
+      # Results are cached for 1 minute to avoid repeated DB lookups.
+      def self.enabled?(key)
+        Rails.cache.fetch(cache_key_for(key), expires_in: 1.minute) do
+          where(key: key, enabled: true).exists?
+        end
+      end
+
+      # Enable a feature flag by key.
+      def self.enable!(key)
+        flag = find_by!(key: key)
+        flag.update!(enabled: true)
+        Rails.cache.write(cache_key_for(key), true, expires_in: 1.minute)
+      end
+
+      # Disable a feature flag by key.
+      def self.disable!(key)
+        flag = find_by!(key: key)
+        flag.update!(enabled: false)
+        Rails.cache.write(cache_key_for(key), false, expires_in: 1.minute)
+      end
+
+      # Toggle a feature flag by key.
+      def self.toggle!(key)
+        flag = find_by!(key: key)
+        flag.update!(enabled: !flag.enabled)
+        Rails.cache.write(cache_key_for(key), flag.enabled, expires_in: 1.minute)
+      end
+
+      # Register a feature flag idempotently.
+      # Only sets description and enabled on initial creation — existing
+      # flags keep their current state so admin changes are preserved.
+      def self.register(key, description: nil, enabled: false)
+        find_or_create_by(key: key) do |flag|
+          flag.description = description
+          flag.enabled = enabled
+        end
+      end
+
+      def self.cache_key_for(key)
+        "panda_core:feature_flag:#{key}"
+      end
+      private_class_method :cache_key_for
+    end
+  end
+end

data/app/models/panda/core/file_categorization.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Panda
+  module Core
+    class FileCategorization < ApplicationRecord
+      self.table_name = "panda_core_file_categorizations"
+
+      belongs_to :file_category, class_name: "Panda::Core::FileCategory"
+      belongs_to :blob, class_name: "ActiveStorage::Blob"
+
+      validates :file_category_id, uniqueness: {scope: :blob_id}
+    end
+  end
+end

data/app/models/panda/core/file_category.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Panda
+  module Core
+    class FileCategory < ApplicationRecord
+      self.table_name = "panda_core_file_categories"
+
+      belongs_to :parent, class_name: "Panda::Core::FileCategory", optional: true
+      has_many :children, class_name: "Panda::Core::FileCategory", foreign_key: :parent_id, dependent: :nullify
+      has_many :file_categorizations, class_name: "Panda::Core::FileCategorization", dependent: :destroy
+      has_many :blobs, through: :file_categorizations
+
+      validates :name, presence: true
+      validates :slug, presence: true, uniqueness: true,
+        format: {with: /\A[a-z0-9-]+\z/, message: "must contain only lowercase letters, numbers, and hyphens"}
+
+      before_validation :generate_slug, if: -> { slug.blank? && name.present? }
+      before_destroy :prevent_system_deletion
+
+      scope :roots, -> { where(parent_id: nil) }
+      scope :ordered, -> { order(:position, :name) }
+      scope :system_categories, -> { where(system: true) }
+      scope :custom_categories, -> { where(system: false) }
+
+      # Returns all blob IDs for this category and its children
+      def all_blob_ids
+        category_ids = [id] + children.pluck(:id)
+        Panda::Core::FileCategorization.where(file_category_id: category_ids).pluck(:blob_id)
+      end
+
+      private
+
+      def generate_slug
+        self.slug = name.parameterize
+      end
+
+      def prevent_system_deletion
+        return unless system?
+
+        errors.add(:base, "System categories cannot be deleted")
+        throw(:abort)
+      end
+    end
+  end
+end

data/app/models/panda/core/import_session.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Panda
+  module Core
+    class ImportSession < ApplicationRecord
+      self.table_name = "panda_core_import_sessions"
+
+      STATUSES = %w[pending mapping previewing importing complete failed].freeze
+
+      belongs_to :user, class_name: "Panda::Core::User"
+      belongs_to :tenant, polymorphic: true, optional: true
+      has_one_attached :import_file
+
+      validates :importable_type, presence: true
+      validates :status, inclusion: {in: STATUSES}
+      validate :importable_type_must_be_importable
+
+      scope :recent, -> { order(created_at: :desc) }
+
+      def importable_class
+        klass = importable_type.safe_constantize
+        raise ArgumentError, "Unknown importable type: #{importable_type}" unless klass
+        raise ArgumentError, "#{importable_type} is not importable" unless klass.include?(Panda::Core::Importable)
+        klass
+      end
+
+      def file_parser
+        return nil unless import_file.attached?
+        @file_parser ||= FileParser.new(import_file.filename.to_s, import_file.download)
+      end
+
+      def file_headers
+        file_parser&.headers || []
+      end
+
+      def file_rows
+        file_parser&.rows || []
+      end
+
+      def preview_rows(limit: 5)
+        file_rows.first(limit)
+      end
+
+      def column_options
+        return [] unless importable_class.respond_to?(:import_field_definitions)
+        importable_class.import_field_definitions
+      end
+
+      def progress_percentage
+        return 0 if total_rows.zero?
+        ((processed_rows.to_f / total_rows) * 100).round
+      end
+
+      def complete?
+        status == "complete"
+      end
+
+      def importing?
+        status == "importing"
+      end
+
+      def failed?
+        status == "failed"
+      end
+
+      private
+
+      def importable_type_must_be_importable
+        return if importable_type.blank?
+        klass = importable_type.safe_constantize
+        if klass.nil?
+          errors.add(:importable_type, "is not a valid class")
+        elsif !klass.include?(Panda::Core::Importable)
+          errors.add(:importable_type, "is not importable")
+        end
+      end
+    end
+  end
+end

data/app/models/panda/core/presence.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Panda
+  module Core
+    class Presence < ApplicationRecord
+      include HasUUID
+
+      self.table_name = "panda_core_presences"
+
+      PRESENCE_TTL = 30.seconds
+
+      belongs_to :presenceable, polymorphic: true
+      belongs_to :user, class_name: "Panda::Core::User"
+
+      validates :last_seen_at, presence: true
+
+      scope :for_resource, ->(resource) {
+        where(presenceable_type: resource.class.name, presenceable_id: resource.id)
+      }
+      scope :active, ->(ttl = PRESENCE_TTL) { where(last_seen_at: ttl.ago..) }
+      scope :stale, ->(ttl = PRESENCE_TTL) { where(last_seen_at: ...ttl.ago) }
+    end
+  end
+end

data/app/models/panda/core/tag.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Panda
+  module Core
+    class Tag < ApplicationRecord
+      self.table_name = "panda_core_tags"
+
+      belongs_to :tenant, polymorphic: true, optional: true
+      has_many :taggings, class_name: "Panda::Core::Tagging", dependent: :destroy
+
+      validates :name, presence: true,
+        uniqueness: {scope: [:tenant_type, :tenant_id], case_sensitive: false}
+      validates :colour, format: {with: /\A#[0-9a-fA-F]{6}\z/, message: "must be a hex colour (e.g. #ff0000)"},
+        allow_blank: true
+
+      before_validation :normalize_name
+
+      scope :for_tenant, ->(tenant) { tenant ? where(tenant: tenant) : where(tenant_type: nil) }
+      scope :ordered, -> { order(:name) }
+      scope :search_by_name, ->(q) { where("name ILIKE ?", "%#{sanitize_sql_like(q)}%") }
+
+      def display_colour
+        colour.presence || "#6b7280"
+      end
+
+      private
+
+      def normalize_name
+        self.name = name&.strip
+      end
+    end
+  end
+end

data/app/models/panda/core/tagging.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Panda
+  module Core
+    class Tagging < ApplicationRecord
+      self.table_name = "panda_core_taggings"
+
+      belongs_to :tag, class_name: "Panda::Core::Tag", counter_cache: true
+      belongs_to :taggable, polymorphic: true
+
+      validates :tag_id, uniqueness: {scope: [:taggable_type, :taggable_id]}
+    end
+  end
+end