smriti 0.5.0

data/app/controllers/smriti/admin/mat_view_runs_controller.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+module Smriti
+  module Admin
+    # Smriti::Admin::MatViewRunsController
+    # -------------------------------
+    # Controller for viewing materialised view run history in the admin UI.
+    #
+    # Responsibilities:
+    # - Provides a list of recent runs (create/refresh/delete) for all definitions.
+    # - Shows details for an individual run in a Turbo frame/drawer context.
+    #
+    # Filters:
+    # - `before_action :ensure_frame` → enforces frame-only access.
+    # - `before_action :set_mat_view_run` → loads and authorizes a single run.
+    #
+    # Views:
+    # - Index renders `smriti/admin/runs/embed_frame` partial.
+    # - Show renders `smriti/admin/runs/embed_show_drawer` partial.
+    #
+    class MatViewRunsController < ApplicationController
+      include Smriti::Admin::DatatableHelper
+
+      before_action :ensure_frame, :parse_headers_to_params
+      helper_method :definition
+      before_action :ensure_frame, only: %i[index show]
+      before_action :set_mat_view_run, only: %i[show]
+
+      # GET /:lang/admin/runs
+      #
+      # Two part rendering:
+      # - Full page load when no `stream` param: renders index with datatable frame. This is
+      #   essentially shell of the datatable for initial load.
+      # - When shell is loaded, it requests the `stream` version which renders just the datatable rows
+      #   and pagination controls. This allows for dynamic updates via Turbo Streams.
+      #
+      # @return [void]
+      def index
+        authorize_smriti!(:read, :smriti_runs)
+
+        assign_index_state
+
+        if params[:stream].present?
+          render_dt_turbo_streams
+        else
+          render 'index', formats: :html, layout: 'smriti/turbo_frame', locals: { row_meta: @row_meta }
+        end
+      end
+
+      # GET /:lang/admin/runs/:id
+      #
+      # Displays details for a single run.
+      #
+      # @return [void]
+      def show
+        authorize_smriti!(:read, :smriti_run, @run)
+
+        render 'show', formats: :html, layout: 'smriti/turbo_frame'
+      end
+
+      private
+
+      # Loads the requested run and checks authorization.
+      #
+      # @api private
+      #
+      # @return [void]
+      def set_mat_view_run
+        @run = Smriti::MatViewRun.find(params[:id])
+      end
+
+      # Loads data for the index datatable with filtering, searching, sorting, and pagination.
+      # sets @data.
+      #
+      # @api private
+      #
+      # @return [void]
+      def index_dt_load_data
+        rel = Smriti::MatViewRun
+        rel = dt_apply_filter(rel, index_dt_columns)
+        rel = dt_apply_search(rel, index_dt_columns)
+        rel = dt_apply_sort(rel, index_dt_columns)
+        @data = dt_apply_pagination(rel, @dt_config[:pagination][:per_page_default])
+      end
+
+      # Configuration for the index datatable.
+      #
+      # @api private
+      #
+      # @return [Hash] datatable configuration
+      def index_dt_config
+        columns = index_dt_columns
+        {
+          id: 'mv-runs-table',
+          index_url: admin_mat_view_runs_path(frame_id: @frame_id),
+          frame_id: 'mv-runs-datatable',
+          columns: columns,
+          dt_humanize_ref: 'Smriti::MatViewRun',
+          empty_row_partial_name: 'dt-index-empty-row',
+          row_partial_name: 'dt-index-row',
+          search_enabled: columns.any? { |_, col| col[:search].present? },
+          filter_enabled: columns.any? { |_, col| col[:filter].present? },
+          pagination: { per_page_default: 10, per_page_options: [10, 25, 50, 100] }
+        }
+      end
+
+      # Column definitions for the index datatable.
+      #
+      # @api private
+      #
+      # @return [Hash] column definitions
+      def index_dt_columns
+        {
+          operation: {
+            label_ref: 'operation',
+            label_type: 'humanize_attr',
+            sort: 'operation',
+            filter: 'operation',
+            search: 'operation'
+          },
+          definition: {
+            label_ref: 'definition',
+            label_type: 'i18n',
+            sort: 'definition',
+            filter: 'definition',
+            search: 'definition'
+          },
+          started_at: {
+            label_ref: 'started_at',
+            label_type: 'humanize_attr',
+            sort: 'started_at',
+            filter: nil,
+            search: nil
+          },
+          status: {
+            label_ref: 'status',
+            label_type: 'humanize_attr',
+            sort: 'status',
+            filter: 'status',
+            search: 'status'
+          },
+          duration: {
+            label_ref: 'duration_ms',
+            label_type: 'humanize_attr',
+            filter: nil,
+            sort: 'duration_ms',
+            search: 'duration_ms'
+          },
+          rows_before_after: {
+            label_ref: 'rows_before_after',
+            label_type: 'humanize_attr',
+            filter: nil,
+            sort: nil,
+            search: nil
+          },
+          details: {
+            label_ref: 'details',
+            label_type: 'humanize_attr',
+            filter: nil,
+            sort: nil,
+            search: nil
+          }
+        }
+      end
+
+      # Assigns instance variables for the index action.
+      #
+      # @api private
+      #
+      # @return [void]
+      def assign_index_state
+        @dt_config = index_dt_config
+        @data = []
+
+        index_dt_load_data
+        @row_meta = {}
+      end
+    end
+  end
+end

