kabk 0.2.0

data/lib/kabk/field.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Kabk
+  # Represents field/column metadata
+  class Field
+    # @return [String] The technical name of the field (e.g., "created_at").
+    attr_accessor :name
+    # @return [String] The human-readable label for the field.
+    attr_accessor :label
+    # @return [Symbol] The underlying data type (:string, :number, :boolean, :date, :datetime, :file, :relation).
+    attr_accessor :type
+    # @return [Symbol] The frontend input component type (e.g., :text, :switch, :date, :image_single).
+    attr_accessor :form_type
+    # @return [Symbol] The calendar system to use if type is date/datetime (e.g., :jalali, :gregorian).
+    attr_accessor :calendar
+    # @return [Boolean] Indicates if this field is the primary key.
+    attr_accessor :primary_key
+    # @return [Boolean] Indicates if this field can be null.
+    attr_accessor :nullable
+    # @return [Symbol] UI hint for how to display the value (e.g., :badge, :thumbnail, :boolean_icon).
+    attr_accessor :display_as
+    # @return [Integer] Bootstrap grid column width (1 to 12).
+    attr_accessor :col_width
+    # @return [Integer] The explicit ordering weight for rendering.
+    attr_accessor :order
+    # @return [Boolean] Indicates if this field is mandatory in forms.
+    attr_accessor :required
+    # @return [Boolean] Indicates if this field is read-only.
+    attr_accessor :readonly
+    # @return [Boolean] If true, hides the field in data tables.
+    attr_accessor :hidden_in_table
+    # @return [Boolean] If true, hides the field in forms.
+    attr_accessor :hidden_in_form
+    # @return [Boolean] If true, wraps this field in an accordion section.
+    attr_accessor :accordion
+    # @return [Integer] For textarea form_type, specifies the number of rows.
+    attr_accessor :rows
+    # @return [Array, Hash] Hardcoded select options if applicable.
+    attr_accessor :options
+    # @return [Object] The default value for the field.
+    attr_accessor :default_value
+    # @return [Hash] Configures field dependency visibility (e.g., { field: "published", value: true }).
+    attr_accessor :depends_on
+    # @return [Hash] Server-side validation rules (e.g., { min_length: 5, unique: true }).
+    attr_accessor :validation
+    # @return [Hash] Relational metadata (e.g., { resource: "user", cardinality: "many_to_one", ... }).
+    attr_accessor :relation
+    # @return [Hash] Configuration for file uploads.
+    attr_accessor :upload_config
+
+    def initialize(name:, **attributes)
+      @name = name.to_s
+      @primary_key = false
+      @nullable = false
+      @col_width = 12
+      @required = false
+      @readonly = false
+      @hidden_in_table = false
+      @hidden_in_form = false
+      @accordion = false
+
+      attributes.each do |k, v|
+        send("#{k}=", v) if respond_to?("#{k}=")
+      end
+    end
+
+    def to_h
+      hash = {
+        name: @name,
+        label: @label,
+        type: @type,
+        form_type: @form_type
+      }
+
+      hash[:calendar] = @calendar if @calendar
+      hash[:primary_key] = @primary_key if @primary_key
+      hash[:nullable] = @nullable unless @nullable.nil?
+      hash[:display_as] = @display_as if @display_as
+      hash[:col_width] = @col_width if @col_width
+      hash[:order] = @order if @order
+      hash[:required] = @required if @required
+      hash[:readonly] = @readonly if @readonly
+      hash[:hidden_in_table] = @hidden_in_table if @hidden_in_table
+      hash[:hidden_in_form] = @hidden_in_form if @hidden_in_form
+      hash[:accordion] = @accordion if @accordion
+      hash[:rows] = @rows if @rows
+      hash[:options] = @options if @options
+      hash[:default_value] = @default_value unless @default_value.nil?
+      hash[:depends_on] = @depends_on if @depends_on
+      hash[:validation] = @validation if @validation
+      hash[:relation] = @relation if @relation
+      hash[:upload_config] = @upload_config if @upload_config
+
+      hash
+    end
+  end
+end