data/app/controllers/smriti/admin/preferences_controller.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+module Smriti
+  module Admin
+    # Smriti::Admin::PreferencesController
+    # --------------------------------------
+    # Controller for managing user preferences in the Smriti admin UI.
+    #
+    # Responsibilities:
+    # - Allows users to view and update UI preferences such as theme and locale.
+    # - Stores theme in cookies and locale in session.
+    # - Provides a force-reload response option to update Turbo frames dynamically.
+    #
+    # Filters:
+    # - `before_action :authorize!` → ensures user can access preferences.
+    # - `before_action :ensure_frame` → requires Turbo frame context for `show`.
+    #
+    class PreferencesController < ApplicationController
+      before_action :authorize!
+      before_action :ensure_frame
+
+      # GET /:lang/admin/preferences
+      #
+      # Displays the current preferences (theme + locale) and available locales.
+      # If `force_reload=1` is passed, sets a non-standard status code (299) and
+      # a custom header to signal the client to reload.
+      #
+      # @return [void]
+      def show
+        @theme   = read_theme
+        @locale  = I18n.locale.to_s
+        @locales = Smriti::Engine.locale_code_mapping.sort_by { |_key, name| name }.map { |code, _name| code.to_s }.uniq
+
+        # force reload frame if requested
+        if params[:force_reload].to_s == '1'
+          response.status = 299
+          response.set_header('X-Status-Name', 'Success force reload')
+        end
+
+        render 'show', formats: :html, layout: 'smriti/turbo_frame'
+      end
+
+      # PATCH/PUT /:lang/admin/preferences
+      #
+      # Updates preferences:
+      # - Theme (`light`, `dark`, or deleted if invalid) stored in cookies.
+      # - Locale stored in session if valid.
+      # Redirects back to preferences with `force_reload=1` to trigger a refresh.
+      #
+      # @return [void]
+      def update
+        theme_param = params[:theme].to_s
+        case theme_param
+        when 'light', 'dark' then cookies[:theme] = { value: theme_param, expires: 1.year.from_now, httponly: false }
+        else cookies.delete(:theme)
+        end
+
+        locale = params[:locale].to_s.presence || Smriti::Engine.default_locale.to_s
+        session[:smriti_locale] = locale if Smriti::Engine.available_locales.map(&:to_s).include?(locale)
+
+        redirect_to "#{admin_preferences_path}?force_reload=1&frame_id=#{@frame_id}", status: :see_other
+      end
+
+      private
+
+      # Authorizes access to preferences.
+      #
+      # @api private
+      #
+      # @return [void]
+      def authorize!
+        authorize_smriti!(:view, :smriti_dashboard)
+      end
+
+      # Reads the theme from cookies.
+      #
+      # @api private
+      #
+      # @return ["light", "dark", "auto"] theme preference or "auto" if unset/invalid
+      def read_theme
+        t = cookies[:theme].to_s
+        %w[light dark].include?(t) ? t : 'auto'
+      end
+    end
+  end
+end

data/app/helpers/smriti/admin/datatable_helper.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+module Smriti
+  module Admin
+    # Smriti::Admin::DatatableHelper
+    # ---------------------------
+    # Helper module providing methods to manage datatable functionalities
+    # such as sorting, searching, filtering, and pagination.
+    #
+    # Responsibilities:
+    # - Apply sorting based on request parameters.
+    # - Apply searching across multiple columns.
+    # - Apply filtering based on specified criteria.
+    # - Handle pagination with customizable page size.
+    # - Generate pagination window for UI display.
+    # - Parse custom headers to parameters for datatable requests.
+    # - Render Turbo Stream responses for dynamic datatable updates.
+    #
+    # Methods:
+    # - dt_apply_sort: applies sorting to a relation based on parameters.
+    # - dt_apply_search: applies search filtering to a relation.
+    # - dt_apply_filter: applies column-based filtering to a relation.
+    # - dt_apply_pagination: paginates a relation.
+    # - pagination_window: generates page numbers for pagination UI.
+    # - parse_headers_to_params: parses custom headers into params.
+    # - render_dt_turbo_streams: renders Turbo Stream responses for datatables.
+    # - param_dtfilter: accessor for dtfilter param.
+    # - param_dtsearch: accessor for dtsearch param.
+    # - param_dtsort: accessor for dtsort param.
+    module DatatableHelper
+      private
+
+      # Applies sorting to the given ActiveRecord relation based on the provided columns and request parameters.
+      #
+      # @api private
+      #
+      # @param rel [ActiveRecord::Relation] the relation to sort
+      # @param columns [Hash] a hash defining the columns and their sort attributes
+      #
+      # @return [ActiveRecord::Relation] the sorted relation
+      def dt_apply_sort(rel, columns)
+        return rel unless param_dtsort.present?
+
+        param_dtsort.split(',').each do |clause|
+          col, dir = clause.split(':')
+          dir = dir&.downcase == 'desc' ? :desc : :asc
+          col_def = columns[col.to_sym]
+          col_def_sort = col_def[:sort] if col_def
+          rel = rel.send("ordered_by_#{col_def_sort}", dir) if col_def_sort
+        end
+        rel
+      end
+
+      # Applies search filtering to the given ActiveRecord relation based on the provided columns and request parameters.
+      #
+      # @api private
+      #
+      # @param rel [ActiveRecord::Relation] the relation to search
+      # @param columns [Hash] a hash defining the columns and their search attributes
+      #
+      # @return [ActiveRecord::Relation] the filtered relation
+      def dt_apply_search(rel, columns)
+        return rel unless param_dtsearch.present?
+
+        scopes = columns.values.filter_map do |col_def|
+          col_def_search = col_def[:search]
+          rel.send("search_by_#{col_def_search}", param_dtsearch) if col_def_search
+        end
+
+        rel = scopes.reduce { |acc, scope| acc.or(scope) } if scopes.any?
+
+        rel
+      end
+
+      # Applies column-based filtering to the given ActiveRecord relation based on the provided columns and request parameters.
+      #
+      # @api private
+      #
+      # @param rel [ActiveRecord::Relation] the relation to filter
+      # @param columns [Hash] a hash defining the columns and their filter attributes
+      #
+      # @return [ActiveRecord::Relation] the filtered relation
+      def dt_apply_filter(rel, columns)
+        return rel unless param_dtfilter.present?
+
+        param_dtfilter.split(',').each do |clause|
+          col, val = clause.split(':')
+          col_def = columns[col.to_sym]
+          col_def_f = col_def[:filter] if col_def
+          rel = rel.send("filtered_by_#{col_def_f}", val) if col_def_f && val.present? && rel.respond_to?("filtered_by_#{col_def_f}")
+        end
+        rel
+      end
+
+      # Applies pagination to the given ActiveRecord relation based on request parameters.
+      #
+      # @api private
+      #
+      # @param rel [ActiveRecord::Relation] the relation to paginate
+      # @param default_per_page [Integer] the default number of items per page
+      #
+      # @return [ActiveRecord::Relation] the paginated relation
+      def dt_apply_pagination(rel, default_per_page)
+        @dt_page = (params[:dtpage] || 1).to_i
+        @dt_per_page = (params[:dtperpage] || default_per_page).to_i
+        total = rel.count
+        @dt_total_pages = rel.total_pages(total: total, per_page: @dt_per_page)
+        rel.paginate(total: total, page: @dt_page, per_page: @dt_per_page)
+      end
+
+      # Returns an array of page numbers and :gap symbols for pagination display
+      #
+      # @api private
+      #
+      # Example:
+      # pagination_window(current_page: 6, total_pages: 20)
+      # => [1, :gap, 4, 5, 6, 7, 8, :gap, 20]
+      #
+      # Use :gap to render "..." in your view.
+      #
+      # @param current_page [Integer] the current page number
+      # @param total_pages [Integer] the total number of pages
+      # @param window [Integer] the number of pages to show on each side of the current page
+      #
+      # @return [Array<Integer, Symbol>] array of page numbers and :gap symbols
+      def pagination_window(current_page:, total_pages:, window: 2)
+        return [] if total_pages < 1
+
+        pages = []
+        left = [1, current_page - window].max
+        right = [total_pages, current_page + window].min
+
+        pages << 1 unless left == 1
+        pages << :gap if left > 2
+
+        (left..right).each { |page| pages << page }
+
+        pages << :gap if right < total_pages - 1
+        pages << total_pages unless right == total_pages
+
+        pages
+      end
+
+      # Parses custom headers into params for datatable requests.
+      #
+      # @api private
+      #
+      # This allows clients to send datatable parameters via headers instead of query parameters.
+      # In this application, this is used to append headers when making Turbo Frame requests.
+      #
+      # Headers parsed:
+      # - X-Dtsearch -> params[:dtsearch]
+      # - X-Dtsort -> params[:dtsort]
+      # - X-Dtfilter -> params[:dtfilter]
+      # - X-DtPage -> params[:dtpage]
+      # - X-DtPerPage -> params[:dtperpage]
+      #
+      # @return [void]
+      def parse_headers_to_params
+        parse_header_to_params(:dtsearch, 'X-Dtsearch')
+        parse_header_to_params(:dtsort, 'X-Dtsort')
+        parse_header_to_params(:dtfilter, 'X-Dtfilter')
+        parse_header_to_params(:dtpage, 'X-DtPage')
+        parse_header_to_params(:dtperpage, 'X-DtPerPage')
+      end
+
+      # Helper method to parse a single header into a parameter if the parameter is not already set.
+      #
+      # @api private
+      #
+      # @param param_key [Symbol] the parameter key to set
+      # @param header_key [String] the header key to read from
+      #
+      # @return [void]
+      def parse_header_to_params(param_key, header_key)
+        return unless request.headers[header_key].present?
+        return if params[param_key].present?
+
+        values = request.headers[header_key].split(',').map(&:strip).reject(&:empty?)
+        params[param_key] = values.join(',')
+      end
+
+      # Renders Turbo Stream responses for datatable updates.
+      #
+      # @api private
+      #
+      # This method is used to dynamically update the datatable rows, pagination controls,
+      # and filters via Turbo Streams when the datatable requests new data.
+      #
+      # @dt_config must be set before calling this method.
+      #
+      # @return [void]
+      def render_dt_turbo_streams
+        dt_config_id = @dt_config[:id]
+        render turbo_stream: [
+          turbo_stream.replace(
+            "datatable-body-#{dt_config_id}",
+            partial: 'smriti/admin/ui/datatable_tbody',
+            locals: { row_meta: @row_meta }
+          ),
+          turbo_stream.replace(
+            "datatable-tfoot-#{dt_config_id}",
+            partial: 'smriti/admin/ui/datatable_tfoot',
+            locals: { dt_config: @dt_config, data: @data }
+          ),
+          if index_dt_config[:filter_enabled]
+            turbo_stream.replace(
+              "datatable-filters-#{dt_config_id}",
+              partial: 'smriti/admin/ui/datatable_filters',
+              locals: { dt_config: @dt_config, dtfilter: params[:dtfilter] || '' }
+            )
+          end
+        ].compact
+      end
+
+      # Accessor methods for datatable filter parameter
+      #
+      # @api private
+      #
+      # @return [String, nil] the dtfilter parameter from params
+      def param_dtfilter
+        params[:dtfilter]
+      end
+
+      # Accessor methods for datatable search parameter
+      #
+      # @api private
+      #
+      # @return [String, nil] the dtsearch parameter from params
+      def param_dtsearch
+        params[:dtsearch]
+      end
+
+      # Accessor methods for datatable sort parameter
+      #
+      # @api private
+      #
+      # @return [String, nil] the dtsort parameter from params
+      def param_dtsort
+        params[:dtsort]
+      end
+    end
+  end
+end