data/lib/kabk/query_builder.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Kabk
+  # Handles applying page, sort, search, and filters to a Sequel dataset
+  class QueryBuilder
+    # @param resource [Kabk::Resource]
+    # @param params [Hash] Request query parameters
+    # @return [Sequel::Dataset] Paginated dataset
+    def self.build(resource, params)
+      dataset = resource.model_class.dataset
+
+      dataset = apply_search(dataset, resource, params["search"])
+      dataset = apply_filters(dataset, resource, params["filter"])
+      dataset = apply_sort(dataset, resource, params["sort"] || resource.default_sort)
+
+      apply_pagination(dataset, resource, params)
+    end
+
+    def self.apply_search(dataset, resource, search_term)
+      return dataset if search_term.nil? || search_term.to_s.strip.empty?
+      return dataset if resource.searchable_fields.nil? || resource.searchable_fields.empty?
+
+      # Apply case-insensitive global search across all searchable fields.
+      search_conditions = resource.searchable_fields.map do |field|
+        Sequel.ilike(field.to_sym, "%#{search_term}%")
+      end
+
+      dataset.where(Sequel.|(*search_conditions))
+    end
+
+    def self.apply_filters(dataset, _resource, filters)
+      return dataset unless filters.is_a?(Hash)
+
+      filters.each do |field, value|
+        # Parse comma-separated values to support SQL IN clauses.
+        values = value.to_s.split(",")
+        dataset = if values.size > 1
+                    dataset.where(field.to_sym => values)
+                  else
+                    dataset.where(field.to_sym => value)
+                  end
+      end
+      dataset
+    end
+
+    def self.apply_sort(dataset, resource, sort_term)
+      return dataset if sort_term.nil? || sort_term.to_s.strip.empty?
+
+      is_desc = sort_term.start_with?("-")
+      field_name = is_desc ? sort_term[1..] : sort_term
+
+      # Ensure sorting is only applied to permitted fields.
+      if resource.sortable_fields&.include?(field_name)
+        col = field_name.to_sym
+        dataset = is_desc ? dataset.order(Sequel.desc(col)) : dataset.order(Sequel.asc(col))
+      end
+      dataset
+    end
+
+    def self.apply_pagination(dataset, resource, params)
+      page = (params["page"] || 1).to_i
+      per_page = (params["per_page"] || resource.per_page_default).to_i
+
+      page = 1 if page < 1
+      per_page = 15 if per_page < 1
+
+      # Depends on Sequel's pagination extension (Sequel.extension :pagination).
+      # Returns a paginated Sequel::Dataset.
+      dataset.extension(:pagination).paginate(page, per_page)
+    end
+  end
+end

data/lib/kabk/registry.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "concurrent-ruby"
+
+module Kabk
+  # Thread-safe registry for managing registered resources
+  class Registry
+    # @return [Registry]
+    def self.instance
+      @instance ||= new
+    end
+
+    def initialize
+      @resources = Concurrent::Map.new
+    end
+
+    # Register a new resource
+    # @param resource [Kabk::Resource]
+    def register(resource)
+      @resources[resource.name.to_sym] = resource
+    end
+
+    # Retrieve a resource by name
+    # @param name [Symbol, String]
+    # @return [Kabk::Resource, nil]
+    def get(name)
+      @resources[name.to_sym]
+    end
+
+    # Get all registered resources
+    # @return [Array<Kabk::Resource>]
+    def all
+      @resources.values
+    end
+
+    # Clear registry (useful for testing)
+    def clear
+      @resources.clear
+    end
+  end
+end