data/app/helpers/smriti/admin/localized_digit_helper.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+# Copyright Codevedas Inc. 2025-present
+#
+# This source code is licensed under the MIT license found in the
+# LICENSE file in the root directory of this source tree.
+
+module Smriti
+  module Admin
+    # Smriti::Admin::LocalizedDigitHelper
+    # -----------------------------------
+    # Helper methods for localizing digits in strings and dates.
+    # This is used in the admin UI to display numbers according to the current locale.
+    #
+    # Responsibilities:
+    # - Map ASCII digits (0-9) to localized representations based on I18n.t('numbers').
+    # - Replace digits in strings or numeric inputs with their localized equivalents.
+    # - Localize dates/times with localized digits.
+    #
+    # Methods:
+    # - localized_numbers: returns a hash mapping '0'-'9' to localized strings.
+    # - localized_digits: replaces digits in a string or number with localized versions.
+    # - l_with_digits: localizes an object (e.g. date/time) and replaces digits.
+    module LocalizedDigitHelper
+      private
+
+      # Replaces ASCII digits in the input with their localized equivalents.
+      #
+      # @api private
+      #
+      # @param str_or_num [String, Numeric] the input string or number
+      # @return [String] the input with digits replaced by localized versions
+      def localized_digits(str_or_num)
+        str_or_num.to_s.gsub(/[0-9]/, localized_numbers)
+      end
+
+      # Returns a hash mapping ASCII digits ('0'-'9') to their localized equivalents.
+      #
+      # @api private
+      #
+      # @return [Hash{String => String}] mapping of '0'-'9' to localized strings
+      def localized_numbers
+        map = I18n.t('numbers', default: nil)
+        {
+          '0' => map[:zero],
+          '1' => map[:one],
+          '2' => map[:two],
+          '3' => map[:three],
+          '4' => map[:four],
+          '5' => map[:five],
+          '6' => map[:six],
+          '7' => map[:seven],
+          '8' => map[:eight],
+          '9' => map[:nine]
+        }.compact
+      end
+
+      # Localizes an object (e.g. date/time) using I18n.l and replaces digits with localized versions.
+      #
+      # @api private
+      #
+      # @param obj [Object] the object to localize
+      # @param kwargs [Hash] additional keyword arguments passed to I18n.l
+      # @return [String] the localized string with digits replaced
+      def l_with_digits(obj, **)
+        localized_digits(I18n.l(obj, **))
+      end
+    end
+  end
+end