data/lib/kabk/relation_hydrator.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "registry"
+
+module Kabk
+  # Hydrates `<field>_display` for relation fields to prevent N+1 queries.
+  class RelationHydrator
+    # Hydrates a collection of records in-memory or via SQL joins/eager loading
+    # @param resource [Kabk::Resource]
+    # @param records [Array<Hash>, Array<Sequel::Model>]
+    # @return [Array<Hash>] Hydrated records as hashes
+    def self.hydrate(resource, records)
+      return [] if records.empty?
+
+      # Convert all records to hashes immediately if they are models
+      record_hashes = records.map { |r| r.is_a?(Hash) ? r.dup : r.values }
+
+      relation_fields = resource.fields.select { |f| f.type == "relation" && f.relation }
+
+      relation_fields.each do |field|
+        rel_meta = field.relation
+        target_resource = Registry.instance.get(rel_meta["resource"] || rel_meta[:resource])
+        next unless target_resource
+
+        target_model = target_resource.model_class
+        value_field = (rel_meta["value_field"] || rel_meta[:value_field]).to_sym
+        label_field = (rel_meta["label_field"] || rel_meta[:label_field]).to_sym
+        display_key = (rel_meta["display_key"] || rel_meta[:display_key] || "#{field.name}_display").to_sym
+        cardinality = rel_meta["cardinality"] || rel_meta[:cardinality] || "many_to_one"
+        field_sym = field.name.to_sym
+
+        # Extract all keys to load
+        keys_to_load = record_hashes.flat_map do |rh|
+          val = rh[field_sym]
+          if val.is_a?(String) && cardinality == "many_to_many" && val.is_a?(String)
+            # Handle JSON or comma-separated string values.
+            val = begin
+              JSON.parse(val)
+            rescue StandardError
+              val.split(",")
+            end
+          end
+          val
+        end.flatten.compact.uniq
+
+        next if keys_to_load.empty?
+
+        # Load relation map.
+        # Example: SELECT id, full_name FROM users WHERE id IN (...)
+        target_data = target_model.where(value_field => keys_to_load).select(value_field, label_field).all
+        target_map = target_data.each_with_object({}) do |row, map|
+          map[row[value_field]] = row[label_field]
+          map[row[value_field].to_s] = row[label_field] # allow string keys too
+        end
+
+        # Map back to records
+        record_hashes.each do |rh|
+          val = rh[field_sym]
+          if cardinality == "many_to_many"
+            arr = if val.is_a?(Array)
+                    val
+                  else
+                    begin
+                      JSON.parse(val.to_s)
+                    rescue StandardError
+                      val.to_s.split(",")
+                    end
+                  end
+            rh[display_key] = arr.map { |v| target_map[v] }.compact if arr
+          elsif val
+            rh[display_key] = target_map[val]
+          end
+        end
+      end
+
+      # Format dates to ISO8601 per standard protocol.
+      format_dates!(resource, record_hashes)
+
+      record_hashes
+    end
+
+    def self.format_dates!(resource, record_hashes)
+      date_fields = resource.fields.select { |f| %w[date datetime].include?(f.type) }.map(&:name).map(&:to_sym)
+
+      record_hashes.each do |rh|
+        # Include standard audit/concurrency fields if present and not explicitly defined as fields
+        %i[created_at updated_at].each do |ts|
+          if rh[ts].respond_to?(:iso8601)
+            rh[ts] = rh[ts].iso8601
+          elsif rh[ts].is_a?(Time) || rh[ts].is_a?(Date) || rh[ts].is_a?(DateTime)
+            # Fallback formatting if it responds to strftime
+            rh[ts] = rh[ts].strftime("%Y-%m-%dT%H:%M:%S.%LZ")
+          end
+        end
+
+        date_fields.each do |df|
+          val = rh[df]
+          if val.respond_to?(:iso8601)
+            rh[df] = val.iso8601
+          elsif val.is_a?(Time) || val.is_a?(Date) || val.is_a?(DateTime)
+            rh[df] = val.strftime("%Y-%m-%dT%H:%M:%S.%LZ")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kabk/resource.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Kabk
+  # Metadata value object for a registered resource
+  class Resource
+    # @return [String] The technical singular name of the resource (e.g., "news_item").
+    attr_accessor :name
+    # @return [String] The plural name used in routing (e.g., "news").
+    attr_accessor :plural_name
+    # @return [Hash] Localization hash for the resource title (e.g., { fa: "اخبار", en: "News" }).
+    attr_accessor :title
+    # @return [String] The identifier of the icon to render in the sidebar.
+    attr_accessor :icon
+    # @return [String] The base API path where the resource is mounted (e.g., "/api/admin/news").
+    attr_accessor :api_path
+    # @return [Boolean] Whether to display this resource in the admin sidebar menu.
+    attr_accessor :display_in_sidebar
+    # @return [String] The menu group category for this resource.
+    attr_accessor :group
+    # @return [Integer] The explicit ordering weight in the sidebar.
+    attr_accessor :order
+    # @return [String] The default sort column and direction (e.g., "-created_at").
+    attr_accessor :default_sort
+    # @return [Integer] Default number of records per page for pagination.
+    attr_accessor :per_page_default
+    # @return [Array<String>] List of field names that support full-text search.
+    attr_accessor :searchable_fields
+    # @return [Array<String>] List of field names that can be sorted by.
+    attr_accessor :sortable_fields
+    # @return [Array<String>] List of field names that can be filtered on.
+    attr_accessor :filterable_fields
+    # @return [String] The field used for Optimistic Concurrency Control (OCC), usually "updated_at".
+    attr_accessor :concurrency_field
+    # @return [Array<String>] Configures standard audit fields (created_at, updated_at).
+    attr_accessor :audit_fields
+    # @return [Hash] The baseline CRUD permissions (can_view, can_edit, etc).
+    attr_accessor :permissions
+    # @return [Array<Kabk::Field>] The array of registered field objects.
+    attr_accessor :fields
+    # @return [Class] The underlying ORM Model class (e.g., Sequel::Model).
+    attr_accessor :model_class
+    # @return [Kabk::Adapters::Base] The adapter instance for this resource.
+    attr_accessor :adapter
+    # @return [Hash] Configured lifecycle hooks.
+    attr_accessor :hooks
+
+    def initialize(name:, model_class:)
+      @name = name.to_s
+      @model_class = model_class
+      @fields = []
+      @hooks = {}
+      @display_in_sidebar = true
+      @per_page_default = 15
+      @permissions = {
+        can_view: true,
+        can_insert: true,
+        can_edit: true,
+        can_delete: true,
+        can_export: true
+      }
+    end
+
+    def to_h
+      hash = {
+        name: @name,
+        plural_name: @plural_name,
+        title: @title,
+        icon: @icon,
+        api_path: @api_path
+      }
+
+      hash[:display_in_sidebar] = @display_in_sidebar unless @display_in_sidebar.nil?
+      hash[:group] = @group if @group
+      hash[:order] = @order if @order
+      hash[:default_sort] = @default_sort if @default_sort
+      hash[:per_page_default] = @per_page_default if @per_page_default
+      hash[:searchable_fields] = @searchable_fields if @searchable_fields
+      hash[:sortable_fields] = @sortable_fields if @sortable_fields
+      hash[:filterable_fields] = @filterable_fields if @filterable_fields
+      hash[:concurrency_field] = @concurrency_field if @concurrency_field
+      hash[:audit_fields] = @audit_fields if @audit_fields
+      hash[:permissions] = @permissions if @permissions
+      hash[:fields] = @fields.map(&:to_h)
+
+      hash
+    end
+  end
+end

data/lib/kabk/resource_builder.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Kabk
+  # Custom error classes
+  class Error < StandardError; end
+  class InvalidFieldError < Error; end
+
+  # DSL builder for resources
+  class ResourceBuilder
+    def initialize(resource)
+      @resource = resource
+    end
+
+    # Delegate dynamic attribute setting (e.g. title, icon, plural_name)
+    def method_missing(method_name, *args, **kwargs, &)
+      if @resource.respond_to?("#{method_name}=")
+        value = if kwargs.any? && args.empty?
+                  kwargs
+                else
+                  args.first
+                end
+        @resource.send("#{method_name}=", value)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      @resource.respond_to?("#{method_name}=") || super
+    end
+
+    # Define a field with attributes
+    def field(name, type:, form_type:, **attributes)
+      # Validate required keys per spec
+      raise InvalidFieldError, "Field '#{name}' is missing 'type'" unless type
+      raise InvalidFieldError, "Field '#{name}' is missing 'form_type'" unless form_type
+
+      # Extract label, if not provided, default to titleized name
+      label = attributes.delete(:label)
+      if label.nil?
+        label = attributes.slice(:fa, :en)
+        label = name.to_s.capitalize.tr("_", " ") if label.empty?
+        attributes.reject! { |k, _v| %i[fa en].include?(k) }
+      end
+
+      f = Field.new(name: name, type: type, form_type: form_type, label: label, **attributes)
+      @resource.fields << f
+    end
+
+    # Configure permissions explicitly
+    def permissions(**perms)
+      @resource.permissions.merge!(perms)
+    end
+
+    # --- Lifecycle Hooks ---
+
+    # Registers a callback executed before the record is created.
+    # @yield [params, context] The incoming parameters and host context.
+    def before_create(&block)
+      @resource.hooks[:before_create] = block
+    end
+
+    # Registers a callback executed after the record is created.
+    # @yield [record, context] The newly created record hash and host context.
+    def after_create(&block)
+      @resource.hooks[:after_create] = block
+    end
+
+    # Registers a callback executed before the record is updated.
+    # @yield [id, params, context] The record ID, incoming parameters, and host context.
+    def before_update(&block)
+      @resource.hooks[:before_update] = block
+    end
+
+    # Registers a callback executed after the record is updated.
+    # @yield [record, context] The updated record hash and host context.
+    def after_update(&block)
+      @resource.hooks[:after_update] = block
+    end
+
+    # Registers a callback executed before the record is deleted.
+    # @yield [id, context] The record ID and host context.
+    def before_delete(&block)
+      @resource.hooks[:before_delete] = block
+    end
+
+    # Registers a callback executed after the record is deleted.
+    # @yield [id, context] The deleted record ID and host context.
+    def after_delete(&block)
+      @resource.hooks[:after_delete] = block
+    end
+  end
+end

data/lib/kabk/rest_engine.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative "validator"
+
+module Kabk
+  # Generic CRUD engine for any registered resource, agnostic to the underlying database
+  class RestEngine
+    # @param resource_name [String, Symbol]
+    def initialize(resource_name)
+      @resource = Registry.instance.get(resource_name)
+      raise NotFoundError, "Resource not found" unless @resource
+      
+      @adapter = @resource.adapter
+      raise StandardError, "Resource has no adapter configured" unless @adapter
+    end
+
+    # List resources with pagination, sorting, filtering.
+    #
+    # @param params [Hash] Request parameters (page, per_page, sort, filters).
+    # @param context [Hash] Context provided by host framework.
+    # @return [Hash] A standard protocol response hash with success, data, and meta properties.
+    def list(params, context: {})
+      @adapter.list(params, context: context)
+    end
+
+    # Get single resource by ID.
+    #
+    # @param id [Integer, String] The primary key of the record.
+    # @param context [Hash] Context provided by host framework.
+    # @return [Hash] A standard protocol response hash with success and data properties.
+    # @raise [NotFoundError] If the record does not exist.
+    def get(id, context: {})
+      @adapter.get(id, context: context)
+    end
+
+    # Create a new resource. Executes lifecycle hooks, validates parameters, and delegates to the adapter.
+    #
+    # @param params [Hash] The raw input attributes from the request payload.
+    # @param context [Hash] Context provided by host framework.
+    # @return [Hash] A standard protocol response hash or an error hash if a hook/validation fails.
+    def create(params, context: {})
+      @resource.hooks[:before_create]&.call(params, context)
+      sanitized = Validator.validate_and_sanitize!(@resource, params)
+      result = @adapter.create(sanitized, context: context)
+      
+      @resource.hooks[:after_create]&.call(result[:data], context)
+      result
+    rescue ApiError => e
+      e.to_h
+    end
+
+    # Update an existing resource. Executes lifecycle hooks and validates Optimistic Concurrency Control (OCC).
+    #
+    # @param id [Integer, String] The primary key of the record.
+    # @param params [Hash] The updated attributes from the request payload.
+    # @param context [Hash] Context provided by host framework.
+    # @return [Hash] A standard protocol response hash or an error hash if a hook/validation fails.
+    def update(id, params, context: {})
+      @resource.hooks[:before_update]&.call(id, params, context)
+      sanitized = Validator.validate_and_sanitize!(@resource, params, is_update: true)
+      result = @adapter.update(id, sanitized, context: context)
+      
+      @resource.hooks[:after_update]&.call(result[:data], context)
+      result
+    rescue ApiError => e
+      e.to_h
+    end
+
+    # Delete a resource by ID. Executes lifecycle hooks and delegates to the adapter.
+    #
+    # @param id [Integer, String] The primary key of the record.
+    # @param context [Hash] Context provided by host framework.
+    # @return [Hash] A standard protocol response hash indicating success or an error hash if a hook fails.
+    def delete(id, context: {})
+      @resource.hooks[:before_delete]&.call(id, context)
+      result = @adapter.delete(id, context: context)
+      
+      @resource.hooks[:after_delete]&.call(id, context)
+      result
+    rescue ApiError => e
+      e.to_h
+    end
+  end
+end

data/lib/kabk/schema_renderer.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative "registry"
+
+module Kabk
+  # Renders the JSON Schema manifest for the protocol v1.6.0
+  class SchemaRenderer
+    # Initializes the schema renderer
+    #
+    # @param system_config [Hash, nil] Optional system config overrides (e.g., title, logo_url, endpoints)
+    # @param validation_schema_url [String, nil] Custom URL for the validation schema
+    def initialize(system_config: nil, validation_schema_url: nil)
+      @system_config = system_config ? default_system_config.merge(system_config) : default_system_config
+      @validation_schema_url = validation_schema_url || "/schemas/admin-protocol-1.6.0.json"
+    end
+
+    def render
+      {
+        "$schema_version": "1.6.0",
+        system: @system_config,
+        validation_schema_url: @validation_schema_url,
+        resources: Registry.instance.all.map(&:to_h)
+      }
+    end
+
+    private
+
+    def default_system_config
+      {
+        title: { fa: "پنل مدیریت سیمرغ", en: "Simurgh Panel" },
+        logo_url: "/simurgh-logo.svg",
+        default_locale: "en",
+        supported_locales: %w[en fa],
+        direction: "ltr",
+        endpoints: {
+          upload: "/api/admin/uploads"
+        },
+        custom_fonts: [
+          {
+            name: "Lalezar",
+            url: "https://fonts.gstatic.com/s/lalezar/v14/OpUp1a5dqj36gZ2zXh_WfQ.woff2",
+            format: "woff2",
+            label: { en: "Lalezar (Title)", fa: "لاله‌زار (عنوان)" }
+          },
+          {
+            name: "Sahel",
+            url: "https://cdn.jsdelivr.net/gh/rastikerdar/sahel-font@v3.4.0/dist/Sahel.woff2",
+            format: "woff2",
+            label: { en: "Sahel (Clean)", fa: "ساحل (خوانا)" }
+          }
+        ],
+        custom_font_sizes: [
+          {
+            size: "15px",
+            label: { en: "Medium Fine (15px)", fa: "متوسط ظریف (۱۵px)" }
+          },
+          {
+            size: "20px",
+            label: { en: "Sub-heading (20px)", fa: "زیرعنوان (۲۰px)" }
+          },
+          {
+            size: "32px",
+            label: { en: "Hero Display (32px)", fa: "تیتر برجسته (۳۲px)" }
+          }
+        ]
+      }
+    end
+  end
+end

data/lib/kabk/upload_handler.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Kabk
+  # Handles generic file uploads and formats them according to Protocol v1.6.0
+  class UploadHandler
+    # @param url [String] Public URL of the uploaded file
+    # @param file_name [String] Original file name
+    # @param size [Integer] File size in bytes
+    # @param mime_type [String] File mime type
+    # @return [Hash] Formatted upload response
+    def self.format_response(url:, file_name:, size:, mime_type: nil)
+      {
+        success: true,
+        message: "File uploaded successfully",
+        data: {
+          url: url,
+          file_name: file_name,
+          size: size,
+          mime_type: mime_type || "application/octet-stream"
+        }
+      }
+    end
+  end
+end